Building the session record

This is the third part of the series, and the one I’m still living inside. Part 1 named the gap; Part 2 mapped how twelve other projects approach it. This part is the build log for the thing I actually made to fill it — and unlike the other two, it isn’t finished, because the project isn’t.

”Keep the byte-faithful transcript as ground truth. Everything clever is an optional layer on top.”

The project is claude-code-session-history. The one-line thesis, carried over from Part 2: keep the lossless, vendor-neutral transcript as the source of truth, and treat distillation as a derived layer. Where the field stores summaries and discards the record, this stores the record and makes summaries optional.

Note — this post is a work in progress. I’m publishing the spine now and filling in the sections as the project reaches milestones, rather than waiting for a tidy retrospective that (per Part 1) I’d only misremember anyway. Consider the headings below a table of contents I’m committing to.

§1 · The shape of it

The system is a capture side and a read side. Capture is a set of lifecycle hooks that fire on every session event and write, as they happen, to a document store; at session end they also push a summary plus the full transcript to object storage. The read side is a small web app for browsing it all back. Two stores, no columnar tier, no message queue — deliberately the lightweight middle that Part 2 argued for.

More on the event model and why it mirrors Langfuse’s observation → trace → session vocabulary — coming soon.

§2 · Why a document store plus object storage

The choice that everything else follows from. The transcript is kept byte-faithful — a copy of the agent’s own record, not a re-serialisation — and the metadata lives beside it in a store I can query without standing up a database cluster.

The full write-up of the storage decision (and the alternatives I rejected) — coming soon.

§3 · The parts I stole, honestly

Part 2 was partly reconnaissance for this section. The recall ideas worth adapting — Mem0’s ADD/UPDATE/DELETE reconciliation, Graphiti’s bi-temporal provenance, Letta’s sleep-time reflection, Basic Memory’s defragmentation — are all things that can sit on top of a faithful transcript without inheriting anyone’s graph database.

Which of these actually made it in, and how they behave over a real corpus — coming soon.

§4 · What’s next

Semantic recall over the archive, an MCP surface so a live session can query its own past, and the honest reckoning with the scale ceiling of the lightweight approach.

Written as it ships.

This is Part 3 of The Session Record, and the only one still open. Start at Part 1, or read Part 2 for the field it grew out of.