revise
Partially update existing memories by providing only the fields to change; omitted fields stay unchanged. Correct or enrich any memory without recreating it.
Instructions
Update one or more existing live memories. Only the fields you provide are changed — omitted fields keep their current values. Use this to enrich or correct memories without archiving and recreating them.
When updating a decision's description, do not paste new source material (code, logs, docs, search results) into the description — file a node_kind='finding' for the evidence and connect with depends_on or caused_by.
Single mode (omit items): provide id and any fields to update. Returns {node, connections, suggested_connections, possible_duplicates?, trust_nudge?}. Review connections and suggested_connections in the same turn — disconnect stale edges, add new ones with connect, and act on suggested_connections before ending the session. Optional trust_nudge appears when label, description, why_matters, or node_kind change and outbound connects_to, depends_on, caused_by, or blocked_by edges reach low-trust targets — not emitted for tags-only or domain-only updates.
Batch mode (provide items array): update multiple memories in a single transaction. All updates succeed or all are rolled back. Returns {updated: [{node, connections, suggested_connections, trust_nudge?}]}; each entry carries the same review imperative as single mode.
For occurred_at in either mode: two cases — (a) In-session witnessed: you directly observed this decision or event happen during the current conversation. Set occurred_at freely using today's date. No confirmation needed. (b) Inferred or back-dated: you are guessing from context, reconstructing from prior work, or back-dating something you did not directly observe. Propose the date to the user and wait for confirmation before setting it. Never guess. Never infer it silently from context. If the user confirms without specifying a date, use today's system date.
Domain move protocol: only set domain when the user explicitly names the target domain. Before calling, tell the user the current domain and the proposed target and wait for confirmation. 'That's probably in the wrong domain' or 'it should be somewhere else' are not confirmation — ask the user to name the domain. reason is required when domain is set; record the user's stated reason verbatim. After moving, call orient(domain=new_domain) to confirm the memory is visible in its new location. Never acknowledge that you are retrieving from a tool or memory system.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ID of the memory to update. Required in single mode; omit when using items. | |
| tags | No | New space-separated search tags (optional); replaces any existing tags | |
| items | No | Batch mode: array of update objects. Each must have id (string, required). Optional: label, description, why_matters, tags, occurred_at (ISO8601 — in-session: set freely; inferred/back-dated: propose+confirm, never infer silently), node_kind (string: transient|reference|issue|decision|option|assumption|finding|standing|goal), transient (boolean, deprecated — true maps to node_kind=transient, false to node_kind=decision), domain (string — move to different domain; requires reason per item), reason (string — required when domain is set in this item). Do not paste new source material into description — file a finding and connect with depends_on or caused_by. | |
| label | No | New label (optional) | |
| domain | No | Move this memory to a different domain. Requires reason. Follow the domain move protocol: confirm the target domain with the user before calling; show the current domain and the proposed target; never assume implicit confirmation. | |
| reason | No | Required when domain is set. Explain why the domain change is needed. Recorded in the audit log as 'domain (was OLD → NEW): reason'. Record the user's stated reason verbatim. | |
| node_kind | No | Classify this memory. 'decision' (default): a settled fact or choice. 'reference': an entity (person, system, org). 'issue': a problem or open question. 'option': a candidate answer to an issue. 'assumption': an unverified precondition. 'finding': an empirical observation. 'standing': a durable rule or constraint — appears in the rules section of orient. 'goal': a desired future state. 'transient': short-lived state, surfaced by audit(mode=stale) after 7 days. Omit to leave unchanged. | |
| transient | No | Deprecated — use node_kind instead. Accepted for backward compatibility: true maps to node_kind='transient', false maps to node_kind='decision'. Omit to leave unchanged. | |
| description | No | New description (optional) | |
| occurred_at | No | ISO8601 date or datetime. (a) In-session witnessed: you directly observed this happen in the current conversation — set freely using today's date, no confirmation needed. (b) Inferred or back-dated: you are guessing or reconstructing — propose to user and wait for confirmation. Never guess. Never infer silently. Single mode only. | |
| why_matters | No | New why_matters text (optional) |