--- summary: "Correct, withdraw, supersede, merge, and unmerge Knowledge records while preserving originals and history" read_when: - A saved Knowledge claim or relationship is wrong and needs replacing - Earlier Knowledge claims are replaced by a claim that already exists, such as status snapshots by their outcome - You need to retract a Knowledge record without deleting history - Two Knowledge pages turn out to describe the same person or entity title: "Knowledge corrections and merges" sidebarTitle: "Corrections and merges" --- Explicit lifecycle changes for saved knowledge. Part of the [Knowledge plugin](/plugins/knowledge) guide. These are agent-only operations. The Control UI inspects records and history and can hand a correction request to chat, but has no direct write controls. Ask the agent, or use the `knowledge-correct` skill. ## Correct a claim or relationship `knowledge_correct` takes: - `requestId`, the exact target `id`, `expectedRevision`, `expectedHash`, and a nonblank `reason`; - the current `expectedOntologyFingerprint` and an optional `expectedVaultId`; - a complete `replacement` of the same kind: `{kind: "claim", ...}` or `{kind: "relationship", ...}`, validated like a create. The target must be a valid active (or expired) claim or explicit relationship. The replacement cannot depend on the original or its dependents. New evidence never supersedes anything automatically. The original keeps its content and evidence and gets a new revision with `lifecycle: superseded`, `superseded_by`, and `lifecycle_change: {reason, at, actor, request_id}`. The replacement is a new record at revision 1 with `supersedes`. Both changes publish in one journal entry with one receipt. Pages are not corrected this way. Edit page prose with a revision-fenced `knowledge_save_page` or `knowledge_edit_body`. ## Withdraw a record `knowledge_withdraw` takes `requestId`, `id`, `expectedRevision`, `expectedHash`, `reason`, and an optional `expectedVaultId`. It retracts one page, claim, or explicit relationship, including a superseded record or one with validation findings. Withdrawing one relationship never withdraws others with the same endpoints. A withdrawn record rejects new withdrawal requests; the original request stays retryable. Withdrawal is not erasure. Originals, evidence, history, Git, exports, and backups keep their content. There is no unwithdraw. ## Supersede claims by an existing claim `knowledge_correct` writes a new replacement. When the replacement already exists, for example a series of CI and review snapshots about one PR followed by the claim that it merged, use `knowledge_supersede` instead so no duplicate is written: - `knowledge_supersede` takes `requestId`, a nonblank `reason`, an optional `expectedVaultId`, `by: {id, expectedRevision, expectedHash}` (the claim that replaces them), and `superseded`: 1 to 25 `{id, expectedRevision, expectedHash}` fences of the earlier claims. - `by` must be a current claim in the caller's scope: active, not expired, and not hidden by an unavailable dependency. Each earlier claim must be an active claim, listed once, other than `by`, and share at least one linked page (`entities` or source page, merge redirects followed) with `by`, as a check that both are about the same subject. Link them first with `knowledge_annotate`. - Each earlier claim keeps its text, evidence, attribution, and history and gets a new revision with `lifecycle: superseded`, `superseded_by`, and `lifecycle_change`, exactly like a corrected original. `by` is not rewritten. All changes publish in one journal entry. The receipt has `operation: "supersede"`, `replacementId`, the dependents in `impact`, and one `items` entry with the new revision and hash per superseded claim. - Because `by` must be current and every earlier claim active, supersession cannot form a cycle, and a superseded claim keeps its first replacement. To undo a supersession, call `knowledge_supersede` again with `undo: true`, the same `by`, and the superseded claims' current fences (from the receipt's `items` or `knowledge_record`). Each claim becomes active again without `superseded_by`; its `lifecycle_change` records the undo reason. The receipt has `operation: "unsupersede"`. Undo applies only to supersessions this tool made: a claim replaced by `knowledge_correct` is rejected, since its replacement is a new version of it. Correct or withdraw that replacement instead. ## Impact and visibility Agent receipts for corrections, withdrawals, and supersessions return the changed records and `impact`; the complete receipt from `knowledge_mutation` also includes `operation`, `targetId`, `replacementId` (for corrections and supersessions), and `reason`. `impact.items` lists authorized direct and transitive dependents through `dependencies`, `entities`, `owner`, and relationship endpoints. These are unresolved impacts, not automatic repairs. Nothing rewrites prose copies, cascades, or deletes. Follow up by inspecting and repairing records, or report them unresolved. Default lookup, search, connections, records, and status counts use current eligibility, so inactive records and their dependents are excluded before counting. `knowledge_records({lifecycle: "all"})` lists historical records, and exact record and history reads stay available. Historical lookup and search include superseded records, never withdrawn ones. A page hidden by an inactive dependency can still be edited by exact ID to repair it. ## Recovery and safeguards Repeat the exact request and payload after a lost response, or resume the accepted request with `knowledge_resume`. A changed payload under the same ID is rejected. Conflicts keep the proposed, original, and displaced material and block reads until reviewed; resume never overwrites a conflicting edit. Durable guards in `state.sqlite` record withdrawals and supersessions per store and partition. A restored or stale active Markdown file cannot clear them, and withdrawal outranks supersession. Only a published `knowledge_supersede` undo lifts a supersession guard, for the claims it restores. Back these tables up with the rest of `state.sqlite`: restoring only Markdown or Git cannot rebuild a guard for a record that is no longer present. ## Merge duplicate pages When two pages of the same type are confirmed to be one entity (the user said so or a source states it), merge them instead of correcting each claim: - `knowledge_merge` takes `requestId`, `reason`, `survivor: {id, expectedRevision, expectedHash}`, `absorbed: {id, expectedRevision, expectedHash}`, and optional `title`, `body`, and identity `evidence`. - The absorbed page stays on disk with `lifecycle: merged` and `merged_into`. Records that name it are not rewritten; every read resolves the reference to the survivor. - The survivor gains the absorbed title and aliases, tags, evidence, and fields it lacks. Its own field values win; conflicts are reported. Bodies are never merged automatically; supply `body` to write a combined one. A combined body is subject to the [page budget](/plugins/knowledge/tools#page-budgets). - New writes that reference a merged page are rejected with the survivor's ID. - Chains resolve up to 8 hops to an active page. Cycles, dead ends, and longer chains are invalid, and records that name them are hidden. `knowledge_unmerge` restores the merged page and removes what the merge added to the survivor, keeping values edited since. A body or title written during the merge is not reverted. `knowledge_diagnostics` reports `mergeCandidates`: pages of one type that share a namespaced identity alias such as `discord:` or `email:
` (strong) or an exact normalized title (weak). Confirm identity before merging; never merge on name similarity alone. Automatic merging, merging claims or relationships, and merging across types are not supported.