The Code Repository as Working Memory
Explore how treating the code repository as durable working memory preserves decisions and evidence, enabling people and AI agents to build more ambitious software together with continuity and confidence.
I work on several projects at once. When I return to one after working on another, I have to reconstruct where I was. I have to rehydrate which options I ruled out, what I decided not to change, and why the next step was next. That takes time. Worse, when I know a task will start with a long round of archaeology, it has a way of sliding to the bottom of my list. I'm human.
Engineering teams have long used architecture decision records, wikis, and project notes to preserve context. Those help, but even with them I still have to remember what to look for, find it, and work out whether it matches what exists today. I wanted decisions captured as part of the work and carried into the next step so that a future agent, a client, or I could pick up the thread without starting over. That's the problem I built the Evidence-Based AI Engineering Toolkit to address.
AI-assisted engineering makes the gap easier to see. An agent can inspect a codebase, weigh alternatives, resolve an ambiguity, and implement a change. The code survives, but the reasoning is frozen in a conversation or transcript. The next person may have to reconstruct why the architecture was chosen or why something was deliberately left alone.
The toolkit treats the repository as working memory for the delivery process, as well as a home for the code it produces.
Conversation is a poor system of record
Conversation is natural way to work while making changes. It is quick, flexible, and good for exploring ideas. It is a less reliable handoff between stages of software development. Even when a transcript is available, the decisions that matter can be buried among tentative ideas and agent chatter.
In the toolkit, the results become explicit artifacts:
- A feature plan records scope, tradeoffs, and product and architecture decisions.
- A task brief and specification define a coherent outcome, its boundaries, and the relevant parts of the repository.
- Validation evidence and review findings record what was checked and what the reviewer found.
These files give the next person or agent a place to start. They preserve the decisions and evidence needed for the next stage of work.
Artifacts are inter-agent APIs
I think of each artifact as a contract between stages. A feature plan answers what should change, what should be outside the scope, and which decisions need a person to make them. The task specification then checks those decisions against the current codebase: which files own the behavior, which conventions apply, and which tests describe core functions.
Implementation can start from that work instead of repeating every product and architecture discussion. It still needs to verify that the plan fits the code it finds. The reviewer can then compare the implementation with the brief, specification, and validation evidence rather than relying on the implementer's summary.
This makes it easier to change agent harnesses, models, or people without losing the thread. The next worker has a record to inspect and a clear place to challenge an assumption.
Evidence has an order
Durable memory is only valuable when it distinguishes decisions from guesses.
Approved product, scope, and architecture decisions define what the work is meant to accomplish. Repository configuration and tests define constraints. Source code, call sites, git history, and observed conventions provide evidence about how the system currently behaves. External guidance can help, but it does not establish what a particular code base does.
The ordering matters too. A familiar architecture pattern can suggest where to investigate; it cannot prove that a codebase follows the pattern. An old task plan can name likely code landmarks; the next worker must verify them. Passing automated tests does not, by itself, prove that a change meets the approved scope or works in a live workflow.
The repository should store enough evidence for someone else to judge whether an implementation holds.
Working memory needs a lifecycle
If every past plan is mixed with active work, a future agent cannot tell which artifacts describe current state and which describe the past state.
The toolkit separates active artifacts from archived ones. Work remains active while decisions, implementation, validation, or review are incomplete. It moves into an archive after the corresponding completion conditions have been met. Archived plans remain a record of the decisions made at the time; they do not need to be edited every time the code changes.
That preserves two useful distinctions:
- Current code and tests are the authority for current behavior.
- Historical artifacts explain the decisions and evidence that produced that behavior.
The archive does not override the current state, but it can make that state easier to understand.
The cost of this is ...
This approach adds files, model calls, and elapsed time. On a typo fix, that overhead would be too much. On a security change, a feature that crosses several parts of a system, or work likely to be revisited six months later the cost calculation changes.
Pre-agentic development, teams already paid for missing context through repeated discovery, confused reviews, scope drift, rework, and decisions made again. Durable working memory moves part of that cost forward, but it also makes it visible - less costly over the long term.
It makes AI-assisted implementations easier to defend. When someone asks why the code is shaped this way the answer does not have to be "the model decided." The repository shows the approved decision, the evidence available at the time, the boundaries of the task, and the checks used.
With the toolkit, when I return to a project, I see why we chose the path, what was left alone, and whether the rational holds. If the repository can answer those questions, I spend less time reconstructing the last decision and more time making the next one.
Originally published at LegUp Studio.