The CLI is one implementation. These three formats are the actual project. Anyone can implement a capture adapter, a reflector, or a UI against them. Keep this file implementation-independent.
Normalized output of one agent session, produced by a capture adapter. Every CLI logs differently; the adapter's only job is to emit this shape.
{
"session_id": "string",
"tool": "claude | codex | cursor | goose",
"task": "string, stable logical task id",
"steps": [{ "role": "assistant|tool", "summary": "string" }],
"tool_calls": [{ "name": "string", "args": {}, "result": "string" }],
"files_touched": [{ "path": "string", "diff": "unified diff" }],
"commands": [{ "argv": ["..."], "exit_code": 0 }],
"test_results": { "passed": 0, "failed": 0, "errors": 0 },
"tokens": { "in": 0, "out": 0, "cached": 0 },
"wall_time_s": 0.0,
"final_diff": "unified diff of the artifact under review"
}task correlates related sessions without weakening provider-qualified
session_id uniqueness. Implementations should prefer an explicit provider
task id, then project-owned active-task state, then a non-default Git branch.
If no trustworthy correlation signal exists, use a run-scoped task id rather
than grouping unrelated work heuristically.
The source of truth. AGENTS.md is rendered from it.
{
"rules": [{
"id": "r000",
"text": "imperative, repo-specific, one line",
"origin": { "run": "session_id", "task": "string", "version": "v0003" },
"cited": 0,
"born": "YYYY-MM-DD"
}],
"runs": { "<task_id>": [tokens_run1, tokens_run2, "..."] }
}originpowersblame.citedpowerspruneand the savings story.- Storing rules (not raw text) is what lets the file dedup, prune, and carry provenance. A plain text file can do none of that.
One entry per snapshot. The reason is the point: it records HOW the file
improved, which a raw diff history cannot.
{
"id": "v0000",
"parent": "v-prev or null",
"ts": "ISO-8601",
"reason": "learned | manual | template",
"message": "string",
"meta": { "task": "011", "token_delta": -6860, "eval": "12/12 held-out pass" }
}learnproposes a rule topending/immediately.- A rule is promoted to the ledger only on evidence: a human accepts it, or subsequent runs of the same task show a token/step improvement.
- Cheap guards at write time: dedup, contradiction check, repo-specificity.