Files as State, Not Chat Memory

Tier 1 · Fundamentals 8 min read

If you understand one thing about running agents beyond a single session, make it this: chat memory is not persistent state. The moment a session ends, everything the agent “knew” from conversation is gone. If it matters tomorrow, it goes in a file.

This isn’t a limitation to work around. It’s the right model, and once you internalize it, everything else about running a long-lived agent system becomes simpler.

The problem with treating chat as memory

Suppose you ask an agent to research a topic, and it summarizes findings in its reply. You close the terminal. The next day you open a new session and ask a follow-up question. The agent has no memory of the conversation. It starts from scratch.

Now suppose instead that after the research, you had it write the findings to ~/notes/research.md. The next day’s session reads that file, and it knows everything the prior session found. Session rotation, computer restart, three days passing — none of it matters. The file is still there.

The files-as-state doctrine is: every piece of information that must persist beyond the current session must be written to disk, not left in the conversation.

What belongs in files

In practice, “state” falls into several categories:

Task state. What work is in progress, what’s done, what’s next. The conventional place for this is a WORKPLAN.md file with a checklist of milestones and a CHANGELOG.md with a dated log of what shipped.

Domain state. Ongoing facts about a domain of life or work — open issues, current status, pending decisions. In a larger system these live in per-domain state/*.yaml files, readable by any agent that needs context about that domain.

Agent memory. Research results, learned preferences, CRM records, session digests. These go in dedicated files under a known path (~/obsidian-vault/11-Agents/research/, per-person CRM files, etc.) so any session can read them back.

Configuration. The rules and standing instructions the agent should always follow. This goes in CLAUDE.md files (covered in the next article).

What doesn’t need to go in files: transient computation, intermediate reasoning the agent does to produce an answer, things you don’t care about after the session ends.

The standard file layout

A well-structured project on this system uses this layout:

~/clawd/projects/<slug>/
├── README.md        # what this project is, one paragraph
├── WORKPLAN.md      # milestones and checklist, the plan
├── CHANGELOG.md     # append-only log of what shipped (dates + bullets)
└── LINKS.md         # external URLs, related resources

The CHANGELOG.md is append-only by convention. Nothing is deleted, nothing is edited after the fact. Every significant action gets a timestamped bullet:

## 2026-06-09
- 13:34 — Shipped the fulfillment drainer. Three bugs found and fixed on the first live order.

This pattern means the system can reconstruct what happened — not from conversation history, but from a plain log file that any tool can read.

The master CHANGELOG

In a multi-project system, the per-project changelogs roll up into a master aggregate at ~/clawd/CHANGELOG.md. This file is auto-generated (never hand-edited) by running:

bash ~/agent-system/scripts/daily-rollup.sh --master

The rollup script reads every per-project CHANGELOG.md and combines them by date. As of mid-2026, the master covers 69 active projects and 1,182 lines of history. It’s the source of truth for “what shipped.” When a new session starts, reading the last few days of the master takes 60 seconds and gives full context across all active work.

An append-only system can’t lie to itself

The discipline of append-only changelogs sounds like a minor formatting preference, but it has a real effect. When you never edit history, the log can’t drift from reality. If you shipped something and it didn’t work, you log “shipped X, turned out broken” and then “fixed X.” Both entries stay. The system’s honest record of itself is in the files, not in anyone’s memory of how they wanted things to go.

This is how a single operator can run a system of ~31 agent packages, 155–160 scheduled jobs, and 200+ database tables and still know what’s actually running and what’s actually broken — because the files say so, not memory.

Next: CLAUDE.md: Teaching the Agent Your Rules — the file that gives the agent standing instructions across every session.