"We already have agent memory."
I hear this a lot. Claude Code has its memory layer, Cursor has rules, Codex reads AGENTS.md, and most teams I talk to keep a CLAUDE.md that the agent updates as it goes. Under the hood it's all the same thing: markdown files that get loaded into context.
It's a reasonable starting point. But I don't think it's memory, and I don't think it holds up even for one developer. Teams just make the cracks impossible to ignore.
It breaks for one developer too
Forget teams for a second. Here's what happens with just you and your agent over a few months:
- The file bloats, and the agent loads all of it, every session. Every line costs context whether it's relevant to today's task or not. More noise, less room for the code that matters, and the one line you needed gets buried.
- There's no search or recall, just one blob. Real memory lets you ask "have I seen this before?" A markdown file gets read top to bottom or not at all.
- Past investigations and dead ends vanish. Your agent spent an hour last month ruling out the connection pool. That rarely makes it into the file, so next time it rules it out again.
- Switching tools splits your memory. Claude Code in the morning, Cursor in the afternoon, Codex for a quick fix. Three tools, three memory silos, one person. None of them knows what the others learned.
- Stale entries silently mislead. The file says "use the v2 client". The v2 client was removed in June. The agent trusts the file, because that's what it's for.
Now multiply all of that by every person on the team.
Scenario 1: the bug your teammate already solved
Tuesday afternoon, Ana spends two hours with Claude Code chasing a flaky checkout test. Root cause: a timezone default in the test fixtures that only bites after 22:00 UTC. Her agent writes a note in her local memory. She fixes the fixture on her branch.
Wednesday morning, Ben hits a different-looking failure in the billing job. Same root cause. His Cursor session has no idea Ana's agent learned anything yesterday. It starts from zero, reads the same files, forms the same wrong hypotheses, and gets there 90 minutes later.
The sentence that would have saved him is one a human teammate says all the time: "Wait, Ana looked at something like this yesterday, let me check if it's the same root cause."
Per-developer memory can't say that sentence. The knowledge exists, it's just in the wrong head.
Scenario 2: the file that ate the context window
To fix scenario 1, teams commit the memory file. Now everyone's agent writes to one CLAUDE.md. Three months later:
- It's 1,400 lines
- Half of it describes code that no longer exists
- Two sections contradict each other ("always use the v2 client" vs "v2 client is deprecated, use the SDK")
- Every session burns a chunk of context loading it, and the agent still misses the line that matters
Memory files only grow. Agents are great at appending and terrible at deleting, because deleting needs judgment about what's still true. Nobody owns pruning, so nobody prunes.
Scenario 3: merge conflicts in your agent's brain
Four developers, each running an agent that "helpfully" updates AGENTS.md. Every PR now touches the same file. You get conflicts that nobody wants to resolve carefully, so people accept both sides, and the contradictions pile up. Or they accept their side, and someone else's hard-won lesson quietly disappears.
Code has review. Memory files mostly don't, because they feel like notes, not code. But they shape every line your agents write.
Scenario 4: rules without reasons
Look at a typical memory file and you'll see lots of rules and very little reasoning:
- Don't use Redis for the job queue
- Keep retries at 3
Why not Redis? Was it cost, ops burden, a bad incident, a client requirement? Is that reason still true? An agent that sees only the rule will either follow it blindly or, worse, "improve" it away when it seems wrong in context. A new teammate can't challenge it, because the reasoning is gone.
Rules tell the agent what. Decisions need the why, and the why is exactly what .md files tend to lose.
Scenario 5: someone rotates off
Chen moves to another project. His local agent memory, eight months of "this service lies about its status codes" and "the staging DB is shared with QA, don't truncate it", goes with him. It was never in the repo. It was in ~/.claude on his laptop.
On a human team we'd call that a bus factor problem. With agents it's the same problem, just quieter, because nobody notices until an agent confidently repeats a mistake Chen's agent had learned to avoid.
If you're sticking with files, at least do this
If .md files are what you've got for now, here's how to make them hurt less, solo or on a team, starting this week.
1. Keep CLAUDE.md / AGENTS.md for rules only
Short, stable, imperative. Build commands, conventions, hard "never do X" lines. Aim for something a human can read in two minutes. If it's over ~200 lines, it's doing too many jobs.
2. Log decisions with the why, in separate files
Use a docs/decisions/ folder with one small, dated file per decision:
# 2026-09-14: No Redis for the job queue
Context: we run on a single managed Postgres, no ops person.
Decision: use Postgres SKIP LOCKED queue.
Why: one less service to run; volume is ~2k jobs/day.
Revisit if: volume > 50k/day or we hire ops.
Then link it from the rules file: "Job queue: Postgres, see docs/decisions/2026-09-14". Your agent gets the rule cheaply and can read the reason when it matters. The "revisit if" line is the part that stops future agents from blindly following, or blindly undoing, it.
3. Write down investigations, not just fixes
When an agent session finds a non-obvious root cause, ask it to write a 5-line note: symptom, root cause, how it was confirmed, fix, where. Put those somewhere shared and searchable (a docs/investigations/ folder works fine). Then add one rule to CLAUDE.md:
Before debugging, search docs/investigations for similar symptoms.
That single line gets you a surprising amount of "a teammate looked at this yesterday."
4. Make agent edits to memory files go through review
Treat changes to rules files like code. Small diff, a reviewer, a reason in the PR. If agents propose memory changes, have them propose, not commit.
5. Prune on a schedule
Once a month, someone (or an agent with a human checking) goes through the rules file and asks of each line: is this still true, and would we miss it? Delete aggressively. Stale memory is worse than no memory, because the agent trusts it.
6. Write memory for the next person, not for yourself
A good test: would a new teammate's agent, on day one, make a better decision because of this note? If the note only makes sense with your context, it belongs in your head, not in shared memory.
The real gap
Per-developer .md memory solves "my agent forgets what I told it." That's a real problem, and the tools handle it well now.
The problem teams hit next is different: my agent doesn't know what my teammates' agents learned. Different tools, different laptops, different sessions, same codebase. The tips above make files hurt less, but they are still files: no recall, no search, one blob per tool. Real memory should let any agent, yours or a teammate's, ask "have we seen this before?" and get an answer.
How is your team handling this? Are you still on files, or have you moved to something else? I'd genuinely like to hear what works.
I'm building an open-source take on shared team memory for agents: palacememory.com (GitHub).
Top comments (0)