claude-mem gives a coding agent memory across sessions. Its README frames the goal as “Persistent Context Across Sessions for Every Agent”: it records what the agent did, summarises it, and “injects relevant context back into future sessions.” The project is Apache-2.0 licensed.
The problem it addresses is real and familiar. Close a session and the agent forgets the architecture you explained, the dead end you already ruled out, and the convention you agreed on. Every new session starts by re-explaining.
How it works
The mechanism is more substantial than a notes file, and worth understanding because it determines what you are running locally:
- Five lifecycle hooks — SessionStart, UserPromptSubmit, PostToolUse, Stop and SessionEnd — implemented across six hook scripts.
- A local worker service, an HTTP API with a web viewer and search endpoints, managed by Bun.
- SQLite for sessions, observations and summaries, with FTS5 full-text search.
- Chroma as a vector database, giving hybrid semantic and keyword search.
- A
mem-searchskill plus four MCP tools following a three-layer workflow:search, thentimeline, thenget_observations. The README claims “~10x token savings” from filtering before fetching detail — a sensible design, though the figure is the project’s own.
So this is not a lightweight add-on. It is a background service with two databases, and it watches everything the agent does.
Installing it
Use the installer, not a global npm install — the README is explicit that npm install -g claude-mem “installs the SDK/library only”:
npx claude-mem installInside Claude Code the plugin route works too:
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-memOther hosts are covered by --ide flags (opencode, t3code, antigravity, omp, pi, dsh). Requirements are Node.js 20 or higher, Claude Code with plugin support, and Bun plus uv, both auto-installed if absent. Settings land in ~/.claude-mem/settings.json. Restart Claude Code after installing or changing CLAUDE_MEM_MODE.
Once running it is automatic: previous-session context appears in new sessions, and the worker’s web viewer shows the memory stream.
Three things to settle before adopting it
It is not simply free. Signing in unlocks the “claude-mem observer” with a “30 Day Free Trial”, after which the README says “memory automatically falls back to your Anthropic plan unless you subscribe.” You can skip sign-in entirely by passing --provider or setting CLAUDE_MEM_ONLINE_OPTIN=false. The Apache-2.0 licence covers the code; the hosted observer is a product. Decide which mode you are running before you depend on it.
It records your work by default. That is the point, but it means tool observations from your repository flow into a local store and, if you enable it, an optional cloud backup to cmem.ai. The privacy control is <private> tags to exclude sensitive content from storage. For client code or anything under NDA, understand that mechanism before installing rather than after.
There is a token in the README. The project includes a section explaining that CMEM is “a token created by a 3rd party but officially embraced by the creator,” unrelated to the software’s core function. It changes nothing technically, and the README is upfront about it — but a cryptocurrency attached to a developer tool is the kind of context a reader should get before clicking install, not discover later.
Smaller caveats
Windows users may need Node and npm on PATH to avoid an “npm is not recognized” error. On Grok Bot there are “no host hooks,” so claude-mem watches chat log files instead and defaults to the hosted provider. SessionStart context defaults to the current harness; pulling in all sources is opt-in.
Worth it if
You run long multi-session work in one codebase and keep paying the re-explanation tax. The architecture is serious, the search design is thoughtful, and the licence on the code is permissive.
Just go in with eyes open on the three points above — a background service with two databases, a trial that converts to a subscription, and a token in the README are all things to weigh deliberately rather than discover after it is wired into every session.
