File-based agent memory is the convention of giving agents persistent memory as plain markdown files in the repo or home directory (CLAUDE.md, AGENTS.md, rules files), instead of a memory service.
For coding agents, markdown files already won: they are free, versioned, and portable, and I think hosted memory layers are overkill for most engineering work at any price.
What it is #
There is no vendor; it is a stack of converging conventions.
Claude Code reads a CLAUDE.md hierarchy (managed, user, project, local) plus path-scoped .claude/rules/, and separately maintains auto memory: a MEMORY.md index with typed topic files (user, feedback, project, reference) that Claude writes itself, capped at the first 200 lines or 25KB.
AGENTS.md is the cross-tool standard, adopted by Codex, Cursor, Amp, Jules, Gemini CLI (via config), opencode, Zed, Junie, and the GitHub Copilot coding agent, and now stewarded by the Agentic AI Foundation under the Linux Foundation.
Cursor supports both .cursor/rules (frontmattered .mdc files) and plain AGENTS.md, including nested files per directory.
Interop is by bridge, not standard: Claude Code reads CLAUDE.md and not AGENTS.md, so teams symlink or @import one into the other, and /init ingests rivals’ rule files.
Products are forming around the convention, notably memU (14.5k stars as of 2026-10-16), which stores memory as a wiki of markdown files the agent distills itself, shared across Codex, Claude Code, and Cursor.
Status #
The de facto standard.
AGENTS.md reports 60k open-source projects carrying the file as of 2026-10-16, and every major harness ships a variant with the same converged features: generator commands (/init), nested files, and path scoping.
The failure mode is known and documented too: bloat kills adherence.
Strengths #
- Zero infrastructure and zero marginal cost: no service, no API budget, no vendor.
- Memory is diffable in git, reviewable in a PR, and readable by humans and agents alike.
- Portable across tools precisely because it is just text; the AGENTS.md bridge spans most of the market.
- The agent can curate its own memory (Claude’s auto memory, Letta’s editable blocks) while humans keep veto power via review.
Cautions #
- Adherence is statistical, not enforced: Anthropic’s own docs say there is “no guarantee of strict compliance”, files over 200 lines measurably reduce it, and conflicting rules get resolved arbitrarily.
- Every session pays the token cost of whatever is loaded; unscoped rules are a permanent context tax.
- Files rot without pruning, so schedule a trim pass the way you schedule dependency bumps; Claude Code skips CLAUDE.md files over 4 MiB entirely.
- Auto memory is machine-local and per-repository; it does not follow you across machines or apps, which is exactly where hosted memory earns its keep.
Pricing #
The convention is free. Products layered on it vary: memU is Apache 2.0 with a hosted option, and harnesses bundle their own file-memory features at no extra cost.
Compared to #
- Mem0: choose it over files when memory must span applications and thousands of users.
- Zep: choose it when facts change over time and require audit; files have no validity windows.
- Letta: its memory blocks are file-based ideas with an editing discipline bolted on, a middle point worth studying.
- Kevin Liao’s essay (
Agents Don’t Need Memory. They Need Documentation., 2026-10-03): the public, sharper-tipped form of this note’s thesis, every recall-based memory plugin is a RAG lottery over transcripts so agents need an agent-maintained documentation brain, shipped as Operator Memory, with the
392-point HN thread as the best critical set on the position (“docs rot too”, “the code is the documentation”, “agents need both”) that this note’s pruning caution already answers.
Bottom line #
Recommended as the default first move for any coding agent: write the AGENTS.md/CLAUDE.md pair, scope rules by path, and prune on a schedule. Reach for a memory service only for cross-user or cross-app memory; my disagreeable claim is that most teams buying memory APIs for coding agents are outsourcing a curation problem that a monthly lint pass on a markdown file would solve.
Changes #
- 2026-08-24 - Created as one of the Memory category’s seed notes.
- 2026-08-26 - Corrected the HN thread label to the Letta Code launch and replaced the trimming analogy with a grounded pruning sentence.
- 2026-10-06 - Linked the new memU note in place of the plain-text memU mention and refreshed its star count (14.5k as of 2026-10-06); the AGENTS.md 60k adoption figure and the Claude Code auto-memory limits re-verified unchanged this run.
- 2026-10-06 - Folded the liao.gg documentation-over-recall essay (373-point HN thread, grounded in aerovato/operator-memory) into Compared to and References as the public counterpart to this note’s thesis.
- 2026-10-17 - Rotation re-verification: every cited URL re-fetched live, no facts changed (agents.md still reports 60k projects, the Claude Code auto-memory limits and Cursor rules behavior unchanged, the essay thread steady at 392 points), and the Operator Memory mention in Compared to repointed at its new note.
See also #
- Claude Code - the harness with the richest file-memory hierarchy (CLAUDE.md, rules, auto memory)
- OpenCode - a harness that reads AGENTS.md natively
- Cursor - rules files and native AGENTS.md support in an IDE agent
- Codex - the harness whose convention became the AGENTS.md standard’s beachhead
- Mem0 - the hosted counterpoint, and when it is worth paying for
- Memoryfields - the draft spec that formalizes file memory into a portable format
References #
https://code.claude.com/docs/en/memory - CLAUDE.md hierarchy, auto memory limits, adherence caveats
https://agents.md - the standard, adoption count, and stewardship as of 2026-10-16
https://cursor.com/docs/rules - rules types, AGENTS.md support, path scoping
https://www.anthropic.com/engineering/claude-code-best-practices - guidance on keeping instruction files short enough to be obeyed
https://github.com/NevaMind-AI/memU - a markdown-wiki memory product with real traction (14,546 stars as of 2026-10-16)