Claude-Mem explained: what a coding agent remembers
Claude-Mem source-code map: manifests, hooks and API semantics
Use the pinned configuration and endpoint contracts to locate the real execution paths
What you will learn
- Start at package and plugin
- Follow local hook behavior
- Read worker, renderer and server contract
Before you start
- A synthetic two-session project
- One supported host
- A deliberate memory provider choice
Use two synthetic sessions and an explicit deletion check before team adoption
Key takeaways
- Hooks are executable configuration.
- Some failures intentionally leave the host usable.
- Server generation can continue after the HTTP response.
Start at package and plugin
`package.json` declares the `claude-mem` CLI binary, engine ranges and build scripts. The plugin manifest identifies the Claude Code package, while `plugin/hooks/hooks.json` lists event matchers, commands and timeouts.
A successful package build is not proof that every host hook loads. Trace the selected host adapter and its generated bundle before attributing behavior to another client.
Follow local hook behavior
The hook configuration contains shell commands that locate cached plugin scripts and invoke the Bun runner. Several paths treat a missing worker as non-blocking for the host.
This is source-level behavior visible in configuration. We did not run commands, verify each fallback branch or audit all scripts launched by those commands.
Read worker, renderer and server contract
`worker-service.ts` initializes database, Chroma and search routes in separate steps. `ContextBuilder.ts` selects timeline entries and full observation IDs, then fits rendered context to an output limit. `docs/api.md` separates older `/api` routes from beta `/v1` endpoints.
The source returns statistics based on selected records, while server generation may continue after an HTTP response. First-key provisioning merits separate security review. We did not execute error branches or certify authentication, timing or retention behavior.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Read package engines and binary entry.
- 2
Match one hook to its invoked script and timeout.
- 3
Keep local worker and beta server route claims separate.
Copy-ready example
package bin -> installer
plugin.json -> hooks.json -> worker-service
ContextBuilder -> selected timeline -> bounded contextFrequently asked questions
Which file defines Claude Code hook wiring?
The pinned `plugin/hooks/hooks.json` lists the configured event handlers.
Does the API response mean summarization finished?
The server document says generation may be queued for a separate worker.
Sources
- Claude-Mem / package.jsonSource checked 2026-10-08
- Claude-Mem / plugin/.claude-plugin/plugin.jsonSource checked 2026-10-08
- Claude-Mem / plugin/hooks/hooks.jsonSource checked 2026-10-08
- Claude-Mem / docs/architecture-overview.mdSource checked 2026-10-08
- Claude-Mem / docs/api.mdSource checked 2026-10-08
- Claude-Mem / src/services/worker-service.tsSource checked 2026-10-08
- Claude-Mem / src/services/context/ContextBuilder.tsSource checked 2026-10-08