How to Set Up Coding Agent Memory: Local Files, Repo, or Shared Service?
Coding agent memory can live in three places. Choose one for each fact by who must approve it, whether it must outlive one laptop, and how often it changes.
DosuCoding agent memory belongs in three places: local files for personal preferences, reviewed repository files for team rules, and a shared service for frequently changing team context. Choose where each fact belongs based on who needs it, whether it requires approval, and how often it changes.
For example, during a logging migration, keep the approved rule (use the new logger) in the repository. Keep the changing list of modules still to migrate in a shared service. Each fact has one home, and teammates' agents can access both.
Team memory for coding agents covers what each shared layer can carry and how to set one up.
Three questions decide where a fact belongs
For any fact your agents need, ask:
- Does another engineer have to approve this before other agents act on it? If yes, it needs a path that enforces approval. For a repository file, that means required review on the protected branch, plus agents that read the approved revision, because required review gates only the merge. For a service, it means a write path that holds the change until a person accepts it.
- Does this have to outlive one laptop? If yes, rule out local placement.
- How often does it change? A fact that stays put once settled can live in a file someone edits. A fact that moves faster than anyone will open a pull request for it needs a path that takes updates without a hand edit.
The first two questions rule placements out. An editor preference needs no approval and no durability, so it stays local. The structured-logging rule needs both, so it belongs in a reviewed file. The third question settles what is left, which is usually the choice between a repository file and a service.
| Placement | Best for | Who can read it | What updates it | Survives a laptop wipe |
|---|---|---|---|---|
~/.claude/CLAUDE.md, CLAUDE.local.md, auto memory | Personal preference, per-machine setup | Only you | You, or the agent itself for auto memory | No |
Committed CLAUDE.md, AGENTS.md, rules files | Conventions and decisions you want reviewed | Anyone with repository access | A commit or pull request, reviewed where branch rules require it | Yes |
| A service the team's agents query at runtime | Fast-changing context agents on other machines need | Members with access to the service | The service's own write and review paths | Yes |
Local files and Claude Code's auto memory reach only you
Claude Code's memory docs list who each instruction file is shared with. The project CLAUDE.md is shared with your team through version control. For ~/.claude/CLAUDE.md the answer is "Only you (all projects)". For a CLAUDE.local.md at the project root it is "Only you (current project)", and the docs recommend adding that file to .gitignore.
Auto memory, the notes Claude writes for itself from your corrections, lives in ~/.claude/projects/<project>/memory/. The docs say auto memory is machine-local, and files are not shared across machines or cloud environments. All worktrees of the same repository share one directory, so your auto memory survives a branch switch, and a teammate's agent never sees it. Auto memory is on by default in local sessions, so Claude can save notes there without anyone deciding it should.
A local file can also change what your agent reads from the repository. In Claude Code v2.1.277 and later, the default claude-md-or-agents-md setting reads AGENTS.md directly only when you have no CLAUDE.md or CLAUDE.local.md in your working directory or above it. Because CLAUDE.local.md counts, the docs say adding one to keep your own uncommitted instructions in a project that relies on AGENTS.md stops Claude from reading AGENTS.md for you. Your teammates' agents keep reading it, and a gitignored file leaves no diff to explain why yours stopped. A CLAUDE.md that imports @AGENTS.md still loads it, and setting Project instructions to claude-md-and-agents-md loads both. Run /context after you add a local file to confirm what loaded.
Keep editor preferences, sandbox URLs, and test data local. Anything another engineer's agent needs belongs in the repository or a shared service.
Committed files are reviewed only where branch rules require it
Committing instruction files lets the team review them alongside the code. Where required review is enforced, approval gates merging an AGENTS.md change into the protected branch. Agents working on a feature branch or local edits can still load an unapproved version, so if you need approval before use, you must also control which revision your agents consume.
The merge gate is the repository's branch protection rule or ruleset, not the file's location. A repository that allows direct pushes to its default branch takes an instruction change with no more scrutiny than a note on a laptop, so confirm that review is enforced, and who can bypass it, before you count a committed file as reviewed. Whatever the branch rules, Git records who changed an instruction, when, and alongside which code. New hires receive the file at checkout, and it travels with a fork.
Git can tell you when someone last changed a line. Git cannot tell you when a line nobody touched stopped being correct. An instruction that says routes are registered in an Express module is wrong from the commit that moves them, and it still carries the approval it got at merge. Agents read it at session start and treat it as fact. When a change retires a convention, update the instruction files that describe it in the same pull request as the code. To automate that step, compare tools that keep AGENTS.md files up to date by what triggers the edit.
Claude Code's resolution order is documented and specific, and other agents apply their own rules to their own files. Before you treat one committed file as the single source of guidance, confirm which files each of your agents loads for the path being edited.
In a shared service, reach and review are separate controls
A service your team's agents query at runtime holds knowledge that changes faster than anyone will hand-edit a file and still has to reach agents on other machines.
Dosu is one. Its MCP server exposes a connected Library to coding agents through read_knowledge and write_knowledge. What a write becomes depends on its context:
- With usable repository and branch context for a connected repository, the write becomes an append-only Branch Note. Library members reading knowledge on that same repository and branch can see it.
- Otherwise Dosu saves it as an unanchored note in the Library. Until it is promoted, it appears in reads that carry no repository and branch.
Either kind of note can become a candidate Topic:
- A Branch Note becomes a candidate when its pull request merges into the default branch.
- On GitHub, a note written on the default branch, or on a branch whose PR already merged, also gets a best-effort promotion check at write time.
- An unanchored note enters the candidate pipeline immediately.
Dosu checks each candidate against existing Topics before adding it.
A Branch Note reaches teammates on that branch without delay, which helps when an agent records a constraint mid-task. Nobody has reviewed that note, though. Treat reach and review as separate controls, or a teammate's agent may follow an unreviewed note as if it were a team convention.
Review runs on a separate path. With a Monitor enabled on a Source, Dosu compares a pull request's changes against published Documents, drafts targeted edits for anything stale, and sends them to Review, where a person can Accept, Edit, or Decline. For updates nobody accepts or declines, the per-Library Auto-Accept Review setting decides whether they publish on merge or wait for approval. Check that setting on the Library you connect before you rely on either behavior.
If you are also evaluating Unblocked, Mem0, Zep, or Cognee, check each product's documentation for who can read a note, what reviews it, and which agents can reach it. Memory APIs built for teams shipping their own agent products answer a different need than context infrastructure for teams running Claude Code and Cursor, and the names make them easy to confuse.
Split a fact that changes often but needs approval
The logging migration from the opening is the hard case, because the rule needs approval and the module list changes every day. Store it as two facts. The approved rule goes in the repository, where it goes through review. The list of modules still to migrate goes in the service, where an agent can update it without anyone editing a file. Recording that a module moved does not approve a change to the rule.
Give each part one home. When the same convention lives in a committed file, a service, and someone's auto memory, agents get whichever copy their configuration happens to load, and the disagreement shows up as inconsistent output with no visible conflict.
FAQ
Should AGENTS.md and CLAUDE.md both exist in the same repo?
Yes. Import one from the other, or set Claude Code to load both. By default Claude Code reads AGENTS.md directly only when no CLAUDE.md or CLAUDE.local.md sits in your working directory or above it, so a CLAUDE.md that does not import AGENTS.md hides it from Claude Code. Start CLAUDE.md with @AGENTS.md and add only Claude-specific instructions below it, or set Project instructions to claude-md-and-agents-md to load both.
Should team knowledge go in an MCP memory server or in CLAUDE.md and AGENTS.md?
Both, for different facts. Keep conventions that need approval in committed files that reviewers see alongside the code, and use a service your agents query over MCP for context that changes too often to hand-edit. A shared service does not replace code review, so it does not replace the committed files. To choose a server, compare MCP memory servers by where they keep the store.
Do teams need per-user memory or shared memory for coding agents?
Per-user memory fits preferences only you need, such as editor settings and sandbox URLs. Anything another engineer's agent would need belongs somewhere shared, either a reviewed file in the repository or a service the team's agents query. Per-user memory also leaves with the laptop, so check what lives on only one machine before an engineer leaves.
How do I see what my agent is reading right now?
In Claude Code, /memory lists your CLAUDE.md, CLAUDE.local.md, and other memory file locations across user and project scopes, and lets you open the auto memory folder. /context shows which files loaded at launch. Run both before you assume an agent knows something it never loaded.
What carries over when a repo is forked or split?
Committed instruction files travel with the code. Local memory does not, and a service connection does not follow automatically. After a split, re-check each new repository's paths and commands in its instruction files, and confirm which Sources a connected Library now covers.
Audit one fact before you move anything
Pick one thing your agents get right today that a new hire's agent would get wrong. Run /memory and /context in Claude Code and find where that fact lives. If it is in auto memory or a CLAUDE.local.md, it exists on exactly one machine.
Then put it through the three questions. If it has to outlive this machine and changes faster than anyone will edit a file, it belongs in a shared service. If it also needs approval, commit the approved rule and keep only the running observations in the service. Connect a repository to Dosu and check what an authorized coding agent can read back.