data-ai MCP Server
On-device memory layer for AI agents. Claude Code, Hermes and OpenClaw. Hooks + MCP server + hybrid RAG search.
Discovered via github-seeds:mcp-hot and last synced 3mo ago.
1. Install the package
npx clawmem
2. Add to claude_desktop_config.json
{
"mcpServers": {
"clawmem": {
"command": "npx",
"args": [
"clawmem"
]
}
}
}Config file location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) / %APPDATA%\Claude\claude_desktop_config.json (Windows)
Purpose
8089
1024
`https://api.openai.com`
USE THIS for "what else relates to X", "show me similar docs". Finds k-NN vector neighbors — discovers connections beyond keyword overlap that search/query cannot find.
1024
`https://api.cohere.com`
**Preferred entry point.** Auto-classifies query and routes to optimal backend (query, intent_search, session_log, find_similar, or query_plan). Use instead of manually choosing a search tool.
USE THIS for complex multi-topic queries ("tell me about X and also Y", "compare A with B"). Decomposes into parallel typed clauses (bm25/vector/graph), executes each, merges via RRF. `query()` searches as one blob — this tool splits topics and routes each optimally.
Temporarily hide a memory from context surfacing until a date. USE PROACTIVELY when `<vault-context>` repeatedly surfaces irrelevant content — snooze for 30 days instead of ignoring it.
128K context
BM25 keyword search — for exact terms, config names, error codes, filenames. Composite scoring + co-activation boost + compact mode. Collection filter supports comma-separated values. Prefer `memory_retrieve` for auto-routing.
Show configured vault names and paths. Empty in single-vault mode.
Index health with content type distribution
Identical to CLAUDE.md — cross-framework compatibility (Cursor, Windsurf, Codex, etc.)
Full hybrid pipeline (BM25 + vector + rerank) — general-purpose when query type is unclear. WRONG for "why" questions (use `intent_search`) or cross-session queries (use `session_log`). Prefer `memory_retrieve` for auto-routing. Intent hint, strong-signal bypass, chunk dedup, candidateLimit, MMR diversity, compact mode.
Retrieve multiple docs by glob or comma-separated list
Show how a document's A-MEM metadata evolved over time
Read recent diary entries. Filter by agent name.
Current static + dynamic user profile
Stop
∞
45 days
(none)
`false`
Write a diary entry. Use for recording important events, decisions, or observations in environments without hook support. Stored as searchable memories.
USE THIS for "last time", "yesterday", "what happened", "what did we do". Returns session history with handoffs and file changes. DO NOT use `query()` for cross-session questions — this tool has session-specific data that search cannot find.
PreCompact
∞
Pin a memory for +0.3 composite boost. USE PROACTIVELY when: user states a persistent constraint, makes an architecture decision, or corrects a misconception. Don't wait for curator — pin critical decisions immediately.
Restore documents that were auto-archived by lifecycle policies. Filter by query, collection, or restore all
Detailed stats: types, staleness, access counts, sessions
SessionStart
Half-life
handoff
300000
`0.93`
Path
`_clawmem/agent/observations/*.md`
MCP schema validation
Document lifecycle statistics: active, archived, forgotten, pinned, snoozed counts and policy summary
Stop
UserPromptSubmit
SessionStart
90 days
enabled
`http://localhost:8090`
SessionStart
Event
∞
Effect
(none)
`research/*.md`
YAML frontmatter parsing
SessionStart
60 days
`http://localhost:8089`
∞
PreToolUse
60 days
disabled
`false`
ClawMem Mechanism
Config parsing
hub
`embedding`
`link`
`100000`
`0.5`
Purpose
Vector similarity extension
∞ (hub)
`_clawmem/agent/beads/*.md`
`_clawmem/agent/antipatterns/*.md`
GGUF model inference (reranking, query expansion, A-MEM)
Notes
Loaded
Retrieve single document by path or docid
Query the SPO knowledge graph: "what does X relate to?", "what was true about X when?". Returns temporal entity-relationship triples with validity windows. Accepts entity name (resolved via `searchEntities`) or canonical ID in `vault:type:slug` form. Triples are populated by the decision-extractor hook from observer-emitted `<triples>` blocks.
30 days
`http://localhost:8088`
8090
Show the temporal neighborhood around a document — what was created/modified before and after it. Progressive disclosure: search → timeline (context) → get (full content). Supports same-collection scoping and session correlation.
Description
USE THIS for "why did we decide X", "what caused Y", "who worked on Z". Classifies intent (WHY/WHEN/ENTITY/WHAT), traverses causal + semantic graph edges. Returns decision chains that `query()` cannot find.
Sync Beads issues from Dolt backend (`bd` CLI) into memory: creates docs, bridges all dep types to `memory_relations`, runs A-MEM enrichment
Status
8088
Port
8K context, Matryoshka dimensions via `CLAWMEM_EMBED_DIMENSIONS`
`/graphs/build`
Model
`CLAWMEM_EMBED_URL`
`/export`
Trace decision chains: "what led to X", "how we got from A to B". Follow up `intent_search` with this tool on a top result to walk the full causal chain. Traverses causes / caused_by / both up to N hops with depth-annotated reasoning.
`true`
deep ``` Then set `memory.provider: clawmem` in your Hermes `config.yaml`, or run `hermes memory setup` to configure interactively. **What the plugin provides:** - **`prefetch()`** — prompt-aware retrieval via `context-surfacing` hook (automatic every turn) - **`on_session_end()`** — decision extraction, handoff generation, feedback loop (parallel) - **`on_pre_compress()`** — pre-compaction state preservation - **`session-bootstrap`** — session registration + first-turn context injection - **5 agent tools** — `clawmem_retrieve`, `clawmem_get`, `clawmem_session_log`, `clawmem_timeline`, `clawmem_similar` - **Plugin-managed transcript** — maintains its own JSONL transcript for ClawMem hooks **Requirements:** `clawmem` binary on PATH and `clawmem serve` running (external mode) or the plugin starts it automatically (managed mode). Python 3.10+. No pip dependencies beyond Hermes itself (uses `urllib` for REST calls, `httpx` optional for better performance). **Alternative:** Hermes also has built-in MCP client support. You can add ClawMem as an MCP server in Hermes's `config.yaml` under `mcp_servers` for tool-only access. But this misses the lifecycle hooks (prefetch, session_end, pre_compress), so the native plugin is recommended. See [Hermes plugin guide](docs/guides/hermes-plugin.md) for architecture details, lifecycle mapping, and troubleshooting. #### Multi-Framework Operation All three integrations share the same SQLite vault by default. Claude Code, OpenClaw, and Hermes can run simultaneously — decisions captured in one runtime are immediately available in the others, giving agents persistent shared memory across sessions and platforms. WAL mode + busy_timeout handles concurrent access. #### Multi-Vault (Optional) By default, ClawMem uses a single vault at `~/.cache/clawmem/index.sqlite`. For users who want separate memory domains (e.g., work vs personal, or isolated vaults per project), ClawMem supports named vaults. **Configure in `~/.config/clawmem/config.yaml`:** ```yaml vaults: work: ~/.cache/clawmem/work.sqlite personal: ~/.cache/clawmem/personal.sqlite ``` **Or via environment variable:** ```bash export CLAWMEM_VAULTS='{"work":"~/.cache/clawmem/work.sqlite","personal":"~/.cache/clawmem/personal.sqlite"}' ``` **Using vaults with MCP tools:** All retrieval tools (`memory_retrieve`, `query`, `search`, `vsearch`, `intent_search`) accept an optional `vault` parameter. Omit it to use the default vault. ``` # Search the default vault (no vault param needed) query("authentication flow") # Search a named vault query("project timeline", vault="work") # List configured vaults list_vaults() # Sync content into a vault vault_sync(vault="work", content_root="~/work/docs") ``` **Single-vault users:** No action needed. Everything works without configuration. The `vault` parameter is always optional and ignored when no vaults are configured. ### GPU Services ClawMem uses three `llama-server` (llama.cpp) instances for neural inference. All three have in-process fallbacks via `node-llama-cpp` (auto-downloads on first use), so ClawMem works without a dedicated GPU. `node-llama-cpp` auto-detects the best available backend — Metal on Apple Silicon, Vulkan where available, CPU as last resort. With GPU acceleration (Metal/Vulkan), in-process inference is fast for these small models (0.3B–1.7B); on CPU-only systems it is significantly slower. For production use, run the servers via [systemd services](docs/guides/systemd-services.md) to prevent silent fallback. **GPU with VRAM to spare (12GB+, recommended):** ZeroEntropy's distillation-paired stack delivers best retrieval quality — total ~10GB VRAM.
Path
Vector semantic search — for conceptual/fuzzy matching when exact keywords are unknown. Composite scoring + co-activation boost + compact mode. Collection filter supports comma-separated values. Prefer `memory_retrieve` for auto-routing.
Build temporal and/or semantic graphs from document corpus
Index markdown from a directory into a named vault. Restricted-path validation rejects sensitive directories.
Trigger vault re-scan
(none)
What
`qwen3`
Workflow guide: prefer `memory_retrieve` → match query type to tool → `multi_get` for full content
Search → deactivate closest match (with audit trail)
Run lifecycle policies: archive stale docs past retention threshold, optionally purge old archives. Defaults to dry_run (preview only)
Stop
∞
60 days
`0.98`
ClawMem Role
`_clawmem/agent/handoffs/*.md`
Feature
note review_by: "2026-03-01" --- ``` ## Suggested Memory Filesystem This structure separates human-curated content from auto-generated memories, and within auto-generated content, separates **user memories** (persist across agents, owned by the human) from **agent memories** (operational, generated from sessions). Static knowledge lives in `resources/` with no recency decay, distinct from ephemeral session logs. The layout works with any MCP-compatible client (Claude Code, OpenClaw, custom agents). ### Workspace Collection The primary workspace where the agent operates. Path varies by client (e.g., `~/workspace/`, `~/.openclaw/workspace/`, or any directory you choose). ``` <workspace>/ ← Collection: "workspace" ├── MEMORY.md # Human-curated long-term memory ├── memory/ # Session logs (daily entries) │ ├── 2026-02-05.md │ └── 2026-02-06.md ├── resources/ # Static knowledge — use content_type: hub (∞ half-life) │ ├── runbooks/ │ │ └── deploy-checklist.md │ └── onboarding.md ├── _clawmem/ # Auto-generated — DO NOT EDIT │ ├── user/ # User memories (persist across agents/sessions) │ │ ├── profile.md # Static facts + dynamic context │ │ ├── preferences/ # Extracted preferences (update_existing merge policy) │ │ └── entities/ # Named entities (people, services, repos) │ ├── agent/ # Agent memories (operational, session-derived) │ │ ├── observations/ # Decisions + observations from transcripts │ │ ├── handoffs/ # Session summaries with next steps │ │ └── antipatterns/ # Accumulated negative patterns (∞ half-life) │ └── precompact-state.md # Pre-compaction snapshot (transient) └── ... ``` ### Project Collections Each project gets its own collection. Same structure, with optional Beads integration. ``` ~/Projects/<project>/ ← Collection: "<project>" ├── .beads/ # Beads issue tracker (Dolt backend, auto-synced) │ └── dolt/ # Dolt SQL database (source of truth) ├── MEMORY.md # Human-curated project memory ├── memory/ # Project session logs │ └── 2026-02-06.md ├── resources/ # Static project knowledge (∞ half-life) │ ├── architecture.md │ └── api-reference.md ├── research/ # Research dumps (fragment-embedded, 90-day decay) │ └── 2026-02-06-topic-slug.md ├── _clawmem/ # Auto-generated per-project │ ├── user/ │ │ └── preferences/ │ ├── agent/ │ │ ├── observations/ │ │ ├── handoffs/ │ │ ├── antipatterns/ │ │ └── beads/ # Beads issues as searchable markdown │ └── precompact-state.md ├── CLAUDE.md ├── src/ └── README.md ``` ### Design Principles