STRATUM: Repository Memory for a Coding Agent — Notes on Bug Causes and Dead Ends That Outlive the Session

An agent that, at the end of its work, writes down the root cause it found and the approaches that failed into persistent storage next to the code — and a new session (even a different, weaker model) that reads those notes before searching — finds the right file noticeably more often and burns noticeably fewer tokens. STRATUM is a sketch of that kind of memory: a store living next to the repository plus nine tools the agent uses to read and write it. The key idea: a context window is not memory. The window is a single-run cache; memory has to survive between sessions.

The familiar pain: you open a fresh agent session and it starts from scratch. It rereads the same files, walks into the same dead end, and forgets the cause it spent two hours digging up yesterday. The problem isn't that the window is small: no matter how big you make it, it gets wiped along with the session. Code search (RAG, text search) shows you what's in the repo, but it doesn't keep what the agent learned about it and where it already got burned.

The method comes in three moves. In the first session the agent investigates the task and at the end writes two kinds of notes: the root cause (root cause analysis, RCA) and the failed attempts, with an explanation of why they didn't work. The store links the notes to the files they touch. In the second session the agent checks the notes first, so the search starts with a hint.

STEP 1 (session 1): The agent investigates the task → at the end it writes "root cause (rca)" and "failed attempt (failure)" notes linked to files
STEP 2: Context resets (new session, possibly a different model)
STEP 3 (session 2): The agent searches the repo + reads the notes → reaches the right file faster
STEP 4: Every tool response reports what was returned, how much is left, and what it cost (pagination and budget)
STEP 5: At the end of the task the agent appends new notes again

In the paper this is a code prototype (SQLite, tools exposed over the MCP protocol). But the gist of steps 1–3 works with a plain file of notes and a couple of lines in the agent's instructions.

First, the boundaries. The method shines where the agent keeps coming back to the same project and where sneaky bugs with non-obvious causes show up. On one-off scripts and small projects that fit entirely in the window, the payoff will be modest.

Task: You run a small Django online store that takes payments through Stripe. On Tuesday Claude Code spent two hours figuring out why payment confirmations sometimes never arrive. Turns out Stripe resends the webhook and the handler isn't idempotent. On Thursday the same thing pops up with FedEx shipping updates, and the new session heads off to check the firewall, nginx and environment variables again — the exact same loop it already walked.

Prompt (at the end of work, session 1):

The task is closed. Before you finish, append two entries to docs/agent-notes.md.

1. ROOT CAUSE (rca): what exactly is broken, in which file and function, how to recognize it, and how it was confirmed.
2. DEAD ENDS (failure): what was checked and didn't pan out; one line per attempt: "checked what — why it missed".

For each entry list the files it concerns and the date. Keep it short and factual, no retelling of how the work went.

Prompt (at the start of a new session):

Before searching the code, read docs/agent-notes.md. Pick the entries that concern the files or symptoms of this task. Tell me which entries you found and which of them you'll use. Don't repeat checks from the "dead ends" section unless there's new data.

Result: In the first session the agent appends two structured entries to the file. In the second session it first lists the notes it found and says which ones it's using, then goes straight to the suspicious files, skipping the dead ends that were already checked.

The model's weakness. An agent has no memory between sessions. Everything it figured out stays in the window that's about to close. If you hand it the entire repository up front, it pays for that on every call and still saves nothing.

The strength. An agent reads short notes well and knows how to use them as a hint: "the cause is usually here, don't bother going there". Choosing where to look is the real bottleneck in bug hunting, not the amount of code.

How the method uses this. Notes are the compressed output of an investigation you've already paid for. They're cheap to read and high-value: they narrow the search. The paper's second finding: code structure reveals only half the connections — files that change together often aren't linked by imports. So knowledge of "what breaks together" has to come from history and experience, not just from the code.

Control levers: - What to record: keep the cause and the dead ends; drop the play-by-play of the work, it just bloats the file. - Linking to files → a note is found by location, not by guessing the right keywords. - Date and version → a month later you can tell the entry is stale. - The "don't repeat dead ends without new data" rule → saves attempts, but add a caveat for when the code has changed a lot. - Paged reading: asking the agent to report "what I got, what's left" helps it decide for itself when to stop.

<Role>You are working on the {project} repository. You have a notes log at {log_path}.</Role>

<At_start_of_work>
1. Read the log. Pick the entries related to the files or symptoms of task {task}.
2. Name the entries you found and explain how they change your search plan.
3. Don't repeat checks from the "dead ends" section without new data.
</At_start_of_work>

<At_end_of_work>
Append to the log:
- rca: the cause, file and function, symptoms, how it was confirmed
- failure: what was checked and why it didn't fit, one line per attempt
- files: {file_list}, date: {date}
Facts only. If you're not sure about the cause, mark it "hypothesis".
</At_end_of_work>

<Report>
When reading the log and the code, report: what you got, what's still unread, and what it cost.
</Report>

Fill in {project}, {log_path} (for example, docs/agent-notes.md) and {task}. The "hypothesis" tag is there so that a wrong entry doesn't poison future sessions — the authors call this out as the main risk.

🚀 Quick start — paste into the chat:

Here's a template for an agent notes log. Adapt it to my project: [your project and stack].
Ask me questions to fill in the fields.

[paste the template above]

The LLM will ask where the log lives, which files in your project are the most tangled, and how you separate hypotheses from confirmed facts — because the method rests on tying notes to files and on trusting the entries. It will take the structure from the template and tune the instructions to your repository.

⚠️ The experiment is small: eight bugs from two libraries, and the answer counted was the name of the file containing the cause. That doesn't prove the same will happen on a new task: in the test the agent re-diagnosed the same symptom rather than solving a new problem.

⚠️ Notes can backfire: a wrong entry poisons the following sessions. The authors flag the risk separately and haven't measured it yet. Content from the web that gets written into memory can carry hidden instructions.

⚠️ Note quality wasn't controlled: the outcome depends on how good the notes are. What happens with sloppy notes wasn't tested.

⚠️ No comparison with a simple summary: a plain recap of the previous session as a baseline wasn't tried. There's no telling how much of the gain comes specifically from the "cause + dead ends" structure.

⚠️ The paper is a sketch: most of the system (eviction management, the nine tools, importance scoring) hasn't been built or tested; the authors call the scoring formula a hypothesis.

The researchers first measured the repositories themselves across six popular projects (Django, Flask, Redis, requests, scikit-learn, Vue core). The result: Django alone takes up 6.2 million tokens — six times more than the largest window. Storing knowledge as indexed text is 10,000–100,000 times cheaper than keeping it inside the model as a cache.

Then they took apart 752 real bug fixes. A typical fix touches two files, and those files together with their direct import neighbors make up 2.7% to 9.9% of the code. Takeaway: the bottleneck isn't volume, it's picking the right part. But 47% of file pairs changed together have no static link at all, meaning half the "map" is invisible if you just parse the code.

The main experiment: Claude Sonnet investigates a bug and writes notes; then a different, smaller model (Claude Haiku) tackles the same symptom from scratch. Without notes it found the file with the cause in 6 of 24 cases; with notes, in 21 of 24, with 4.5 times lower median input-token usage. When 26 notes about different bugs were dumped into the store, the result held at 8 of 8. For comparison, putting the whole repository into the window gave 14 of 16 successes, but a single call cost 3.8 times more than an entire session with memory, and nothing was saved.

The surprise wasn't that notes help, but that one model wrote them and another read them, and it worked. That means the log outlives any session and any model.

🔧 Technique: store dead ends separately → the agent stops going in circles

Keep a "dead ends" section separate from "causes". At the start of a session add: "If you're about to repeat a check from the dead ends section, say what has changed since then."

🔧 Technique: add a "confidence" field → protection against log poisoning

Tag every entry "confirmed / hypothesis". The agent uses hypotheses as hints, not facts, and ranks confirmed entries higher.

Extrapolation to an instructions file (CLAUDE.md): add one line at the end — "Before finishing a task, append the cause and dead ends to docs/agent-notes.md using the template." That way the log keeps growing without you having to nag.

STRATUM: Repository Memory for Coding Agents Beyond the Context Window. Authors: Naser Ezzati-Jivan, Yuvraj Sehgal (Brock University, Canada), Mahsa Panahandeh (University of Ottawa). Replication package: https://doi.org/10.5281/zenodo.23615180. Related work: MemGPT, Model Context Protocol, SWE-bench, the idea of mining co-changed files from version history (Zimmermann et al., 2005).