Claude-Mem

// Overview

Claude-Mem is an open-source persistent memory system for coding agents. During a session it captures what the agent does — tool calls and their observations — compresses those observations with an AI model into semantic summaries, and stores them locally. When a new session starts, the relevant summaries are injected back in, so the agent begins with knowledge of what happened on the project before rather than from a blank slate.

It is built around lifecycle hooks rather than a library you import. Installing it registers hook scripts (SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd) plus a local worker service that exposes an HTTP API and a web viewer. Observations, sessions and summaries live in a SQLite database, and a Chroma vector database backs hybrid semantic-plus-keyword search over them. The project describes itself as built for Claude Code, and the repository also documents installs for OpenCode, Antigravity CLI and OpenClaw gateways.

Retrieval is deliberately layered to keep token cost down — the project calls this progressive disclosure. Four MCP search tools implement a three-step workflow: `search` returns a compact index of matching observations at roughly 50–100 tokens per result, `timeline` shows what was happening chronologically around a result, and `get_observations` fetches the full detail (roughly 500–1,000 tokens each) only for the IDs you actually chose. The README puts the saving from filtering before fetching at about 10x.

// What it does

• Automatic capture of tool-use observations during a session, summarized and stored without manual intervention
• Context from previous sessions injected into new ones, with fine-grained configuration over what gets injected
• MCP search tools (`search`, `timeline`, `get_observations`) implementing a token-efficient three-layer retrieval workflow
• SQLite storage with FTS5 plus a Chroma vector database for hybrid semantic and keyword search
• A local worker service with an HTTP API and a real-time web viewer for the memory stream
• Privacy control via `<private>` tags, which exclude the wrapped content from storage

// Getting started

Claude-Mem installs as a plugin with hooks and a worker service, not as a plain npm dependency. The README is explicit that `npm install -g claude-mem` gives you the SDK/library only and does not register hooks — use the installer or the plugin marketplace. Node.js 20+ is required; Bun, uv and SQLite are installed automatically if missing.

npx claude-mem install

/plugin marketplace add thedotmack/claude-mem

/plugin install claude-mem

// Step 1 — search for an index
search(query="authentication bug", type="bugfix", limit=10)

// Step 2 — review the index, pick relevant IDs (e.g. #123, #456)

// Step 3 — fetch full details, batching the IDs
get_observations(ids=[123, 456])

{
  "CLAUDE_MEM_MODE": "code--zh"
}

Commands and code are distilled from the project's own documentation — always check the official repo for the latest.

// When to use it

• Keep a long-running project's history available to a coding agent so it stops re-deriving the same context every session
• Search back through past sessions in natural language to find when and why a bug was fixed or a decision was made
• Cut the token cost of memory retrieval by pulling a cheap index first and full observations only on demand
• Give several agent CLIs a shared, locally-stored record of what has already been tried on a codebase

// How Claude-Mem compares

Claude-Mem alongside other open-source agent memory tools AI/TLDR tracks, ranked by GitHub stars.