Team Memory for Coding Agents: How to Share Context Across a Dev Team

A senior engineer spends twenty minutes explaining to their agent why the service uses an outbox table instead of publishing events inline. The agent gets it, writes good code for the rest of the afternoon, and that explanation is now sitting on one laptop. A new hire joins three weeks later, opens their own agent, and asks the same question from zero. Nobody did anything wrong. The memory worked exactly as designed, and the design is per developer.

This guide covers how the context one person's agent accumulates reaches everyone else's agents, rather than how to write a better instruction file, which is well covered elsewhere. Team memory comes in two or three distinct layers that carry different kinds of context, and picking the right one starts with naming what your team is losing.

Why your agent's memory stops at your laptop

Look at where a coding agent keeps what it knows, and the boundary becomes obvious.

Claude Code is the clearest documented case. Its instruction files are split by scope, and the scope decides who ever sees them. A project CLAUDE.md at ./CLAUDE.md or ./.claude/CLAUDE.md is shared with team members through source control. A user file at ~/.claude/CLAUDE.md applies to just you, across every project on your machine. A CLAUDE.local.md is just you again, scoped to one project, and the documentation tells you to add it to .gitignore. Two of those three scopes are private by construction.

The automatic layer is more emphatic. Claude Code's auto memory, where the agent saves notes from your corrections without being asked, writes to ~/.claude/projects/<project>/memory/. The documentation states plainly that auto memory is machine-local, and that the files are not shared across machines or cloud environments. Every worktree of a repository on your computer shares one memory directory. Your teammate's copy of that same repository shares nothing with it.

Session history has the same shape. The explanation about the outbox table lives in one conversation, under one account. A fresh session may compress or drop it, and another developer's agent has no path to it at all. Account-level retention keeps a transcript for one person. It does not make the reasoning available to the team.

None of this is a defect. Private scopes are what let you keep a scratch URL or a personal preference out of everyone else's context. But it means the default state of a team running coding agents is a set of parallel, private understandings of the same codebase, each rebuilt from scratch. When someone leaves, the code stays and their agent's accumulated context does not.

What each layer of team memory can carry

Three mechanisms get called "memory" and they are not interchangeable. Keeping them separate is most of the work.

Committed instruction files are the cheapest shared context you will ever get. A file the whole team pulls, reviewed like code, telling every agent the test command and the architectural boundaries. Claude Code loads these by directory scope, so a root file can hold repository-wide rules while a file next to a specialized package applies only when the agent works in that directory. Path-scoped rules under .claude/rules/ narrow it further using a paths field in frontmatter. Keep them short. Anthropic's guidance targets under 200 lines per file, because longer files cost context and reduce adherence.

What they cannot do is explain themselves. A line saying "use the repository pattern for data access" is a rule without provenance. No agent reading it knows who decided that, what it replaced, or what evidence would justify revisiting it. Instruction files also go stale silently, and a written instruction cannot enforce anything. Tests, permissions, and review are what stop an agent from doing the prohibited thing.

Shared retrieval answers what is true now. An agent planning a change can reach the current issue thread, the pull request that touched this file last month, and the design doc, instead of trusting a rule someone wrote in March. The limit is that retrieval finds what exists. It can surface the conversation where a decision was made, but only if that conversation happened somewhere indexed, and it cannot reconstruct reasoning that was never written anywhere.

Memory services add durable, queryable storage that persists across sessions. Whether it also reaches across people is a configuration question, not a given. Mem0, for one, partitions memories by user, agent, app, or run, so check each product's scoping model before assuming a teammate's agent will see what yours learned. Mem0, Zep, and Cognee are the memory-infrastructure end of this: programmable layers you build agents on top of, with operations to store, recall, correct, and delete. Cognee frames its version as a company brain assembled from documentation, conversations, tickets, and code, which is a different product category from a maintained set of engineering documents. A memory service is only as good as its ingestion, and unreviewed session notes preserve mistakes as faithfully as lessons.

These layers stack. Most teams need more than one, because a stable rule, a current source, and a durable lesson are three different things.

The part no layer gives you for free

Every layer above surfaces knowledge that exists somewhere. None of them can recover reasoning nobody recorded, and unrecorded reasoning is usually the context that hurts most when it goes missing.

The failure mode is specific. An agent reads the code, finds a piece of middleware or an indirection that looks unnecessary, and simplifies it. The change is locally reasonable. Tests pass. Review passes, because the reviewer also does not remember why that code is there. What the agent could not know is whether the pattern was deliberate, accidental, deprecated, or actively disputed. Code records what the team decided. It does not record what the team rejected, and an agent cannot tell the difference between a constraint and an accident.

Wikis tend not to close this gap, because the summary gets written after the deciding conversation. By then the rejected options and the operating conditions that made the choice correct have usually fallen out.

Architecture decision records are the standard artifact for this, and they work for agents for the same reason they work for people. Write one in the same pull request as the change, mark a replaced record superseded instead of deleting it, and keep the directory somewhere your agents can reach, because a record they cannot read is human documentation, not team memory. How to make coding agents remember architectural decisions covers templates, triggers, and supersession in detail.

Not every decision needs one. If a choice affects a single pull request and requires no future coordination, leave it in the pull request. Service boundaries, authentication, and anything touching persistent data usually earn a record.

Set up team memory this week

Work from cheapest to most involved, and add a layer only when you can name the context that is still missing.

1. Commit and scope your instruction files. Put repository-wide commands and boundaries in the root file your agents read. Move narrower rules beside the subdirectory they govern so they load only for work in that area. Test every sentence against one question: if I deleted this line, would a contributor pick a different file, command, or boundary? If not, cut it.

Keep task plans and dated migration notes out. Those belong in issues where they carry an owner and a status.

2. Put a maintenance loop around them. Give each file an owner, but let failures drive updates rather than a calendar. When an agent repeats a mistake or review catches a missing rule, that is the signal to edit the file, and the addition should name the failure it prevents. Add a line to your pull request template asking whether the change adds, invalidates, or narrows an agent instruction. Sweep for rules the code now makes obvious and delete them.

3. Start a decision log. Add doc/adr and write short records for decisions future contributors will reasonably want to revisit, in the same pull request as the code.

4. Evaluate retrieval or a memory service against a named gap. Only once you can point at context your agents keep missing that instruction files structurally cannot hold. Test any candidate with questions drawn from last month's real work, and check whether its answers point back at current source material.

How to tell whether it is working

Some of these you can measure, and some you can only watch.

The cleanest signal is repeated explanation. Tag it every time someone has to explain a convention or a known failure mode that is documented somewhere. Set a threshold, say the same explanation twice in a month, and move that knowledge into a file, a record, or an indexed source. Then watch whether the question stops.

Log knowledge gaps separately from failed tasks. Ask developers to flag sessions where the agent lacked information that existed elsewhere in the company, and note which source held it. Repeated gaps in one area tell you where coverage is thin.

Two signals teams care about most, new-hire ramp time and rejected approaches resurfacing, are not things you can pull from a dashboard, and published research does not establish a standard method for either. Track them by hand in retrospectives. Count how long new hires go before they stop needing repeated context, and count the times an agent proposes something the team ruled out. Falling counts suggest rationale is reaching your agents. Recurring ones point at a record that is missing or that your agents cannot read.

FAQ

How do CLAUDE.md, AGENTS.md, and Cursor rules differ?

CLAUDE.md is what Claude Code reads, and it can scope guidance by directory. AGENTS.md is the portable equivalent that several coding agents read. Claude Code reads your AGENTS.md when you have no CLAUDE.md or CLAUDE.local.md in the working directory or above it, and you can configure it to load both. Cursor keeps its own rules files. Support and precedence differ per client, so confirm what each tool on your team loads rather than assuming they agree.

Do committed instruction files replace a memory service?

No. Committed files are good at stable commands, conventions, and boundaries. They do not capture session history or knowledge spread across tickets and chat, and they do not update themselves. Those are different jobs.

Who should own keeping instruction files current?

Code owners, beside the code they govern, updating the file in the same pull request that changes a command or a boundary. A single documentation owner doing periodic cleanups is the pattern that decays.

How do we add decision records without process people abandon?

Require one only when a decision will affect work across multiple pull requests or engineers. Keep it to context, choice, rejected alternatives, and a review trigger, written in the pull request that makes the change.

Find the layer your team is missing

Open your repository and run /context in Claude Code to see which memory files are loading. Then ask the two questions that matter: is anything in there wrong now, and where would a teammate's agent have to go to learn something you explained last week?

If the answer is that each developer's agent is rebuilding the same understanding privately, the missing layer is shared and maintained, which is the gap Dosu is built for. Dosu captures engineering context from coding sessions and connected Sources, and coding agents read it over MCP and the Dosu CLI. When the working repository is connected to the selected Library, a note written with write_knowledge is scoped to that repository and branch, and other members of that Library can read it back with the author attached. Without that connection, or when the client does not supply git context, the note is still saved, without the repository anchor. With Monitor enabled, Dosu checks ready pull requests and subsequent commits against relevant published Documents and proposes edits when it detects drift. Whether those edits publish with the merge or wait for a person is a per-Library setting. Dosu also supports generating AGENTS.md, README.md, architecture.md, and deps.md, and is SOC 2 Type II compliant.

Connect a repository to Dosu and give the next agent that opens it the context your team paid for the first time.