Guides
Persistent memory for AI agents: files or memory APIs
Persistent memory for AI agents can be stored two ways. A memory API extracts facts from conversations into a vector or graph store and retrieves them by similarity. A file-based approach keeps readable Markdown that any agent reads and edits. APIs suit high-volume app memory. Files suit memory that people need to inspect, correct and own.
The two approaches
Long-term memory for LLM agents means the agent still knows something next session. There are two common designs.
Memory APIs sit between the agent and a store. You send conversation turns, the service extracts facts, indexes them with embeddings or a graph, and returns relevant ones at query time. Mem0, Zep and Supermemory are examples.
Plain files keep memory as Markdown, text, JSON or CSV in a folder the agent can read and write. Claude Code's auto memory, Codex's AGENTS.md and Letta's MemFS work this way in different forms. Cozy is also in this camp.
What memory APIs do well
Be fair to the API side. These systems solve problems that files do not.
- Automatic extraction. The service decides what to remember from raw conversation. With files, an agent or person has to write the note.
- Semantic retrieval. Embedding search finds related items even when the wording differs. Cozy has no embeddings and its search is lexical, so heavy semantic recall is a real gap.
- Scale per end user. Mem0 is built to sit inside an app serving many users. Zep's Graphiti models facts as bi-temporal edges with validity windows, and Zep lists SOC 2 Type II and HIPAA support on its pricing page.
- Connectors and file processing. Supermemory offers a broader set of built-in connectors and a managed retrieval stack.
What plain files do well
- You can read the memory. Open a file and see exactly what the agent will be told. Fix a wrong fact with an edit.
- No retrieval index to trust. Nothing is lost inside an embedding. Mem0's export is an LLM-driven job against a schema you supply, while files are already files.
- Portability. Any agent that can read a file can use the memory, and you can move the folder.
- No metering. The memory APIs above bill per token, query or credit. Files have no per-write meter at the storage layer.
The honest weakness of files
Zep published a critique of Markdown memory. It concedes files work for one agent and one user, then argues they break with concurrent writes, stale facts, unresolved contradictions, and no audit trail or access control. Those are fair concerns for a bare folder. They are not inherent to files if the storage layer adds guardrails.
How Cozy answers those concerns
Cozy is a private wiki and cloud file space for each person and their AI agents. It runs no model, so you bring your own agent, and it exposes every workspace through one hosted MCP server per account. Each concern maps to a mechanism:
| Concern | Cozy mechanism |
|---|---|
| Concurrent writes | Edits need expectedRevision, and a clash returns a conflict |
| Stale facts | Health flags pages whose cited source changed after the last edit |
| Contradictions | CONFLICT: lines are counted in Health |
| No audit trail | History, with the last 50 revisions readable and restorable |
| Access control | Scopes read, wiki-write, source-write, optional folder prefixes, revocable and expiring |
The graph is derived from Markdown conventions on every save: frontmatter, wikilinks and relation:: [[target]] lines. Tools such as cozy_context return a page with typed neighbors, excerpts and warnings, and cozy_graph walks relations to depth 3. See typed links for the syntax.
Consolidation is called Dreaming. Your own agent runs it: orient with cozy_health, scope to cozy_changes since the last run, verify claims against sources, merge duplicates, record CONFLICT: lines and log the run. Details are on memory consolidation.
What Cozy does not do
Cozy does not extract memories automatically, does not use embeddings, and does not model facts as bi-temporal edges. Freshness is handled with as_of frontmatter, stale-page detection and conflict lines, which is coarser than Graphiti but readable by a person. If your product needs per-user recall across thousands of end users, a memory API is the better fit.
Choosing
- Building memory into an app for many end users: use an API such as Mem0 or Zep.
- Memory a person must inspect and correct, shared across Claude, Codex and other clients: use files with guardrails.
- An agent runtime that owns its memory: look at Letta, which is also file-based but requires its harness.
- Unsure: start with files, since you can read them and move them later.
For a side-by-side with the API products see Cozy vs Mem0, Zep, Letta and Supermemory. To connect an agent, start with Claude Code and point it at https://cozy.cloud/mcp.
Frequently asked questions
What is the best way to give an AI agent persistent memory?
It depends on who needs to read the memory. For per-user recall inside an app, a memory API with retrieval fits. For memory that people must inspect, edit and share across agents, plain files with revision checks and audit history fit better.
Do I need a vector database for long-term LLM memory?
Not always. Vector search helps with fuzzy semantic recall, but a file-based wiki with lexical search and links works for many personal uses. Cozy uses no embeddings, so it is weaker where semantic matching matters.
How does Cozy stop two agents overwriting each other?
Edits require expectedRevision, which is 0 for a new file. If another write landed first, the edit returns a conflict instead of overwriting, and the last 50 revisions can be restored. See multi-agent memory.
Does Cozy extract memories automatically?
No. Cozy runs no model. Your own agent writes pages and runs the Dreaming consolidation pass through MCP tools.
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