Skip to main content

The logbook database

The vault holds what is true and how things are done. The logbook holds what is happening right now. It is one database file on the box, shared by every agent.

Where you see it​

The owner sees the logbook through the screens on the box: the logbook page, the Office, and each agent's desk. Questions an agent asked, plans it made, and money it spent all come from here.

The logbook page on the box The logbook page shows each agent's recent work, drawn from the database.

Each agent also has a run-log.md file. It looks like a diary, but it is drawn from the database. Editing it by hand changes nothing.

What happens, step by step​

  1. Nora, a resident agent, wakes up on her timer.
  2. A checker called wake_hooks.py makes sure she follows her wake checklist. It refuses a skipped step.
  3. She reads her inbox and plan from the logbook.
  4. She finds a question she needs the owner to answer, so she files an ask through the ask door.
  5. She marks a milestone done through the plan door.
  6. At the end she records what she did through the session door.
  7. The runlog door redraws her run-log.md from those rows.

What powers it​

PartWhat it does
logbook.dbThe one SQLite file (a database in a single file) at ~/agent/state/.
logbook.pyThe only way in. Every change goes through one of its named doors.
Named doorsplan, ask, inbox, forum, improve, session, runlog, permissions, thread, spend, interview.
wake_hooks.pyEnforces each agent's wake checklist.
soft_delete.pyMoves deleted items to a deleted-items table instead of erasing them.

The database holds, for every agent: its asks, its inbox, its plan (milestones and blockers), its threads, its settings, its spend, and its history. It also holds one shared settings row that every door reads for which model to use.

Why it works this way​

One module, many doors. Nothing writes to the database directly. Every change goes through logbook.py, through a door with a name and a clear job. That keeps the rules in one place.

Deletes are soft. Nothing an agent deletes is really gone. It moves to a deleted-items table, so a mistake can be undone.

It is not in git. Almost everything else in the system lives in the vault and in git. The logbook is the one deliberate exception. Spend, sessions, and half-done plans change by the minute. They are live state, not shared facts, so they stay on the box. The code that runs the logbook does live in the vault, and ships to the box like any other file.

The engine rule

A new agent is set up, never coded. It is rows in the logbook and files in the vault. If adding an agent means changing logbook.py, the design is wrong.

The engine takes the agent's name as input and knows nothing about any one agent. Nora, Ada, and Otto all run on the same code. A new agent, a new client, or a new kind of project is a matter of setup: rows, settings, and files.

Connected to​