> ## Documentation Index > Fetch the complete documentation index at: https://piloop.autoresearch.inc/llms.txt > Use this file to discover all available pages before exploring further. # Research memory > What past campaigns found, for every agent and for the next orchestrator session. 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. ```sql theme={null} INSERT INTO lessons (project_id, family, status, effect, metric, body, created_by) VALUES (3, 'confidence calibration', 'dead', 0.002, 'accuracy', 'Three attempts (idea#41, #57, #63) on evaluator#3 calibrated well on the panel and moved nothing.', 'orchestrator'); ``` 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 =

)`, whatever directory each campaign ran in. ## Documents Campaign reports, orchestrator logs and design notes live outside the database. Name them in `piloop.toml`: ```toml theme={null} [memory] documents = ["docs/evidence/**/*.md"] ``` `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.] 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 ""` 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.