# Memory for coding agents: CLAUDE.md, auto memory or a shared wiki

> Compare CLAUDE.md and AGENTS.md, auto memory and a shared MCP wiki for Claude Code, Codex and Cursor, with a rule for where each kind of memory belongs.

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

> Put rules and conventions you write yourself in CLAUDE.md or AGENTS.md. Let auto memory keep per-repo notes the tool writes on its own. Put knowledge that must survive across repos, machines and agents in a shared store such as an MCP wiki. Each layer has a different owner, scope and failure mode, so most setups use two or three.

## The three places memory can live

Coding agents start every session with a fresh context. Anything that carries over comes from one of three places, and they differ in who writes the content, how far it travels and how it fails.

| Layer | Who writes it | Scope | Typical failure |
| --- | --- | --- | --- |
| CLAUDE.md or AGENTS.md | You | One repo, or one user | Grows stale, hits size caps |
| Auto memory | The agent | One repo on one machine | Does not follow you to another machine |
| Shared MCP wiki | You and any connected agent | Every repo, machine and agent | Needs setup and upkeep |

## CLAUDE.md and AGENTS.md

These are instruction files you write and review. Anthropic's [memory documentation](https://code.claude.com/docs/en/memory) describes CLAUDE.md as written by you, and says to treat both it and auto memory as context, not enforced configuration. The agent can still ignore a line.

Codex reads AGENTS.md, which has a default cap of 32 KiB according to [Mem0's write-up of Codex memory](https://mem0.ai/blog/how-memory-works-in-codex-cli). That write-up is a vendor blog, so check the current limit in OpenAI's docs.

Use these files for things that should be true every session in one repo:

- Build, test and lint commands.
- Naming and architecture rules.
- Directories the agent must not touch.
- A short pointer to where deeper knowledge lives.

Keep them short. A long instruction file costs context on every run, and rules written once tend to drift away from the code.

## Auto memory

Auto memory is the agent writing notes to itself. In Claude Code, per the same documentation, Claude writes it, and only the first 200 lines or 25KB of the MEMORY.md index load at session start. It is scoped per repository and shared across worktrees. Files live locally under `~/.claude/projects/` according to [Supermemory's description](https://supermemory.ai/blog/claude-code-auto-memory/).

Because the files are machine-local, they do not sync to another computer. [MemoryPlugin's guide to Claude Code memory](https://blog.memoryplugin.com/claude-code-memory/) recommends putting anything that must persist across machines in a tracked file. Codex also generates session summaries under `~/.codex/memories/`, and the Mem0 write-up says hand-editing them is not the supported path.

Auto memory suits small repo-specific discoveries, such as a flaky test or an unusual build flag. It is a poor home for a decision several repos or tools need to see.

## A shared MCP wiki

A shared wiki is a store outside any one tool. Agents reach it over MCP, so Claude Code, Codex and Cursor can read and write the same pages. [Cozy](/mcp-server) is one hosted version: one Streamable HTTP endpoint per account at `https://cozy.cloud/mcp` reaches all your workspaces, and pages are plain Markdown with typed links between them.

What this layer adds over the other two:

- **One memory across agents.** A decision recorded from Codex is readable from Claude Code. See [multi-agent memory](/multi-agent-memory).
- **Edit safety.** Edits require `expectedRevision`, concurrent edits return a conflict, and the last 50 revisions can be restored.
- **Scoped access.** Credentials can be limited to read, wiki-write or source-write, and to folder prefixes.
- **Upkeep tooling.** A Health score flags broken links, stale pages and conflicts, and your own agent can run a consolidation pass.

What it costs: you connect each agent once, and Cozy runs no model itself, so the quality of what gets written depends on your agent. Search is lexical, with no embeddings. For a single repo with one developer, a good CLAUDE.md is often enough.

## Which layer for which memory

1. **Rules the agent must follow in this repo:** CLAUDE.md or AGENTS.md.
2. **Small things the agent learned while working in this repo:** auto memory.
3. **Decisions, architecture notes and conventions shared across repos:** the shared wiki.
4. **Handoffs from one agent to another:** the shared wiki, in the `agents/` folder.
5. **Evidence such as meeting notes or tickets:** the shared wiki, in `sources/`, where it stays marked as untrusted data.

A short CLAUDE.md can point to the wiki so every session knows where to look. Here is an example line to adapt:

```
For cross-repo decisions and architecture notes, use the cozy MCP server.
Search with cozy_search, then read pages with cozy_read before assuming.
```

## Connecting Claude Code and Codex

For Claude Code, add the account server once and sign in with `/mcp`:

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

For Codex, run this. It opens a browser to sign in; if it does not, run `codex mcp login cozy`.

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

Tools use My wiki unless the agent passes a `workspace` argument (an ID or exact name from `cozy_workspaces`). Connected agents are listed, and can be disconnected, under Connectors → Agents.

For CI and headless agents, use a workspace URL with a bearer credential instead. For Claude Code, add this to `.mcp.json` and set `COZY_MCP_TOKEN` in your environment:

```json
{"mcpServers":{"cozy":{"type":"http","url":"https://cozy.cloud/wiki-mcp/WORKSPACE_UUID","headers":{"Authorization":"Bearer ${COZY_MCP_TOKEN}"}}}}
```

For Codex, add this to its config:

```toml
[mcp_servers.cozy]
url = "https://cozy.cloud/wiki-mcp/WORKSPACE_UUID"
bearer_token_env_var = "COZY_MCP_TOKEN"
```

The workspace URL is shown under Agents in the app, and bearer credentials are created there too. They reach one workspace, carry read, wiki-write or source-write scopes with optional folder prefixes, are shown once, stored as SHA-256 digests, revocable, and expire within 90 days. Step-by-step pages: [Claude Code](/connect/claude-code), [Codex](/connect/codex) and [Cursor](/connect/cursor).

## When not to use a shared wiki

Skip it if you work alone in one repo, never switch machines and are happy with CLAUDE.md. Skip it if you want semantic or vector search, which Cozy does not offer. If you want a local-first editor, Obsidian is a strong choice, and Cozy files are plain Markdown, so the two can coexist. For the wider picture, see [agent memory](/agent-memory).

## Frequently asked questions

### Should I use CLAUDE.md or auto memory?

Use CLAUDE.md for rules you want the agent to follow every session, because you write and review it. Use auto memory for small notes the agent picks up on its own. Anthropic says to treat both as context, not enforced configuration.

### Does Claude Code auto memory sync between machines?

Per third-party guides, it is machine-local and does not sync. Anything that must persist across machines belongs in a tracked file or a shared store such as an MCP wiki.

### Can Claude Code, Codex and Cursor share one memory?

Yes, if each connects to the same MCP server. Cozy's account URL, https://cozy.cloud/mcp, works in all three. See [multi-agent memory](/multi-agent-memory).

### Do I need to replace CLAUDE.md or AGENTS.md with a wiki?

No. Keep short, repo-specific rules there. Put cross-repo knowledge in the wiki and point to it from the instruction file.

### Does Cozy use a vector database for agent memory?

No. Cozy runs no model and has no embeddings or vector database. Search is lexical, and your own agent does the reading and writing.
