Claude-Mem: Persistent Memory for AI Coding Agents

What Claude-Mem is

Claude-Mem is a persistent memory compression system built for Claude Code. Coding agents normally start every session with a blank slate: whatever the agent learned about a codebase yesterday, which bug it tracked down, which design decision was made and why, is gone the moment the session ends unless someone writes it down by hand. Claude-Mem fills that gap automatically. It captures observations of the tools the agent uses while it works, generates semantic summaries from them, and makes those summaries available to future sessions, so the agent keeps continuity of knowledge about a project even after sessions end or reconnect.

Although Claude Code is the primary target, the installer now registers the plugin with a growing list of agent harnesses: OpenCode (1.3.4 or later, including OpenCode 2), T3 Code with its Codex and Claude Code providers, Antigravity CLI, OMP (Oh My Pi), the Pi extension, DeepSeek Harness, Grok Bot and OpenClaw gateways. The audience is developers who spend long stretches working with an AI coding agent on the same repositories and are tired of re-explaining context at the start of every session.

The project is written in TypeScript, licensed under Apache-2.0 and authored by Alex Newman (@thedotmack). The README's version badge shows the 13.x series, which says a lot about how quickly it has been iterating since the repository was created in August 2025.

How it works

Claude-Mem plugs into the agent's lifecycle hooks rather than wrapping the agent. The README lists six core components:

1. Lifecycle hooks for SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop and SessionEnd. Each one is a single shell-free command, claude-mem hook claude-code <event>, run by a small launcher the installer puts on the PATH.
2. Smart install, a cached dependency checker that runs on setup and through npx claude-mem install or repair.
3. A worker service, a local HTTP API with a web viewer UI and search endpoints, managed by Bun.
4. A SQLite database that stores sessions, observations and summaries.
5. The mem-search skill for natural-language queries over that history.
6. A Chroma vector database for hybrid semantic and keyword search.

The architecture overview in the docs describes the memory pipeline as: hook input arrives on stdin, observations are written to SQLite, the worker reads them and processes them through the Claude Agent SDK (or Gemini or OpenRouter), the processed summaries go back into the database, and the next session's context hook reads them and injects them at startup. The worker is an Express HTTP server on a per-user port, it streams a real-time memory feed to a React viewer over Server-Sent Events, and full-text search runs on SQLite FTS5 virtual tables.

Retrieval is built around what the project calls progressive disclosure. Instead of dumping everything it remembers into the context window, Claude-Mem exposes MCP tools in a three-layer workflow:

1. search returns a compact index of matching observations with IDs (the README estimates roughly 50 to 100 tokens per result).
2. timeline returns chronological context around an interesting result.
3. get_observations fetches full details only for the IDs that matter (roughly 500 to 1,000 tokens per result).

The README claims about a 10x token saving from filtering before fetching details. That figure is the project's own estimate; how much it saves in practice depends on how much history a project accumulates and how targeted the agent's queries are.

Key features

• Persistent memory: context survives across sessions and reconnects without any manual note-taking.
• Progressive disclosure: layered memory retrieval with visible token cost per layer.
• Skill-based search: the mem-search skill lets the agent query project history in natural language, for example "what bugs did we fix?".
• Local My Work view: live requests, progress, human handoffs and a saved review queue at the worker URL printed on startup; memory, sessions and settings live at /viewer.
• Privacy control: content wrapped in <private> tags is excluded from storage.
• Context configuration: fine-grained control over what context gets injected, including an option to include observations from every harness at session start rather than only the current one.
• Citations: past observations can be referenced by ID through the worker API or browsed in the web viewer.
• Modes and languages: the CLAUDE_MEM_MODE setting switches workflow behaviour (such as code, chill or investigation) and the language of generated observations, with patterns like code--zh and code--ja.
• Claude Desktop skill: memory can also be searched from Claude Desktop conversations.

Getting started

The system requirements are Node.js 20 or higher and a current Claude Code with plugin support. Bun (the runtime and process manager) and uv (the Python package manager used for vector search) are installed automatically if missing, and SQLite is bundled. The standard install is a single command:

npx claude-mem install

Alternatively, the plugin can be installed from the marketplace inside Claude Code, followed by a restart:

/plugin marketplace add thedotmack/claude-mem

/plugin install claude-mem

Other harnesses use the same installer with an --ide flag, for example:

npx claude-mem install --ide opencode
npx claude-mem install --ide t3code

One detail trips people up: the package is also published on npm, but npm install -g claude-mem installs only the SDK and library. It does not register the plugin hooks or set up the worker service, so the README says to always use npx claude-mem install or the /plugin commands. Settings live in ~/.claude-mem/settings.json, which is created with defaults on first run and controls the AI model, worker port, data directory, log level and context injection.

Use cases

• Long-running projects with an agent: pick up a refactor on Monday with the agent already aware of what was changed on Friday and why.
• Debugging history: ask the agent which bugs were fixed in a module and pull the full observation only for the relevant ones.
• Switching between harnesses: developers who move between Claude Code, Codex and OpenCode can keep one memory store and optionally include observations from all sources at session start.
• Reviewing agent work: the local My Work view and review queue give a place to inspect what the agent did and where it handed off to a human.
• Keeping secrets out of memory: wrap sensitive content in <private> tags so it is never written to the store.

How it compares

The README does not benchmark itself against named alternatives. The obvious comparison is the hand-maintained approach most teams use today, such as project instruction files that the agent reads at startup. Those are explicit and reviewable but only contain what someone remembered to write. Claude-Mem takes the opposite approach and records automatically from tool usage, then relies on summarisation and search to keep the injected context small. The two are not mutually exclusive: instruction files can hold rules and conventions while Claude-Mem holds the running history of what happened.

Things to know before adopting

• Open-core boundary: the repository's licence documents describe an open-core structure. The memory engine, server, CLI, SDKs, MCP tools, adapters and docs are Apache-2.0, while hosted cloud, team and organisation memory sync, enterprise features and premium agents are reserved as commercial areas outside the public code.
• Hosted sign-in by default: the interactive installer asks you to sign in by email magic link, which provisions a memory key and starts a 30-day free trial of the hosted claude-mem observer. To stay fully local, pass an explicit --provider flag, set CLAUDE_MEM_ONLINE_OPTIN=false, or install in CI or a non-interactive shell. After the trial, memory falls back to your Anthropic plan unless you subscribe, and you can also choose your own OpenRouter or Gemini key.
• Model usage costs: observations are compressed by an LLM, so memory processing consumes tokens from whichever provider you configure.
• Grok Bot integration is different: that harness has no host hooks, so Claude-Mem watches chat log files instead, and its default is the hosted memory.
• Fast release cadence: the version number and the steady stream of new integrations mean behaviour and settings change often; pin a version if stability matters.
• Third-party token: the README closes with a section about a third-party crypto token that the author has endorsed. It is not part of the software, but teams with procurement or compliance reviews may want to be aware of it.

Project activity

As of October 2026 the repository has about 101,000 stars. It was created in August 2025, is written in TypeScript and is licensed under Apache-2.0, with pushes as recent as mid-October 2026. Releases ship from the main branch and are published to npm, and the README has been translated into more than 30 languages. The source is at github.com/thedotmack/claude-mem, the documentation at docs.claude-mem.ai and the project site at claude-mem.ai.