Every developer on your team runs Claude Code against the same codebase. And every one of those agents learns the same lessons separately. Alice's agent works out why the payments module talks to the ledger the way it does. Bob's agent, one desk over, rediscovers it next week from scratch. Nothing compounds.
We build kgai, a decision-memory plugin for Claude Code, so read this knowing where we stand. But most of what follows is about the problem, because the problem is worth understanding even if you never touch our tool.
The CLAUDE.md trap
Search "share Claude Code memory with your team" and the answer you'll mostly find is commit your CLAUDE.md to git. That advice is genuinely right, for part of the job. CLAUDE.md is loaded into every session, git distributes it to everyone, done.
So teams start stuffing it with everything. Coding standards, sure. But then also why you picked Postgres over DynamoDB, why the retry logic looks weird, why the queue-based import got abandoned in March. It feels like memory. For a few weeks it even works.
Then three things happen.
The file bloats. CLAUDE.md goes into the context of every single session, whole. Every decision you add is a tax on every future conversation, including the 95 percent of conversations that decision is irrelevant to. So people start trimming.
It goes stale. Nobody deletes from a shared instructions file with confidence, because nobody's sure who still depends on which line. Decisions that were reversed months ago sit next to current ones with no marker saying which is which.
And it merge-conflicts, because it's one file with the whole team appending to it, plus agents that helpfully edit it mid-session. You end up resolving conflicts in prose, which git is bad at and humans hate.
None of this means CLAUDE.md is bad. It means it's being asked to do a second job it's the wrong shape for.
Policy is not history
CLAUDE.md is policy. Rules you want enforced right now, in every session. Use pnpm. Don't touch the generated files. Run the linter before committing. Policy should be small, current, and hand-curated, and a file in git is exactly the right shape for it.
Decision history works the other way round. It only grows, most of it is irrelevant to any given task, and its value shows up at retrieval time. You don't want 400 past decisions sitting in your context window. You want the three that touch the module the agent is about to change, surfaced right before it changes it.
Policy gets enforced, decisions get retrieved. Every attempt to make one file do both turns your instructions file into a landfill.
So keep your CLAUDE.md. Make it shorter. Put the history somewhere built for history.
What team decision memory actually needs
Write down the requirements and the list is short.
Append-only records. When a decision gets reversed, the old one shouldn't be edited or deleted. The new one should supersede it by an explicit link, and the old one stays, with the reason it died. "We tried X and it cost us a day" is worth more than X quietly missing.
Recall that knows what's in force. History is kept, but by default the agent should only see decisions that currently apply. Superseded ones surface when you're auditing why direction changed, not when the agent is writing code.
Retrieval by area, not wholesale loading. Ask about the invoice module, get the decisions that shape the invoice module.
Sync that can't merge-conflict. This one is non-negotiable for teams. Multiple people record decisions in parallel, and increasingly their agents do it for them, mid-session, without asking. Any design where two writers can collide on the same file will collide daily.
The gap is real, and it's on the public record
claude-mem is the best-known memory plugin for Claude Code, and it's good at what it does. Its memory lives in a local SQLite file on each machine. Team sharing keeps coming back in its tracker. Issue #2420 asks for a pluggable MySQL backend for team-shared memory, #1415 asks for Postgres, #1981 asks for Turso. The author of #2420 put the pain plainly. Every engineer starts from scratch, and the "collective memory never compounds across the team."
All three were closed without the feature shipping, one of them explicitly as not planned.
There is a paid cloud sync now, and it's worth being precise about it: per its docs it replicates your memory across your own devices through a per-user sync hub. Multi-device, not multi-person. That's not a knock on the maintainers. Single-user memory is their core product, and multi-writer sync is a genuinely different problem, closer to distributed systems than to prompt engineering. But if you came in with the team use case, claude-mem itself still doesn't ship it. What does exist is a third-party project, claude-mem-sync, which adds team sharing on top with a Claude Code plugin and a GitHub Action, and the fact that the community is building this themselves tells you the demand is real.
The general-purpose memory layers (mem0, Graphiti, Cognee) can be bent toward it. You'll be running shared infrastructure and building the decision model yourself, though. We wrote up that landscape honestly in a separate article, including what those tools are better at than we are.
How we approached it
kgai starts from the requirements list above and works backward.
A decision is an immutable, content-addressed event in an append-only log, carrying what changed, why, and what was rejected. Capture is automatic. While you work, the plugin records structural decisions on its own, and a hook catches the case where the model edits code but forgets to record. Trivial edits record nothing, so the graph stays signal instead of noise.
The sync design is the part that answers the team question. Every writer gets their own shard of the log, and sync pushes write-once objects to an S3 bucket you own. One writer per file means two teammates, or ten agents, recording in parallel can never produce a textual conflict. There's nothing to merge, ever. Each machine replays the shared log into the same graph, deterministically, and you can verify that with kg export --canonical on two machines and compare digests. Sync also runs on its own in the background, so nobody has to remember to push what they recorded.
Genuinely contradictory decisions, where two people decided the same thing two different ways, don't get silently last-writer-won. They surface as a branch via kg conflicts, you resolve it by recording one decision that supersedes both, and the branch and its resolution stay in history.
Sync is opt-in and the bucket is yours. Any S3-compatible store works, including MinIO and R2. There's no server of ours in the path and your code never leaves your machines. On the numbers side, we've measured a store of 1,000,000 decisions across 30 writers' shards, and a decision lookup still answers in about 100 ms. That figure is for the decision lookup specifically. Recall and free-text search are slower.
What kgai doesn't do
Git remotes are implemented but experimental. They haven't been through the same testing as S3, so S3 is the path we'd actually recommend to a team today.
Search is lexical. There are no embeddings and no vector index, which keeps the install at zero infrastructure, but it also means phrasing matters more than it would with semantic search. A contextual-search index for large stores is on the roadmap, not shipped.
It's not general agent memory. Preferences, conversation history, arbitrary facts about a user, none of that. The tools in the article linked above do that better, and we'd point you at them for it.
And it's a Claude Code plugin today. An MCP endpoint for other agents is roadmap, not product.
Trying it
Two commands to install.
claude plugin marketplace add kgaidev/kgai
claude plugin install kgai@kgai-marketplace
It runs local-first from that point, no account, no server. When you want the team on one memory, point a project at a bucket you own.
kg init --remote s3://your-bucket/team-kg
kg sync
You can also set one global default remote with kg remote --global, so new projects sync without per-project setup.
If you skip the tool entirely, this is the part that still holds. Your CLAUDE.md is policy, and it's good at that. Team memory is a retrieval problem over an append-only history, and no amount of markdown discipline turns one into the other.
kgai is MIT licensed and the code is at github.com/kgaidev/kgai. Docs, the benchmark, and what still doesn't work well are on kgai.dev.
Top comments (0)