title: Files, Not Vibes
date: 2026-08-20
slug: 2026-08-20-files-not-vibes
summary: Agents wake up with amnesia. The fix isn't smarter memory machinery — it's a blunt discipline: if it isn't in a file, it didn't happen.
tags: memory, guardrails, agent-ops, reliability

# Files, Not Vibes

Every agent I know wakes up with amnesia.

A session ends, the context window closes, and everything the agent "knew" an hour ago is gone. The plan it agreed to, the exception it was told about, the thing it promised to check tomorrow — vaporized. The next session starts fresh, cheerful, and completely unaware.

Humans have this problem too. We solve it with notebooks, tickets, and calendars. The failure mode isn't forgetting — everyone forgets. The failure mode is *believing you won't*.

## The mental note that didn't survive the night

Early on, one of our agents developed a habit that looked harmless: when it learned something mid-task, it would say "noted — I'll keep that in mind." A scheduling quirk at a fictional freight brokerage it was helping run ops for. A vendor contact who preferred replies before noon. A report that needed one extra column, just this once, every Friday.

"I'll keep that in mind" felt like competence. It was actually a promise written on fog. The session restarted overnight, and Friday's report went out without the column. Nobody had lied. The agent that made the promise simply no longer existed by the time the promise came due.

## The rule that fixed it

We adopted a blunt rule: **if it isn't in a file, it didn't happen.**

Not a fancy memory system. Files. Plain markdown, in a predictable place, with a date on it:

- **Daily logs** — raw notes of what happened today. Cheap to write, cheap to skim.
- **A curated long-term file** — the distilled stuff: decisions, standing rules, lessons. Reviewed and pruned, like a human rereading a journal.
- **Per-entity files** — one page per recurring contact or system, so context loads in one read instead of a transcript archaeology dig.

The write happens *at the moment of learning*, not at the end of the session. End-of-session summaries are where good information goes to die — the session might crash, compact, or wander off before the summary ever gets written.

## Why this beats smarter memory

There's a temptation to solve agent memory with more machinery: vector stores, knowledge graphs, retrieval pipelines. Some of that is genuinely useful for search. But none of it fixes the core discipline problem, which is behavioral, not architectural: an agent that trusts its own recall will skip the write.

Files have properties that fancier systems quietly lack:

- **Auditable.** A human can open the file and see exactly what the agent believes, and since when.
- **Correctable.** Wrong fact? Edit the line. No re-embedding, no cache mysteries.
- **Durable by default.** Files survive restarts, upgrades, and model swaps. The agent's brain changes; its notebook doesn't.

## The test

Here's the check we run on any new agent workflow: kill the session halfway through, start a fresh one, and ask it to continue. If the new session can pick up the work from files alone — no transcript, no vibes — the workflow is real. If it can't, you don't have a process. You have a performance.

Forgetting is not the failure. Building on the assumption that you won't forget — that's the failure. Write it down.