The Problem With Shared Agent Memory

The real problem

Once you have one AI agent, putting the rule in AGENTS.md feels reasonable.

Once you have five agents, it becomes theater.

The problem is not that agents need more instructions. They already have plenty. The hard part is keeping a shared canonical set of startup and context files in Crew Home, then safely materializing the right parts into each agent’s actual runtime without corrupting identity, copying stale files, or pretending a source file is live because it exists somewhere tidy.

Crew Home can hold the common operating memory:

• AGENTS.md
• USER.md
• shared response policy
• preflight checklist
• shared tools and rules fragments
• common Crew operating context

That sounds simple until each agent has its own workspace, launcher, runtime shape, and identity layer.

Ada, Book, Scotty, Spock, and Zora do not all boot the same way. Some files are shared. Some are agent-specific. Some are generated. Some are loaded by a gateway. Some are only archival. If you blindly copy one folder everywhere, you eventually get the wrong agent wearing the wrong context and calling it continuity.

That is not memory. That is a wardrobe accident with root privileges.

The spine of the problem is distribution and reconciliation:

canonical source fragments -> adapter/compiler -> per-agent generated files -> runtime readback proof

Prompt rules say what should happen. Source control, sync, and verification prove what actually happened.

Shared memory is not one file

People say “shared memory” as if it is a document.

It is really a contract.

A shared rule can belong in Crew Home. An identity file may not. A tool reference may need generated sections. A policy may be common, but the loading path can differ by runtime. A checklist may apply everywhere, while the file that wakes an agent up has to be shaped for that agent’s bootstrap system.

This is where shared memory breaks when handled by hand.

One agent updates the common policy. Another agent keeps the old copy. A third agent writes a local fix into the generated file instead of the source fragment. A fourth agent drops runtime state into a shared folder because it was the nearest plausible place. Everyone means well. The system still drifts.

The answer is not another paragraph saying “please do not drift.”

The answer is a source tree with boundaries:

• shared fragments live in one canonical place
• agent overlays live with the agent
• generated files are marked as generated
• runtime targets are explicit
• adapters define how source becomes runtime context
• manifests record what changed
• readback proves what the agent can actually load

That is the difference between a shared study and a junk drawer.

Adapters are mandatory

A naive sync says: copy the shared files to every workspace.

That is how you make a mess quickly.

OpenClaw root files and Hermes StartupContext are different targets. A file that is correct for Ada may be wrong for Book. A shared AGENTS.md fragment may need to compile into a different final shape depending on the runtime. TOOLS.md may include registry-generated blocks in one place and profile-specific overlays in another. USER.md may be common enough to share, but still needs care because it carries identity-adjacent context.

The adapter is the boundary between source and runtime.

It answers boring questions that prevent expensive confusion:

• Which source fragments apply to this agent?
• Which overlay is identity-bound?
• Which output file is generated?
• Which runtime path is authoritative?
• Which service or gateway must reload?
• Which hash should match after apply?
• What should runtime readback return?

Without adapters, shared memory becomes shared copying. Shared copying becomes stale files with confidence.

Runtime proof beats source proof

A source file existing in Crew Home is not success.

A manifest saying a file was generated is not success.

A commit saying “sync startup context” is not success.

Success means the target file exists where the runtime actually reads it, has the expected hash, and the live agent or gateway can read back the expected identity and context.

The proof chain should look like this:

source hash
compiled hash
apply manifest
runtime target hash
runtime readback

That chain matters because agents do not obey the file you wish they had loaded. They obey what their process actually sees.

This is why StartupContext needs strict gates. It touches identity, memory, policy, tools, and bootstrap behavior. Those are not normal docs. A bad copy can contaminate an agent’s identity or silently remove a rule the rest of the fleet assumes is active.

For this class of file, “probably synced” is not a receipt. It is an outage seed with nicer stationery.

Drift Intelligence watches. Janitor cleans carefully.

Prompt rules reduce drift.

Drift Intelligence detects it.

Layout Janitor fixes only allowlisted reversible cases.

StartupContext Monitor gets strict gates.

Those are separate jobs.

Drift Intelligence should scan broadly and mutate nothing. It should notice stale generated files, wrong-folder writes, missing manifests, identity contamination, runtime hash mismatches, and source/runtime divergence. It should report findings with enough evidence that a human or a gated workflow can act.

Layout Janitor should be boring on purpose. It can move known file classes to known canonical paths. It can quarantine uncertain files. It can archive superseded generated outputs. It should write manifests, hashes, rollback paths, and receipts. It should refuse identity-sensitive files unless the policy says the move is safe and reviewable.

The operating-manual version is simple:

The smoke alarm does not swing the wrench without a manifest.

That line matters. The thing that sees drift should not silently repair drift. Detection is observability. Mutation is authority. Mixing them is how an automated cleaner becomes an automated vandal with a dashboard.

What a good apply proves

A good StartupContext apply is boring because every important question has a receipt.

It should prove which shared fragments were used. It should prove which agent overlay was applied. It should name the adapter. It should show the compiled output hash before anything lands in a runtime workspace. It should show the destination path. It should show the target hash after apply. It should show the runtime readback that confirms the agent can load the expected context.

That last step is where most fake syncs die.

A file can be correct and still irrelevant if it lands in the wrong workspace. A manifest can be correct and still stale if the service points somewhere else. A generated file can be perfect and still unused if the gateway loads another profile. The verifier has to check the thing the agent actually uses, not the thing the operator hoped it used.

The same applies to shared versus agent-bound context. Shared policy can move through the compiler. Identity files need stricter boundaries. Generated files should not be hand-edited. Local overlays should not be backfilled into the shared source unless that is an intentional promotion. These distinctions are dull. That is why they work.

The outcome should be easy to audit:

what source changed
what compiled
where it landed
what loaded it
how to roll it back

If any line is missing, the system is asking for trust where it should be producing proof.

The lesson

The lesson is not “write better prompts.”

Better prompts help. They do not enforce placement, compile shared fragments, preserve identity overlays, reload runtimes, or prove readback.

The lesson is that shared agent memory needs a control plane:

• canonical source fragments in Crew Home
• explicit shared versus identity-bound boundaries
• adapters per runtime
• generated files with provenance
• manifests for every apply
• drift detection that cannot mutate
• janitor actions limited to safe reversible classes
• StartupContext checks with source, compiled, target, and readback hashes

That is how a multi-agent crew keeps common memory without turning every workspace into a haunted scrapbook.

The rule in AGENTS.md is useful.

The verifier is what tells you whether it mattered.