What is shared memory for AI agent teams?
Shared memory is knowledge produced by doing the work, stored once and recalled by every agent on the team: why a decision was made, what broke last time, where a feature lives. For why a single agent forgets in the first place, see why AI agents forget. It is different from instructions, which tell an agent how to behave, and from document search, which finds what someone wrote on purpose.
The test is simple. A teammate's agent made a decision on Tuesday. On Thursday you open a fresh session in a different tool. Does your agent know about Tuesday before it acts? If the answer depends on someone remembering to tell it, the team has no shared memory, only individual ones.
The cost of not having it is quiet. Agents re-ask questions the team already answered, repeat fixes that were already rejected, and search for files someone found last week. Each instance is small; across a team running many sessions a day, it is most of the friction people blame on the model.
What does Claude Code share across a team today?
Claude Code has two memory systems, and only one of them is shared. CLAUDE.md files hold instructions you write; a project CLAUDE.md is shared with the team through source control. Auto memory holds notes Claude writes itself from corrections and preferences; Anthropic's documentation says it is "machine-local", stored under ~/.claude/projects/<project>/memory/, and "not shared across machines or cloud environments". The same page notes that both are treated "as context, not enforced configuration".
| Mechanism | Written by | Shared with | Loaded |
|---|---|---|---|
| Project CLAUDE.md | You | The team, via git | Every session in the repo |
| CLAUDE.local.md | You | Only you, in this project | Every session in the repo |
| User rules and CLAUDE.md in ~/.claude | You | Only you, every project | Every session |
| Managed CLAUDE.md | Your organisation | Everyone on managed machines | Every session |
| Auto memory | Claude | Only you, on this machine | First 200 lines or 25KB of the index |
sourcesClaude Code docs: memory
Why is a shared CLAUDE.md not team memory?
Because instructions and learned knowledge behave differently. Instructions are few, stable and apply to every session. Learned knowledge is many small facts, each relevant to a few tasks, arriving every day. Push the second into the first and the file grows until the agent skims it, merge conflicts appear in a text file nobody owns, and the reason behind each line is lost.
A team memory needs three things a file does not give you. Ranking, so an agent gets the five facts that matter for this task rather than all five hundred. Capture at the moment of decision, with the reason and a link to the work that produced it. And reach beyond one tool: a teammate in Cursor or ChatGPT should recall what was decided in Claude Code.
CLAUDE.md still earns its place. Keep it for the few things every session needs: build and test commands, code style, the rules you never want broken, and a short instruction to recall before acting. When a line only matters for one kind of task, it belongs in memory or in a skill instead.
What should a team memory store?
Store what the next person would otherwise have to rediscover or re-decide. Leave out what belongs elsewhere.
| Kind | Example | Keep it? |
|---|---|---|
| Decision, with the reason | Keep the checkout button green; red tested worse | Yes |
| Correction | The signature header moved in v2; read X-Sig | Yes |
| Preference or convention | Release notes lead with what users can do now | Yes, or a skill if it is a procedure |
| Location | Checkout UI lives in web/components/checkout/ | Yes, as a map entry |
| Whole transcripts | A 4,000-line session log | No: store the decision, link the work |
| Secrets and credentials | API keys, passwords | Never |
| Personal data | Customer details | Only if your data rules allow it |
- One fact per memory, so it can be ranked, corrected or forgotten on its own
- The reason next to the fact, because a rule without its why gets broken first
- A link to the task or decision that produced it
- An honest importance score: most things are not a 10
How should agents read and write shared memory?
Two habits do most of the work: recall before acting, capture on the way out. Recall means the first move on any task is a query for what is known and where things live, ranked by meaning, importance and recency. Capture means the step where a decision is made records the decision and its reason as part of finishing that step, not as a chore someone remembers on Friday.
Make capture structural where the reason matters. A step that cannot close without a recorded why is worth more than a policy asking people to write things down. Keep the store healthy as it grows: merge duplicates, forget what is wrong, and let unused entries fall in ranking.
Whatever store you choose, judge it by a few questions. Where does the data live, and who can read it? Can two teams be kept apart? Does recall rank by relevance, or return everything? Can a wrong memory be corrected without editing a file by hand? And does it work from every client your team uses, or only one?
How do you set up shared memory for a Claude Code team?
There are three common routes. A memory folder committed to the repo is simple and reviewable, but it has no ranking and only works in that repo. An MCP memory server gives every client a shared store; check where it keeps data and how it isolates teams. A workflow engine with a built-in brain ties memory to the work itself. The steps below use ConvOps, which is an MCP server, so the same memory is available in Claude Code, Codex, Cursor, ChatGPT and other MCP clients.
- 1
Connect Claude Code
Add the server once per machine. You sign in with OAuth on first use.
claude mcp add --transport http convops https://mcp.convops.app/ - 2
Invite the team to one workspace
Memories belong to a workspace. Everyone who is a member recalls the same store.
- 3
Tell the agent to recall first
Two lines in the project CLAUDE.md are enough; the instruction file stays short because the knowledge lives elsewhere.
Before any task: context_query("<task keywords>"). After a decision: memory_store(content, category, workspace). - 4
Capture at the step
When work runs through a workflow, the advance that finishes a step can carry the decision and the why. A require_context gate makes it mandatory where it matters.
- 5
Map where things live
Routes record where code, docs and data live for a kind of work, so no session searches for them again.
- 6
Review weekly
Consolidate duplicates and forget what turned out to be wrong. Memory is an asset only while it stays accurate.
Who can see shared memory, and how is it controlled?
In ConvOps, every memory belongs to one workspace and every write lands in exactly one. Members of that workspace can recall it; recall can search across every workspace you belong to, while ownership stays with each workspace. Memories can be filed under a project, so a project read returns only that project's knowledge.
Nothing is captured behind your back: automatic capture is a set of workspace toggles that ship off. Agents store memories when a step or an instruction tells them to. Memories are categorised (decisions, learnings, corrections, preferences, procedures, context) and carry an importance score, which recall uses with meaning and recency to rank results. ConvOps does not run AI models; your client's model reads what recall returns.
Frequently asked questions
Does Claude Code have shared team memory?
It shares instructions: a project CLAUDE.md travels with the repo through git. Its auto memory is machine-local and not shared across machines, according to Anthropic's documentation. Shared learned knowledge needs a separate store, such as an MCP memory server.
Can different AI tools share one memory?
Yes, if the memory lives behind a protocol they all speak. With an MCP server, Claude Code, Codex, Cursor, ChatGPT and other MCP clients can recall from the same store.
Is shared memory the same as RAG?
No. Retrieval over documents finds what someone wrote on purpose. Agent memory holds what the team learned while working, such as decisions, corrections and locations, which usually is not written anywhere else.
Will every teammate see every memory?
In ConvOps, members of a workspace share its memories. Use separate workspaces for teams or clients that must not see each other's knowledge; one person can search across all the workspaces they belong to.
What should never go into team memory?
Secrets, credentials, and personal data your rules do not allow. Store the decision and its reason, and link to the work, rather than pasting transcripts or sensitive records.