Agent memory

I run five to eight Claude Code sessions in parallel, and each one used to start from scratch: it did not know what we decided yesterday, what the neighboring session was doing or how we had already fixed a similar bug. The memory solves this without a separate service: it is a folder of markdown under git that the agents write to themselves.

Hooks bring in what is needed without being asked. On start a session gets a primer, the project card and the day’s checkpoints from neighboring sessions, and on every prompt the search adds up to three links if it finds something relevant. Facts are written only through a script: the file is append-only and ids are issued without races between sessions.

Every 20 minutes a session rewrites its checkpoint. Closing rituals roll checkpoints up into a daily log, days into a week, weeks into a month and a quarter, with decisions (ADRs) and lessons alongside. Search on SQLite FTS5 ranks decisions and lessons above raw logs.

I cut the session start context from 21,700 to 12,000 tokens. The memory now holds 1,868 facts, 32 decisions, 263 lessons and over 2,000 commits. There are no screenshots of the real memory here, because it holds work and personal data, so a diagram stands in for them.