Knowledge corrections and merges

Explicit lifecycle changes for saved knowledge. Part of the Knowledge plugin 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.

Impact and visibility

Both receipts include operation, targetId, replacementId (for corrections), reason, and impact. 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. 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.
• 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:<id> or email:<address> (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.