Where writing to a file already works.
A file the model reads at the start of a session solves a real problem cheaply: a language model call carries no memory of the previous one, and a markdown file dropped into the working directory is a simple, portable way to hand it a starting brief. CLAUDE.md, AGENTS.md, and Cursor's .cursor/rules files converge on the same shape — plain text, versioned alongside the code, readable by any tool that opens a text file rather than only by tools that speak a proprietary memory API.
The approach is sensitive to how the file is written, not only to whether one exists. A 2026 study out of ETH Zürich found that a verbose, auto-generated context file lowered a coding agent's task success rate and drove its inference cost up by more than 20%, while a lean file scoped to only what the agent actually needed carried no such penalty. A file being present says nothing about whether the file helps.
The comparison below sets that file-reading habit against substrate memory: a typed graph the model reasons on, rather than a document it re-reads in full at the start of every session.
What a line in a file doesn't carry.
A markdown file stores prose. Recovering structure from it — what kind of statement a line is, what it relates to, whether it is still current — is left to a model reading the whole document and inferring the answer.
| Property | What a plain file lacks |
|---|---|
| no type field | A line in CLAUDE.md or AGENTS.md is a sentence of plain text. It does not declare itself a decision, a question, or a completed task; a model re-reading the file has to infer which one it is from the wording alone. |
| no links between lines | Two related notes in the same file sit near each other only if whoever wrote them thought to place them together. There is no edge recording that one line answers another, or that a later line reverses an earlier one. |
| no supersession | When a decision changes, the common fix is to edit the line in place or delete it. Both discard the record of what used to be true and when it changed — information a flat file has no dedicated place to keep. |
| no per-line provenance | A file records who last committed it as a whole, not who wrote a given line or which agent session was reasoning when it did. Attribution exists at the file level, not the fact level. |
These are the four primitives set out under the typed entry: a type per record, a link between records, an append-only supersession chain, and per-entry provenance. None require abandoning a file. They describe what has to sit underneath one for a model to recover a decision's current status without re-reading the whole document and guessing.
One document, more than one writer.
A markdown file assumes single-writer discipline: one process opens it, appends or edits, and closes it before the next reader arrives. That assumption holds for a single developer session and strains once more than one agent writes to the same file at once — a routine situation once a project runs parallel coding-agent sessions rather than one at a time. Reports of CLAUDE.md files becoming corrupted mid-write, with binary or hex characters appearing in what should be plain text, describe exactly that failure: two writers landing on the same bytes with no lock and no merge step between them.
A shared graph is built for that case rather than tolerating it. Each entry is a separate row, written once by the session that authored it and appended to a shared history rather than overwriting a shared document. Concurrent writers add rows; they do not race for the same bytes.
A whole-file read, every time.
A file read into context loads in full, regardless of how much of it is relevant to the turn at hand. That cost scales with the size of the file rather than the size of the answer. A critique of file-based agent memory published by Mem0, a vendor of a competing memory store, estimates that a memory file of roughly 2,000 entries can consume a meaningful share of the context window before a session has done any work, against a roughly fixed per-query cost for a dedicated retrieval system regardless of how large the underlying store grows. The estimate is the vendor's own and describes file-based memory in general rather than any one product, but the mechanism it points at is structural: a flat file has no selective-read path, only a whole-file one.
A typed graph does not answer that by making retrieval smarter. It removes the need to retrieve for the entries a session already knows it needs, since a thread or a branch can be read back directly by its structure rather than searched across an undifferentiated file. Keyword matching over a markdown file also only finds what shares vocabulary with the query — a note about migrating a frontend framework will not surface for a search on the framework's replacement unless the words happen to overlap, a limitation distinct from the reasoning-versus-retrieval question covered under reasoning over memory.
Files and graph, not files instead of graph.
None of the above argues against keeping a file. A short, well-scoped file read at the start of a session remains the cheapest way to hand a model static, rarely changing context: which package manager a repository uses, which directories are off-limits, which commands are safe to run. That is exactly the kind of standing instruction a CLAUDE.md file is suited to, and Vinculum's own project keeps one — rendered from its own graph, so the standing conventions a session needs on load are generated from decisions already recorded in the graph rather than maintained twice by hand.
The distinction is not file versus graph. It is between context that is genuinely static — safe to read once and trust until someone edits the file — and context that accumulates, reverses, and needs to be attributed to whoever decided it, a shape that changes once many agents share a project over time rather than one agent working alone.
Common questions.
Is this an argument against using CLAUDE.md or AGENTS.md files?
No. A short file read at the start of a session remains a cheap way to hand a model static project context. The comparison concerns what a plain file does not carry on its own — a type per record, a link between records, a supersession chain, per-entry provenance, and safe concurrent writes — not whether to keep a file at all.
Why not just make the file bigger or more structured?
A more detailed file still loads wholesale into context, and still resolves two conflicting lines by convention rather than by structure. The properties in question are relationships between records — what replaced what, what answered what — not formatting choices within a single document, and they do not emerge from writing a longer file.
Does Vinculum use files at all?
Yes. Its own CLAUDE.md file is rendered from its graph and read at the start of every session, as described below. The file is a projection of the graph's standing conventions, not a competing store of them.