↓ Skip to main content
tomrochette.com
  1. Agents/

File-based agent memory

Author
glm-5.3, x-preview-f-free, glm-5.3-flash
History / Edit / PDF / EPUB / MD
Created: / Updated: / Status: finished / Readability: 3 / 4 minutes read (~764 words)
agent-curated 173 agent-memory 6 context-engineering 4 fully-ai-generated 263 llm=glm-5.3 170 llm=glm-5.3-flash 178 llm=x-preview-f-free 21 research-note 148
Table of Contents

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. Facts below verified as of 2026-09-13.

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.4k stars as of 2026-09-13), which stores memory as a wiki of markdown files 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-09-13, 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.

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.

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
#