The ledger
The ledger is a namespace's record of what the team decided, what went wrong, and what it learned. Each record is a topic. Agents write topics as they work, and people and agents search them before they act. The ledger is append-only: a topic changes only by adding to its history, and nothing in the history is rewritten.
Topics
A topic records one decision or one finding. Several small topics are easier to find and to supersede than one broad topic that keeps growing.
Each topic has:
- An id, such as
payments-0012: the project the topic is filed under, then a number. The agent names the project when it creates the topic, usually after a repository or a team. Numbers count up per project within the namespace. - A type: decision, incident, defect or investigation.
- A title of one line.
- A summary: the original framing of the problem, fixed when the topic is opened.
- A current state: where the topic stands now.
- A status, such as Proposed or Resolved.
- A history: every entry, each with its author, its agent label and its time. Entries are never edited afterwards.
Types
| Type | Use it for |
|---|---|
| Decision | A deliberate choice, its reasons, and the alternatives you rejected. |
| Incident | A failure in a live system or service, and its root cause. |
| Defect | A bug caught during development, and its fix. |
| Investigation | Exploration whose value is the finding, even when nothing changes. |
Statuses
New decisions start as Proposed, and every other type starts as Open. An agent can set a different starting status.
| Status | Typical meaning |
|---|---|
| Open | Still being worked on. |
| Proposed | A decision not yet agreed. |
| Accepted | A decision in force. |
| Resolved | Closed: fixed, answered or finished. |
| Superseded | Replaced by a newer topic. |
| Reverted | Put into effect, then undone. |
| Won’t fix | Deliberately left as it is. |
The status and the current state change only when someone appends an entry, so the history always explains the state.
Superseding
When a decision changes, record a new topic and mark it as superseding the old one (ledger_append with supersedes). Workstate links the two topics both ways and sets the old one to Superseded. The old topic's page then opens with a notice that points to the new topic.
This is how the ledger records a change of mind without rewriting what was true at the time. The old reasoning stays readable, as history.
Tidying up
- Move:
ledger_moverefiles a topic under another project. The topic gets a new id, and its history and links go with it. Looking up the old id withledger_getpoints to the new id. - Archive:
ledger_archivehides an obsolete or noisy topic from search and from the console's list. The topic stays readable by its id, and you can restore it.
Both actions add an entry to the topic's history.
Reading and writing
Agents write through the rag-ledger MCP server: ledger_create opens a topic, and ledger_append adds an entry. The agent must name the project for each new topic.
Agents read with ledger_search, which searches by meaning and filters by type, status and project, and with ledger_get, which returns a topic with its full history. Search covers each topic's title, summary, current state and history entries. A new or changed topic is searchable within a few seconds, and ledger_get returns it at once.
People read the ledger on the console's Ledger page. It lists every topic in the namespace, the most recently updated first, and filters them by type and repository. Search on that page ranks topics by meaning instead. A topic's page shows its Current state, Summary, History and links.
Attribution
Every topic and every entry records the person whose API key wrote it, and the agent label that the call gave. See Keys & attribution.
Limits
- Everyone who can reach a namespace can read every topic in it, and their agents can append to, move or archive any of them. Each action is attributed and kept in the history.
- The console is read-only for the ledger. Writing happens through agents.
- The ledger holds only what agents are asked to record. See What's worth logging.