{"skill":{"slug":"openclaw-memory-stack","displayName":"Openclaw Memory Stack","summary":"Total recall, 90% fewer tokens. Open source OpenClaw memory plugin — 5-engine local search, structured fact extraction, smart dedup, cross-agent sharing, and...","description":"---\nname: openclaw-memory-stack\ndescription: \"Total recall, 90% fewer tokens. Open source OpenClaw memory plugin — 5-engine local search, structured fact extraction, smart dedup, cross-agent sharing, and self-healing. Replace native memory with something that actually remembers. No cloud API, no subscription, MIT licensed and free.\"\nversion: \"0.6.1\"\nlicense: mit\nmetadata:\n  openclaw:\n    requires:\n      bins:\n        - bash\n        - python3\n        - sqlite3\n      anyBins:\n        - bun\n        - qmd\n    emoji: \"\\U0001F9E0\"\n    homepage: https://github.com/Apptah/openclaw-memory-stack\n    tags:\n      - memory\n      - search\n      - rag\n      - vector-search\n      - code-search\n      - knowledge-management\n      - fact-extraction\n      - entity-tracking\n      - token-savings\n      - long-term-memory\n      - context-window\n      - recall\n      - local\n      - offline\n      - dedup\n      - persistence\n    pricing:\n      model: free\n      amount: 0\n      currency: usd\n      url: https://github.com/Apptah/openclaw-memory-stack\n      note: \"Free and open source under MIT license. No activation, no cloud dependency.\"\n    network:\n      - host: openclaw-api.apptah.com\n        purpose: \"Update check on manual upgrade. Sends only current_version.\"\n      - host: localhost:8080\n        purpose: \"Local MLX LLM for fact extraction. Never leaves machine.\"\n      - host: localhost:11434\n        purpose: \"Local Ollama LLM for fact extraction. Never leaves machine.\"\n      - host: api.openai.com\n        purpose: \"Cloud LLM fallback for fact extraction. Only active if user sets API key. User-configurable endpoint.\"\n    permissions:\n      shell:\n        - binary: sqlite3\n          purpose: \"Local database read/write for all 5 search engines. No arbitrary command execution.\"\n        - binary: qmd\n          purpose: \"QMD CLI for vector search and collection management.\"\n      fileAccess:\n        read: [\"~/.openclaw/memory-stack/\", \"~/.openclaw/memory/external/\", \".openclaw/\"]\n        write: [\"~/.openclaw/memory-stack/\", \"~/.openclaw/memory/\"]\n    envVars:\n      - name: OPENCLAW_LLM_API_KEY\n        purpose: \"API key for cloud LLM fact extraction (optional)\"\n        sentTo: \"user-configured llmEndpoint only\"\n      - name: OPENAI_API_KEY\n        purpose: \"Fallback API key for OpenAI (optional)\"\n        sentTo: \"api.openai.com or user-configured llmEndpoint\"\n      - name: OPENCLAW_LCM_DB\n        purpose: \"Override lossless DB path (local only)\"\n      - name: OPENCLAW_ROUTER_CONFIG\n        purpose: \"Override router config path (local only)\"\n      - name: OPENCLAW_BACKENDS_JSON\n        purpose: \"Override backends config path (local only)\"\n    dataFlow:\n      localOnly: \"All search/storage (5 engines, sqlite3, markdown) runs on-device. Shell execution targets only local databases.\"\n      remote: \"LLM extraction sends conversation excerpts to user-configured endpoint only. No license verification, no activation keys.\"\n      neverTransmitted: \"Raw memory content never sent to apptah.com. No telemetry or analytics.\"\n---\n\n# OpenClaw Memory Stack\n\n**Total recall. 90% fewer tokens.**\n\nYour agent forgets past decisions and burns tokens re-reading the same context. Memory Stack runs 5 search engines locally, returns only what matters, and never loses a fact.\n\n> **Free and open source. MIT license.** No subscription, no cloud API costs.\n> All search and storage runs entirely on your machine.\n> GitHub: [github.com/Apptah/openclaw-memory-stack](https://github.com/Apptah/openclaw-memory-stack)\n\n## Architecture\n\n```\n┌──────────────────────────────────────────────────────────────┐\n│                  OPENCLAW MEMORY STACK                        │\n├──────────────────────────────────────────────────────────────┤\n│                                                              │\n│  SEARCH PIPELINE (runs on every conversation turn)           │\n│                                                              │\n│  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐               │\n│  │  E1  │ │  E2  │ │  E3  │ │  E4  │ │  E5  │               │\n│  │ Full │ │Vector│ │ DAG  │ │ Fact │ │  MD  │               │\n│  │ Text │ │Search│ │Compr.│ │Store │ │Files │               │\n│  └──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘               │\n│     └────────┴────────┴────────┴────────┘                    │\n│                        │                                     │\n│                        ▼                                     │\n│               ┌──────────────┐                               │\n│               │ Result Fusion│                               │\n│               │ + Reranking  │                               │\n│               └──────────────┘                               │\n│                        │                                     │\n│              ┌─────────┼─────────┐                           │\n│              ▼         ▼         ▼                           │\n│          ┌──────┐  ┌──────┐  ┌──────┐                        │\n│          │  L0  │  │  L1  │  │  L2  │  Token Budget           │\n│          │~100t │  │~800t │  │ full │  Control                │\n│          └──────┘  └──────┘  └──────┘                        │\n│                                                              │\n│  CAPTURE (runs after every conversation turn)                │\n│                                                              │\n│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐        │\n│  │    Fact       │  │   Entity     │  │   Dedup &    │        │\n│  │  Extraction   │  │  Tracking    │  │  Supersede   │        │\n│  │  (8 types)    │  │  (queryable) │  │  (3-level)   │        │\n│  └──────────────┘  └──────────────┘  └──────────────┘        │\n│                                                              │\n│  CROSS-AGENT SHARING                                         │\n│                                                              │\n│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐        │\n│  │   CLI API    │  │  Drop Zone   │  │   Unified    │        │\n│  │ query/add/   │  │  ~/.openclaw │  │   Global     │        │\n│  │   recent     │  │  /external/  │  │   Memory     │        │\n│  └──────────────┘  └──────────────┘  └──────────────┘        │\n│         ▲                 ▲                 ▲                 │\n│  Claude Code       Cursor / Windsurf    Any MCP client       │\n│                                                              │\n│  SELF-HEALING MAINTENANCE (24h cycle, zero config)           │\n│                                                              │\n│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐        │\n│  │  Auto-Init   │  │   Graceful   │  │   Health     │        │\n│  │  workspace   │  │   Fallback   │  │   Monitor    │        │\n│  │  + indexing   │  │  FTS5-only   │  │  + alerting  │        │\n│  └──────────────┘  └──────────────┘  └──────────────┘        │\n│                                                              │\n└──────────────────────────────────────────────────────────────┘\n```\n\n## Built-in Code Search\n\nFind function names, variable names, or any pattern across your entire memory — instantly. No extra tools needed, works offline, gets faster the more you use it.\n\n## 5-Engine Search\n\nFive engines search in parallel on every conversation turn:\n\n| Engine | What it does |\n|--------|-------------|\n| Full-text | Keyword matching with relevance ranking |\n| Vector | Semantic search — understands meaning, not just words |\n| Compressed history | Conversation DAG with drill-down |\n| Fact store | Structured facts — decisions, deadlines, requirements |\n| Markdown | Scans memory files directly |\n\nResults are merged with rank fusion, deduplicated, reranked for diversity, and scored with time decay.\n\n## 3-Tier Token Control\n\nEvery wasted token is money burned. Memory Stack eliminates the waste.\n\n| Tier | Tokens | When used |\n|------|--------|-----------|\n| L0 | ~100 | Auto-recall every turn — minimal cost |\n| L1 | ~800 | On-demand search summary |\n| L2 | full | Full content on request |\n\n**The agent generates summaries — no separate LLM service required.**\n\nWhen the OpenClaw agent stores or surfaces a memory, it should also produce L0/L1\nsummaries from its own context (it is already an LLM) and persist them via:\n\n```bash\nopenclaw-memory tier set <file> \\\n  --l0 \"<one-sentence abstract, ≤100 tokens>\" \\\n  --l1 \"<focused overview, ≤800 tokens, covers what + why + when to use>\"\n```\n\nRead back at any tier:\n\n```bash\nopenclaw-memory tier show <file> --level L0   # or L1, L2\n```\n\nFor unattended/offline contexts where no agent is available, fall back to a pure\nheuristic (first non-empty line for L0, char-bounded prefix for L1):\n\n```bash\nopenclaw-memory tier auto <file>\n```\n\n## Structured Fact Memory\n\nExtracts 8 fact types automatically: decisions, deadlines, requirements, entities, preferences, workflows, relationships, corrections.\n\n- Structured key/value storage with confidence scores\n- Negation-aware — \"We will NOT use MongoDB\" preserved correctly\n- Automatic supersede — when a fact changes, old version archived, new one takes over\n\n## Smart Dedup & Conflict Resolution\n\n- 3-level write-time dedup: exact match, normalized text, structured key match\n- Full audit trail via archive table\n- Removes duplicates before sending — you never pay twice for the same memory\n\n## Cross-Agent Memory Sharing\n\nWorks across Claude Code, Cursor, Windsurf, and any MCP-compatible client.\n\n- CLI commands: `openclaw-memory query/add/recent` — any tool can read/write facts\n- Drop zone: drop `.md` files into `~/.openclaw/memory/external/` — auto-ingested, no duplicates\n- Unified global memory under `~/.openclaw/memory/` — your memory follows you across workspaces\n\n## Self-Healing Maintenance\n\nZero maintenance. The plugin takes care of itself.\n\n- Auto-init: detects workspace, creates search index, schedules embedding — no manual setup\n- Graceful fallback: if vector search unavailable, runs in keyword-only mode — always functional\n- 24h maintenance cycle: rebuilds index on corruption, archives stale facts, alerts on health issues\n\n## OpenClaw Native vs Memory Stack\n\n| | Native | Memory Stack |\n|---|--------|-------------|\n| Search engines | 2 | 5 (parallel, fused) |\n| Token efficiency | Full text every time | Up to 90% fewer |\n| Output tiers | Full text | 3 tiers (~100 / ~800 / full) |\n| Fact extraction | No | 8 types, structured, negation-aware |\n| Duplicate handling | Can pay twice | 3-level dedup, auto-supersede |\n| Entity tracking | No | Yes, queryable |\n| Cross-agent | No | CLI + drop zone, works with any tool |\n| Memory across projects | Separate per workspace | Unified global memory — follows you everywhere |\n| Self-healing | No | Auto-maintain, auto-fallback |\n| Runs locally | Yes | Yes — all search runs locally, no cloud dependency |\n\n## Memory Stack vs Other AI Memory Systems\n\nMost AI memory systems make you choose between control and convenience. Memory Stack doesn't.\n\n| | Hermes Agent | Google Always-On | Memory Stack |\n|---|---|---|---|\n| **Trigger** | Explicit tool call | Automatic (Google decides) | Deterministic router — 7 explicit rules |\n| **Routing logic** | Agent judgment (opaque) | Black box | Keyword pattern matching — fully inspectable |\n| **Fallback on poor recall** | None | Uncontrollable | Sequential chain — relevance < 0.4 → next backend |\n| **Storage location** | Developer-managed DB | Google cloud | Local git branch + SQLite — nothing leaves your machine |\n| **Token control** | None | None | 3 tiers: ~100 / ~800 / full |\n| **Deduplication** | Manual | Unknown | 4-level auto-dedup |\n| **Works offline** | Depends on DB | No | Yes — core search fully offline |\n| **Open source** | Varies | No | MIT — full source on GitHub |\n| **Setup time** | Hours | Minutes (Gemini only) | One command, any MCP client |\n\nHermes gives developers control but no routing or fallback infrastructure. Google gives convenience but no privacy and no control. Memory Stack gives you both.\n\n## Install\n\n```bash\nnpx clawhub@latest package install openclaw-memory-stack\n```\n\nOr clone and run directly:\n\n```bash\ngit clone https://github.com/Apptah/openclaw-memory-stack\ncd openclaw-memory-stack\n./install.sh\n```\n\nRuns on macOS, Linux, and Windows (WSL2). Requires bash, python3, and OpenClaw 2026.3.2 or later. Bun is optional (enables QMD vector search).\n\n## What the installer does\n\nThe included `install.sh` performs the following actions:\n\n- **Files**: Copies plugin and backend files to `~/.openclaw/memory-stack/`, registers plugin in `~/.openclaw/extensions/openclaw-memory-stack/`, updates `~/.openclaw/openclaw.json`\n- **Upgrade downloads**: `install.sh --upgrade` downloads new versions with mandatory SHA-256 checksum verification\n- **No telemetry**: No usage data, memory content, or analytics are ever sent\n- **Optional LLM**: `OPENCLAW_LLM_API_KEY` / `OPENAI_API_KEY` env vars are optional, used only for LLM-powered fact extraction. If not set, falls back to local Ollama/MLX. These keys are sent only to the endpoint you configure (default: api.openai.com), never to our servers\n\nAll search and storage runs entirely on your machine.\n\n## License\n\nMIT. Free and open source. See [LICENSE](https://github.com/Apptah/openclaw-memory-stack/blob/main/LICENSE).\n\n## Support\n\nQuestions or issues? Open a GitHub issue at [github.com/Apptah/openclaw-memory-stack](https://github.com/Apptah/openclaw-memory-stack/issues).\n","tags":{"code-search":"0.6.1","context-window":"0.6.1","dedup":"0.6.1","early-bird":"0.6.1","entity-tracking":"0.6.1","fact-extraction":"0.6.1","free":"0.6.1","knowledge-graph":"0.6.1","knowledge-management":"0.6.1","latest":"0.6.1","local":"0.6.1","long-term-memory":"0.6.1","memory":"0.6.1","offline":"0.6.1","persistence":"0.6.1","rag":"0.6.1","recall":"0.6.1","search":"0.6.1","token-savings":"0.6.1","vector-search":"0.6.1"},"stats":{"comments":0,"downloads":717,"installsAllTime":1,"installsCurrent":1,"stars":1,"versions":40},"createdAt":1774150335574,"updatedAt":1779078828906},"latestVersion":{"version":"0.6.1","createdAt":1777452519417,"changelog":"v0.6.1 — Security: defense-in-depth SQL escape on chunk_id and hash in plugin/lib/ngram.mjs. WSL2: multi-signal detection (kernel >=5, /run/WSL, WSLInterop-late, or explicit WSL2 suffix); WSL1 refused; warn on /mnt/c paths; install_bun() now invoked on fresh systems. Upgrade fix: ${ENCODED_EMAIL:-} so --upgrade no longer aborts under set -u. child_process usage remains bounded to local sqlite3 + qmd, declared in openclaw.plugin.json.","license":"MIT-0"},"metadata":{"setup":[{"key":"OPENCLAW_LLM_API_KEY","required":true},{"key":"OPENAI_API_KEY","required":true},{"key":"OPENCLAW_LCM_DB","required":true},{"key":"OPENCLAW_ROUTER_CONFIG","required":true},{"key":"OPENCLAW_BACKENDS_JSON","required":true}],"os":null,"systems":null},"owner":{"handle":"apptah","userId":"s170xd9yydt52xyh9fz43m12f983h58c","displayName":"Apptah","image":"https://avatars.githubusercontent.com/u/243065487?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1780090583191}}