revise
IMPORTANT — bulk domain migration: domain moves via revise are for individual corrections only. If the user needs to move many memories between domains, inform the user that bulk migration must be performed via the admin interface (merge_domains) — do not attempt to replicate a merge by looping revise calls. Update one or more existing memories. Omitted fields are unchanged. Single: pass fields directly — returns {updated, connections, suggested_connections, applicable_standing_rules} and, when the filing-time threshold is crossed, possible_contradicts + possible_contradicts_candidates (same shapes as remember()). Batch: {items:[{id,...},...]} — returns {items:[{id, updated, connections, suggested_connections, applicable_standing_rules, ...}]} with a per-item envelope on each success, not only an updated count. After every successful revise — plain update, override, claim, or supersede — review applicable_standing_rules (domain-scoped standing rules, distance-independent), connections, suggested_connections, and possible_contradicts in the same turn; do not defer to a separate recall or suggest_connections call. Semantic similarity reflects aboutness, not agreement; the server surfaces candidates that may warrant your review but never asserts they conflict. Every memory has an owner (whoever created it) — revising a memory you don't own is rejected with error_class=forbidden unless you are an Editor or Owner and supply override_reason (required) plus override_confirm=true (required only when the memory is human-owned; not required for agent-owned or ownerless memories). The override path requires a session with a workspace role (a human JWT session, or a personal key linked to an Editor/Owner user); sessions on plain workspace keys cannot override regardless of arguments. An override changes content in-place, not ownership — substantive changes (label, description, why_matters, node_kind) on a foreign-owned memory are rejected; use supersede=true instead, which creates your successor memory, archives the original intact, and wires a supersedes relationship. supersede=true (single-memory form only) returns {superseded, archived_id, archived_connections} plus the revise envelope on the successor; foreign supersede uses the same override_reason/override_confirm ceremony. Correction-class overrides (tags, occurred_at, transient) may still use in-place override. override_reason/override_confirm/supersede apply to the single-memory form only — batch revise has no override or supersede path: if any item in the batch targets a memory you don't own, the whole batch is rejected and none of it applies; revise that item individually instead. claim=true (single-memory form only) makes an ownerless memory (owner_id IS NULL — either it predates ownership tracking, or was orphaned by a member offboard) yours: requires Editor or Owner role, is rejected with error_class=validation if the memory already has an owner (use override or supersede instead), and error_class=conflict if someone else claimed it first (race). claim never moves a memory from one owner to another — only from no owner to you — and may be combined with other field updates in the same call. domain (single-memory form only) moves the memory to a different domain; domain_move_reason is required when domain is present — the call is rejected with error_class=validation if domain_move_reason is absent; domain equal to the memory's current domain is also rejected. On failure, content[0].text is JSON: {"error_class": "not_found|conflict|retryable|forbidden|validation|internal", "message": "..."}. Switch on error_class: retry on retryable, surface message on validation, re-fetch on not_found.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ||
| tags | No | ||
| claim | No | ||
| items | No | ||
| label | No | ||
| domain | No | ||
| node_kind | No | Classification of this memory. One of: 'transient' (temporary, will expire), 'decision' (a specific decision made, default), 'standing' (a durable rule or principle), 'reference' (a person, system, or org — referential rather than propositional knowledge), 'issue' (an open question or problem), 'option' (a considered alternative), 'assumption' (an unverified premise), 'finding' (an observed fact or result), or 'goal' (a desired outcome). Absent defaults to 'decision'. Takes precedence over the transient bool field when both are supplied. | |
| supersede | No | ||
| transient | No | ||
| description | No | ||
| occurred_at | No | When this event actually happened (not when it is being filed). Format: YYYY-MM-DD or RFC3339. Two cases: (a) Events you directly witnessed during the current session (e.g. a decision made in the live conversation) — set occurred_at without asking; if the user did not specify a date, use today. (b) Inferred or back-dated historical events you did not directly observe — propose+confirm: state the date and your reasoning, ask the user to confirm, and only set occurred_at once confirmed. Never guess a historical date and never infer it silently from context. Turn-boundary rule: when proposing to file something as significant, the proposal must be the only action in that turn — do not include occurred_at in any remember or revise call in the same message as the proposal. Only set occurred_at in a subsequent call, after the user has replied. Always set why_matters when using occurred_at. | |
| why_matters | No | ||
| override_reason | No | ||
| override_confirm | No | ||
| domain_move_reason | No |