How to Share Claude Code Memory Across a Team
A shared CLAUDE.md is the obvious first step.
It is also where teams hit a ceiling.
The next layer is path-scoped memory that survives tool, machine, and teammate changes.
What this covers
- Claude Code has three memory layers: project memory in CLAUDE.md, user memory in the home directory, and auto memory the assistant writes for itself.
- Only the project CLAUDE.md is naturally shareable. User memory and auto memory stay on the local machine.
- Sharing a single CLAUDE.md works at small scale and breaks the same way every team file does once it grows past a hundred-plus instructions.
- Pathrule layers path-scoped memories, rules, and skills on top so the team can share specific knowledge to specific folders without bloating the root file.
Comparison
| Memory layer | Where it lives | Shareable across the team? |
|---|---|---|
| Project memory (./CLAUDE.md) | In the repository | Yes, via git |
| User memory (~/.claude/CLAUDE.md) | Each developer's home directory | No |
| Auto memory | The local Claude Code state | No |
| Path-scoped team memory | A shared workspace tree (Pathrule) | Yes, with scope, review, and history |
Signs your team has outgrown a single CLAUDE.md
- New teammates ask the same context questions in chat that the file already covers.
- The file is past a hundred instructions and nobody reads it end to end.
- Folder-specific notes keep getting added at the root because there is no better place.
- The same exception appears in multiple sections written in slightly different words.
- Reviewers cannot tell whether a generated change was made under the right rule.
- A rule needed for one folder breaks behavior in another folder where it was loaded by accident.
What Claude Code shares by default, and what it does not
Claude Code reads three places. The project CLAUDE.md at the repo root is loaded for any session opened inside the repo. A user CLAUDE.md in the home directory is loaded for every session that user runs, on any repo. Auto memory is a separate store the assistant writes for itself.
Only the project CLAUDE.md travels with the codebase. The other two stay on the machine that wrote them. That is the right default for personal preferences and tool habits. It is the wrong default for shared team conventions.
In practice this means the only memory layer your team currently shares is the one file at the root. Everything else is private knowledge the rest of the team cannot see and cannot improve.
Why a single shared file hits a ceiling
A small repo with ten clear instructions works well. The file is short, the assistant follows it, and the team trusts it. Adding the eleventh and twelfth feels free. So does the fortieth.
Past a certain length the file stops being a contract and becomes a wall. Teammates skim it. The assistant treats later items as background. Nobody refactors it because nobody owns the whole thing. The signal does not drop suddenly. It drops by one percent every week until the team is back to repeating context in chat.
The pattern is well documented across CLAUDE.md, AGENTS.md, .cursorrules, and copilot-instructions.md. The shape of the failure is the same: one flat file carrying too many scopes.
The local memory gap
User memory and auto memory accumulate the most interesting knowledge a developer learns. A senior engineer with two years on the project has built up a private set of conventions, gotchas, and patterns that the assistant references reliably for them.
None of that reaches a new teammate. The new joiner gets the same CLAUDE.md the senior engineer had on day one. The two years of learned context lives on the senior engineer's laptop, in a store the team has no way to read.
Teams that notice this gap usually try to fix it by moving learnings into CLAUDE.md, which lengthens the file, which lowers follow-rate, which sends people back to chat. The fix recreates the original problem.
A shape that scales: scoped memory above CLAUDE.md
The healthy pattern keeps CLAUDE.md short and adds a path-scoped layer for everything else. CLAUDE.md carries conventions that genuinely apply across the whole repo: how to run tests, the project overview, the commit style. The scoped layer carries the rest.
Pathrule is one implementation. Team memories, rules, and skills attach to paths in a workspace tree that mirrors the repo. A schema gotcha lives at the schema folder. A release checklist lives at the deployment service. A surface-specific design note lives at the surface. Retrieval walks from the active path up the ancestors. The session sees what matches the work.
The CLAUDE.md does not grow. The scoped knowledge becomes visible at the moment it matters. A new teammate opens a folder and inherits the team learning for that folder without anyone copying it into the root.
Sharing means review, not just sync
A team memory layer is more than a sync mechanism. The interesting part is that team learnings get a review surface. Each memory and rule has an owner, a scope, and a history. A wrong rule can be retired. A stale fact can be repaired. A new postmortem can become a memory at the path where the failure happened.
That changes onboarding. The new hire is not reading a static doc that was last updated three quarters ago. They are entering a workspace where the team has continuously written down what it has learned, attached to where it applies.
It also changes incidents. The lesson from the last outage does not stay in a Slack thread. It lives at the path it protects, and the next change near that path arrives with the context already present.
How to try this without disrupting the team
A useful first pass is small. Read CLAUDE.md. Pull out the sections that are really folder-specific and move them to Pathrule under the matching path. Keep the genuinely global conventions in CLAUDE.md. The file gets shorter, the follow-rate on what remains goes up, and the folder-specific knowledge starts showing up exactly where it matters.
Run a session in one folder afterward. Watch the slice arrive at hook time. If a teammate joins the next week, they get the same slice with no copy-paste from chat.
Every signup gets three months of Pathrule PRO on the house. If your team wants help shaping the first split with us, [email protected] is open.