Structured agent memory: turning project experience into reusable notes
Watch the source walkthrough on YouTube.
An agent session often discovers project details that are easy to lose: why a test is flaky, which service owns a boundary, or what a migration changed. A simple way to preserve that context is to turn selected findings into concise, versioned notes that a later session can inspect.
This is not a replacement for every kind of memory. Claude Code already supports memory files and automatic memory. Retrieval systems can also use metadata, reranking, summaries, and graph structure. The useful question is whether a project needs a more deliberate record of conclusions than a collection of raw documents provides.
Notes as a compiled artifact
“Compilation” is a helpful metaphor here. Raw session output is like source material: it contains observations, commands, dead ends, and partial conclusions. A maintained note extracts the parts that remain useful, such as a verified constraint, a working recovery procedure, or a dependency relationship.
Preprocessing can reduce repeated reading in a later session, but it has a cost. A note can become stale, omit important context, or preserve a mistaken conclusion. Treat it as an artifact that needs maintenance, not as an automatically correct memory layer.
A small working loop
At the start of a task, load only the notes relevant to the area being changed. During the work, record evidence from code, tests, logs, or documentation. At the end, update a note when there is a durable conclusion worth keeping.
Each entry should say what it claims, where the evidence came from, and when it was last checked. Contradictions need an explicit resolution, and superseded notes should be removed or marked obsolete. This keeps the next session from inheriting an unexamined instruction.
Structured notes can link to one another when relationships matter. A project does not need a full knowledge graph before this becomes useful. A clear file structure and links to code, issues, and decisions are often enough to begin.
Files, retrieval, and scale
Plain files have real advantages: they are easy to read, diff, review, and version in Git. They are not automatically the best storage choice. A distributed or multi-user system may need synchronization, access controls, conflict handling, and a faster search layer as the corpus grows.
Naive retrieval over raw chunks can be insufficient when an agent needs a project decision rather than a similar paragraph. In that case, curated notes and summaries can complement retrieval. They do not make retrieval obsolete, and they need the same attention to provenance and freshness.
Measure the trade-off
Well-chosen short notes may reduce repeated file reading and help an agent start with better context. Loading them still uses tokens, and writing or reviewing them takes time. Measure the effect on the project: task success, time to completion, repeated failures, context size, and maintenance effort.
Start with one small area of the repository. Keep findings inspectable, tie them to evidence, and review them after meaningful changes. The result is a durable project record that can complement an agent’s built-in memory instead of asking every new session to reconstruct the same history.