Shared Memory for AI Agents: Why Your Team Needs a Two-Tier Split

Two agent sessions. Same repo, separate branches. Both edit decisions.md.

Session A updates the status section to say the next release is still waiting on auth. Session B just finished the auth work, so it updates the auth section to say the service is ready and its dependencies are resolved.

Both edits are true when made. Git merges both branches cleanly, with exit code zero and no conflict marker.

The file on main now says auth is ready. It also says the release is still blocked on auth.

Git did its job.

Its conflict model is textual. It flags concurrent edits to the same lines, and these branches touched different sections. The contradiction lives across sections, not within lines.

You can run this yourself in a minute. Take a decisions.md with an ## auth section and a ## status section. Branch A edits only the status line, branch B only the auth line, and you merge A then B. The merge exits zero. The file is wrong.

Shared agent memory does not corrupt because it is shared. It corrupts because nothing stands between a session's scratch and the team's record. A team layer needs two things a folder of files does not give you. It needs a promotion step that decides what gets in, and a write that can fail when the record changed underneath it.

What shared agent memory actually has to store for a team

Every agent session produces two kinds of memory. One is scratch, the working notes and half-tested conclusions of a task that may not survive the next context window. The other is settled knowledge, the decisions the team made last week and the rules that hold no matter which agent runs next.

Scratch should be cheap to write and easy to throw away. Settled knowledge should be expensive to write and hard to lose. It is the reason the tenth agent does not re-derive what the first nine already decided.

You probably hold that settled layer already, in a root AGENTS.md and a memory folder in the repo. It works. At single-player scale you are the only author and the only reader, so nothing argues back.

One pool that everyone writes to freely serves neither need. Scratch from a finished task sits next to rules still in force, and later sessions inherit the pile without knowing which parts still hold. A rule written in five seconds gets worked around for ten weeks, because the file holding it had nothing behind it.

Why one shared pool corrupts: the two-writer problem

Shared memory corrupts when agents share transient state and two sessions write one record at once; a shared layer needs conflict handling, not one flat pool.

The clean merge is the simplest case. Walden Yan named the mechanism in "Don't Build Multi-Agents," a Cognition blog post: "Actions carry implicit decisions, and conflicting decisions carry bad results." The merge did not fail. The decisions conflicted, and nothing saw it.

We have watched a slower version. We run many agent sessions in parallel against one repo, and each closes with a handoff note. One note recorded what the session finished and also how it had run the work. Later sessions carried the "how" forward as a standing team decision, and it outlived the rule it contradicted.

The fix was a written rule. A handoff is authoritative for state, never for method. How to work comes from the shared rules, and the shared rules win on conflict.

We caught it because we were watching how state moves between sessions. A flat pool gives you nothing to watch.

The two-tier split: private per-agent memory versus one shared team layer

A team needs two memories: private per-agent scratch for a session, and one shared team layer that keeps decisions durable across agents and sessions.

This is the shape our own practice settled into. Each session works in its own worktree with its own plan and lesson notes. A lesson moves into the shared rules only after it holds in more than one area. Every session re-reads the shared rules at start and does not write to them freely.

The promotion step carries the weight. Without it, the two tiers share one pool, age at different rates, and contradict each other with no signal.

The docs for the harness most of you run already describe this split. A project instruction file is "shared with your team through version control," next to a gitignored personal file. The agent's self-written memory is "machine-local" and "not shared across machines." The tier the agent writes to freely never reaches the team. The tier the team shares is written by a human, and promotion between them is a manual act.

The same docs say the agent treats instruction files "as context, not enforced configuration," and that blocking an action regardless of what the model decides takes a hook. The vendor is telling you, in its own words, that the shared rules layer is advisory. The file describes a constraint. It cannot halt an action.

What belongs in the shared layer, and what never should

Architecture decisions still in force belong there. So do the rules the whole team holds, the interfaces and conventions everyone builds against, and finished work that later sessions need to know about. This is the information where two sessions acting on conflicting copies does real damage.

The pre-AI practice for exactly this layer is the architecture decision record. Michael Nygard described the discipline in "Documenting Architecture Decisions," Cognitect blog: "If a decision is reversed, we will keep the old one around, but mark it as superseded."

Append and supersede, never edit in place. A session checking an architecture choice reads the latest record that is not superseded, and the history stays visible instead of collapsing into one current state.

Scratch stays out. Mid-session notes, untested conclusions, and working state from an unfinished task have value inside the session that made them. Promoted early, they mislead every session after.

Most "shared memory causes corruption" failures are really "we shared the wrong thing" failures. The handoff that became doctrine was one. A copy that was quietly a fork was another.

Our shared context lived as a canonical copy and as local copies in several sessions. A routine sync from a local copy would have silently overwritten a section someone had added to the shared copy. Both copies looked current. The rule now is to pull the shared copy before editing and compare content before writing back. A local copy that has drifted is a fork, and a fork that syncs back silently loses data.

Keeping the shared layer consistent when two sessions write at once

Git is a real write path with real conflict detection. Concede that fully. Rejected pushes, conflict markers and code review catch real coordination failures, and they do more than most memory stores do.

The boundary is where git looks. Its conflicts are textual, and team decisions contradict each other in meaning.

The HTTP semantics standard has a name for this class of failure, the lost update problem. Its answer is a conditional write. The session notes the version it read and asserts that version when it writes back. If a newer version landed in between, the write fails, and the session re-reads and decides again.

That is not the whole answer for agent memory. A version check tells you the record moved, not whether your write still makes sense. But it turns a silent overwrite into a write that can fail, and a failed write gives the team one place to handle the conflict before every session loads the bad state.

A vector store does not change this. Similarity search is the read side. It says nothing about which write is current.

How a small team should evaluate a shared memory layer

Evaluate a shared layer on three axes: what an agent can write (not just read), how concurrent writes resolve, and whether your context exports cleanly.

The first axis is the most common miss. Many memory tools are retrieval-first. Writing is unsupported, or it needs a separate human step, or it lands in an agent-only pool that people cannot see or edit. The people who set the team's decisions and the agents who act on them need to work from the same record.

We built around that split. SynthWeave is a company-wide context substrate (snips, bases, and projects with hybrid search) that both people and AI agents read and write from the same place.

On axes two and three, run the same test on us. Ask how concurrent writes resolve and where they do not. Export your context and try to work from it without the platform. Those answers should come as runnable artifacts, not claims, so we are not answering them here.

The variable that drives all of this is concurrent sessions, not headcount. A 15 to 30 engineer team running two concurrent sessions has the two-writer problem. So does one developer running two. Headcount decides how many sessions you run. It does not change what two sessions writing one record require.

Back to the repro

Run the contradictory merge against your own decisions file. It exits zero. The result is wrong.

That is the problem a shared memory layer exists to solve. Not retrieval, not connection, not the size of the context window. It is the write that landed after you read, carrying a decision that contradicts the one you are about to record.

Git tells you when two sessions touch the same line. A folder of files cannot tell you when they reach different conclusions about the same fact, because the folder does not know what the file means.

A promotion step and a write that can fail are what separate a shared layer from a shared pool. Run the merge tonight, then ask which of your tools would have refused the second write.

<script type="application/ld+json"> { "@context": "https://schema.org", "@type": "BlogPosting", "headline": "Your agents need two memories, and only one of them should be shared" } </script>