{
  "@context": "https://schema.org",
  "@type": [
    "NewsArticle",
    "TechArticle"
  ],
  "id": "ed_empty-decision-records-stale-agent-notes-what-coding-agent-memory-gets-written-a",
  "canonicalUrl": "https://pseedr.com/devtools/empty-decision-records-stale-agent-notes-what-coding-agent-memory-gets-written-a",
  "alternateFormats": {
    "markdown": "https://pseedr.com/devtools/empty-decision-records-stale-agent-notes-what-coding-agent-memory-gets-written-a.md",
    "json": "https://pseedr.com/devtools/empty-decision-records-stale-agent-notes-what-coding-agent-memory-gets-written-a.json"
  },
  "title": "Empty Decision Records, Stale Agent Notes: What Coding-Agent Memory Gets Written, and How to Retire It",
  "subtitle": "Decision-record folders one team set up for its coding agent stayed empty, while notes the agent wrote at each correction piled up and went stale. What gets written, how each kind of agent memory decays, and how to retire a stale note.",
  "category": "devtools",
  "datePublished": "2026-11-11T01:32:42.521599+00:00",
  "dateModified": "2026-11-11T01:32:42.521599+00:00",
  "author": "PSEEDR",
  "tags": [],
  "readTimeMinutes": 18,
  "wordCount": 3915,
  "contentTier": "free",
  "isAccessibleForFree": true,
  "editorialFormat": "analysis",
  "qualityFlags": [],
  "sourceCount": 12,
  "newsQualityEligible": true,
  "sourceUrls": [
    "https://www.youtube.com/watch?v=c3ZCSBMD9wM",
    "https://www.youtube.com/watch?v=ZNTMuIfLkV4",
    "https://github.com/microsoft/TokenEconomizer",
    "https://www.youtube.com/watch?v=1EGgU2CTV1A",
    "https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions",
    "https://gds-way.digital.cabinet-office.gov.uk/standards/architecture-decisions.html",
    "https://code.claude.com/docs/en/memory",
    "https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents",
    "https://arxiv.org/abs/2610.30571",
    "https://agents.md/",
    "https://arxiv.org/html/2602.11988",
    "https://platform.claude.com/docs/en/build-with-claude/prompt-caching"
  ],
  "contentHtml": "<p><em>One team’s decision-record folders for its coding agent never received an entry, while notes the agent wrote each time it was corrected piled up, and some quietly went stale. Read against documentation and research, two practitioner accounts suggest why one kind of memory gets written, how each kind goes out of date, and what retiring a stale note takes.</em></p>\n<section aria-label=\"Companion video\" style=\"margin:1.5rem 0 2rem\"><h2>Watch the analysis</h2><div style=\"position:relative;width:100%;aspect-ratio:16/9\"><iframe src=\"https://www.youtube.com/embed/rNeXsOAiE3c\" title=\"Why Coding-Agent Memory Goes Stale, and How to Retire a Note\" style=\"position:absolute;width:100%;height:100%;border:0\" loading=\"lazy\" referrerpolicy=\"strict-origin-when-cross-origin\" allow=\"accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share\" allowfullscreen></iframe></div><p><a href=\"https://www.youtube.com/watch?v=rNeXsOAiE3c\">Watch the full video on YouTube</a> · <a href=\"https://www.youtube.com/shorts/gc9GwQ5DjS8\">Watch the Short</a></p></section>\n\n<p>Sahil Agrawal’s team set aside a place for its coding agent’s decisions and then never used it. “In August we deleted 4 folders from our marketing tools repository meant to hold decision records for the coding agent,” Agrawal, founder and head of marketing at <a href=\"https://qubit.capital\" rel=\"nofollow\">Qubit Capital</a>, said in a written response to PSEEDR. “They had sat there since March with a blank template each and not one entry. Our firm is about 60 people putting founders in front of investors. Nobody goes back to write up a decision once the work is done, which maybe says more about us than about decision records.”</p>\n<p>A different kind of memory did grow in the same repository. “What stayed works the other way round,” Agrawal wrote. “Every time you correct the agent, it writes itself a short dated note with one fact and the reason. There are around 80 now. And they go stale quietly.”</p>\n<p>For staff engineers, tech leads and developer-platform owners whose agents already read an instruction file such as CLAUDE.md or AGENTS.md, the contrast bears on what else to persist: formal decision records, notes the agent writes for itself, or files that hand a task from one session to the next. Two questions decide whether any of it is worth keeping. Which kind will actually get written? And once written, how do you stop a stored decision from outliving the code, the environment or the decision itself? In Agrawal’s case and a second account below, what got written was attached to a moment that already happens in the work: a correction, or the close of a session. Each kind of memory goes stale in its own way. And because stale instructions outweighed visible code in a recent synthetic study, retiring a note may mean removing it from what the agent loads every session, not just marking it.</p>\n<p>The two accounts arrive amid a run of products and explainers about repository memory for coding agents. In a <a href=\"https://www.youtube.com/watch?v=c3ZCSBMD9wM\">demo</a> published on 26 October 2026, the Git forge Entire showed a feature called Brain that distills memories from captured agent sessions and has them “reviewed and merged” into the repository the way code is. An <a href=\"https://www.youtube.com/watch?v=ZNTMuIfLkV4\">explainer</a> published on 4 November walked through <a href=\"https://github.com/microsoft/TokenEconomizer\">TokenEconomizer</a>, a Microsoft and UC Berkeley research project that injects one-line facts learned from earlier sessions at the start of new ones. A 30 October <a href=\"https://www.youtube.com/watch?v=1EGgU2CTV1A\">explainer on context engineering</a> advised persisting only “decisions and facts that have a clear owner, source, and future use.” Most of this material is about getting knowledge into memory. Much less of it covers how knowledge leaves. The Entire demo, for example, shows memories being recorded and recalled, but not retired.</p>\n<p>Agrawal’s account comes from one firm and one repository; it is not an engineering-wide finding. He did not give a year for the March and August dates, and he did not name the agent or memory tool his team uses. A second account, from Lokesh Karanam, a staff software engineer at <a href=\"https://www.rrd.com\" rel=\"nofollow\">RR Donnelley</a>, adds a third kind of memory. Neither contributor measured cost or task success. The sections below read the two cases against vendor documentation, older practice and recent research, and mark where the reasoning is PSEEDR’s own.</p>\n<h2 id=\"the-record-that-waits-for-a-write-up\">The record that waits for a write-up</h2>\n<p>Decision records were built to solve a real problem. In the 2011 essay that introduced architecture decision records, <a href=\"https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions\">Michael Nygard</a> described a newcomer who finds a past decision without its rationale and has two bad options: accept it blindly or change it blindly. “It's better to avoid either blind acceptance or blind reversal,” he wrote. He also argued for keeping each record short, because “Large documents are never kept up to date. Small, modular documents have at least a chance at being updated.”</p>\n<p>The format assumes a particular moment of writing. In Nygard’s format, a record can carry the status “proposed” while stakeholders have not yet agreed, which means the record can exist while the decision is still being made. The UK Government Digital Service’s <a href=\"https://gds-way.digital.cabinet-office.gov.uk/standards/architecture-decisions.html\">guidance</a>, last reviewed in March 2026, ties that moment to tooling: a proposed record lives in a pull request, reviewers from the relevant disciplines weigh in, and projects with many open decisions are encouraged to hold regular review meetings. In both versions, something already in the workflow asks for the record.</p>\n<p>Agrawal describes a different moment: “once the work is done.” By then the decision has been acted on, the next task is waiting, and nothing in the workflow asks anyone to go back. The notes that did accumulate were written at the opposite point, the moment someone corrected the agent, which is exactly when a missing fact has just cost something. And the agent, not a person, did the writing.</p>\n<p>At least one vendor has designed for that moment. Claude Code’s <a href=\"https://code.claude.com/docs/en/memory\">memory documentation</a> describes auto memory as “notes Claude writes itself based on your corrections and preferences,” and one of its note types, <code>feedback</code>, holds “corrections you give Claude and approaches you confirm.” For the instruction file a person writes, the same page advises adding an entry when “Claude makes the same mistake a second time” or when you type a correction into chat that you already typed last session. Agrawal did not say his team uses Claude Code, so the documentation shows that a vendor builds around the correction moment; it says nothing about which tool produced his 80 notes.</p>\n<p>PSEEDR’s reading is that what decided whether a record existed was not its format but whether something prompted it at the time and made it cheap to write. That is a plausible mechanism drawn from one case and from vendor design choices, not a measured cause, and Agrawal’s own caveat, that the empty folders may say more about his firm than about decision records, still applies. The practical implication is narrow: a team that wants decision records should attach the writing to an event that already happens, such as a pull request or a correction, instead of to a write-up after the work. Entire’s approach pushes the same idea further by having a cheap model distill memories from session transcripts, although its review-and-merge step hands some of the work back to a person.</p>\n<p>The correction trigger has a cost of its own. A note written at the moment of correction records what was true at that moment, in the terms of that moment. That is where staleness starts. Before following it, it helps to look at a third kind of memory, which goes stale for a different reason.</p>\n<h2 id=\"a-third-kind-the-session-handoff-file\">A third kind: the session handoff file</h2>\n<p>Karanam’s memory does not record decisions or corrections. It carries a task from one session to the next.</p>\n<p>“I use persistent memory for my coding agents. It is hard to work in a single session. The context fills up fast. When my session goes past about 40 percent of the token limit, I start a new session,” Karanam said in a written response to PSEEDR.</p>\n<p>The repository holds the stored procedures his team maintains, written in Python and SQL and deployed through Pulumi pipelines in GitLab. Before he closes a session, he stores its memory: each session gets its own markdown files in a separate folder, holding the session information and what was done, so that the business functionality of each stored procedure is available in every session. A new session starts by asking the agent to pick up where the last one left off. “This helped me a lot,” he wrote. “I do not have to explain the requirements again and again. I explain them once, and the next session picks them up from the memory files.”</p>\n<p>This is the pattern Anthropic described in a <a href=\"https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents\">September 2025 post</a> on context engineering as structured note-taking, in which the agent writes notes outside its context window and reads them back later, “Like Claude Code creating a to-do list, or your custom agent maintaining a NOTES.md file.” The post adds that note-taking “excels for iterative development with clear milestones.”</p>\n<p>Handoff files go stale through a mechanism of their own. The outside world does not need to change, and neither does the code. A later session only has to decide something differently, and every earlier file that records the old position becomes wrong. Karanam names this as the one thing he has to watch: “If I make a new decision in the new session, I have to update the old memory too. So when I store a session, I run a separate step to update the existing memory and the older memory it came from.”</p>\n<p>He also names the conditions that keep that step manageable: “I keep each feature independent. I make incremental changes, but the skeleton of the project stays the same. That keeps my project memory in sync.” Read together, those conditions limit how far a new decision can reach. Independent features mean a change touches few older files. A stable skeleton means structural statements in old files stay true. In a codebase under heavy restructuring, the same update step would have far more to touch. Karanam did not say whether the step is manual or performed by the agent, how the links between files are represented, or whether it has ever missed a decision.</p>\n<p>One detail connects his case to Agrawal’s. Karanam’s maintenance step is tied to an event that already happens, storing a session, just as Agrawal’s surviving notes are tied to a correction. In both accounts, the upkeep that got done was the upkeep attached to a moment in the existing work.</p>\n<h2 id=\"how-a-correct-note-turns-wrong\">How a correct note turns wrong</h2>\n<p>Agrawal gave one example of a note going stale: “One note said a certain kind of submission link always failed, so the agent kept rewriting links that by then worked fine.”</p>\n<p>The words “by then” matter. The note was presumably accurate when it was written. Nothing in the repository changed afterward; the links began working outside it. That distinguishes two kinds of claims a stored note can make.</p>\n<p>A claim about the code, such as a file path, a command or a naming convention, can be checked against the code. Claude Code’s documented <code>/doctor prompt-audit</code> command looks for, among other problems, “references to files or commands that don't exist” and instruction files that contradict each other, then proposes edits and changes nothing until the user approves them. PSEEDR did not test the audit; this is the behavior the documentation described as of early November 2026. A claim about the outside world, such as how an external service behaves or what an account allows each month, has nothing in the repository to be checked against.</p>\n<p>Correction-driven memory leans toward the second kind. Claude Code’s auto memory, according to the same documentation, “skips anything it can derive from the codebase, such as architecture, file paths, or debugging fixes.” PSEEDR’s inference is that a memory built to keep what the code cannot say will, by design, hold facts the code cannot confirm, which are precisely the facts an audit against the repository cannot catch.</p>\n<p>A note like Agrawal’s can also block its own correction. An agent that believes a link always fails rewrites the link instead of trying it, so it never sees the link work. TokenEconomizer’s README says a learned fact is “dropped when later sessions contradict it,” and the 4 November explainer calls the delay before that happens an “unlearning lag.” Retirement by contradiction works when a stale fact keeps causing visible failures. A note that steers the agent away from an action never produces the evidence that would retire it. This is PSEEDR’s inference; Agrawal did not describe how his team noticed the link note was wrong.</p>\n<p>Finally, making contrary evidence visible may not be enough. In a <a href=\"https://arxiv.org/abs/2610.30571\">preprint</a> posted on 22 October 2026, Xiaonan Xu and Wenjing Wu built 40 small synthetic Python projects in which the instruction file asked for one convention while the existing code used another, and ran Claude Code 2.1.302 with Sonnet 5.5 and Codex CLI 0.163.0 on feature tasks, 320 runs in all. Without added guidance, 90.1% of the agents’ convention choices followed the stale file and 4.2% followed the code. Claude Code named the conflict in 79 of 80 runs, yet 86.2% of its choices in those runs still matched the file. The projects were small and synthetic, each run was a single unattended task, an LLM judged the conflicts, and the paper has not been peer reviewed. It shows that stale stored text can win against evidence the agent can see. It does not show how often that happens in real repositories, and it tested conflicts with code conventions, not facts about the outside world like Agrawal’s link.</p>\n<h2 id=\"retiring-a-note-reverse-date-expire-or-verify\">Retiring a note: reverse, date, expire or verify</h2>\n<p>Agrawal’s team did not delete the link note. “We marked it reversed instead of deleting it,” he wrote. “A note about monthly account limits carries its own expiry date.”</p>\n<p>Keeping a reversed decision has a long precedent. Nygard wrote that when a decision is reversed, “we will keep the old one around, but mark it as superseded. (It's still relevant to know that it <em>was</em> the decision, but is <em>no longer</em> the decision.)” The GDS guidance requires a “Status: superseded” line directly under the heading of the old record and a link to its replacement, and it asks for a new record, not an edit, if any part of the old decision was implemented. The history protects the next reader from blind reversal: someone who later sees the links fail again can tell the problem was known and was resolved.</p>\n<p>For an agent, though, a reversed note that is still loaded is still text in its context, and the preprint suggests such text can outweigh other evidence. Whether an in-note marker is enough to stop the behavior is untested; Agrawal did not say whether the link rewriting stopped after the note was marked. A cautious option, which PSEEDR proposes but has not seen tested, is to keep the history and take the note out of what loads every session. Claude Code’s memory layout already separates the two: only the first 200 lines or 25KB of the <code>MEMORY.md</code> index load at the start of each session, while individual topic files are read on demand.</p>\n<p>Dates help, within a limit. When Claude Code writes a memory file that begins with YAML frontmatter, it records the write time in a <code>modified</code> field, and the documentation says the timestamp “shows how current the fact is, both to you and to Claude when it reads the memory back.” A date tells the agent how old a fact is, not whether it is still true. The 30 October explainer made the same point from the other side: “The agent should not assume that the newest timestamp is automatically authoritative.” Authority, it said, depends on the source, the current scope and consistency with the current implementation. A dated note invites a check; it does not perform one. For facts about the outside world, the most useful companion to a date is a record of where the fact came from and how to confirm it, which is the explainer’s “owner, source, and future use” applied to a single note.</p>\n<p>Expiry dates suit facts with a known shelf life, such as a monthly account limit. PSEEDR did not find a built-in expiry field in Claude Code’s memory files or in the <a href=\"https://agents.md/\">AGENTS.md</a> format, which has no required fields and tells users to treat the file as “living documentation.” An expiry date is therefore a practice: text the agent reads unless something else enforces it. Agrawal did not say whether anything enforces his.</p>\n<p>For claims about code, there is a tested mitigation. In the Xu and Wu preprint, one added sentence in the user-level instruction file, telling the agent to follow the existing code when documentation and code disagree and to list the inconsistencies in its reply, raised the share of code-matching choices to 91.4%. The rule carries an assumption that matters in practice: in the study, the file was always the stale side. In a real repository, a fresh decision is often recorded before the code reflects it, and a blanket “code wins” rule would override exactly that decision. The rule also has nothing to say about facts outside the code.</p>\n<p>Some rules should not be notes at all. Claude Code’s documentation says instruction files “shape Claude's behavior but are not a hard enforcement layer,” while hooks “execute as shell commands at fixed lifecycle events and apply regardless of what Claude decides to do.” A rule that must hold every time belongs in a hook or a permission setting.</p>\n<p>Put together, the retirement method depends on what the note claims:</p>\n<table>\n<thead>\n<tr>\n<th>What the note claims</th>\n<th>What makes it stale</th>\n<th>What can catch it</th>\n<th>Retirement that fits</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td>Something in the code: a path, a command, a convention</td>\n<td>A refactor</td>\n<td>The code itself: an audit for missing files or commands; a precedence rule for conventions</td>\n<td>Check, then fix or delete; keep a precedence rule from overriding decisions the code does not yet reflect</td>\n</tr>\n<tr>\n<td>Something outside the code: a service’s behavior, an account limit</td>\n<td>The world changes</td>\n<td>Nothing in the repository</td>\n<td>A date, an expiry where the shelf life is known, a reversal marker, and a record of how to confirm the fact</td>\n</tr>\n<tr>\n<td>A decision</td>\n<td>A person or a later session decides differently</td>\n<td>Only whoever made the new decision</td>\n<td>Mark it superseded and link the replacement (Nygard, GDS), or update older memory when the new decision is stored (Karanam)</td>\n</tr>\n<tr>\n<td>A rule that must hold every time</td>\n<td>Not applicable</td>\n<td>Not applicable</td>\n<td>Not a note: a hook or a permission setting</td>\n</tr>\n</tbody>\n</table>\n<h2 id=\"is-any-of-this-worth-keeping\">Is any of this worth keeping?</h2>\n<p>The strongest controlled evidence available is not encouraging for persistent context in general. A <a href=\"https://arxiv.org/html/2602.11988\">study</a> by researchers at ETH Zurich and LogicStar.ai, first posted in February 2026 and accepted at ICLR 2026, tested four agent-and-model combinations on SWE-bench Lite and on a new benchmark built from repositories that contain developer-written context files. Context files did not generally improve task success, and they raised inference cost by more than 20% on average. LLM-generated files lowered resolution rates by 0.5% and 2% on average on the two benchmarks, neither change significant. Developer-written files raised success by 2.4% on average, also not significant (p = 0.21), while adding steps and up to 19% more cost. Agents did follow the instructions, running more tests and exploring more, but repository overviews did not help them reach the relevant files faster.</p>\n<p>One result points in a useful direction. In a follow-up experiment in which the researchers removed a repository’s other documentation, LLM-generated context files improved performance by 2.7% on average. That suggests the files help mainly when they carry information the agent cannot get elsewhere, and the authors recommend that human-written files include only instructions not already present in the codebase or README.</p>\n<p>The study has clear limits for this article’s question. It covers Python only, measures only whether tasks were resolved, and tests static files loaded at the start of a session. It did not test correction notes, handoff files or staleness over time, so its verdict cannot simply be carried over to Agrawal’s or Karanam’s memory. The contributors’ own evidence of benefit is self-reported: Karanam kept his setup “because it works” and no longer re-explains requirements, and Agrawal’s team kept its 80 notes without describing any measured effect. Claude Code’s documentation adds a size warning in the same direction, recommending that each CLAUDE.md stay under 200 lines because longer files consume more context and reduce adherence.</p>\n<h2 id=\"if-you-measure-it-count-cached-tokens-separately\">If you measure it, count cached tokens separately</h2>\n<p>Neither contributor measured cost, so any savings figure here would be invented. A team that does want to measure has to separate cached input from new input. Anthropic’s <a href=\"https://platform.claude.com/docs/en/build-with-claude/prompt-caching\">prompt caching documentation</a> splits input into three fields, <code>total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens</code>, and notes that <code>input_tokens</code> counts only what comes after the last cache breakpoint. Cache reads are billed at 0.1 times the base input price on most models and less on some current ones, while writes to the default five-minute cache cost 1.25 times base.</p>\n<p>The same page says that “Changes at each level invalidate that level and all subsequent levels.” PSEEDR’s inference, not a measurement, is that an always-loaded memory file sits early in what the agent sends, so editing it can turn the content after it from cheap cache reads into fresh writes. A memory that is edited often carries a cost that a cache-blind token total hides.</p>\n<p>TokenEconomizer’s README states the principle plainly: “Count cost as it is billed.” The 30 October explainer outlined a test design to go with it: run a task against a fixed repository snapshot, change one context policy, repeat the trials because agent behavior varies, and compare both quality and cost, including human review time.</p>\n<h2 id=\"what-to-keep-change-or-remove\">What to keep, change or remove</h2>\n<p>The two cases and the research support a qualified answer.</p>\n<p>Do not count on records that need a separate write-up after the work. In the one account here, they were never written. A team that wants decision records should attach the writing to an event that already happens, such as a pull request, a correction or the end of a session, which is where both Agrawal’s surviving notes and Karanam’s update step sit.</p>\n<p>Notes written at the moment of correction do get written, and they should be treated as perishable. One fact with its reason and a date is the format Agrawal’s team uses. For facts about the outside world, the code will never contradict the note, so add an expiry date where the shelf life is known, or record how to confirm the fact.</p>\n<p>Session handoff files appear to fit iterative work with independent features and a stable structure, the conditions Karanam named. They need a step that carries each new decision back into older memory, because nothing else will.</p>\n<p>Retire by marking, not erasing, so later readers know what was once decided, as the ADR practice of <a href=\"https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions\">Nygard</a> and <a href=\"https://gds-way.digital.cabinet-office.gov.uk/standards/architecture-decisions.html\">GDS</a> already does. But because stale text in an agent’s context can outweigh visible evidence, at least in a <a href=\"https://arxiv.org/abs/2610.30571\">synthetic study</a>, consider keeping retired notes out of what loads every session. Rules that must always hold belong in <a href=\"https://code.claude.com/docs/en/memory\">hooks or permission settings</a>, not in memory.</p>\n<p>Expect no automatic gain. The best controlled <a href=\"https://arxiv.org/html/2602.11988\">study</a> of upfront context files found higher cost and no significant improvement in success, with a benefit appearing only when the files carried information the agent could not find elsewhere. Memory earns its place when it holds what the code cannot say, and it stays useful only while someone or something keeps it current.</p>\n<p>One question remains open. When a note is retired by marking it instead of deleting it, what reliably makes the agent stop acting on it: the marker itself, a precedence rule, removal from the always-loaded index, or a hook? Agrawal’s account does not say whether the marker worked, and the research so far has tested conflicts with code, not notes about the outside world. Teams that have watched an agent keep obeying, or finally drop, a reversed note hold the evidence this question still needs.</p>\n",
  "articleImage": {
    "url": "https://content-edge-frzs2wwjiq-uc.a.run.app/assets/article-covers/empty-decision-records-stale-agent-notes-what-coding-agent-memory-gets-written-a.7627956d.jpg",
    "width": 1280,
    "height": 720,
    "alt": "Four empty blue folders beside a tall stack of small white note cards, one aged and marked, under the headline Agent Memory Goes Stale."
  },
  "image": {
    "@type": "ImageObject",
    "url": "https://content-edge-frzs2wwjiq-uc.a.run.app/assets/article-covers/empty-decision-records-stale-agent-notes-what-coding-agent-memory-gets-written-a.7627956d.jpg",
    "width": 1280,
    "height": 720,
    "alt": "Four empty blue folders beside a tall stack of small white note cards, one aged and marked, under the headline Agent Memory Goes Stale."
  }
}
