Our AI coworkers run on files

The most consequential architecture decision we made for our agents is also the least glamorous: agent memory is plain files in a git-friendly tree. One note per fact, frontmatter for machines, prose for the model:

---
name: payment-retry-policy
description: retry queue must never re-attempt a captured payment
type: project
---
The retry worker treats 'captured' as terminal. The 2025-11 double-charge
incident came from retrying on a timeout after capture succeeded.
Related: [[refund-flow]], [[idempotency-keys]]

A session starts by reading a 40-line index, one line per note, not the 400 KB corpus. The model picks the two or three notes whose description matches the task and opens exactly those. Retrieval is a decision made by something that can reason, against descriptions a human curated, and it is fully explainable after the fact: here is the index line, here is the file, here is the sentence.

Why not embeddings

We prototyped the same corpus behind a vector store and killed it in two weeks. When an agent behaved oddly there was no file to open, only similarity scores to second-guess. Corrections meant re-embedding instead of editing a paragraph. And nothing about a few hundred curated notes needs approximate nearest neighbors; the whole index fits in one screen of context. Embeddings solve scale and fuzziness. Curated memory has neither problem.

Caps matter more than schemas

• The rules file fits on one screen, and adding a line requires deleting a line.
• The state file has a hard line cap; a cron sweeps anything stale into an archive that recall can still search.
• Every note links related notes with [[name]] references, so the graph is walkable with grep alone.

Memory that grows without bound stops being read, and memory that is not read is decoration. The caps are what keep the system honest.

The boundary that makes it safe

Agents propose, gates dispose. An agent can draft anything into its tree, but irreversible actions, deploys, deletions, payments, outbound messages, pass through the same mechanical gates as our cron jobs: whitelists, caps, ledgers, human approval where it counts. We do not ask the model to remember to be careful. Care is compiled into the pipeline around it.