Claude Code team memory: how to share what your agents learn

On Tuesday an engineer spends three hours with Claude Code on a flaky checkout test. They rule out the payment mock, find a race in the session store, and get halfway through a fix. Then they get pulled onto an incident.

On Wednesday a teammate picks up the ticket. Their Claude Code starts from zero. It suggests checking the payment mock.

That is the gap behind one of the most specific requests in the Claude Code tracker, a feature proposal for shared team memory. Until something like it ships, here is what a team can share today, what it can't, and where each kind of knowledge should live. Facts come from Anthropic's documentation, checked on 4 November 2026.

Can Claude Code share memory across a team?

Not natively. Claude Code's auto memory is stored in your home directory and, in the documentation's words, is not shared across machines or cloud environments. Your teammate's agent never sees what yours learned.

What a team can share is anything that lives in the repository or a shared git host:

Mechanism	Where it lives	Shared with the team?	Who writes it
Auto memory	~/.claude/projects/<project>/memory/	No. Machine-local	Claude
User CLAUDE.md	~/.claude/CLAUDE.md	No	You
Project CLAUDE.md and .claude/rules/	The repo	Yes, through git	The team
Skills	.claude/skills/ in the repo, or a plugin	Yes	The team
Subagent with memory: project	.claude/agent-memory/<agent-name>/	Yes, through git	The subagent
Team plugin marketplace	A git repo with .claude-plugin/marketplace.json	Yes, for anyone who adds it	The team
Managed CLAUDE.md	A system path, deployed by IT	Yes, every user on the machine	The organization

Most teams use the third row and stop. The fifth and sixth rows are where the useful sharing is.

What teams actually want to share

The feature request lists seven situations where context dies between people. Grouped by the kind of knowledge involved, they look like this:

Situation from the request	Kind of knowledge	How long it stays true
A sprint task changes hands mid-way	Task state: what was tried, what failed	Days
An incident moves to the next shift	Investigation notes	Hours to days
An engineer works in another team's service	Domain gotchas	Months
A reviewer wonders why the author chose an approach	Rationale behind one change	As long as the code
An architectural choice is made inside a session	A decision	Until someone replaces it

These are not one thing. Task state should expire. Domain gotchas should accumulate. Decisions should be owned and replaced deliberately. A single shared memory pool would mix all three, and the team would end up trusting none of it. The options below give each kind its own home.

Option 1: commit the instructions everyone needs

The project CLAUDE.md and .claude/rules/ are already shared through git. Use them for stable instructions that apply to nearly every task: commands, boundaries, conventions.

Two habits make this work for a team. Keep CLAUDE.md under 200 lines, which is Anthropic's recommendation, and push anything that applies to only part of the codebase into a rule with paths, so it loads only when Claude touches matching files. Then review changes to these files in pull requests like code. They are code, for the agent.

What this can't hold: anything that changes weekly, and anything learned during a session that nobody stops to write down. For the full load order and limits, see how Claude Code memory works.

Option 2: give a subagent project-scope memory

This is the most useful sharing feature in Claude Code, and the least used. A subagent can have its own persistent memory, and with memory: project that memory lives in the repository at .claude/agent-memory/<agent-name>/. Anthropic recommends project scope as the default because, per the documentation, it makes the subagent's knowledge shareable through version control.

A domain expert for one service might look like this, saved as .claude/agents/payments-expert.md:

---
name: payments-expert
description: Knows the payments service. Use for any change under services/payments/.
memory: project
---

You are the team's expert on the payments service. Before answering,
read your memory for known gotchas. When you learn something that would
save the next engineer time, such as a race condition, a flaky test cause,
or an undocumented constraint, add it to your memory.

When anyone on the team uses this subagent, it loads the first 200 lines or 25KB of its MEMORY.md, and what it writes back lands in a directory that goes through code review with everything else. The engineer from the opening example would have left the session-store race in that memory. Their teammate's agent would have read it.

Three cautions. The memory is written by whoever runs the subagent, so review those files in pull requests rather than merging them blind. Two people editing MEMORY.md on different branches will produce ordinary merge conflicts. And the main conversation's auto memory is not loaded into subagents, so this is a separate store, not an extension of anyone's personal memory.

Option 3: ship skills through a team plugin marketplace

Skills hold procedures: how to cut a release, how to add a migration, how to debug the queue. They can live in .claude/skills/ in one repo. When several repos need the same skills, package them as plugins.

A plugin marketplace is a git repository with a .claude-plugin/marketplace.json file that lists your plugins. It can be private. Teammates register it once:

claude plugin marketplace add your-org/claude-plugins
claude plugin install release-tools@your-org-plugins

Updates reach everyone who installed from it, and an administrator can require the marketplace on every machine. This shares how the team works. It does not share what anyone learned yesterday.

Option 4: write handoffs for unfinished work

Task state is the one kind of knowledge that should not live in permanent memory. It goes stale in days. For a mid-task handoff, the most reliable tool is still a short file committed to the branch: what the goal is, what was tried, what failed, and the next step.

Ask Claude to write it before you stop, and ask the next session to read it before it starts. When the branch merges, delete the file. For a template and what to put in it, see Claude Code keeps forgetting context?.

What none of these share

Every option above covers knowledge that someone writes into the repository. The hardest kind of team knowledge rarely gets there.

A product manager and an engineering lead agree in Slack that exports must exclude a customer's internal notes. The PRD is updated. Nobody edits CLAUDE.md, because it isn't an instruction about the codebase. A week later an engineer's agent builds an export endpoint from an older prototype and includes the notes.

Decisions like this have properties that files in a repo don't track:

• An owner. Someone decided, and someone can change it.
• A status. Proposed is different from approved.
• A replacement history. When the call changes, the old one should be marked replaced, not silently edited.
• A source outside the repo. Slack threads, PRDs, and tickets, not commits.

Knowledge	Best home
Commands, conventions, boundaries	Project CLAUDE.md and rules
Domain gotchas that accumulate	A subagent with memory: project
Repeatable procedures	Skills, shared through a plugin marketplace
Unfinished task state	A handoff file on the branch
Product and architecture decisions	A shared decision record with owners and status

Where Lockstep fits

Lockstep is shared team memory for Claude Code, built for the last row of that table. Decisions are captured from PRDs, Slack, and pull requests, and become binding when their owner approves them. At the start of each Claude Code session, the agent is briefed on the decisions that apply to the work, and it can query the same record over MCP mid-session. When a decision is replaced, the old version is marked replaced, so no agent treats it as current.

For engineering leads, Standards & Skills publishes versioned standards and skills once and rolls them out by team, repo, or path, with a view of which version reached which checkout. That overlaps with a plugin marketplace on distribution; the difference is the rollout control and the adoption view.

It does not replace CLAUDE.md, project-scope subagent memory, or handoffs, and it does not make agents obey anything. Session briefings and managed skills work with Claude Code today; other MCP clients can call the tools without the automatic briefing. Try it on one repository with npx lockstep-cli onboard.

Sources checked 4 November 2026

• https://code.claude.com/docs/en/memory
• https://code.claude.com/docs/en/sub-agents
• https://code.claude.com/docs/en/plugin-marketplaces
• https://github.com/anthropics/claude-code/issues/38536

Related reading

For every memory file and limit, read how Claude Code memory works. For parallel agents in one repo, see two AI agents, one codebase. For the split between instructions and memory, see CLAUDE.md vs agent memory.