how-it-works

1# How claude-mem works
2 
3## What it does
4 
5While you work, an observer (a second agent) watches what your agent reads, edits and runs, and writes short notes about what mattered. Those notes are called observations. When a session ends, the observer writes a summary. When the next session starts, your agent gets a compact index of the observations that matter for this project and fetches full details only when it needs them.
6 
7So the next session starts where the last one left off: no re-explaining the codebase, no re-discovering decisions.
8 
9## When it kicks in
10 
11Memory injection starts on your second session in a project.
12 
13The first session seeds memory as you work. To front-load a whole repo in one pass instead, run `/learn-codebase` (~5 minutes on a typical repo, optional).
14 
15## Where data lives
16 
17Your memory lives in ~/.claude-mem on this machine: the SQLite database, vector index, logs and settings. `npx claude-mem uninstall` removes it.
18 
19What leaves the machine:
20 
21- What the observer reads goes to the model you chose to run it: your Claude plan unless you picked another provider (Codex, OpenRouter, Gemini, or the claude-mem observer on CMEM Pro).
22…