I've spent the last six months on an MCP server that gives a repo one shared memory file .. decisions, open questions, standing rules .. that every agent session reads at startup and writes back to. npx klypix-mcp install wires it into Claude Code, Cursor, Cline, whatever speaks MCP. Apache 2.0, repo at the bottom.
The MCP plumbing was the easy part. The interesting mess was everything that broke once more than one agent could write to the same file. The log, in order:
1. Two writers, one file. The app and an agent hook both save the same file. The app's save was a plain overwrite, so it silently destroyed any card an agent captured while the app was open. I lost real decisions before I even noticed. The fix was a three-way merge (base snapshot vs mine vs disk) under a lock, plus one hard rule: the save refuses to write a file that lost a card. That one rule has caught more bugs than any test I've written.
2. The merge kept resurrecting deleted duplicates. De-dup collapsed twin edges, then the next merge brought them right back, because a union of "ours" and "theirs" re-adds whatever one side deleted. Every cleanup quietly undid itself on the next save. I had to teach the merge that an exact twin is the same edge, not two opinions.
3. The same card, serialized twice, turned into a "conflict". A card written by an agent, then re-serialized by the app after opening, produced different bytes for identical content. The merge saw both sides changed vs base and duplicated the card into a conflict twin. My test harness never caught it, because the fixtures were byte-identical by construction. They inherited exactly the assumption that was wrong. Quitting and reopening the actual app caught it in a day.
4. My first eval number was a lie I almost shipped. First measurement said 95% recall vs 0% cold. It never reproduced. After hardening the judge: 0/20 cold, 55% with the brief injected at session start, 73% with brief plus one search round, on 20 frozen questions about decisions actually made in the project. Small n, self-eval, all the caveats apply. But it reproduces, and the 95 is banned from every piece of copy I write now.
5. Retrieval kept ranking a rejected proposal above its rejection. Ask "what's our caching strategy?" and it matched the Redis proposal (high similarity) over the later decision that killed it, which lives in a different card and scores lower. Similarity has no concept of "no longer true". So now corrections supersede instead of delete, and when recall surfaces a card that a later card contradicts, the result carries an explicit warning: matched a STALE card, do not act on it. The agent at least sees the ground is contested instead of getting a confident wrong answer.
6. Thresholds tuned on test data fell apart on real data. Overlap detection passed at 0.5 on short fixture cards. Real cards are long, and the same detector measured about 0.33 in the field. Standing rule since then: nothing counts as verified until it runs against the real six-month file.
Two things surprised me in the other direction. The brief didn't grow linearly. It's a graph you traverse, not a log you replay, so at 900+ cards it's still around 3–5k tokens. And the sessions started coordinating through the file in ways I never designed: lane claims ("I'm editing middleware.ts, shout if you're mid-edit"), one-shot messages that get delivered at another session's next prompt, and cards anchored to git blob hashes that flag themselves as drifted when the code they were decided against moves on. 14 cards are flagged as I type this. The notes confess when they rot.
What six months left me believing, weakly held: the hard problem in agent memory isn't storage or retrieval. It's write contention and truth maintenance. The moment two sessions write, memory is a distributed system, and most memory layers are designed like single-writer diaries.
Where I'd honestly like to be told I'm wrong:
- I picked three-way merge over CRDTs because the file has to stay human-editable and git-versioned. Wrong call?
- Is there a better formal model for supersession than edges plus warnings? Bitemporal databases and event sourcing keep coming up, but both give up the one-readable-file property.
- At what scale does this collapse? 900 cards works. I have no idea about 9,000.
Repo in the first comment.
