Supersede, move & archive

The ledger is append-only. Nothing in a topic's history is ever edited or deleted: you change the record by adding to it. This page covers the four ways to do that: append, supersede, move and archive.

Why history is never rewritten

• Readers see what was believed, and when. A decision that was right last year may be wrong now. The history shows both, so nobody mistakes an old reason for a current one.
• Authorship stays true. Every entry names the person whose API key wrote it and the agent they used. An edit would put words in someone's name that they never wrote.
• Agents can rely on it. A record that can't be quietly changed is one an agent can cite.

What can change, and how

Part of a topic	How it changes
Title, type and summary	Never. They are fixed when the topic is opened
Current state	Only by appending an entry that sets a new one
Status	By appending an entry, or when a newer topic supersedes it
Repository and id	Only by moving the topic
Whether search finds it	By archiving or restoring it
History entries	Never. New entries are added; old ones stay as they are

Append to evolve a topic

ledger_append records a change to the thing the topic is about: progress, a correction, or the outcome. An entry can also:

• set a new current state (set_state);
• set a new status (set_status);
• say that this topic supersedes another (supersedes, described below).

Each entry has a kind. The kind is a label for readers; it does not change what the entry does.

Kind	Shown in the console as	Use it for
note (the default)	Note	Progress, context or a finding
state_change	State changed	An entry that moves the current state on
status_change	Status changed	An entry that changes the status
correction	Correction	Fixing a mistake in an earlier entry

To fix a mistake, append a correction that says what was wrong and what is right. The mistaken entry stays, and the correction appears above it in the history.

A new decision or finding is not an append. Give it its own topic.

Supersede an earlier topic

When a decision turns out to be wrong, or a better approach replaces it, don't rewrite the old topic. Record the new approach as a new topic, and have it supersede the old one:

1. Create the new topic with ledger_create.
2. Append to the new topic with supersedes set to the old topic's id. In the same entry, set the new topic's own status, for example accepted.

What happens:

• The two topics are linked both ways. The new topic's Links show "Supersedes payments-0012", and the old topic's show "Superseded by payments-0019".
• The old topic's status becomes superseded.
• In the console, the old topic shows a Superseded notice saying that a newer topic replaced it and that the record is kept as history.
• Both topics stay searchable, so anyone who finds the old approach also finds out why it was dropped.

Rules:

• Both topics must be in the same namespace.
• A topic can't supersede itself.
• Recording the same supersession twice changes nothing.

For example, ask your agent: "We're moving from our own retry schedule to the payment provider's smart retries. Record that as a new decision under payments, and have it supersede payments-0012."

Superseded or reverted?

Supersede when a newer topic replaces the old one. If a decision is undone with nothing in its place, append an entry that sets its status to reverted and says why.

Move a topic to another repository

ledger_move refiles a topic that was filed under the wrong repository name. Give it the topic's id and the right repository name.

• The topic gets a new id: the next free number in the new repository. For example, webapp-0003 might become payments-0020.
• The whole history, and every link in both directions, moves with it.
• A note records the move, for example: "Moved from webapp-0003 (repo webapp) to payments-0020 (repo payments); id reassigned."
• The topic keeps its original opening date.
• The old id is never given to another topic. ledger_get on the old id returns a pointer to the new id, so agents can follow it. Appending to the old id is refused, with a message that names the new id.
• A topic moves within its namespace. It can't move to another namespace.

In the console, open the topic by its new id. A saved link to the old id shows "No such topic in this namespace."

For example, ask your agent: "webapp-0003 is about payments, not the web app. Move it to payments."

Archive a topic

Archiving hides a topic without deleting it. Use it for noise: a duplicate, a test entry, or trivia that should never have been recorded.

ledger_archive with a topic's id:

• keeps the topic and its whole history in the ledger;
• hides it from ledger_search, and from the list and the search on the console's Ledger page;
• removes it from the search index, so search_corpus no longer returns it either;
• adds an entry: "Archived (soft-deleted): retained in the ledger, removed from the search index."

An archived topic is still readable by its id. To find archived topics, call ledger_search with archived: true. That search matches words in the title, summary and current state; it does not rank by meaning.

To restore a topic, call ledger_archive with archived: false. The topic is indexed again, and an entry records the restore.

Archive noise, not mistakes

Don't archive a decision because it turned out to be wrong. Supersede it instead, so the lesson stays findable. Archiving is not deletion either: an archived topic is kept. Topics are removed for good only when their whole namespace is deleted.

Who can do this

Anyone whose API key reaches a namespace can append to, supersede, move and archive the topics in it, through their agent. Roles don't limit ledger writes. Every one of these actions adds an entry that names the person and the agent, so the history shows who changed what. The console is read-only for everyone.

Next steps

• Recording decisions
• Incidents & defects
• What's worth logging
• MCP tools