Files: the simplest honest memory

Lesson 2 of 5 in Agent Memory: Remembering and Forgetting on Purpose.

Strip away the vendor gloss and long-term memory needs exactly three operations: read at session start, write when something durable is learned, edit or delete when it goes stale. A plain text file gives you all three — and something the fancy alternatives quietly surrender.

Call that property honesty. A memory file is honest because everything about it is inspectable: you can open it and read every fact the agent will believe tomorrow. You can diff it to see what a run added. You can version it in git and answer "when did the agent start believing this?" with a blame command. You can delete a line and be certain it is forgotten. No embedding, no similarity threshold, no opaque retrieval step stands between you and the agent’s beliefs.

The file-memory loop

  1. Session starts
  2. Read memory file into context

    The whole file is serialized into the context window — every fact in it now shapes this session.

  3. Run the agent loop
  4. Learned something durable?

    A preference, a project fact, a procedure that future sessions will need — not scratch detail.

  5. Worth persisting? (write gate)

    Who said it? Will it still be true next month? Is it personal data? Lesson 4 turns this into a checklist.

  6. Append or edit, with date and source

    A dated, attributed entry is auditable; a bare assertion is a future stale fact.

  7. Session ends — file persists

Flat file

One file, read whole at session start. Human-readable, diffable, versionable, deletable line by line.

The catch: the entire file competes for context tokens every single session, relevant or not. Works beautifully up to a few thousand tokens of memory; degrades — in cost and in the model’s attention — as it grows. The honest store is honest partly because it is small enough to read.

Structured store

Keyed records in a database — each fact a row with fields for source, timestamp, expiry. Now you can query ("only facts about this project"), enforce retention, and load selectively instead of wholesale.

The catch: someone must design and maintain the schema and the selection logic, and the store is no longer readable at a glance — auditing needs tooling instead of a text editor.

Vector store

Semantic retrieval at scale — embed every memory, retrieve the top-k most similar to the current task. This is RAG pointed at your own past, and it is the only approach that scales to millions of memories.

The catch: retrieval is fuzzy. Similar-but-wrong memories surface; the memory that mattered may not. And a poisoned entry hides among the embeddings, invisible until the similarity math decides to serve it. You cannot diff a vector index.

Interactive checkpoint quiz (2 questions) — open this page in a browser to take it.