# ClawMem

On-device memory layer over your markdown notes: hooks plus a 33-tool MCP server, no API keys.

ClawMem indexes a folder of markdown notes and project docs into a local SQLite vault with hybrid retrieval (BM25 plus local embeddings and reranking), then surfaces context into Claude Code, OpenClaw, or Hermes on every prompt through lifecycle hooks. An MCP server exposes search, timeline, and causal-link tools for targeted retrieval. Fully local; MIT.

- Capabilities: adaptable, operable
- Vertical: notes-knowledge
- Shape: mcp-server
- Form factor: mcp-server
- Execution model: hybrid
- Provenance: unknown (recorded, never ranked)
- Repo: https://github.com/yoloshii/ClawMem (MIT), 207 stars, last commit 2026-08-18
- Last activity: 2026-08-18
- Page: apps/yoloshii--clawmem.html
- JSON: apps/yoloshii--clawmem.json

## Use it when

- you want Claude Code to remember your project decisions without sending notes to a cloud
- you run OpenClaw or Hermes agents and want them sharing one memory with your coding sessions

## Gotchas

- Needs Bun; native Windows is not recommended, use WSL2
- SOTA embedding stack wants 16GB+ VRAM; smaller hardware falls back to CPU models or a cloud embedding endpoint
- Snap-installed Bun cannot read stdin, which breaks hooks (README)
- Sits at the agent-memory edge of notes-knowledge; flagged for the Curator

## Editions

- Free: Free, open source
  - source: https://github.com/yoloshii/ClawMem
  - installable: npm install -g clawmem && clawmem bootstrap ~/notes --name notes

## Adaptable: make it yours

Effort: config-only (15 things to edit)

clawmem bootstrap ~/notes does init, index, embed, hooks, and MCP registration in one go. The business surface is ~/.config/clawmem/config.yaml: named collections with a glob pattern each (default **/*.md) and optional named vaults (or CLAWMEM_VAULTS), which decide what the agent remembers; SKILL.md holds the retrieval rules the agent follows. .env.example names only model plumbing: CLAWMEM_EMBED_URL, CLAWMEM_EMBED_MODEL, CLAWMEM_EMBED_DIMENSIONS, CLAWMEM_EMBED_API_KEY, CLAWMEM_RERANK_URL, CLAWMEM_LLM_URL, CLAWMEM_NO_LOCAL_MODELS; CLAWMEM_HEAVY_LANE and CLAWMEM_JUDGE_* switch optional lanes. Hooks land in Claude Code settings.json.

- Env vars: CLAWMEM_EMBED_URL, CLAWMEM_EMBED_MODEL, CLAWMEM_EMBED_DIMENSIONS, CLAWMEM_EMBED_API_KEY, CLAWMEM_EMBED_TPM_LIMIT, CLAWMEM_RERANK_URL, CLAWMEM_LLM_URL, CLAWMEM_NO_LOCAL_MODELS, CLAWMEM_API_TOKEN, CLAWMEM_HEAVY_LANE, CLAWMEM_VAULTS
- Config files: ~/.config/clawmem/config.yaml, .env, ~/.claude/settings.json
- Prompt files: SKILL.md
- Accounts you'll need: none

## Operable: what an agent can drive

Operability: native. Interface: mcp at https://github.com/yoloshii/ClawMem#readme (published by the builder, local).

### Reach (partial coverage)

- Retrieve relevant notes for a prompt: reachable. memory_retrieve, query, search, vsearch, intent_search MCP tools; context-surfacing hook does it automatically
- Navigate the timeline around a document: reachable. timeline tool
- Find causal links between decisions: reachable. find_causal_links tool
- Capture decisions and session handoffs: reachable. Stop and PreCompact hooks run decision extraction and precompact-extract
- Detect and decay contradicted decisions: reachable. runs when a judge is configured with CLAWMEM_JUDGE_*; disabled otherwise
- Index additional collections: not reachable. clawmem collection add is CLI; pattern per collection in config.yaml
- Import chat exports (Claude, ChatGPT, Slack): not reachable. clawmem mine is a CLI command, not an MCP tool
- Sync Beads issues into memory: not reachable. CLI plus bd; not an MCP tool
- Query across multiple vaults: reachable. retrieval tools accept an optional vault parameter

## Code stack

- Languages: TypeScript
- Frameworks: Bun
- Package manager: bun
- Database: SQLite (FTS5, sqlite-vec)
- Hosting target: local

## Model stack

- Providers: local embedding and reranker models (zembed-1, zerank-2, QMD combo), optional OpenAI-compatible embedding endpoint
- Models: zembed-1, zerank-2
- Keys you need (names only): CLAWMEM_EMBED_API_KEY, CLAWMEM_EMBED_URL, CLAWMEM_LLM_URL, CLAWMEM_RERANK_URL
- Prompts live in: SKILL.md
- Tools: memory_retrieve, search, vsearch, query, query_plan, intent_search, timeline, find_causal_links

## Skills

bundled: A root SKILL.md teaching an agent to use the ClawMem memory MCP server.
- Paths: SKILL.md

## Evidence and confidence

- formFactor: README: MCP stdio server plus hooks and CLI; registered in ~/.claude.json (confidence 0.9)
- executionModel: runs local embedding and reranker models; optional LLM synthesis and judge (confidence 0.75)
- operability: hooks and MCP are the product; README 'On-device memory for Claude Code, OpenClaw, and Hermes' (confidence 0.9)
- effort: .env.example CLAWMEM_* names; README names ~/.config/clawmem/config.yaml (confidence 0.8)
- editions: MIT, npm package, no paid edition (confidence 0.95)
- active: pushedAt 2026-08-18; Show HN 2026-03-22
- provenance: CLAUDE.md, AGENTS.md, SKILL.md present; no authorship statement (confidence 0.3)
- reach:  (confidence 0.8)

## Open questions

- Full list of the 33 MCP tools
- Which CLAWMEM_JUDGE_* names exist and what provider they expect

## Sources

- https://github.com/yoloshii/ClawMem (sourcing:notes-knowledge:community)