Why your AI coding agent forgets team decisions (and what to store instead)
Teams running Cursor and Claude Code side by side hit the same wall.
CLAUDE.md works for one seat. It does not carry decisions across seats. One agent learns why you dropped Redis. Another suggests Redis tomorrow.
Rules files are static. Team context is not.
The bottleneck moved
Model quality jumped. Shared context did not.
What still burns time every week:
- Re-explaining the same architecture tradeoff at the start of a session
- Switching tools (Cursor to Claude Code, or Codex) and losing what the last agent learned
- Alice fixing a migration bug on Monday; Bob's agent rediscovering it on Tuesday
- Treating a third-party "memory SaaS" as fine when the team is under GDPR, on-prem, or client NDAs
Built-in memory is usually per machine or per repo. Rules files are hand-maintained and diverge. Neither is a shared team store across tools.
What is worth persisting
Chat logs are a bad primary memory. They are long, noisy, and full of abandoned ideas.
Prefer small, durable records:
- Decision - what you chose
- Reason - why (the constraint that would change the answer)
- Scope - which repo, service, or env it applies to
- Provenance - who or which agent wrote it, and when
"Use Postgres" gets ignored or overridden.
"Use Postgres because we need row-level locks for billing" actually changes what the next agent does.
Store conventions the same way: naming, error handling, "never call X from Y", known landmines. Skip ephemeral brainstorming unless you explicitly mark it as a decision.
Local vs shared
Local memory is enough for a solo workflow: one machine, one developer, one tool chain.
Shared memory becomes useful when:
- More than one person runs agents on the same codebase
- You hop between clients that do not share a private store
- You need an audit trail of what the agents were told
Shared does not have to mean "someone else's cloud." For many teams the right shape is local-first for individuals, plus an optional team store on their own infra.
A minimal MCP memory shape
If you expose memory over MCP, keep the tool surface small. A few task-shaped tools beat mirroring every storage API.
A workable set:
- write - store a memory with decision, reason, scope, tags
- search - retrieve by query (hybrid lexical + embedding works well)
- recall - fetch by id or recent for a scope
- forget / supersede - mark stale entries so agents stop treating them as truth
Always return provenance with results. Agents (and humans) need to know whether a hit is from last week or last year, and who wrote it.
Failure modes to design for
Stale memory. A decision from six months ago can be wrong now. Prefer supersede over silent overwrite, and surface age in recall.
Over-recall. Dumping twenty memories into every prompt wastes context and confuses the model. Retrieve top-k with a relevance floor; let the agent ask again if needed.
No ownership. If anyone can write and nothing is reviewed, garbage accumulates. Team stores need seats, and ideally a light review path for high-impact conventions.
Chat as memory. Persisting full transcripts looks complete and performs poorly. Extract decisions; leave the rest in the session.
Wrong layer. Putting secrets, raw PII, or full customer data in agent memory is a policy bug, not a feature. Keep memory to engineering decisions and project conventions unless you have a deliberate compliance story.
A practical habit
When an agent (or a human) makes a lasting call, write one line in this shape before you move on:
Decision: X. Reason: Y. Scope: Z.
That habit compounds whether you keep notes in a repo file, a ticket, or a memory server. The format matters more than the product.
I work on Palace, a local-first MCP memory layer (open-core) with an optional self-hosted Team mode on your infra. Details: palacememory.com.
Top comments (0)