The memory
Claude Code forgets everything when a session ends. So I gave it a database. This is what's inside it, and how it's wired together.
October 2025 → October 2026 · roughly 11 months of history ·
How it works
Five steps, none of them exotic. The interesting part isn't any single piece — it's that they run continuously and unattended.
- 1
Claude Code writes JSONL
Every session is appended to a transcript on disk. This is stock behaviour — nothing custom yet.
- 2
A parser ingests it
jsonl_processor.py walks the transcripts, decodes project paths, extracts messages, tool calls, tokens and cost, and upserts them. Re-runnable and idempotent.
- 3
Embeddings get generated
Messages and memories are embedded as vector(1536) and stored in Postgres via pgvector, so recall is semantic rather than keyword-only.
- 4
An MCP server exposes it
37 tools over stdio — search, recall, stats, observations. Claude queries its own history as a first-class tool.
- 5
The agent reads its own past
Ask about work from months ago and it searches the database instead of guessing. That is the whole point.
The schema
23 tables, 100 indexes, 460,999 rows. The two big ones are big because of embeddings, not text.
| Table | Rows | Size | Purpose |
|---|---|---|---|
memories | 16,678 | 435 MB | Long-term facts with vector embeddings. Semantic recall across sessions. |
conversation_messages | 367,446 | 381 MB | Every message, embedded for hybrid semantic + trigram search. |
resources | 7,403 | 142 MB | Saved URLs, docs, and reference material. |
observations | 49,702 | 142 MB | Behavioural notes captured during sessions. |
observation_digests | 896 | 31 MB | Periodically compacted observations, to keep recall cheap. |
session_stats | 5,724 | 5176 kB | Per-session metrics: tokens, tool calls, cost, duration. |
conversation_sessions | 5,572 | 3552 kB | Session index — project path, timing, message counts. |
session_summaries | 1,012 | 3304 kB | Generated summaries used to warm-start later sessions. |
generated_images | 54 | 1264 kB | Image generation log. |
tool_usage | 3,235 | 960 kB | Daily tool-call counts. Drives the tool distribution chart. |
usage_hourly | 1,945 | 376 kB | Hourly rollup. Drives the 24-hour clock. |
model_usage | 610 | 336 kB | Per-model, per-day tokens and cost. |
pi_memories | 18 | 248 kB | Pi scout system memory store. |
project_profiles | 264 | 232 kB | Detected framework and dependencies per project. |
notifications | 118 | 168 kB | — |
usage_daily | 249 | 112 kB | Daily rollup. Drives the heatmap. |
time_entries | 55 | 96 kB | Manual time tracking. |
clients | 3 | 88 kB | — |
capture_amendments | 4 | 80 kB | — |
session_attributions | 10 | 48 kB | — |
bucket_list | 0 | 32 kB | Personal backlog. |
reminder_timed_sent | 1 | 24 kB | — |
pi_observations | 0 | 16 kB | Pi scout system observations. |
How it filled up
Messages recorded per month, with the running total behind it. The early months are thin because they were backfilled from migrated transcripts — the archive only becomes continuous once the database was running live.
The database
- Engine
- PostgreSQL 16 (pgvector/pgvector:pg16, Docker)
- Embeddings
vector(1536)- Extension
-
pg_trgm1.6 - Extension
-
vector0.8.2 - Indexes
- 100
- Host
- Docker, localhost only
The MCP server
- Language
- Python, stdio transport
- Tools exposed
- 37
- Lines of code
- 5,664
Modules
api.py conversations.py db_config.py embeddings.py jsonl_processor.py memory.py observations.py stats.py stats_db.py What this isn't
It isn't a product. It's a local Docker container on one machine, bound to localhost. There's no hosted version and no install script.
It isn't magic recall. Semantic search over 423,368 messages returns plausible neighbours, not guaranteed answers. It's a research tool for the agent, and it still has to read what it finds.
It isn't free. Embedding 460,999 rows costs real money and real disk — 1156 MB of it, most of that vectors rather than prose.
It isn't the hard part. Storing history is easy. Deciding what's worth remembering, and getting the agent to actually consult it before answering, is where the work is.