Claude-Mem explained: what a coding agent remembers
Claude-Mem architecture: from host event to searchable observation
Trace hooks, queue, generated summaries and retrieval without collapsing the layers
What you will learn
- Capture events
- Process and store
- Return context selectively
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
- Hook configuration is more detailed than the overview diagram.
- Storage and vector search have distinct roles.
- The README tool count is internally inconsistent.
Capture events
The pinned `plugin/hooks/hooks.json` declares Setup, SessionStart, UserPromptSubmit, PostToolUse, PostToolUseFailure, PreToolUse, Stop and SessionEnd keys. Some handlers launch scripts through the Bun runner.
The architecture overview groups these into a simplified lifecycle. Use the actual hook file when counting configured events; documentation diagrams may omit newer or narrower handlers.
Process and store
The local architecture describes a worker receiving session and observation events, a pending-message queue and an SDK agent that generates structured observations. SQLite holds sessions, observations and summaries; Chroma supports vector retrieval.
A queue item, generated observation and search hit are different records. The overview describes recovery after generator errors, but this series did not exercise crash or replay behavior.
Return context selectively
The README presents index search, timeline inspection and fetching observations by ID as a progressive retrieval pattern. Native host adapters may capture events differently and use the worker through their own integration path.
The README calls these four MCP tools yet lists three named tools in that section. Rely on the specific client’s exposed tools rather than repeating an inconsistent count.
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
Identify the host event and handler.
- 2
Follow worker, queue and stored record separately.
- 3
Retrieve only the observations needed for a checkable answer.
Copy-ready example
host -> hook or adapter -> worker queue
worker -> SQLite observation + Chroma index
search index -> timeline -> selected observationFrequently asked questions
Is every host captured by identical hooks?
No. Native integrations and transcript watchers have their own capture paths.
Does a search hit prove the past event occurred as summarized?
Check the relevant source or transcript when accuracy matters.
Sources
- Claude-Mem / README.mdSource checked 2026-10-08
- Claude-Mem / docs/architecture-overview.mdSource checked 2026-10-08
- Claude-Mem / plugin/hooks/hooks.jsonSource checked 2026-10-08
- Claude-Mem / docs/native-harness-integrations.mdSource checked 2026-10-08