# ClawMem > On-device memory layer for AI agents. Claude Code, Hermes and OpenClaw. Hooks + MCP server + hybrid RAG search. - **Type:** MCP server - **Install:** `agentstack add mcp-yoloshii-clawmem` - **Verified:** Pending review - **Seller:** [yoloshii](https://agentstack.voostack.com/s/yoloshii) - **Installs:** 0 - **Category:** [Databases](https://agentstack.voostack.com/c/databases) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [yoloshii](https://github.com/yoloshii) - **Source:** https://github.com/yoloshii/ClawMem ## Install ```sh agentstack add mcp-yoloshii-clawmem ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # ClawMem — On-device memory layer for Claude Code, OpenClaw, and Hermes agents **On-device memory for Claude Code, OpenClaw, Hermes, and AI agents.** Retrieval-augmented search, hooks, and an MCP server in a single local system. No API keys, no cloud dependencies. ClawMem fuses recent research into a retrieval-augmented memory layer that agents actually use. The hybrid architecture combines [QMD](https://github.com/tobi/qmd)-derived multi-signal retrieval (BM25 + vector search + reciprocal rank fusion + query expansion + cross-encoder reranking), [SAME](https://github.com/sgx-labs/statelessagent)-inspired composite scoring (recency decay, confidence, content-type half-lives, co-activation reinforcement), [MAGMA](https://arxiv.org/abs/2501.13956)-style intent classification with multi-graph traversal (semantic, temporal, and causal beam search), and [A-MEM](https://arxiv.org/abs/2510.02178) self-evolving memory notes that enrich documents with keywords, tags, and causal links between entries. Pattern extraction from [Engram](https://github.com/Gentleman-Programming/engram) adds deduplication windows, frequency-based durability scoring, and temporal navigation. Integrates via Claude Code hooks, an MCP server (works with any MCP-compatible client), a native OpenClaw plugin, or a Hermes Agent `MemoryProvider` plugin. All paths write to the same local SQLite vault. A decision captured during a Claude Code session shows up immediately when an OpenClaw or Hermes agent picks up the same project. TypeScript on Bun. MIT License. ## What It Does ClawMem turns your markdown notes, project docs, and research dumps into persistent memory for AI coding agents. It automatically: - **Surfaces relevant context** on every prompt (context-surfacing hook) - **Bootstraps sessions** with your profile, latest handoff, recent decisions, and stale notes - **Captures decisions, preferences, milestones, and problems** from session transcripts using a local GGUF observer model - **Imports conversation exports** from Claude Code, ChatGPT, Claude.ai, Slack, and plain text via `clawmem mine`, with optional post-import LLM fact extraction (`--synthesize`) that pulls structured decisions / preferences / milestones / problems and cross-fact links out of otherwise full-text conversation dumps (v0.7.2) - **Generates handoffs** at session end so the next session can pick up where you left off - **Learns what matters** via a feedback loop that boosts referenced notes and decays unused ones - **Guards against prompt injection** in surfaced content - **Classifies query intent** (WHY / WHEN / ENTITY / WHAT) to weight search strategies - **Traverses multi-graphs** (semantic, temporal, causal) via adaptive beam search - **Evolves memory metadata** as new documents create or refine connections - **Infers causal relationships** between facts extracted from session observations - **Detects contradictions** between new and prior decisions, auto-decaying superseded ones (with an additional merge-time contradiction gate in the consolidation worker that blocks cross-observation contradictions before they land, v0.7.1) - **Guards against cross-entity merges** during consolidation — name-aware dual-threshold merge safety compares entity anchors before merging similar observations, preventing "Alice decided X" from merging into "Bob decided X" (v0.7.1) - **Prevents context bleed in derived insights** — the Phase 3 deductive synthesis pipeline validates every draft against an anti-contamination wrapper (deterministic entity contamination check + LLM validator + dedupe) before writing cross-session deductive observations (v0.7.1) - **Frames surfaced facts as background knowledge** — `context-surfacing` wraps injected content in `` + `` + `` blocks, telling the model to treat facts as already-known and exposing memory-graph edges between surfaced docs directly in-prompt (v0.7.1) - **Injects knowledge-graph facts as structured triples** — when the user's prompt mentions entities already known to the vault, `context-surfacing` resolves them via a three-path prompt-only extractor (canonical IDs, proper nouns, lowercased n-grams), queries the SPO graph for current-state triples, and appends a `` block of raw `subject predicate object` lines to `` — off for `speed`, 200 tokens on `balanced`, 250 on `deep`, token-truncated at the triple boundary (v0.9.0) - **Session-scoped focus topic boost** — `clawmem focus set "" --session-id ` writes a per-session focus file that steers query expansion, reranking, chunk selection, snippet extraction, and post-composite-score topic boosting (1.4× match / 0.75× demote) for that session only — session-isolated, fail-open, never writes to SQLite or lifecycle columns (v0.9.0) - **Scores document quality** using structure, keywords, and metadata richness signals - **Boosts co-accessed documents** — notes frequently surfaced together get retrieval reinforcement - **Decomposes complex queries** into typed retrieval clauses (BM25/vector/graph) for multi-topic questions - **Cleans stale embeddings** automatically before embed runs, removing orphans from deleted/changed documents - **Transaction-safe indexing** — crash mid-index leaves zero partial state (atomic commit with rollback) - **Deduplicates hook-generated observations** within a 30-minute window using normalized content hashing, preventing memory bloat from repeated hook output - **Navigates temporal neighborhoods** around any document via the `timeline` tool — progressive disclosure from search to chronological context to full content - **Boosts frequently-revised memories** — documents with higher revision counts get a durability signal in composite scoring (capped at 10%) - **Supports pin/snooze lifecycle** for persistent boosts and temporary suppression - **Manages document lifecycle** — policy-driven archival sweeps with restore capability - **Auto-routes queries** via `memory_retrieve` — classifies intent and dispatches to the optimal search backend - **Syncs project issues** from Beads issue trackers into searchable memory - **Runs a quiet-window heavy maintenance lane** — a second consolidation worker, off by default behind `CLAWMEM_HEAVY_LANE=true`, that runs on a longer interval only inside a configurable hour window. Gated by `context_usage` query-rate so it never competes for CPU/GPU with interactive sessions, scoped exclusively via DB-backed `worker_leases`, stale-first by default with an optional surprisal selector, and journals every attempt in `maintenance_runs` for operator visibility (v0.8.0) Runs fully local with no API keys and no cloud services. Integrates via Claude Code hooks and MCP tools, as a native OpenClaw plugin, or as a Hermes Agent `MemoryProvider` plugin. All modes share the same vault for cross-runtime memory. Works with any MCP-compatible client. Full version history is in [RELEASE_NOTES.md](RELEASE_NOTES.md). Upgrade instructions for existing vaults are in [docs/guides/upgrading.md](docs/guides/upgrading.md). ## Architecture ## Install ### Platform Support | Platform | Status | Notes | |---|---|---| | **Linux** | Full support | Primary target. systemd services for watcher + embed timer. | | **macOS** | Full support | Homebrew SQLite handled automatically. GPU via Metal (llama.cpp). | | **Windows (WSL2)** | Full support | Recommended for Windows users. Install Bun + ClawMem inside WSL2. | | **Windows (native)** | Not recommended | Bun and sqlite-vec work, but `bin/clawmem` wrapper is bash, hooks expect bash commands, and systemd services have no equivalent. Use WSL2 instead. | ### Prerequisites **Required:** - [Bun](https://bun.sh) v1.0+ — runtime for ClawMem. On Linux, install via `curl -fsSL https://bun.sh/install | bash` (not snap — snap Bun cannot read stdin, which breaks hooks). - SQLite with FTS5 — included with Bun. On macOS, install `brew install sqlite` for extension loading support (ClawMem detects and uses Homebrew SQLite automatically). **Optional (for better performance):** - [llama.cpp](https://github.com/ggml-org/llama.cpp) (`llama-server`) — for dedicated GPU inference. Without it, `node-llama-cpp` runs models in-process (auto-downloads on first use). GPU servers give better throughput and prevent silent CPU fallback. - systemd (Linux) or launchd (macOS) — for persistent background services (watcher, embed timer, GPU servers). ClawMem ships systemd unit templates; macOS users can create equivalent launchd plists. See [systemd services](docs/guides/systemd-services.md). **Optional integrations:** - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — for hooks + MCP integration - [OpenClaw](https://github.com/openclaw/openclaw) — for native plugin integration - [Hermes Agent](https://github.com/NousResearch/hermes-agent) — for `MemoryProvider` plugin integration - [bd CLI](https://github.com/dolthub/dolt) v0.58.0+ — for Beads issue tracker sync (only if using Beads) ### Install from npm (recommended) ```bash npm install -g clawmem ``` If you use Bun as your package manager: ```bash bun add -g clawmem ``` ### Install from source ```bash git clone https://github.com/yoloshii/clawmem.git ~/clawmem cd ~/clawmem && bun install ln -sf ~/clawmem/bin/clawmem ~/.bun/bin/clawmem ``` ### Setup roadmap After installing, here's the full journey from zero to working memory: | Step | What | How | Details | |------|------|-----|---------| | **1. Bootstrap** | Create a vault, index your first collection, embed, install hooks and MCP | `clawmem bootstrap ~/notes --name notes` | One command does it all. Or run each step manually (see below). | | **2. Choose models** | Pick embedding + reranker models based on your hardware | 16GB+ VRAM → SOTA stack (zembed-1 + zerank-2 sidecar). Less → QMD native combo. No GPU → cloud embedding or CPU fallback. | [GPU Services](#gpu-services) | | **3. Download models** | Get the model files for your chosen stack (GGUFs for embedding/LLM/default-reranker; the zerank-2 SOTA reranker builds its own sidecar artifact) | `wget` from HuggingFace, let `node-llama-cpp` auto-download the QMD native models, or run the sidecar recipe | [Embedding](#embedding), [LLM Server](#llm-server), [Reranker Server](#reranker-server) | | **4. Start services** | Run GPU servers (if using dedicated GPU) and background services. Optionally enable the v0.8.2 background maintenance workers in the watcher unit so consolidation + deductive synthesis run automatically. | `llama-server` for each model. systemd units for watcher + embed timer. Drop-in for the watcher to enable workers + tune intervals + set the quiet window. | [systemd services](docs/guides/systemd-services.md), [background workers](docs/guides/systemd-services.md#background-maintenance-workers-v082) | | **5. Decide what to index** | Add collections for your projects, notes, research, and domain docs | `clawmem collection add ~/project --name project` | The more relevant markdown you index, the better retrieval works. See [building a rich context field](docs/introduction.md#building-a-rich-context-field). | | **6. Connect your agent** | Hook into Claude Code, OpenClaw, Hermes, or any MCP client | `clawmem setup hooks && clawmem setup mcp` for Claude Code. `clawmem setup openclaw` for OpenClaw. Copy `src/hermes/` to Hermes plugins for Hermes. | [Integration](#integration) | | **7. Verify** | Confirm everything is working | `clawmem doctor` (full health check) or `clawmem status` (quick index stats) | [Verify Installation](#verify-installation) | **Fastest path:** Step 1 alone gets you a working system with in-process CPU/GPU inference and default models — no manual model downloads or service configuration needed. Steps 2-4 are optional upgrades for better performance. Steps 5-6 are where you customize what gets indexed and how your agent connects. **Customize what gets indexed:** Each collection has a `pattern` field in `~/.config/clawmem/config.yaml` (default: `**/*.md`). Tailor it per collection — index project docs, research notes, decision records, Obsidian vaults, or anything else your agents should know about. The more relevant content in the vault, the better retrieval works. See the [quickstart](docs/quickstart.md#customize-index-patterns) for config examples. ### Quick start commands ```bash # One command: init + index + embed + hooks + MCP clawmem bootstrap ~/notes --name notes # Or step by step: clawmem init clawmem collection add ~/notes --name notes clawmem update --embed clawmem setup hooks clawmem setup mcp # Add more collections (the more you index, the richer retrieval gets) clawmem collection add ~/projects/myapp --name myapp clawmem collection add ~/research --name research clawmem update --embed # Verify clawmem doctor ``` ### Upgrading ```bash bun update -g clawmem # or: npm update -g clawmem ``` Database schema migrates automatically on next startup (new tables and columns are added via `CREATE IF NOT EXISTS` / `ALTER TABLE ADD COLUMN`). After **major version updates** (e.g. 0.1.x → 0.2.0) that add new enrichment pipelines, run a full enrichment pass to backfill existing documents: ```bash clawmem reindex --enrich # Full enrichment: entity extraction + links + evolution for all docs clawmem embed # Re-embed if upgrading embedding models (not needed for most updates) ``` `--enrich` forces the complete A-MEM pipeline (entity extraction, link generation, memory evolution) on all documents, not just new ones. Without it, reindex only refreshes metadata for existing docs. Routine patch updates (e.g. 0.2.0 → 0.2.1) do not require reindexing. For version-specific upgrade notes (opt-in features, optional cleanup steps, verification commands), see [docs/guides/upgrading.md](docs/guides/upgrading.md). ### Integration #### Claude Code ClawMem integrates via hooks (`settings.json`) and an MCP stdio server. Hooks handle 90% of retrieval automatically - the agent never needs to call tools for routine context. ```bash clawmem setup hooks # Install lifecycle hooks (SessionStart, UserPromptSubmit, Stop, PreCompact) clawmem setup mcp # Register MCP server in ~/.claude.json (31 tools) ``` **Automatic (90%):** `context-surfacing` injects relevant memory on every prompt. `postcompact-inject` re-injects state after compaction. `decision-extractor`, `handoff-generator`, `feedback-loop` capture session state on stop. **Agent-initiated (10%):** MCP tools (`query`, `intent_search`, `find_causal_links`, `timeline`, etc.) for targeted retrieval when hooks don't surface what's needed. #### OpenClaw ClawMem registers as a native OpenClaw memory plugin (`kind: memory`, v0.10.0+). Same 90/10 automatic retrieval, delivered through OpenClaw's plugin-hook bus instead of Claude Code hooks. ```bash # v0.10.4+: profile-aware. Delegates to `openclaw plugins install --force` when the OpenClaw CLI # is on PATH (auto-enables the plugin, honors OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, --profile). # Falls back to a recursive copy honoring OPENCLAW_STATE_DIR when the CLI is absent. clawmem setup openclaw # Custom profile (e.g. dev profile at ~/.openclaw-dev): OPENCLAW_STATE_DIR=~/.openclaw-dev clawmem setup openclaw ``` **What the plugin provides:** - **`before_prompt_build` hook (load-bearing)** - prompt-aware retrieval (context-surfacing + session-bootstrap) AND the pre-emptive `precompact-extract` run when token usage approaches the compaction threshold. This is the authoritative path for precompact state capture because it runs synchronously before the LLM call that would trigger compaction, so it cannot race the compactor. - **`agent_end` hook** - decision extraction, handoff generation, feedback loop (parallel, fire-and-forget at the OpenClaw call site). OpenClaw v2026.4.26+ also enforces a 30s default void-hook timeout on `agent_end` — slow handlers are logged but the underlying postrun work is not cancelled (fail-open). - **`before_compaction` hook (defense-in-depth fallback)** - fires `pr … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [yoloshii](https://github.com/yoloshii) - **Source:** [yoloshii/ClawMem](https://github.com/yoloshii/ClawMem) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** yes - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: flagged — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-yoloshii-clawmem - Seller: https://agentstack.voostack.com/s/yoloshii - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.