Supersede

supersede is the lifecycle operation. It is how records get retired, replaced, or merged without losing their history.

Why supersede instead of update

Records in Cortex are append-only in spirit. A record’s content can be edited, but its identity — its ID, its provenance, its place in the relation graph — should be stable.

When something genuinely changes — a fact is corrected, a decision is reversed, a meeting is rescheduled — the right model is not “edit the old record” but “produce a new record and mark the old one superseded.”

The benefits:

• History is preserved. The old record still exists, still has its provenance, still resolves by ID. It is just marked superseded and excluded from default recalls.
• Provenance is explicit. The new record’s provenance.supersedes field points to the old one. Anyone reading the new record can trace back to its predecessor.
• Relation graphs survive. Any record that was related to the old one is still related to it; the relationship can be carried forward to the new record by explicit declaration.

Shape

Supersede takes:

Argument	Description
record_id	The ID of the record being superseded
replacement	The new record content (or a reference to an already-captured one)
reason	Optional human-readable reason for the supersession

It returns the ID of the new record and confirms the status change on the old record.

What happens

1. The old record’s frontmatter is updated: status: superseded, superseded_by: <new_id>, superseded_at: <timestamp>.
2. If a replacement is provided inline, a new record is created with provenance back to the old one.
3. The SQLite sidecar is updated: the old record is excluded from default recall ranking, the new record is indexed.
4. Optionally, the change is committed to git as a single commit covering both file changes.

Use cases

• Correcting a fact. A meeting was minuted incorrectly; the corrected version supersedes the original.
• Replacing a stale memory. The architecture changed; the new description supersedes the old one.
• Merging duplicates. Two records ended up describing the same thing; one supersedes the other, and any related-to references are migrated.
• Closing a thread. A long-running open item is resolved; a final record supersedes the running notes.

In all of these cases, the old record is still there. It can be read, linked to, and reasoned about. It just no longer surfaces in default queries.

What supersede is not

• It is not delete. The old record is preserved.
• It is not edit. The old record’s content is not modified, only its status field.
• It is not implicit. The user (or AI client acting on behalf of the user) must explicitly call supersede; nothing else marks records superseded.

The explicit boundary is what makes the operation safe to use confidently. A record that has not been superseded is current; a record that has been superseded is historic. There is no third state.