Give your AI coding agent a memory between sessions

This morning I opened a fresh Claude Code session on my research code and typed one line: read the journal, pick up the next thing. Two minutes later the agent had reoriented itself from yesterday’s notes, found the next campaign in the plan index, spotted that the queued task was pinned to a different model than the one it was running as, and asked me exactly one question. I re-explained nothing.

None of that is model magic. It comes from two small pieces of setup that only work as a pair: a rolling journal file the agent reads when a session starts, and a handover ritual it performs when a session ends. If you use an AI coding agent on work that spans weeks, the underlying problem will be familiar. The project outlives every chat session, and each new session is born knowing nothing.

Before this setup existed, every session opened with me re-typing context from memory. Some of it arrived wrong, and all of it already existed somewhere in the repo, unread. The agent was never the bottleneck. The memory was.

Three files and a ritual

Everything lives in a tasks/ folder committed to the repository next to the code. Plain text, versioned in git, as easy for me to read and edit as it is for the agent.

• tasks/journal.md is a rolling session log, newest entry first. One entry per working session, five to eight lines, always the same four fields. Moved: records what actually changed. Runs: lists long-running jobs still alive, or “none”. Next: names the single next action. Open: holds a decision waiting on me, or “none”. The file header instructs whoever opens it, human or agent, to read the top two entries at session start and stop there.
• tasks/todo.md is a plan index, not a plan. One line per campaign (a campaign being any block of work too big for one sitting), with the priority order stated outright. The detail lives in one file per campaign, with checkable items ticked as the work proceeds, never batch-ticked at the end.
• tasks/lessons.md collects numbered rules distilled from past corrections. Each entry ends with a rule that prevents the mistake recurring, not a story about the mistake.
• The /handover skill (a skill is a small reusable instruction file the agent can execute) runs at session end. It appends the journal entry, updates the campaign files, and prints a short handover block I can paste into the next session for a warm start.

The journal being newest-first looks like a small formatting preference. It is the load-bearing design choice, and it is the answer to the obvious objection about growth, which gets its own section below.

Each half covers the other’s weakness

A journal without a closing ritual goes stale, because humans forget to write it, and the days you forget are exactly the busy days most worth recording. A handover without a durable, ordered home is orphaned context: a pasteable block that dies with the chat window it was pasted into. I have produced both failure modes by hand.

So the skill guarantees the write, and the journal guarantees the read. Writing the handover is the agent’s job, not mine, and that allocation of labour is why it happens at all. The context needed to write a good handover is exactly the context loaded in the dying session, and the agent is the one holding it. Asking the human to reconstruct it later is asking the least reliable witness.

What reorientation looked like this morning

The top two journal entries said yesterday ended with a consolidation branch merged and a blog post published, and the Next: line named the campaign file to open.

The todo index gave the queue order. The campaign file at priority 1, a GPU kernel refactoring campaign, opened with a note I had written two days earlier pinning that campaign to a specific model at a specific effort setting, with the reasoning recorded: the failure modes in that kind of work are silent rather than loud, so the model choice was deliberate. The agent was running as a different model. It surfaced the conflict instead of ploughing ahead and asked the one question worth asking: switch models, or override the pin?

It also noticed the index still listed a finished campaign as in progress, corrected the record, and moved on. Total reorientation cost: roughly forty lines of plain text.

The start is set by the end

The generalisable point sits one level up from the files. The quality of a session’s start is fixed by the end of the previous session. At the moment the handover is written, all the context is loaded and the write costs almost nothing. The next morning that context is gone, and rebuilding it is expensive.

If you want a tidy way to hold the pieces in your head: the journal is the agent’s episodic memory, the record of what happened. The lessons file is its semantic memory, the rules that survived. The todo index is its task queue. All of it is plain text in git. There is no database or vector store involved, and nothing I cannot inspect and fix with an ordinary editor.

The obvious objection: the file only ever grows

Every append-only file invites the same worry, that it must eventually balloon. Arithmetic first. An entry is five to eight lines, roughly half a kilobyte. A session a day for a year comes to about 200 to 300 KB and a few thousand lines, which is comfortably inside what git and grep handle without noticing.

Growth does not hurt because of the newest-first ordering. The protocol reads the top two entries and stops, so the cost of starting a session stays constant however long the tail below grows. The agent reads the head of the file, never the whole thing. Searching the older history, on the rare day it matters, is a grep.

Maintenance, when it is eventually needed, is an archive cut rather than sharding. Once the live file feels heavy in an editor, somewhere in the multi-thousand-line range, move the previous year’s entries to something like tasks/archive/journal-2025.md. Splitting the journal monthly would be over-engineering: it fragments grep and buys nothing, because nothing ever reads the middle of the file.

The design rule underneath is worth keeping. Optimise the read path you actually have, the top of the file twice a day, rather than the hypothetical one, random access to an entry from March.

Where to start

Not with the whole apparatus. Start with the journal file alone and a fixed entry format. The four fields above have earned their place, but any fixed set beats free-form prose, because a fixed format is what lets the reader stop after two entries and trust it saw everything that matters. Add the closing skill the day you notice entries going missing, because forgetting to write is the failure mode it exists to remove.

The journal is one piece of a wider set of plumbing around AI-assisted work. One blog system, four sites is another piece of the same story, pointed at publishing rather than research.