Shared memory vs CLAUDE.md and AGENTS.md files
Instruction files hold the rules an agent follows, per repository or per machine and per client. Org-owned memory holds searchable facts that follow you across both. Use both.
CLAUDE.md and AGENTS.md are instruction files: static text one client loads at the start of a session, from the repository or from a user-level file on that machine. Memory is a searchable store the organization owns, scoped private or shared, that any client reaches through MCP. Put standing rules in the file. Put durable facts, preferences and decisions in memory.
| Aspect | CLAUDE.md or AGENTS.md | Org-owned memory |
|---|---|---|
| Reaches the agent | the whole file, every session | search hits, plus a pinned index at session start |
| Scope | one repository or one machine, one client | the organization, private or shared |
| Changes by | a commit | memory__update_memory, archive, or a proposal |
| Who sees it | anyone with the repository | you, or the whole org if shared |
| Enforced | the client treats it as instruction | never; it is context |
| Best for | commands, conventions, hard rules | preferences, decisions, relationships, constraints |
What do instruction files do well?
An instruction file is loaded every session, in full, before the agent does anything. A repository file is versioned with the code and reviewed like code, and it is scoped to that project, so a rule about one project never leaks into another. A user-level file carries your own rules to every project on that machine. And the agent always sees it, with no retrieval step that might miss.
That makes it the right home for rules: how to run the tests, which commands to avoid, naming conventions, what the agent must do before it opens a pull request. It is also the right home for the standing rules about memory itself, which is covered below.
Where do instruction files fall short?
They are static. A change is a commit, and until it merges every agent reads the old text. They are per machine. A user-level file carries your preferences to every project, but only on the machine it sits on; a second laptop, a CI runner or a teammate starts without it. They are per client. Claude Code reads CLAUDE.md, Codex reads AGENTS.md, Cursor reads its own rules, so the same fact is maintained several times or drifts.
They have no search. The whole file enters the context on every session, so it grows, and a long file gets skimmed. They have one scope each. A repository file is read by anyone who clones it, so a private preference does not belong there; a user-level file is read by nobody but you. And they do not learn. A fact an agent discovers at run time, such as which teammate owns a service, has nowhere to go unless someone edits the file afterward.
What does org-owned memory do differently?
Memory on CoreSpeed is a set of MCP tools: memory__remember, memory__search_memory, memory__get_memory, memory__ingest, memory__update_memory, memory__delete_memory, memory__list_memory, memory__link_memories, and, where memory maintenance is rolled out, memory__archive_memory and the proposal tools. The memory page lists all of them.
The organization owns the store. Each write is scope: "private" by default or scope: "shared" when asked for explicitly. Caller identity comes from auth, an agent cannot supply a different user id, and the boundary is enforced in Postgres by row-level security rather than only in application code.
Retrieval is hybrid: exact and relaxed lexical matching, entity aliases and vector similarity fused into one ranking behind memory__search_memory. A memory of 1,200 characters or fewer comes back whole; longer ones come back as the passage that matched. Memory operations cost 0 credits per call. And because the store sits behind the MCP server rather than inside any client, the same memory is there when you move from Claude Code to Codex, or replace the agent.
Two more properties matter for the comparison. On every MCP initialize, the server sends instructions that tell the agent to search memory with two or three short queries at the start of a non-trivial task and to save durable facts after significant work, plus a short index of the caller's pinned memories. And memory enforces nothing. It is context, not policy, which is exactly why rules still belong in the file.
| Concern | Instruction file | Memory |
|---|---|---|
| How it reaches the agent | Whole file, every session | Search hits, plus a pinned index at session start |
| Scope | One repository or one machine, one client | The organization, private or shared |
| How it changes | A commit | memory__update_memory, archive, or a proposal |
| Who sees it | Anyone with the repository, or only you for a user-level file | You, or the whole org if shared |
| Best for | Commands, conventions, hard rules | Preferences, decisions, relationships, constraints |
| Enforcement | The client treats it as instruction | None; it is context |
| Cost | None | 0 credits per call |
How do you use both together?
Write the memory rules into the instruction file, once, and let memory hold the facts. A short block is enough:
## Memory
- At the start of a non-trivial task, call `memory__search_memory` with two or three short queries.
- After significant work, save durable decisions with `memory__remember`.
- Use `scope: "shared"` for facts the whole team should know. Private is the default.Then keep the file for what only the file can do: how to build, how to test, the repository layout, what never to touch. Keep memory for what the file cannot hold well: a product decision and why it was made, a named relationship such as who owns the billing service, an operating constraint, a teammate's stated preference.
What does not belong in memory is the same list as before: a transcript archive, a secret, application data. And when a shared fact goes stale, archive it with superseded_by naming the replacement, where maintenance is available, rather than saving a correction next to it. A correction beside a stale memory does not stop the stale one being retrieved.
One honest limit applies to both. Neither transfers a conversation. Memory holds the facts and decisions that came out of it, and the next session starts from those.
FAQ
Does memory replace CLAUDE.md? No. The file holds rules the client applies every session. Memory holds facts the agent searches for. A team that uses one without the other ends up either with a bloated file or with no standing rules.
Can a teammate's agent read my memories?
Only the ones written with scope: "shared". Private memories are readable by you alone, and row-level security enforces that in the database.
What happens when the file and memory disagree? The file is an instruction and memory is context, so the client follows the file. Save the correction to memory, and where maintenance is rolled out, archive the stale entry.
How much memory do I get? 200 MB on the Free plan and 2 GB on Pro. Calls cost nothing; quotas and rate limits protect the shared service.
Is retrieval good enough to trust? On LongMemEval-S, 500 questions, the published result is 94.2 end to end with a flash-class reader, with retrieval recall at 10 holding 0.99. The write-up is in the LongMemEval post.