# Shared memory for a team of AI agents

> How to give several of your AI agents one shared memory with handoff notes, scoped credentials and safe concurrent edits, using a hosted Markdown wiki over MCP.

Updated 2026-11-09. Canonical: https://cozy.cloud/multi-agent-memory

> 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](https://code.claude.com/docs/en/memory). 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:

- **Reach.** Agents on different machines or products cannot see each other's files.
- **Collisions.** Two agents editing the same page can silently overwrite each other. Zep's [critique of Markdown memory](https://www.getzep.com/blog/markdown-is-not-agent-memory/) lists races, stale facts and contradictions with no audit trail.
- **Handoffs.** When one agent stops, the next one needs to know what was done, what is open and what to avoid. Without a written note, you retype it.

## 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.

| Need | What it means | How Cozy handles it |
| --- | --- | --- |
| One endpoint | Every agent connects to the same place | One hosted MCP endpoint per account, plus per-workspace endpoints for credentials |
| Separate identities | You can tell agents apart and revoke one | Each connected agent listed and disconnectable in Connectors → Agents, or one credential per agent |
| Least privilege | A research agent should not edit curated pages | Scopes read, wiki-write, source-write, plus folder-prefix grants |
| Safe writes | No silent overwrites | expectedRevision on every edit |
| Recovery | Undo a bad agent edit | Last 50 revisions readable and restorable |
| Handoff | State passed to the next agent | agents/ 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:

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

Then sign in with `/mcp`. For Codex:

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

See [Connect Claude Code](/connect/claude-code) and [Connect Codex](/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`:

```markdown
---
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](/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](/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](/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](/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.
