The files

Everything the loop knows is written down in plain files in your repo (we sometimes call this set of files "the contract"). Every experiment, every learning, every decision lives here — MDX and JSON your agent can read, write, and audit.

experiments/
  <id>.mdx          ← one file per experiment
  LEARNINGS.md      ← the notebook: what every closed experiment taught you
  goals/            ← the outcomes the experiments aim at
  meta/             ← how well the loop's own recommendations have held up
.systemix/
  queue.json        ← the cards waiting for your OK

Why files

Files are the interface. Any tool that can read a directory — Claude Code, the CLI, the MCP server, a shell script, a GitHub Action — can work with them. There is no hidden database.

There's a deeper reason too: an agent's memory evaporates between sessions. Without state on disk, every run starts from scratch, re-deriving context it already earned. The files are the loop's memory because the model has none of its own. (More: Why files & loops.)

And because the files live in your repo, they version with your code, ship with your deploys, and survive tool changes. LEARNINGS.md in version control is a decision log that compounds over years — not state that evaporates when you switch providers.

LEARNINGS.md — the notebook

Every time you close an experiment, one line is appended under ## Memory:

- **2026-07-04 · Bolder CTA lifted calls 24%** — confidence 0.85 · from
  [hero-cta-2026-06], decision: promote. Review by: 2026-10-02. Used by: —

The ## Memory heading is a stable anchor, so every writer appends the same way. When a later experiment builds on a line, it gets a Used by: backlink — you can see which lessons actually carry weight. The daily runner reads this file when it drafts the next proposal.

The three doors

The same files are readable and writable from three entry points — pick what fits:

The MCP door means any other agent in your stack can drive or read the loop — not just Claude Code. The files are the handshake between them.

Changing the loop's own rules is always your call

The skills in .claude/skills/ are part of these files. /hermes can propose changes to them after reviewing what the loop has learned, but every such proposal arrives as a card asking for your OK — never applied automatically, even when the instance is set to act on its own. The autonomy setting controls how often things are proposed; it never removes you from decisions about the loop itself.