Humans rely on working memory for what is active now and long-term memory for durable knowledge. Many AI coding agents begin each session with only the first kind.
That means decisions, bugs, architectural trade-offs, and failed approaches can disappear as soon as the session ends.
I built a small project-memory system with two Markdown layers:
- A compact file that is read at the start of every session. It contains short summaries of durable past work, newest first.
- One detailed file per session, opened only when the current task makes it relevant.
The first version failed because it remembered too much. Clean test runs, temporary logs, and one-off explorations accumulated until useful context was buried in noise.
The fix was a stricter definition of memory. Save shipped changes, decisions, gotchas, and rules the next agent needs to honour. Leave out transient process.
The files alone are not enough. The agent needs an explicit instruction to read them, so the workspace guidance must make memory retrieval part of the normal startup routine.
General-purpose assistant memory is closer to a user profile: it may remember a language preference, but not why a team chose one architecture over another three sprints ago. Project memory needs to be shared, portable, and grounded in the repository.
The next challenge is forgetting: stale context needs a safe way to expire before it becomes another form of noise.