Five hooks turn coding activity into a searchable record
Claude-Mem wires 5 documented lifecycle hooks into supported coding agents. Those hooks initialize a session, capture reads and tool results, and ask a provider model to turn the activity into shorter observations. A Bun-managed worker keeps the records in SQLite and maintains a web viewer. When a later session starts, selected observations are injected into its context. This solves a familiar problem: an agent can resume a repository without making the developer explain every prior decision again.
The machinery is substantial. Our commit fa6a1e9 checkout contained 1,055 files, roughly 167,601 source lines, and 146.9 MB before dependencies. Chroma supplies semantic retrieval through Python tooling, while SQLite holds the durable session data. The system therefore has several stateful parts that must agree after an update or a crash. Treat the database and worker as development infrastructure, with backups and a recovery check, rather than as disposable plugin cache.
Three MCP tools make retrieval selective
The configuration guide documents 3 MCP tools: search, timeline, and get_observations. Search returns a compact index, timeline supplies nearby events, and the final call fetches chosen records. That sequence can keep old project history from flooding the prompt. It also lets an agent cite observation IDs, which is much easier to audit than an unexplained paragraph of recalled context. The main README calls the feature set 4 MCP tools while listing only these 3, a small documentation mismatch worth fixing.
Claude-Mem also controls how much history enters automatically. The settings UI can load 1 to 200 observations from as many as 50 sessions, and it can expand only the newest records. Those limits matter because every recalled observation consumes input tokens. The 799-package installation does not buy perfect selection: teams still need to test whether titles, summaries, and search terms recover the decisions they care about without dragging unrelated work into a new task.
What happened when we ran it
Our sandbox installed 799 npm packages in 148 seconds and finished with 995 MB on disk. The build completed successfully in 10 seconds. That is a heavier local footprint than the single install command suggests, although it is consistent with a repository that includes hooks, a worker, a viewer, search services, and integrations for several agent hosts. Npm audit reported 0 known vulnerabilities in the dependency set installed for commit fa6a1e9.
The test command failed with exit code 127 after 8 seconds. Its final output showed bun test tests, followed by sh: 1: bun: not found. No test assertions ran far enough to produce a pass count. The log establishes only that the checked-out repository expected Bun and our Node 22 container did not have it. The project has a tests directory and 8 CI workflow files, but the supplied test command was not self-contained in that fresh environment.
The supported installer manages two extra runtimes
Node.js 20 or newer starts the documented install, and the installer adds Bun plus uv if they are missing. It detects supported coding tools, copies plugin files, registers hooks, installs dependencies, and starts the worker. Users then choose the hosted claude-mem observer, an OpenRouter or Gemini key, or their Anthropic plan for compression. An explicit provider flag or CLAUDE_MEM_ONLINE_OPTIN=false skips the account sign-in step.
Source contributors have a different path: npm installs the 799 packages, the build generates hook and manifest artifacts, and Bun runs the test suite and worker. A global npm install -g claude-mem is easy to misread because it installs the SDK without agent hooks. Use npx claude-mem install or the Claude Code marketplace route for the product described in the README, then verify the worker status and retrieve a known observation before relying on it.
Local storage still needs a data-boundary decision
The default database, settings, logs, and worker files live under ~/.claude-mem. Compression is performed by the provider selected during setup, so local persistence does not by itself keep observation content off external model services. Optional cloud sync goes further: its guide says observation narratives, session summaries, and full prompts are uploaded to a per-user hub, with prompt fields capped at 200 KB. Organizations handling client code should map both paths before enabling capture.
Private tags and tool skip lists provide controls, but they depend on correct configuration before sensitive output is observed. The 995 MB local install also creates state outside a repository checkout, which means deleting a project directory does not delete its memories. Start with a non-sensitive repository, inspect stored rows and provider traffic, test the exclusion rule, and document how to remove local and synced records when a developer leaves a project.
Two v13.21.2 reports block blind trust in recall
Open issue 3828 says a Codex plugin copy for v13.21.2 arrived without node_modules, causing every hook to fail until dependencies were installed manually. The reporter says the fix had to be repeated after an upgrade. Open issue 3832 describes a different failure on Windows: a database constraint error during conversation-budget recycling, followed by lost summary work. These are user reports, not results from our sandbox, but both name the current release and give reproduction detail.
The repository is plainly active. GitHub recorded a September 1, 2026 push, v13.21.2 was published on August 31, and the repository showed 92,828 stars with 288 combined issues and pull requests when fetched. Eight CI workflow files and a same-day issue queue show ongoing engineering work. They do not settle whether a particular host integration is safe. Run an upgrade, a long session, a worker restart, and a known-memory retrieval before adopting Claude-Mem as the only record of project decisions.