{"id":45104073,"url":"https://github.com/joshuaswarren/openclaw-engram","last_synced_at":"2026-04-08T23:06:22.847Z","repository":{"id":336745532,"uuid":"1150677698","full_name":"joshuaswarren/openclaw-engram","owner":"joshuaswarren","description":"Local-first memory plugin for OpenClaw AI agents. LLM-powered extraction, plain markdown storage, hybrid search via QMD. Gives agents persistent long-term memory across conversations.","archived":false,"fork":false,"pushed_at":"2026-03-26T14:55:45.000Z","size":10672,"stargazers_count":32,"open_issues_count":0,"forks_count":11,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-26T18:50:34.677Z","etag":null,"topics":["ai-agent","ai-memory","conversational-ai","engram","knowledge-graph","llm","local-first","long-term-memory","markdown","memory-plugin","openai","openclaw","semantic-search","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joshuaswarren.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":["joshuaswarren"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2026-02-05T15:04:53.000Z","updated_at":"2026-03-26T14:59:06.000Z","dependencies_parsed_at":"2026-02-25T02:03:40.625Z","dependency_job_id":null,"html_url":"https://github.com/joshuaswarren/openclaw-engram","commit_stats":null,"previous_names":["joshuaswarren/openclaw-engram"],"tags_count":236,"template":false,"template_full_name":null,"purl":"pkg:github/joshuaswarren/openclaw-engram","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshuaswarren%2Fopenclaw-engram","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshuaswarren%2Fopenclaw-engram/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshuaswarren%2Fopenclaw-engram/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshuaswarren%2Fopenclaw-engram/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joshuaswarren","download_url":"https://codeload.github.com/joshuaswarren/openclaw-engram/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshuaswarren%2Fopenclaw-engram/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31292631,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","ai-memory","conversational-ai","engram","knowledge-graph","llm","local-first","long-term-memory","markdown","memory-plugin","openai","openclaw","semantic-search","typescript"],"created_at":"2026-02-19T21:56:38.075Z","updated_at":"2026-04-08T23:06:22.830Z","avatar_url":"https://github.com/joshuaswarren.png","language":"TypeScript","funding_links":["https://github.com/sponsors/joshuaswarren"],"categories":["Community Plugins"],"sub_categories":["Memory \u0026 Context"],"readme":"# Engram\n\n**Persistent, private memory for AI agents.** Your agents forget everything between sessions — Engram fixes that.\n\nEngram gives AI agents long-term memory that survives across conversations. Decisions, preferences, project context, personal details, past mistakes — everything your agent learns persists and resurfaces exactly when it's needed. All data stays on your machine as plain markdown files. No cloud services, no subscriptions, no sharing your data with third parties.\n\n[![npm version](https://img.shields.io/npm/v/@joshuaswarren/openclaw-engram)](https://www.npmjs.com/package/@joshuaswarren/openclaw-engram)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink)](https://github.com/sponsors/joshuaswarren)\n\n\u003e **Engram is now a monorepo.** For standalone (non-OpenClaw) use, install the scoped packages:\n\u003e [`@engram/core`](https://www.npmjs.com/package/@engram/core),\n\u003e [`@engram/server`](https://www.npmjs.com/package/@engram/server),\n\u003e [`@engram/cli`](https://www.npmjs.com/package/@engram/cli).\n\u003e The `openclaw-engram` and `@joshuaswarren/openclaw-engram` packages remain the OpenClaw plugin entry point.\n\u003e Python users: [`engram-hermes`](https://pypi.org/project/engram-hermes/) on PyPI.\n\n## Support Engram\n\nEvery bit of support is genuinely appreciated and helps keep this project alive and free for everyone.\n\nIf you're able to, [sponsoring on GitHub](https://github.com/sponsors/joshuaswarren) or sending a Lightning donation to `joshuaswarren@strike.me` directly funds continued development, new integrations, and keeping Engram open source.\n\n[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink?style=for-the-badge)](https://github.com/sponsors/joshuaswarren)\n\nIf financial support isn't an option, you can still make a big difference — [star the repo on GitHub](https://github.com/joshuaswarren/openclaw-engram), share it on social media, or recommend it to a friend or colleague. Word of mouth is how most people find Engram, and it means the world.\n\n## The Problem\n\nEvery AI agent session starts from zero. Your agent doesn't know your name, your projects, the decisions you've already made, or the bugs you already debugged. Whether it's a personal assistant, a coding agent, a research agent, or a multi-agent team — they all forget everything between conversations. You re-explain the same context over and over, and your agents still make the same mistakes.\n\nOpenClaw's built-in memory works for simple cases, but it doesn't scale. It lacks semantic search, lifecycle management, entity tracking, and governance. Third-party memory services exist, but they cost money and require sending your private data to someone else's servers.\n\n## The Solution\n\nEngram is an open-source, local-first memory system that replaces OpenClaw's default memory with something much more capable — while keeping everything on your machine. It watches your agent conversations, extracts durable knowledge, and injects the right memories back at the start of every session. Use OpenAI or a **local LLM** (Ollama, LM Studio, etc.) for extraction — your choice.\n\nEngram is the **universal memory layer for AI agents**. It works natively with **[OpenClaw](https://github.com/openclaw/openclaw)**, **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)**, **[Codex CLI](https://github.com/openai/codex)**, **[Hermes Agent](https://github.com/hermes-agent/hermes)**, and any **MCP-compatible client** (Replit, Cursor, etc.). When you tell any agent a preference, every agent knows it — they share one memory store.\n\n| Without Engram | With Engram |\n|---|---|\n| Re-explain who you are and what you're working on | Agent recalls your identity, projects, and preferences automatically |\n| Repeat context for every task | Entity knowledge surfaces people, projects, tools, and relationships on demand |\n| Lose debugging and research context between sessions | Past root causes, dead ends, and findings are recalled — no repeated work |\n| Manually restate preferences every session | Preferences persist across sessions, agents, and projects |\n| Context-switching tax when resuming work | Session-start recall brings you back to speed instantly |\n| Default OpenClaw memory doesn't scale | Hybrid search, lifecycle management, namespaces, and governance |\n| Third-party memory services cost money and share your data | Everything stays local — your filesystem, your rules |\n\n## Installation\n\n### Option 1: Install from the CLI\n\n```bash\nopenclaw plugins install @joshuaswarren/openclaw-engram --pin\n```\n\n### Option 2: Ask your OpenClaw agent to install it\n\nTell any OpenClaw agent:\n\n\u003e Install the openclaw-engram plugin and configure it as my memory system.\n\nYour agent will run the install command, update `openclaw.json`, and restart the gateway for you.\n\n### Option 3: Developer install from source\n\n```bash\ngit clone https://github.com/joshuaswarren/openclaw-engram.git \\\n  ~/.openclaw/extensions/openclaw-engram\ncd ~/.openclaw/extensions/openclaw-engram\nnpm ci \u0026\u0026 npm run build\n```\n\n### Option 4: Standalone (no OpenClaw)\n\n**From npm (recommended):**\n\n```bash\nnpm install -g @engram/cli      # Installs the `engram` binary\nengram init                     # Create engram.config.json\nexport OPENAI_API_KEY=sk-...\nexport ENGRAM_AUTH_TOKEN=$(openssl rand -hex 32)\nengram daemon start             # Start background server\nengram status                   # Verify it's running\nengram query \"hello\" --explain  # Test query with tier breakdown\n```\n\n**From source** (requires [Node.js](https://nodejs.org/) 22.12+ and [pnpm](https://pnpm.io/)):\n\n```bash\ngit clone https://github.com/joshuaswarren/openclaw-engram.git\ncd openclaw-engram\npnpm install \u0026\u0026 pnpm run build\ncd packages/engram-cli \u0026\u0026 pnpm link --global  # Makes `engram` available on PATH\ncd ../..\nengram init\n```\n\n\u003e **Note:** The `engram` binary (`packages/cli/bin/engram.cjs`) is a CJS wrapper that auto-locates `tsx` from `node_modules` (falling back to a global `tsx`). Running `npm link` from `packages/cli/` (not the repo root) makes the CLI globally available — the root package only exposes `engram-access`. Alternatively, invoke directly: `npx tsx packages/cli/src/index.ts \u003ccommand\u003e`.\n\nThe standalone CLI provides 15+ commands for memory management, project onboarding, curation, diff-aware sync, dedup, connectors, spaces, and benchmarks -- all without requiring OpenClaw. See the [Platform Migration Guide](docs/guides/platform-migration.md) for the full command reference.\n\n### Option 5: Connect Other AI Agents\n\nOnce the Engram daemon is running, connect any supported agent:\n\n```bash\nengram connectors install claude-code   # Claude Code (hooks + MCP)\nengram connectors install codex-cli     # Codex CLI (hooks + MCP)\nengram connectors install replit        # Replit (MCP only)\npip install engram-hermes               # Hermes Agent (Python MemoryProvider)\n```\n\nEach connector generates a unique auth token, installs the appropriate plugin/hooks, and verifies the connection. All agents share the same memory store — tell one agent your preference, and every agent remembers it.\n\n| Platform | Integration | Auto-recall | Auto-observe |\n|----------|------------|-------------|--------------|\n| **OpenClaw** | Memory slot plugin | Every session | Every response |\n| **Claude Code** | Native hooks + MCP | Every prompt | Every tool use |\n| **Codex CLI** | Native hooks + MCP | Every prompt | Every tool use |\n| **Hermes** | Python MemoryProvider | Every LLM call | Every turn |\n| **Replit** | MCP only | On demand | On demand |\n\n### Configure\n\nAfter installation, add Engram to your `openclaw.json`:\n\n```jsonc\n{\n  \"plugins\": {\n    \"allow\": [\"openclaw-engram\"],\n    \"slots\": { \"memory\": \"openclaw-engram\" },\n    \"entries\": {\n      \"openclaw-engram\": {\n        \"enabled\": true,\n        \"config\": {\n          // Option 1: Use OpenAI for extraction:\n          \"openaiApiKey\": \"${OPENAI_API_KEY}\"\n\n          // Option 2: Use Engram's local LLM path (plugin mode only; no API key needed):\n          // \"localLlmEnabled\": true,\n          // \"localLlmUrl\": \"http://localhost:1234/v1\",\n          // \"localLlmModel\": \"qwen2.5-32b-instruct\"\n\n          // Option 3: Use the gateway model chain (primary path in gateway mode):\n          // \"modelSource\": \"gateway\",\n          // \"gatewayAgentId\": \"engram-llm\",\n          // \"fastGatewayAgentId\": \"engram-llm-fast\"\n        }\n      }\n    }\n  }\n}\n```\n\n\u003e **Gateway model source:** When `modelSource` is `\"gateway\"`, Engram routes all LLM calls (extraction, consolidation, reranking) through an OpenClaw agent persona's model chain instead of its own config. Extraction starts on the `gatewayAgentId` chain directly in this mode; `localLlm*` settings do not control primary extraction order. Define agent personas in `openclaw.json → agents.list[]` with a `primary` model and `fallbacks[]` array — Engram tries each in order until one succeeds. This lets you build multi-provider fallback chains like Fireworks → local LLM → cloud OpenAI. See the [Gateway Model Source](docs/config-reference.md#gateway-model-source) guide for full setup.\n\nRestart the gateway:\n\n```bash\nlaunchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway   # macOS\n# or: systemctl restart openclaw-gateway                    # Linux\n```\n\nStart a conversation — Engram begins learning immediately.\n\n\u003e **Note:** This shows only the minimal config. Engram has 60+ configuration options for search backends, capture modes, memory OS features, and more. See the [full config reference](docs/config-reference.md) for every setting.\n\n### Verify installation\n\n```bash\nopenclaw engram setup --json         # Validates config, scaffolds directories\nopenclaw engram doctor --json        # Health diagnostics with remediation hints\nopenclaw engram config-review --json # Opinionated config tuning recommendations\n```\n\n## Using Engram with Codex CLI\n\nStart the Engram HTTP server:\n\n```bash\n# Generate a token\nexport OPENCLAW_ENGRAM_ACCESS_TOKEN=\"$(openssl rand -base64 32)\"\n\n# Start the server\nopenclaw engram access http-serve \\\n  --host 127.0.0.1 \\\n  --port 4318 \\\n  --token \"$OPENCLAW_ENGRAM_ACCESS_TOKEN\"\n```\n\nAdd to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.engram]\nurl = \"http://127.0.0.1:4318/mcp\"\nbearer_token_env_var = \"OPENCLAW_ENGRAM_ACCESS_TOKEN\"\n```\n\nThat's it. Codex now has access to Engram's recall, store, and entity tools. See the [full Codex integration guide](docs/guides/codex-cli.md) for session-start hooks, cross-machine setup, and automatic recall at session start.\n\n## Using Engram with Any MCP Client\n\nRun the stdio MCP server:\n\n```bash\nopenclaw engram access mcp-serve\n```\n\nPoint your MCP client's command at `openclaw engram access mcp-serve`. Works with Claude Code, and any other MCP-compatible client. The server exposes the same tools as the HTTP endpoint.\n\n**Claude Code (MCP over HTTP):** Start the Engram HTTP server, then add to `~/.claude.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"engram\": {\n      \"url\": \"http://localhost:4318/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer ${ENGRAM_TOKEN}\"\n      }\n    }\n  }\n}\n```\n\nSee the [Standalone Server Guide](docs/guides/standalone-server.md) for multi-tenant setups and connecting multiple agent harnesses.\n\n## Standalone Usage\n\nEngram also works as a standalone tool without OpenClaw. Install and run the CLI directly:\n\n```bash\nnpm install -g @joshuaswarren/openclaw-engram\nengram init                     # create engram.config.json\nexport OPENAI_API_KEY=sk-...\nexport ENGRAM_AUTH_TOKEN=$(openssl rand -hex 32)\nengram daemon start             # start background server\nengram query \"hello\"            # verify\n```\n\nThe CLI provides 15+ commands for querying, onboarding projects, curating files, managing spaces, running benchmarks, and more. See the [full CLI reference](docs/api.md#standalone-cli-commands) for all commands.\n\n### Connect to any coding tool\n\nEngram works with 10+ coding tools via MCP or HTTP. See the [Connector Setup Guide](docs/integration/connector-setup.md) for config snippets for Claude Code, Codex CLI, Cursor, GitHub Copilot, Cline, Roo Code, Windsurf, Amp, Replit, and any generic MCP client.\n\nOpenClaw remains the recommended path for most users. The standalone CLI is useful for CI/CD pipelines, scripted memory operations, and environments without OpenClaw.\n\n### Package Architecture\n\n```\n@engram/core            — Framework-agnostic engine (re-exports orchestrator, config, storage, search, extraction, graph, trust zones)\n@engram/cli             — Standalone CLI binary (15+ commands)\n@engram/server          — Standalone HTTP/MCP server\n@engram/bench           — Benchmarks + CI regression gates\n@engram/hermes-provider — HTTP client for remote Engram instances\n```\n\n## How It Works\n\nEngram operates in three phases:\n\n```\n Recall    → Before each conversation, inject relevant memories into context\n Buffer    → After each turn, accumulate content until a trigger fires\n Extract   → Periodically, extract structured memories using an LLM\n```\n\nMemories are stored as plain markdown files with YAML frontmatter — fully portable, git-friendly, no database required:\n\n```yaml\n---\nid: decision-1738789200000-a1b2\ncategory: decision\nconfidence: 0.92\ntags: [\"architecture\", \"search\"]\n---\nDecided to use the port/adapter pattern for search backends\nso alternative engines can replace QMD without changing core logic.\n```\n\nMemory categories include: `fact`, `decision`, `preference`, `correction`, `relationship`, `principle`, `commitment`, `moment`, `skill`, `rule`, and more.\n\n## Architecture\n\nEngram is organized as a monorepo with a core engine, standalone server/CLI, and native plugins for multiple AI platforms:\n\n```\n                         ┌─────────────────┐\n                         │  @engram/core   │\n                         │  (engine)       │\n                         └────────┬────────┘\n                                  │\n        ┌──────────┬──────────┬───┴────┬──────────┬──────────┐\n        │          │          │        │          │          │\n  ┌─────┴─────┐ ┌─┴──────┐ ┌┴─────┐ ┌┴────────┐ │  Native  │\n  │ @engram/  │ │@engram/│ │engram│ │openclaw- │ │ Plugins  │\n  │ cli       │ │server  │ │hermes│ │engram    │ │          │\n  └───────────┘ └────────┘ └──────┘ └─────────┘ └──────────┘\n                    │                             │\n              ┌─────┴─────┐        ┌──────────────┼──────────┐\n              │ @engram/  │        │              │          │\n              │ bench     │   claude-code     codex     replit\n              └───────────┘\n```\n\n| Package | npm/PyPI | Description |\n|---------|----------|-------------|\n| `@engram/core` | [![npm](https://img.shields.io/npm/v/@engram/core)](https://www.npmjs.com/package/@engram/core) | Framework-agnostic engine — orchestrator, storage, search, extraction, graph, trust zones |\n| `@engram/server` | [![npm](https://img.shields.io/npm/v/@engram/server)](https://www.npmjs.com/package/@engram/server) | Standalone HTTP/MCP server with multi-token auth. Run as daemon via launchd/systemd |\n| `@engram/cli` | [![npm](https://img.shields.io/npm/v/@engram/cli)](https://www.npmjs.com/package/@engram/cli) | CLI binary — memory management, daemon lifecycle, connectors, tokens, spaces, benchmarks |\n| `@engram/hermes-provider` | [![npm](https://img.shields.io/npm/v/@engram/hermes-provider)](https://www.npmjs.com/package/@engram/hermes-provider) | TypeScript HTTP client for remote Engram instances |\n| `@engram/bench` | (private) | Latency ladder benchmarks with CI regression gates |\n| `openclaw-engram` | [![npm](https://img.shields.io/npm/v/openclaw-engram)](https://www.npmjs.com/package/openclaw-engram) | OpenClaw adapter — thin bridge (embedded or delegate mode) |\n| `engram-hermes` | [![PyPI](https://img.shields.io/pypi/v/engram-hermes)](https://pypi.org/project/engram-hermes/) | Python MemoryProvider for Hermes Agent |\n| `@engram/plugin-claude-code` | (installed via `engram connectors install`) | Native Claude Code plugin — hooks, skills, MCP |\n| `@engram/plugin-codex` | (installed via `engram connectors install`) | Native Codex CLI plugin — hooks, skills, MCP |\n\nThe `@joshuaswarren/openclaw-engram` npm package is **deprecated** — use `openclaw-engram` (for OpenClaw) or the `@engram/*` packages (for standalone/multi-platform use).\n\n## Why Engram?\n\n### Your data stays yours\n\nAll memory lives on your filesystem as plain markdown files. No cloud dependency, no subscriptions, no proprietary formats, no sending your private conversations to third-party servers. Back it up with git, rsync, or Time Machine. Move it between machines with a folder copy. You own your data completely.\n\n### A real upgrade from default OpenClaw memory\n\nOpenClaw's built-in memory is basic — it works for getting started, but lacks semantic search, entity tracking, lifecycle management, governance, and multi-agent isolation. Engram is a drop-in replacement that brings all of those capabilities while keeping the same local-first philosophy.\n\n### Smart recall, not keyword search\n\nEngram uses hybrid search (BM25 + vector + reranking via [QMD](https://github.com/tobilu/qmd)) to find semantically relevant memories. It doesn't just match keywords — it understands what you're working on and surfaces the right context.\n\n### Flexible LLM routing — OpenAI, local, or gateway model chain\n\nUse OpenAI for extraction and reranking, run entirely offline with a local LLM (Ollama, LM Studio), or route through the **gateway model chain** to use any provider with automatic fallback. The `local-llm-heavy` preset is optimized for fully local operation. See the [Local LLM Guide](docs/guides/local-llm.md) and the [Gateway Model Source](docs/config-reference.md#gateway-model-source) section for multi-provider setups.\n\n### Progressive complexity\n\nStart with zero config. Enable features as your needs grow:\n\n| Level | What You Get |\n|-------|-------------|\n| **Defaults** | Automatic extraction, recall injection, entity tracking, lifecycle management |\n| **+ Search tuning** | Choose from 6 search backends (QMD, Orama, LanceDB, Meilisearch, remote, noop) |\n| **+ Capture control** | `implicit`, `explicit`, or `hybrid` capture modes for memory write policy |\n| **+ Memory OS** | Memory boxes, graph reasoning, compounding, shared context, identity continuity |\n| **+ LCM** | Lossless Context Management — never lose conversation context to compaction |\n| **+ Parallel retrieval** | Three specialized agents (DirectFact, Contextual, Temporal) run in parallel — same latency, broader coverage |\n| **+ Advanced** | Trust zones, causal trajectories, harmonic retrieval, evaluation harness, poisoning defense |\n\nUse a preset to jump to a recommended level: `conservative`, `balanced`, `research-max`, or `local-llm-heavy`.\n\n### Works with your tools\n\n- **[OpenClaw](https://github.com/openclaw/openclaw)** — Native plugin with automatic extraction and recall injection\n- **[Codex CLI](https://github.com/openai/codex)** — MCP-over-HTTP with session-start hooks for automatic recall\n- **Any MCP client** — stdio or HTTP transport, 8 tools available\n- **Scripts \u0026 automation** — Authenticated REST API for custom integrations\n- **Local LLMs** — Run extraction and reranking with local models (Ollama, LM Studio, etc.)\n\n### Standalone Multi-Tenant Server\n\nRun Engram as a standalone HTTP server that multiple agent harnesses share. Isolate tenants with namespace policies, feed conversations from any client via the observe endpoint, and search archived history with LCM full-text search. Works with OpenClaw, Codex CLI, Claude Code, and custom HTTP agents. See the [Standalone Server Guide](docs/guides/standalone-server.md).\n\n### Built for production\n\n- **672 tests** with CI enforcement\n- **Evaluation harness** with benchmark packs, shadow recall recording, and CI delta gates\n- **Governance system** with review queues, shadow/apply modes, and reversible transitions\n- **Namespace isolation** for multi-agent deployments\n- **Rate limiting** on write paths with idempotency support\n\n## Features\n\n### Core\n\n- **Automatic memory extraction** — Facts, decisions, preferences, corrections extracted from conversations\n- **Observe endpoint** — Feed conversation messages from any agent into the extraction pipeline via HTTP or MCP\n- **Recall injection** — Relevant memories injected before each agent turn\n- **Entity tracking** — People, projects, tools, companies tracked as structured entities\n- **Lifecycle management** — Memories age through active, validated, stale, archived states\n- **Episode/Note model** — Memories classified as time-specific events or stable beliefs\n\n### Search Backends\n\n| Backend | Type | Best For |\n|---------|------|----------|\n| **QMD** (default) | Hybrid BM25+vector+reranking | Best recall quality |\n| **Orama** | Embedded, pure JS | Zero native deps |\n| **LanceDB** | Embedded, native Arrow | Large collections |\n| **Meilisearch** | Server-based | Shared search |\n| **Remote** | HTTP REST | Custom services |\n| **Noop** | No-op | Extraction only |\n\nSee the [Search Backends Guide](docs/search-backends.md) or [write your own](docs/writing-a-search-backend.md).\n\n### Memory OS (opt-in)\n\nThese capabilities can be enabled progressively:\n\n- **Memory Boxes** — Groups related memories into topic-windowed episodes\n- **Graph Recall** — Entity-relationship graph for causal and timeline queries\n- **Compounding** — Weekly synthesis surfaces patterns and recurring mistakes\n- **Shared Context** — Cross-agent memory sharing for multi-agent setups\n- **Identity Continuity** — Consistent agent personality across sessions\n- **Hot/Cold Tiering** — Automatic migration of aging memories to cold storage\n- **Memory Cache** — Process-level singleton cache for `readAllMemories()` — turns 15s disk scans into \u003c100ms cache hits, shared across all sessions\n- **Semantic Consolidation** — Finds clusters of semantically similar memories, synthesizes canonical versions via LLM, archives originals to reduce bloat\n- **Native Knowledge** — Search curated markdown (workspace docs, Obsidian vaults) without extracting into memory\n- **Behavior Loop Tuning** — Runtime self-tuning of extraction and recall parameters\n\n### Lossless Context Management (LCM)\n\nWhen your AI agent hits its context window limit, the runtime silently compresses old messages — and that context is gone forever. LCM fixes this by proactively archiving every message into a local SQLite database and building a hierarchical summary DAG (directed acyclic graph) alongside it. When context gets compacted, LCM injects compressed session history back into recall, so your agent never loses track of what happened earlier in the conversation.\n\n- **Proactive archiving** — Every message is indexed with full-text search before compaction can discard it\n- **Hierarchical summaries** — Leaf summaries cover ~8 turns, depth-1 covers ~32, depth-2 ~128, etc.\n- **Fresh tail protection** — Recent turns always use the most detailed (leaf-level) summaries\n- **Three-level summarization** — Normal LLM summary, aggressive bullet compression, and deterministic truncation (guaranteed convergence, no LLM needed)\n- **MCP expansion tools** — Agents can search, describe, or expand any part of conversation history on demand\n- **Zero data loss** — Raw messages are retained for the configured retention period (default 90 days)\n\nEnable it in your `openclaw.json`:\n\n```jsonc\n{\n  \"plugins\": {\n    \"entries\": {\n      \"openclaw-engram\": {\n        \"config\": {\n          \"lcmEnabled\": true\n          // All other LCM settings have sensible defaults\n        }\n      }\n    }\n  }\n}\n```\n\nSee the [LCM Guide](docs/guides/lossless-context-management.md) for architecture details, configuration options, and how it complements native compaction.\n\n### Parallel Specialized Retrieval (opt-in)\n\nEngram's default retrieval runs a single hybrid search pass. Parallel Specialized Retrieval (inspired by [Supermemory's ASMR technique](https://blog.supermemory.ai/we-broke-the-frontier-in-agent-memory-introducing-99-sota-memory-system/)) runs three specialized agents in parallel so total latency equals `max(agents)` not `sum(agents)`.\n\n| Agent | What It Does | Cost |\n|-------|-------------|------|\n| **DirectFact** | Scans entity filenames for keyword overlap with the query | File I/O only, \u003c5ms |\n| **Contextual** | Existing hybrid BM25+vector search (unchanged) | Same as current |\n| **Temporal** | Reads the temporal date index, returns recent memories with recency decay scoring | File I/O + math, \u003c10ms |\n\n**Zero additional LLM cost.** The DirectFact and Temporal agents reuse existing indexes with no new embeddings or inference. The Contextual agent is the same hybrid search already running.\n\nResults from all three agents are merged by path, deduplicated, and weighted (`direct=1.0×, temporal=0.85×, contextual=0.7×`) before returning the top N results. Any agent error degrades gracefully without blocking the others.\n\nEnable it in your `openclaw.json`:\n\n```jsonc\n{\n  \"plugins\": {\n    \"entries\": {\n      \"openclaw-engram\": {\n        \"config\": {\n          \"parallelRetrievalEnabled\": true\n          // Optional tuning:\n          // \"parallelMaxResultsPerAgent\": 20,\n          // \"parallelAgentWeights\": { \"direct\": 1.0, \"contextual\": 0.7, \"temporal\": 0.85 }\n        }\n      }\n    }\n  }\n}\n```\n\nSet `parallelMaxResultsPerAgent: 0` to disable an individual agent's results without disabling the feature entirely.\n\n### Semantic Consolidation (opt-in)\n\nOver time, memory stores accumulate redundant facts — the same information extracted multiple times across sessions, expressed slightly differently. Semantic consolidation finds clusters of similar memories using token overlap, synthesizes a single canonical version via LLM, and archives the originals. This reduces storage bloat, speeds up recall, and improves memory quality.\n\n- **Conservative by default** — Only merges when 80%+ token overlap is detected across 3+ memories\n- **LLM synthesis** — Uses your configured model to combine unique information from all cluster members\n- **Safe archival** — Originals are archived (not deleted) with full provenance tracking\n- **Configurable** — Adjust threshold, cluster size, excluded categories, model, and schedule\n- **Excluded categories** — Corrections and commitments are never consolidated (configurable)\n\nEnable it in your `openclaw.json`:\n\n```jsonc\n{\n  \"plugins\": {\n    \"entries\": {\n      \"openclaw-engram\": {\n        \"config\": {\n          \"semanticConsolidationEnabled\": true\n          // Optional tuning:\n          // \"semanticConsolidationThreshold\": 0.8,    // 0.8=conservative, 0.6=aggressive\n          // \"semanticConsolidationModel\": \"fast\",      // \"auto\", \"fast\", or specific model\n          // \"semanticConsolidationIntervalHours\": 168, // weekly (default)\n          // \"semanticConsolidationMaxPerRun\": 100\n        }\n      }\n    }\n  }\n}\n```\n\nRun manually from the CLI:\n\n```bash\nopenclaw engram semantic-consolidate --dry-run    # Preview what would be merged\nopenclaw engram semantic-consolidate --verbose     # Run with detailed output\nopenclaw engram semantic-consolidate --threshold 0.6  # Override threshold\n```\n\n### Advanced (opt-in)\n\n- **Objective-State Recall** — Surfaces file/process/tool state snapshots alongside semantic memory\n- **Causal Trajectories** — Typed `goal -\u003e action -\u003e observation -\u003e outcome` chains\n- **Trust Zones** — Quarantine/working/trusted tiers with promotion rules and poisoning defense\n- **Harmonic Retrieval** — Blends abstraction nodes with cue-anchor matches\n- **Verified Recall** — Only surfaces memory boxes whose source memories still verify\n- **Semantic Rule Promotion** — Promotes `IF ... THEN` rules from verified episodes\n- **Creation Memory** — Work-product ledger tracking agent outputs\n- **Commitment Lifecycle** — Tracks promises, deadlines, and obligations\n- **Resume Bundles** — Crash-recovery context for interrupted sessions\n- **Utility Learning** — Learns promotion/ranking weights from downstream outcomes\n\nSee [Enable All Features](docs/enable-all-v8.md) for a full-feature config profile.\n\n## Access Layer\n\nEngram exposes one shared service layer through multiple transports:\n\n### HTTP API\n\n```bash\nopenclaw engram access http-serve --token \"$OPENCLAW_ENGRAM_ACCESS_TOKEN\"\n```\n\nKey endpoints: `GET /engram/v1/health`, `POST /engram/v1/recall`, `POST /engram/v1/memories`, `GET /engram/v1/entities/:name`, and more. Full reference in [API docs](docs/api.md).\n\nThe HTTP server also hosts a lightweight operator UI at `http://127.0.0.1:4318/engram/ui/` for memory browsing, recall inspection, governance review, trust-zone promotion, and entity exploration.\n\n### MCP Tools\n\nAvailable via both stdio and HTTP transports:\n\n| Tool | Purpose |\n|------|---------|\n| `engram.recall` | Retrieve relevant memories for a query |\n| `engram.recall_explain` | Debug the last recall |\n| `engram.day_summary` | Generate structured end-of-day summary from memory content |\n| `engram.memory_get` | Fetch a specific memory by ID |\n| `engram.memory_timeline` | View a memory's lifecycle history |\n| `engram.memory_store` | Store a new memory |\n| `engram.suggestion_submit` | Queue a memory for review |\n| `engram.entity_get` | Look up a known entity |\n| `engram.review_queue_list` | View the governance review queue |\n| `engram.observe` | Feed conversation messages into memory pipeline (LCM + extraction) |\n| `engram.lcm_search` | Full-text search over LCM-archived conversations |\n| `engram_context_search` | Full-text search across all archived conversation history (LCM) |\n| `engram_context_describe` | Get a compressed summary of a turn range (LCM) |\n| `engram_context_expand` | Retrieve raw lossless messages for a turn range (LCM) |\n\n### MCP over HTTP\n\nThe HTTP server exposes an MCP JSON-RPC endpoint at `POST /mcp`, allowing remote MCP clients to use Engram tools over HTTP:\n\n```bash\nopenclaw engram access http-serve --host 0.0.0.0 --port 4318 --token \"$TOKEN\"\n```\n\nFor namespace-enabled deployments, pass `--principal \u003cname\u003e` where `\u003cname\u003e` matches a `writePrincipals` entry for your target namespace. Deployments with `namespacesEnabled: false` (the default) do not need `--principal`.\n\n## CLI Reference\n\n```bash\n# Setup \u0026 diagnostics\nopenclaw engram setup              # Guided first-run setup\nopenclaw engram doctor             # Health diagnostics with remediation hints\nopenclaw engram config-review      # Config tuning recommendations\nopenclaw engram stats              # Memory counts, search status\nopenclaw engram inventory          # Full storage and namespace inventory\n\n# Search \u0026 recall\nopenclaw engram search \"query\"     # Search memories from CLI\nopenclaw engram harmonic-search \"query\"  # Preview harmonic retrieval matches\n\n# Governance\nopenclaw engram governance-run --mode shadow  # Preview governance transitions\nopenclaw engram governance-run --mode apply   # Apply reversible transitions\nopenclaw engram review-disposition \u003cid\u003e --status rejected  # Operator review\n\n# Benchmarking\nopenclaw engram benchmark recall   # Benchmark status and validation\nopenclaw engram benchmark-ci-gate  # CI gate for regressions\n\n# Memory maintenance\nopenclaw engram consolidate                  # Run standard consolidation\nopenclaw engram semantic-consolidate         # Run semantic dedup consolidation\nopenclaw engram semantic-consolidate --dry-run  # Preview without changes\n\n# Access layer\nopenclaw engram access http-serve --token \"$TOKEN\"  # Start HTTP API\nopenclaw engram access mcp-serve   # Start stdio MCP server\n\n# Trust-zone demos\nopenclaw engram trust-zone-demo-seed --dry-run       # Preview the opt-in buyer demo dataset\nopenclaw engram trust-zone-demo-seed                 # Explicitly seed the demo dataset\nopenclaw engram trust-zone-promote --record-id \u003cid\u003e --target-zone working --reason \"Operator review\"\n```\n\n### Trust-zone demo workflow\n\nTrust zones now ship with a dedicated admin-console view plus an explicit demo seeding path for buyer-facing walkthroughs.\n\n- **Never automatic** — Engram does not seed sample trust-zone records on install, startup, or feature enablement.\n- **Explicit only** — demo records appear only after you run `openclaw engram trust-zone-demo-seed` or trigger the matching admin-console action.\n- **Buyer-friendly story** — the trust-zone view surfaces provenance strength, promotion readiness, corroboration requirements, and operator promotion actions in one place.\n\nThe seeded scenario is `enterprise-buyer-v1`, which creates a small, opinionated dataset covering:\n\n- quarantine records that are ready for review\n- working records that are blocked on missing provenance\n- working records that still need corroboration\n- working records with independent corroboration support\n- a trusted operator policy record\n\nSee the [full CLI reference](docs/api.md#cli-commands) for all commands.\n\n## Configuration\n\nAll settings live in `openclaw.json` under `plugins.entries.openclaw-engram.config`. The table below shows the most commonly changed settings — Engram has **60+ configuration options** covering search backends, capture modes, memory OS features, namespaces, governance, benchmarking, and more.\n\n| Setting | Default | Description |\n|---------|---------|-------------|\n| `openaiApiKey` | `(env)` | OpenAI API key (optional when using a local LLM) |\n| `localLlmEnabled` | `false` | Enable Engram's local LLM path when `modelSource` is `plugin` |\n| `localLlmUrl` | unset | Local LLM endpoint (e.g., `http://localhost:1234/v1`) |\n| `localLlmModel` | unset | Local model name (e.g., `qwen2.5-32b-instruct`) |\n| `model` | `gpt-5.2` | OpenAI model for extraction when `modelSource` is `plugin` and local LLM is disabled |\n| `searchBackend` | `\"qmd\"` | Search engine: `qmd`, `orama`, `lancedb`, `meilisearch`, `remote`, `noop` |\n| `captureMode` | `implicit` | Memory write policy: `implicit`, `explicit`, `hybrid` |\n| `recallBudgetChars` | `maxMemoryTokens * 4` | Recall budget (default ~8K chars; set 64K+ for large-context models) |\n| `memoryDir` | `~/.openclaw/workspace/memory/local` | Memory storage root |\n| `memoryOsPreset` | unset | Quick config: `conservative`, `balanced`, `research-max`, `local-llm-heavy` |\n| `lcmEnabled` | `false` | Enable Lossless Context Management (proactive session archive + summary DAG) |\n| `semanticConsolidationEnabled` | `false` | Enable periodic semantic dedup of similar memories |\n| `semanticConsolidationThreshold` | `0.8` | Token overlap threshold (0.8=conservative, 0.6=aggressive) |\n| `semanticConsolidationModel` | `\"auto\"` | LLM for synthesis: `\"auto\"`, `\"fast\"`, or specific model |\n\n**[See the full config reference for all 60+ settings](docs/config-reference.md)** including search backend configuration, namespace policies, Memory OS features, governance, evaluation harness, trust zones, causal trajectories, and more.\n\n## Documentation\n\n- [Getting Started](docs/getting-started.md) — Installation, setup, first-run verification\n- [Config Reference](docs/config-reference.md) — Every setting with defaults\n- [Architecture Overview](docs/architecture/overview.md) — System design and storage layout\n- [Retrieval Pipeline](docs/architecture/retrieval-pipeline.md) — How recall works\n- [Memory Lifecycle](docs/architecture/memory-lifecycle.md) — Write, consolidation, expiry\n- [Search Backends](docs/search-backends.md) — Choosing and configuring search engines\n- [Writing a Search Backend](docs/writing-a-search-backend.md) — Build your own adapter\n- [API Reference](docs/api.md) — HTTP, MCP, and CLI documentation\n- [Codex CLI Integration](docs/guides/codex-cli.md) — Setup Engram with OpenAI's Codex\n- [Standalone Server Guide](docs/guides/standalone-server.md) — Multi-tenant HTTP server for multiple agent harnesses\n- [Local LLM Guide](docs/guides/local-llm.md) — Local-first extraction and reranking\n- [Cost Control Guide](docs/guides/cost-control.md) — Budget mappings and presets\n- [Namespaces](docs/namespaces.md) — Multi-agent memory isolation\n- [Shared Context](docs/shared-context.md) — Cross-agent intelligence\n- [Identity Continuity](docs/identity-continuity.md) — Consistent agent personality\n- [Graph Reasoning](docs/architecture/graph-reasoning.md) — Opt-in graph traversal\n- [Evaluation Harness](docs/evaluation-harness.md) — Benchmarks and CI delta gates\n- [Operations](docs/operations.md) — Backup, export, maintenance\n- [Lossless Context Management](docs/guides/lossless-context-management.md) — Never lose context to compaction\n- [Enable All Features](docs/enable-all-v8.md) — Full-feature config profile\n- [Migration Guide](docs/guides/migrations.md) — Upgrading from older versions\n- [Platform Migration Guide](docs/guides/platform-migration.md) — Migrating to the monorepo architecture (v9.1.36+)\n- [Hermes Setup](docs/integration/hermes-setup.md) — HTTP client for remote Engram instances\n- [Deployment Topologies](docs/integration/deployment-topologies.md) — Localhost, LAN, remote, containerized, standalone\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feat/my-feature`)\n3. Write tests for new functionality\n4. Ensure `npm test` (672 tests) and `npm run check-types` pass\n5. Submit a pull request\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshuaswarren%2Fopenclaw-engram","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoshuaswarren%2Fopenclaw-engram","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshuaswarren%2Fopenclaw-engram/lists"}