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 → August 2026 · roughly 9 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
18 tables, 86 indexes, 365,271 rows. The two big ones are big because of embeddings, not text.
| Table | Rows | Size | Purpose |
|---|---|---|---|
memories | 11,525 | 308 MB | Long-term facts with vector embeddings. Semantic recall across sessions. |
conversation_messages | 307,729 | 255 MB | Every message, embedded for hybrid semantic + trigram search. |
resources | 4,254 | 88 MB | Saved URLs, docs, and reference material. |
observations | 26,883 | 82 MB | Behavioural notes captured during sessions. |
observation_digests | 738 | 27 MB | Periodically compacted observations, to keep recall cheap. |
session_stats | 4,177 | 3928 kB | Per-session metrics: tokens, tool calls, cost, duration. |
session_summaries | 958 | 3240 kB | Generated summaries used to warm-start later sessions. |
conversation_sessions | 4,063 | 2552 kB | Session index — project path, timing, message counts. |
generated_images | 396 | 1080 kB | Image generation log. |
tool_usage | 2,208 | 640 kB | Daily tool-call counts. Drives the tool distribution chart. |
usage_hourly | 1,435 | 296 kB | Hourly rollup. Drives the 24-hour clock. |
model_usage | 450 | 256 kB | Per-model, per-day tokens and cost. |
pi_memories | 0 | 216 kB | Pi scout system memory store. |
project_profiles | 242 | 192 kB | Detected framework and dependencies per project. |
usage_daily | 203 | 112 kB | Daily rollup. Drives the heatmap. |
time_entries | 7 | 64 kB | Manual time tracking. |
bucket_list | 3 | 32 kB | Personal backlog. |
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
- 86
- Host
- Docker, localhost only
The MCP server
- Language
- Python, stdio transport
- Tools exposed
- 37
- Lines of code
- 5,376
Modules
api.py conversations.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 255,284 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 365,271 rows costs real money and real disk — 781 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.