Shared memory for a team of AI agents

Updated · By the Cozy team

To share memory across several agents, put it in one hosted place every agent reaches over MCP: a Markdown wiki with per-agent access you can revoke, revision checks on every write, and an agents/ folder for handoff notes. Each agent reads the same pages, writes its own notes, and the next agent starts from them.

Why local memory stops working with more than one agent

Most agent memory lives on one machine. Claude Code's auto memory, for example, is machine-local according to Anthropic's memory docs. A second laptop or a cloud agent starts with none of it. A CLAUDE.md file in git shares instructions, but it is a poor place for evolving facts, decisions and in-progress work.

Three problems show up once you add agents:

What a shared memory needs

A shared memory for agents has a short list of requirements. Cozy covers each one, and so do some other tools. Where the tool differs matters less than whether your setup has all of them.

NeedWhat it meansHow Cozy handles it
One endpointEvery agent connects to the same placeOne hosted MCP endpoint per account, plus per-workspace endpoints for credentials
Separate identitiesYou can tell agents apart and revoke oneEach connected agent listed and disconnectable in Connectors → Agents, or one credential per agent
Least privilegeA research agent should not edit curated pagesScopes read, wiki-write, source-write, plus folder-prefix grants
Safe writesNo silent overwritesexpectedRevision on every edit
RecoveryUndo a bad agent editLast 50 revisions readable and restorable
HandoffState passed to the next agentagents/ folder and cozy_changes

Set up one workspace for your agents

Use My wiki, or create a private workspace for the project. Cozy is single-player: only you and the agents you authorize can reach a workspace, and an agent never gets more access than you have.

Connect each agent to your account endpoint, https://cozy.cloud/mcp, and sign in with OAuth. One URL reaches all your workspaces. Tools use My wiki by default, so agents pass another workspace's name or ID as the workspace argument, and cozy_workspaces lists the options. For Claude Code:

claude mcp add --transport http --scope user cozy https://cozy.cloud/mcp

Then sign in with /mcp. For Codex:

codex mcp add cozy --url https://cozy.cloud/mcp

See Connect Claude Code and Connect Codex for the step-by-step versions. Connected agents are listed and can be disconnected under Connectors → Agents.

For scripts, CI and headless agents, use the workspace endpoint https://cozy.cloud/wiki-mcp/WORKSPACE_UUID with one bearer credential per agent, created under Agents. Tokens are random, shown once, stored as SHA-256 digests and expire within 90 days. Give a code-review agent read access, a note-taking agent wiki-write limited to an agents/ prefix, and keep source-write for importers.

Write handoff notes into the agents/ folder

Cozy workspaces have four folders: wiki/ for curated pages, sources/ for evidence from connectors and importers, skills/ for editable SKILL.md files, and agents/ for agent notes and handoffs. Handoffs belong in agents/, away from curated pages.

A handoff note works best when it is short and has fixed headings. Ask your agents to write one at the end of every session, for example at agents/handoffs/2026-11-08-billing-migration.md:

---
type: handoff
description: Billing migration, state at end of session
status: open
---
## Done
- Moved invoice export to the new schema.
## Open
- Webhook retries still fail for [[wiki/billing/webhooks]].
## Do not repeat
- Backfill script timed out on the full table; run it in batches.
## Next step
- Fix retry backoff, then update [[wiki/billing/overview]].

Because the note links to wiki pages with wikilinks, the link graph connects it to the page it concerns. The agent that picks up the work calls cozy_changes with the time of its last run, reads the new handoffs with cozy_read_many, and calls cozy_context on the pages they link to. It does not have to scan the whole wiki.

Keep durable facts out of the handoff. When a note contains something that will still be true next month, the agent should move it into a wiki/ page and leave a link behind. Handoffs are working state, wiki pages are memory.

Handle concurrent writes

Every edit tool needs an expectedRevision, with 0 for a new file. If another agent changed the page since you read it, the write returns a conflict instead of overwriting. The agent re-reads, merges and retries. For logs and running notes, cozy_append adds to a file without rewriting it.

Deleting a file leaves a tombstone. If an agent damages a page, use cozy_history to see revisions and cozy_restore to bring one back. Moves keep history and return the links that need repair. This is not a substitute for review, but it makes mistakes cheap to undo. Agents cannot see connector credentials or permanently purge.

Keep the shared memory healthy

Many writers produce duplicates and contradictions. Cozy's Health view scores the workspace for broken links, duplicate titles, orphans, stale pages and conflicts, and lists fixes in priority order. See Wiki Health for the checks.

You can also schedule Dreaming, an offline pass your own agent runs. It reads cozy_changes since the last run recorded in agents/dream/state.md, verifies claims against sources, records CONFLICT: lines and merges duplicates. Cozy runs no model itself, so the agent and its cost are yours. Read more in memory consolidation.

Where this does not fit

Search is lexical, with no embeddings, so agents need good titles, aliases and links to find things. Curated files are limited to 90,000 bytes. And if your agents only need private per-user conversation memory inside a product you build, an API memory store may suit better than a wiki. For one person on one machine, a plain CLAUDE.md or local vault is simpler. For the single-agent version of this problem, see agent memory.

Frequently asked questions

How do I share memory between several Claude Code agents?

Connect every agent to https://cozy.cloud/mcp and have it pass the same workspace as the workspace argument, or give headless agents their own bearer credential on the workspace URL. They read and write the same wiki, and cozy_changes shows what others edited. See Connect Claude Code.

What should an agent handoff note contain?

Four short sections: what is done, what is open, what not to repeat, and the next step, with wikilinks to the relevant pages. Store it in the agents/ folder and move lasting facts into wiki/ pages.

What happens if two agents edit the same page?

Edits require an expectedRevision. The second writer gets a conflict instead of overwriting the first, so it re-reads, merges and retries. The last 50 revisions can be restored.

Can I limit what each agent is allowed to change?

Yes. An OAuth agent is capped by the scopes you approved (wiki:read, wiki:write, sources:write) and your own access. Bearer credentials carry the scopes read, wiki-write or source-write, can be restricted to folder prefixes, and never exceed your own access. They expire within 90 days and can be revoked.

Give your agents a memory worth keeping

Cozy gives every account a private wiki that Claude, Codex, ChatGPT and other MCP clients can read and maintain.

Start your wiki