Skip to main content

An agent's files

Each resident agent is a folder of plain text files in the vault, plus a few rows in the logbook. Nothing it learns carries over to the next wake unless it wrote it down.

Where you see it​

Each agent has its own folder in the vault. The owner can open any of these files and read them like a note. The Office page shows the same things in a friendlier way: the goal, the plan, the current step, the face.

What happens, step by step​

Here is every file in an agent's folder.

FileWhat it isOwner edits?Agent edits?
agent.mdThe contract: who it is, its goal, its rules, when to stopYes, it is the owner's to changeNever
memory.mdWhat it learned: decisions, lessons, open threads. Not a diary.Rarely, to fix a mistakeYes
scoreboard.mdThe one number it is graded on, the target, and the historyRarelyYes
run-log.mdOne line per wake. A view drawn from the logbook.No, read onlyNo, it writes a logbook row instead
inbox.mdWhat happened while it slept: the owner's answers, notes from routed emailYes, a line here reaches it next wakeYes, it deletes each entry once handled
display-name.txtOptional. The name the owner sees.YesYes
avatar.png and look.jsonIts pixel-art face, and the colors for its figure in the office pictureYesNo
skills/proposed/Skills it drafted for itself. Nothing here runs.Yes, to promote oneYes, to write one
A site playbookHow to drive one website it uses, kept up to dateRarelyYes

A normal wake uses them like this:

  1. The agent wakes and reads agent.md first. This tells it who it is and what it must never do.
  2. It reads its plan from the logbook, then memory.md, scoreboard.md, and the last lines of its run log.
  3. Only then does it open inbox.md. Say the owner typed "Skip the June date, the room is taken." The agent acts on it and deletes the line.
  4. At the end, it updates memory.md with anything worth keeping, updates the score, and writes one row that says what it did.
  5. The run log file is rebuilt from those rows. Anyone who edits run-log.md by hand will see the edit vanish.

The plan and the next wake are rows, not files. They used to be files. Now the plan (the milestones and the numbers it works toward) and the next wake time live in the logbook, the system's database. The agent reaches them only through one door, logbook.py plan (the plan door). The Office page reads and writes the same rows, so the two can never disagree.

What powers it​

PartWhat it does
agent.mdThe contract. The owner's file, never the agent's.
memory.mdWhat the agent keeps between wakes.
inbox.mdThe mailbox for things that happened while it slept.
logbook.py session didWrites the one-line record of a wake. run-log.md is drawn from these.
logbook.py planThe plan door: milestones, numbers, and the next wake time.
skills/proposed/A holding pen. A skill here does nothing until the owner moves it.

Why it works this way​

Only what is written survives

An agent is not a program that stays running. Each wake is a fresh start. If it did not write something down before it stopped, it is gone.

agent.md belongs to the owner because it is the deal between them. It says what the agent is for and where its limits are. If the agent could edit it, it could quietly widen its own job.

run-log.md is read-only for a similar reason. A log the agent can rewrite is a log nobody can trust. So the agent writes a row to the logbook, and the file is rebuilt from the rows.

Proposed skills do not run because an agent should not be able to hand itself new powers. The owner reads it and moves it if it is good.

Nothing from an email or a sign-up form may ever go into memory.md. Memory is read at the start of every wake. One bad line there would steer every wake after it.

Connected to​