Skip to main content
Every campaign that piloop ever ran is in one database. Research memory makes it easy to find, so that a new campaign does not pay again for what an old one learned. Agents find it with SQL: there is no search command.

​
Lessons

A lesson is the standing conclusion about one mechanism family (ideas.family) of a project: a row of the lessons table. It replaces the findings on that family. The newest lesson for a project and family is the current one, so a new conclusion is a new row: a lesson is never changed.
The status is dead, promising or untested. effect is the best effect measured, in the units of metric, with its sign: a gain can be a lower time. Both are NULL when nothing was measured. The body says why, citing idea and candidate ids. When a [stop] condition ends a campaign, the closing watchdog writes one lesson for each family that the campaign tried: what was tried, the best effect and on which evaluator, why it stopped, and its status. The orchestrator can write lessons too.

​
The same code, in every clone

projects.repo names the repository that a project works on: the URL of its origin remote, as host/owner/name, or else its path. Two campaigns in two clones of one repository have the same repo. So “what was tried on this code” is one condition, p.repo = (SELECT repo FROM projects WHERE id = <p>), whatever directory each campaign ran in.

​
Documents

Campaign reports, orchestrator logs and design notes live outside the database. Name them in piloop.toml:
piloop init and the stop of a campaign copy them into the documents table. Each distinct content of a file is one row, so a second sync of unchanged files does nothing, and an edited file is a new version. Agents search them with documents_fts, and may add their own. Never name a document that is derived from validation or test data: every agent of every project can read it.

​
What agents read

The briefs of workers and research sweeps open with the current lessons of the repo. Each mechanism family gets one line, from the newest campaign that tried it. The lines are ranked in this order:
  1. The metric of the lesson (lessons.metric). The project’s primary metric comes first. Its other metrics come next. Then come metrics that share a word with them, for example rep_correct_at_b with val_correct_at_b. Then come lessons with no effect. The rest come last.
  2. The status. A dead or promising lesson comes before an untested one.
  3. The size of the effect, whatever its sign. Only lessons in the same metric are compared, so seconds never outrank words.
  4. The age of the campaign. A newer campaign comes first.
The overview is [memory] wake_budget tokens (default 400). [roles.<kind>] wake_budget changes it for one role. 0 turns it off. Watchdogs do not get it by default.
  • The database procedures that every brief carries (piloop schema, “Remember past campaigns”) have the queries: prior attempts at a mechanism on this repo, labelled with the project, what they came to and the metric that judged them; implementations to copy from any project; the current lessons; the documents; and how to read the session that worked a past idea.
  • Research checks this before it develops a seed or proposes an idea. A worker checks it before it builds a mechanism from scratch.
A discard under one project’s evaluator is not a dead end under another’s, so every query shows what judged a result.

​
The orchestrator’s journal

An orchestrator session can lose its context: a crash, or a full context window. The journal lets the next session pick up the work.
  • piloop journal "<line>" adds one line, at most 280 bytes: a decision, a plan or a result, with its ids. The journal is append-only: no agent can change, delete or replace a line.
  • piloop wake prints, in a fixed budget (--budget, default 2000 tokens, headings included), the latest journal lines, the open inbox, the head of each active project and the current lessons on their repos. Each section says how to read what did not fit.
The piloop-operate skill runs piloop wake first and journals as it goes.