OpenClaw Memory Stack#

Total recall. 90% fewer tokens.

Your 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.

Free and open source. MIT license. No subscription, no cloud API costs. All search and storage runs entirely on your machine. GitHub: github.com/Apptah/openclaw-memory-stack

Architecture#

text

┌──────────────────────────────────────────────────────────────┐
│                  OPENCLAW MEMORY STACK                        │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  SEARCH PIPELINE (runs on every conversation turn)           │
│                                                              │
│  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐               │
│  │  E1  │ │  E2  │ │  E3  │ │  E4  │ │  E5  │               │
│  │ Full │ │Vector│ │ DAG  │ │ Fact │ │  MD  │               │
│  │ Text │ │Search│ │Compr.│ │Store │ │Files │               │
│  └──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘               │
│     └────────┴────────┴────────┴────────┘                    │
│                        │                                     │
│                        ▼                                     │
│               ┌──────────────┐                               │
│               │ Result Fusion│                               │
│               │ + Reranking  │                               │
│               └──────────────┘                               │
│                        │                                     │
│              ┌─────────┼─────────┐                           │
│              ▼         ▼         ▼                           │
│          ┌──────┐  ┌──────┐  ┌──────┐                        │
│          │  L0  │  │  L1  │  │  L2  │  Token Budget           │
│          │~100t │  │~800t │  │ full │  Control                │
│          └──────┘  └──────┘  └──────┘                        │
│                                                              │
│  CAPTURE (runs after every conversation turn)                │
│                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐        │
│  │    Fact       │  │   Entity     │  │   Dedup &    │        │
│  │  Extraction   │  │  Tracking    │  │  Supersede   │        │
│  │  (8 types)    │  │  (queryable) │  │  (3-level)   │        │
│  └──────────────┘  └──────────────┘  └──────────────┘        │
│                                                              │
│  CROSS-AGENT SHARING                                         │
│                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐        │
│  │   CLI API    │  │  Drop Zone   │  │   Unified    │        │
│  │ query/add/   │  │  ~/.openclaw │  │   Global     │        │
│  │   recent     │  │  /external/  │  │   Memory     │        │
│  └──────────────┘  └──────────────┘  └──────────────┘        │
│         ▲                 ▲                 ▲                 │
│  Claude Code       Cursor / Windsurf    Any MCP client       │
│                                                              │
│  SELF-HEALING MAINTENANCE (24h cycle, zero config)           │
│                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐        │
│  │  Auto-Init   │  │   Graceful   │  │   Health     │        │
│  │  workspace   │  │   Fallback   │  │   Monitor    │        │
│  │  + indexing   │  │  FTS5-only   │  │  + alerting  │        │
│  └──────────────┘  └──────────────┘  └──────────────┘        │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Built-in Code Search#

Find 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.

5-Engine Search#

Five engines search in parallel on every conversation turn:

EngineWhat it doesFull-textKeyword matching with relevance rankingVectorSemantic search — understands meaning, not just wordsCompressed historyConversation DAG with drill-downFact storeStructured facts — decisions, deadlines, requirementsMarkdownScans memory files directly

Results are merged with rank fusion, deduplicated, reranked for diversity, and scored with time decay.

3-Tier Token Control#

Every wasted token is money burned. Memory Stack eliminates the waste.

TierTokensWhen usedL0100Auto-recall every turn — minimal costL1800On-demand search summaryL2fullFull content on request

The agent generates summaries — no separate LLM service required.

When the OpenClaw agent stores or surfaces a memory, it should also produce L0/L1 summaries from its own context (it is already an LLM) and persist them via:

bash

openclaw-memory tier set <file> \
  --l0 "<one-sentence abstract, ≤100 tokens>" \
  --l1 "<focused overview, ≤800 tokens, covers what + why + when to use>"

Read back at any tier:

bash

openclaw-memory tier show <file> --level L0   # or L1, L2

For unattended/offline contexts where no agent is available, fall back to a pure heuristic (first non-empty line for L0, char-bounded prefix for L1):

bash

openclaw-memory tier auto <file>

Structured Fact Memory#

Extracts 8 fact types automatically: decisions, deadlines, requirements, entities, preferences, workflows, relationships, corrections.

• Structured key/value storage with confidence scores
• Negation-aware — "We will NOT use MongoDB" preserved correctly
• Automatic supersede — when a fact changes, old version archived, new one takes over

Smart Dedup & Conflict Resolution#

• 3-level write-time dedup: exact match, normalized text, structured key match
• Full audit trail via archive table
• Removes duplicates before sending — you never pay twice for the same memory

Cross-Agent Memory Sharing#

Works across Claude Code, Cursor, Windsurf, and any MCP-compatible client.

• CLI commands: openclaw-memory query/add/recent — any tool can read/write facts
• Drop zone: drop .md files into ~/.openclaw/memory/external/ — auto-ingested, no duplicates
• Unified global memory under ~/.openclaw/memory/ — your memory follows you across workspaces

Self-Healing Maintenance#

Zero maintenance. The plugin takes care of itself.

• Auto-init: detects workspace, creates search index, schedules embedding — no manual setup
• Graceful fallback: if vector search unavailable, runs in keyword-only mode — always functional
• 24h maintenance cycle: rebuilds index on corruption, archives stale facts, alerts on health issues

OpenClaw Native vs Memory Stack#

NativeMemory StackSearch engines25 (parallel, fused)Token efficiencyFull text every timeUp to 90% fewerOutput tiersFull text3 tiers (~100 / ~800 / full)Fact extractionNo8 types, structured, negation-awareDuplicate handlingCan pay twice3-level dedup, auto-supersedeEntity trackingNoYes, queryableCross-agentNoCLI + drop zone, works with any toolMemory across projectsSeparate per workspaceUnified global memory — follows you everywhereSelf-healingNoAuto-maintain, auto-fallbackRuns locallyYesYes — all search runs locally, no cloud dependency

Memory Stack vs Other AI Memory Systems#

Most AI memory systems make you choose between control and convenience. Memory Stack doesn't.

Hermes AgentGoogle Always-OnMemory StackTriggerExplicit tool callAutomatic (Google decides)Deterministic router — 7 explicit rulesRouting logicAgent judgment (opaque)Black boxKeyword pattern matching — fully inspectableFallback on poor recallNoneUncontrollableSequential chain — relevance < 0.4 → next backendStorage locationDeveloper-managed DBGoogle cloudLocal git branch + SQLite — nothing leaves your machineToken controlNoneNone3 tiers: ~100 / ~800 / fullDeduplicationManualUnknown4-level auto-dedupWorks offlineDepends on DBNoYes — core search fully offlineOpen sourceVariesNoMIT — full source on GitHubSetup timeHoursMinutes (Gemini only)One command, any MCP client

Hermes gives developers control but no routing or fallback infrastructure. Google gives convenience but no privacy and no control. Memory Stack gives you both.

Install#

bash

npx clawhub@latest package install openclaw-memory-stack

Or clone and run directly:

bash

git clone https://github.com/Apptah/openclaw-memory-stack
cd openclaw-memory-stack
./install.sh

Runs on macOS, Linux, and Windows (WSL2). Requires bash, python3, and OpenClaw 2026.3.2 or later. Bun is optional (enables QMD vector search).

What the installer does#

The included install.sh performs the following actions:

• Files: Copies plugin and backend files to ~/.openclaw/memory-stack/, registers plugin in ~/.openclaw/extensions/openclaw-memory-stack/, updates ~/.openclaw/openclaw.json
• Upgrade downloads: install.sh --upgrade downloads new versions with mandatory SHA-256 checksum verification
• No telemetry: No usage data, memory content, or analytics are ever sent
• 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

All search and storage runs entirely on your machine.

License#

MIT. Free and open source. See LICENSE.

Support#

Questions or issues? Open a GitHub issue at github.com/Apptah/openclaw-memory-stack.