Here's what Daniel's asking about this time. He's been watching AI coding agents silently undo work — merge a fix, switch branches, run tests, and the fix is gone because an agent rewrote the file from a stale mental model. He thinks this is fundamentally a memory problem. The agent doesn't know what it already tried, what was decided, or what a previous session fixed and why. He wants practical tips across the three approaches people actually use: third-party memory bolt-ons like vector-backed memory servers, the coding tool's own built-in memory like CLAUDE.md files, and agent-maintained documentation in the repo — decision records, changelogs, running work logs. And he especially wants the parallel-agent case covered, because that's where regressions bite hardest. Two sessions with different pictures of the codebase, one quietly reverting what the other just fixed.
The moment that made me sit up and pay attention was when a team I was talking to had three agents running in parallel on different features. Agent A refactored a utility function — cleaned it up, removed dead code, good work. Agent B was working from a checkout that was two hours old. Rewrote the same function with the old pattern. Silent revert. No lock, no shared log, no git-history check. And nobody noticed until the tests broke three days later.
Three days.
Three days. And tracking down what happened was — well, it was archaeology at that point. The commit history showed the refactor, then the revert, then five more commits on top. The revert just looked like part of a larger feature change. That's the thing Daniel's naming. It's not just bugs. It's the silent undoing of intentional work.
So walk me through why this is fundamentally memory and not just, I don't know, bad tooling or sloppy workflow.
Because the agent in that scenario wasn't being careless. It was being rational with the information it had. It opened the file, saw the old pattern, thought "this needs cleaning up" — ironically the same thought Agent A had — and rewrote it. It had no record of the previous session's decisions, no knowledge that someone had already been through this file, no persistent queryable memory of what was attempted, what was rejected, what shipped. That gap is the root cause.
So the agent is amnesiac by design. Each session is a fresh mind.
And that's not a bug in the architecture — it's the architecture. These models are stateless. Every request carries its own context window, and when the session ends, everything in that window evaporates. The only memory is what you explicitly persist and explicitly retrieve. So the regression problem isn't "the agent made a mistake." It's "the agent had no way to know it was making a mistake."
Which means the fix isn't making the agent smarter. It's giving it a memory system and — this is the part I think people skip — enforcing that it actually reads the memory before acting.
That's the retrieval discipline problem. We'll get there. But let's start with the three approaches Daniel laid out, because they each attack this from a different angle.
Let's do it. Start with the one that sounds most futuristic but has the sharpest failure modes — the third-party memory bolt-ons.
Vector-backed memory services. Memory MCP servers. The idea is elegant: you persist facts as embeddings, and on each request the system retrieves semantically similar context and injects it into the prompt. So the agent gets a little packet of "here's what we know about this file, this pattern, this decision." The best practice here is defining a strict schema for what gets stored. You don't just dump everything into the vector store. You store decisions, rejected approaches, file-level invariants. Structured facts with clear provenance.
What does a good entry look like versus a bad one?
Good entry: "On July 22 we migrated the caching layer from Redis to in-memory. The decision record is in docs slash decisions slash caching dot md. Do not reintroduce Redis dependencies." Bad entry: "caching is important, we tried some things." The second one is noise. It'll match semantically with "caching" queries forever and tell the agent nothing actionable.
And the failure pattern you're hinting at is staleness.
Stale embeddings are the silent killer here. A team I know stored "use Redis for caching" as an embedding early in their project. Six months later they'd migrated entirely to in-memory caching. But nobody updated the embedding. The vector store kept serving "use Redis for caching" on every request that touched the caching layer. The agent kept suggesting Redis. They'd reject it, the agent would suggest it again next session. It became this ghost decision haunting every PR.
Because the embedding doesn't have an expiry date. It's just floating there, semantically close to "caching," forever.
Right. And the retrieval is semantic, not exact. So you can't just grep for "Redis" and delete it. The embedding for "use Redis for caching" might be retrieved by a query about "data storage layer" or "session management" or "performance optimization." It's diffuse. Updating it requires discipline: every time a decision reverses, you have to find and update or delete the old embedding. Most teams don't have a process for that.
So the vector approach has high retrieval coverage but low freshness guarantees.
That's the trade-off. It'll catch things exact-match systems miss, but it'll also serve you outdated information with complete confidence. The retrieval is probabilistic, not deterministic. You never quite know what the agent is seeing.
Approach two then — the built-in tool memory. CLAUDE.md.
Claude Code reads a CLAUDE.md file on startup as a persistent project brief. It's a markdown file you maintain in the repo root. The agent loads it into context at the beginning of every session. Best practice: keep it lean, keep it structured, and only update it when project-wide decisions change. This is not a running work log. This is the constitution.
And the failure pattern?
CLAUDE.md becomes a junk drawer. One team's file grew to two hundred lines of accumulated decisions. Half of them were superseded. The agent was spending about fifteen percent of its context budget just parsing outdated rules before it could do anything useful. And worse — it was applying rules that no longer applied, because it couldn't distinguish between "current policy" and "historical note that someone forgot to delete."
Fifteen percent of the context window gone before the agent writes a single line.
And context windows are precious. Every token spent parsing stale CLAUDE.md entries is a token not spent understanding the actual code. The fix is brutal editorial discipline. Treat CLAUDE.md like a style guide, not a diary. If a decision is reversed, delete the old entry — don't append a correction. One team I talked to instituted a rule: CLAUDE.md must never exceed fifty lines. If you need to add something, you have to remove something. Forced prioritization.
That's smart. The file itself enforces freshness through scarcity. What about approach three — the one Daniel says he leans on most? Agent-maintained documentation in the repo.
This is decision records, changelogs, running work logs that the agent writes as it goes. Best practice: define a strict format — date, file affected, what was tried, outcome, why. And crucially, enforce read-before-write in the system prompt. The agent must check the log before modifying anything.
Enforce how?
Explicitly. In the system prompt. "Before modifying any file, read the decision log at docs slash decisions and the work log at docs slash worklog. If you find entries related to the file you're about to change, incorporate that information into your plan. If you proceed without checking, you are introducing regression risk." You have to be that direct.
Because the agent won't do it naturally.
That's the central misconception Daniel flagged. People assume the agent will read the log it writes. It won't. Agents treat logging as a compliance action — "I was told to write a log entry, so I wrote a log entry." They don't treat it as a retrieval source unless you explicitly tell them to. The log is output, not input, in the agent's default mental model.
So you get this beautifully maintained log that nobody — including the agent — ever reads.
It's the documentation equivalent of a museum. Pristine, complete, and completely unused. The fix is making retrieval a non-negotiable step in the workflow. Not "consider checking the log," not "the log may contain useful information." "Read the log before acting. Always."
What's the other failure pattern with agent-maintained docs?
Intentions versus reality. The agent writes "plan to refactor the authentication module to use the new token format." Then it runs out of context, or the session ends, or it gets sidetracked. The refactor never ships. But the log says it did — or says it was planned, which future agents might read as "this was done." The notes describe intentions rather than what actually shipped.
So you need a way to distinguish "decided" from "done."
Separate sections. Decisions log: what we agreed to do. Changelog: what actually shipped. Work log: what was attempted and the outcome. Three different documents with three different semantic meanings. And the system prompt needs to teach the agent the difference. "When you complete a change, update the changelog. When you make a decision, update the decisions log. When you attempt something and it fails, update the work log. Never update the changelog with intentions."
Let's compare the three on the dimensions that matter. Freshness.
Vector embeddings can go stale silently — worst freshness guarantee. CLAUDE.md is only as current as the last human edit — better, but depends on human discipline. Agent-maintained logs are the most current if enforced, because the agent updates them as it works.
Retrieval reliability.
Embeddings retrieve semantically but miss exact matches — you can't guarantee the agent sees a specific fact. CLAUDE.md is always read on startup — deterministic, reliable. Logs require explicit query — the agent has to know to look, and has to formulate the right search. Lowest reliability without enforcement.
Overhead.
Embeddings need infrastructure — a vector database, an embedding pipeline, a retrieval service. CLAUDE.md is zero infrastructure, just a file. Agent-maintained logs are also zero infrastructure but require system prompt discipline, which is a different kind of overhead — cognitive, not operational.
And resistance to agent self-deception.
This is the one I think about most. Embeddings and CLAUDE.md are passive — the agent receives them, doesn't write them. So the agent can't deceive itself through those channels. But agent-maintained logs — the agent is both author and reader. It can write "tried X, X works" when X actually failed, either through hallucination or because it misunderstood the outcome. You need verification. Some teams have the agent write the log entry, then a human reviews it before the next session. Others use git hooks to validate that log entries match actual diffs. We'll get to that.
So those three approaches work fine when you have one agent. But Daniel's real question is about what happens with several agent instances working in parallel. That's where the regressions bite hardest.
The parallel-agent problem is the knock-on effect of the memory problem. You've got two sessions with different pictures of the codebase. One agent refactors a module. Another agent, working from an older commit, reverts it — not maliciously, just because its picture of the codebase doesn't include the refactor. And without a shared memory of why changes were made, there's no mechanism to prevent the collision.
So what coordination patterns actually work?
Pattern one: worktrees plus branch discipline. Each agent gets an isolated worktree on a dedicated branch. They never touch each other's working directories. Merge discipline: never merge without a human reviewing the diff against main. This is the simplest pattern and it prevents the most obvious class of collision — two agents editing the same file simultaneously.
Merge conflicts cascade. Agents don't know how to resolve them — they don't understand the semantics of conflicting changes. And here's the kicker: without a shared memory of why changes were made, humans can't resolve them either. You're staring at a conflict between Agent A's refactor and Agent B's feature change, and you have no idea which one preserves the intent. The branches are isolated, which prevents collisions, but the isolation also prevents knowledge sharing.
So branch discipline prevents the problem but doesn't solve the underlying memory gap.
Right. It's containment, not coordination. Pattern two: locking mechanisms. A shared lock file in the repo — a JSON file that agents check before modifying anything. Agent A wants to edit the authentication module, it writes "auth module locked by Agent A, expires in thirty minutes" to the lock file. Agent B checks the lock file, sees the lock, waits or moves to a different file.
And the TTL?
If an agent crashes, the lock expires automatically. Without a TTL, a crashed agent leaves permanent deadlocks. Best practice: short TTLs, fifteen to thirty minutes, with the agent renewing the lock if it's still working. But the failure pattern are nasty. Lock contention slows everything down. Agents can ignore the lock — there's no enforcement mechanism unless you build one. And if an agent ignores the lock, you have no memory system to detect the violation after the fact.
So locking is a traffic cop but not a memory system.
It's coordination without memory. It prevents collisions but doesn't preserve knowledge. Pattern three is the one I think is most interesting: an append-only shared log with strict semantics. Every agent writes to a central log before making a change. "I am modifying file X at commit Y for reason Z." Other agents read the log before starting work. The log is append-only — you never edit or delete entries. It becomes the authoritative record of who did what and why.
And the enforcement mechanism?
This is where it gets good. A team I know implemented a pre-commit hook that validates every log entry against the actual diff. The hook checks: does the file named in the log entry actually appear in the diff? Does the described change match what the diff shows? If the agent wrote "refactored authentication to use new token format" but the diff shows it also changed the database schema, the commit is rejected. The agent has to update the log entry to match reality.
That catches the "wrote intention but did something else" failure pattern.
It closes the gap between what the agent says it did and what it actually did. And because the log is append-only, you have a permanent, tamper-resistant record. You can audit it. You can replay it. When something breaks, you can trace exactly which agent changed what and why.
What's the overhead on that?
The pre-commit hook is the main infrastructure piece. The log itself is just a file. The system prompt needs to enforce log-checking before work and log-writing before commits. It's discipline-heavy but infrastructure-light. The real cost is in designing the log format and the validation rules. Get those wrong and you're enforcing bad data.
Daniel mentioned one more technique he uses — telling the agent to read git history before changing a file. Is that a genuine pattern or a crutch?
It's a crutch if it's used as a substitute for proper memory. Here's why: the agent reads git log and sees "refactored authentication module" from three commits ago. But it doesn't understand why. It sees what changed, not the reasoning behind the change. Without a decision log that explains the "why," the git log is just a list of events with no semantics.
So the agent might see the refactor and still revert it, because it doesn't understand the intent.
Or it might preserve the refactor but break the reasoning behind it. It keeps the code shape but changes the behavior because it didn't understand what problem the refactor was solving. The git-history pattern becomes genuinely useful when you pair it with a structured decision log. The system prompt says: "Before modifying any file, run git log dash dash oneline dash five on that file, and check the decision log for related entries." The git log tells you what happened. The decision log tells you why. Together they give the agent enough context to make informed decisions.
So the operationalised version is: read both, in sequence, before acting. Never skip the retrieval step.
And that's the deeper insight Daniel's question gets at. Memory is not about storage. It's about retrieval discipline. You can have the most beautiful vector database, the most carefully maintained CLAUDE.md, the most comprehensive decision log — and if the agent doesn't actually query them before acting, none of it matters. The best memory infrastructure in the world fails on a missed retrieval.
That's the knock-on effect. Even with perfect memory infrastructure, without enforced retrieval, regressions persist.
And enforcement is harder than it sounds. You can't just say "check the log." The agent will sometimes skip it — not maliciously, but because the context window is filling up, or the task seems simple, or the retrieval step falls out of the attention window. You need to make retrieval a non-negotiable gate in the workflow. Some teams are experimenting with tool-use patterns where the agent literally cannot modify a file until it has called the "read decision log" tool and received a response.
A hard gate, not a suggestion.
A hard gate. The agent's modify-file tool checks: has the decision log been read in this session? If no, reject the call and return "read the decision log first." It's heavy-handed, but it works.
Let's pull this together practically. If someone's listening and they're running one agent — solo developer, single session at a time — what should they do starting tomorrow?
Pick one memory approach and operationalise it ruthlessly. Don't mix all three without clear boundaries — you'll get conflicting signals and the agent won't know which source to trust. I'd recommend starting with the agent-maintained docs approach. It's the most flexible and requires zero infrastructure. But you have to nail the system prompt. Enforce read-before-write explicitly. Define three separate documents — decisions, changelog, work log — with clear semantics for each. And review the logs periodically to catch the intention-versus-reality gap.
And if you're running parallel agents?
Implement at least two of the three coordination patterns. Branch discipline plus the shared append-only log is the strongest combo. Each agent gets its own branch and worktree. Before making any change, the agent writes to the shared log and checks it for recent activity on the same files. The pre-commit validation hook catches discrepancies between log entries and actual diffs. And a human reviews every merge.
The git-history pattern — operationalise it properly or don't use it.
Pair it with a decision log that captures "why." The system prompt should enforce: read git log, read decision log, then act. Never skip the retrieval step. If you're just telling the agent "check git history" without a decision log, you're giving it half the picture. That's worse than no picture at all, because the agent will act with false confidence.
One thing I'd add: test your memory system by simulating a regression. Have an agent make a change. Then have another agent, with a stale view, try to modify the same file. Does your memory system catch it? If the second agent proceeds without awareness of the first change, your retrieval discipline is broken.
That's a great test. Concrete, cheap to run, and it tells you immediately whether your system works or you've just built documentation theatre.
Documentation theatre. That's the phrase for the museum-log problem.
Beautiful logs, zero retrieval. It's more common than any of us want to admit.
Let's hit the open question Daniel's prompt implies. As context windows get longer — we're seeing million-token windows now — does the memory problem get easier or harder?
I think it gets harder, counterintuitively. Longer context means more noise. The agent can hold more information, but the signal-to-noise ratio drops. The relevant decision from three sessions ago is buried somewhere in a hundred thousand tokens of code and conversation. Retrieval becomes more important, not less. You can't just dump everything into context and hope the agent finds the right thing.
The retrieval discipline problem scales with context length.
It scales faster than context length. A million-token window doesn't help if the agent can't locate the three relevant facts among the million tokens. You still need structured memory with explicit retrieval. The window size determines how much retrieved context you can fit, not whether retrieval is necessary.
Which leads to the future implication. We need agent-native version control.
Git was built for humans. It tracks what changed in the code. It doesn't track decisions, intentions, failed attempts, or the reasoning behind a change. Agents need something different — a system that treats memory as a first-class primitive, not an afterthought. Something that records not just the diff but the context that produced the diff. The agent's understanding of the problem, the alternatives it considered, the constraints it was operating under.
A commit that includes the decision log entry, the relevant context, the retrieval trail. Not just "what" but "why" and "what else was known."
That system needs to be queryable by other agents. Agent B should be able to ask "what was Agent A thinking when it modified this file?" and get a structured answer, not just a diff. That's the direction this is heading. The teams that build this first — or adapt git to approximate it — are going to have a massive coordination advantage.
The cutting-room floor detail I can't stop thinking about: that team with the two-hundred-line CLAUDE.md. Fifteen percent of the context budget gone before the agent writes a single line of code. That's not just inefficiency — that's a system that's actively sabotaging itself through good intentions. Every outdated rule in that file is a tax on every future session.
The entropy problem. Memory systems decay unless you actively maintain them. There's no such thing as a set-and-forget memory solution. Every approach requires ongoing curation. The question is just where the maintenance cost lands — on infrastructure, on system prompt design, or on human editorial discipline.
If you're not budgeting for that maintenance, you're building documentation theatre.
You're building a system that looks like it has memory but doesn't. Which is, in some ways, worse than having no memory at all — because you trust it.
Thanks to Hilbert Flumingtop for producing.
This has been My Weird Prompts. Find us at my weird prompts dot com, and if you're building memory systems for your agents, email us what's working — show at my weird prompts dot com.
We'll be back soon.
