revise
Update an existing memory item by ID, keeping unmentioned fields unchanged and requiring a reason before any checked rule is weakened.
Instructions
Code lane: corrects an EXISTING item by id through the same write gate as remember; a field left unmentioned keeps its current value, and none may silently vanish - clear one with clear_severity/clear_project/clear_expires/clear_key/clear_falsifier/clear_check; an empty string on the field is the harness-only equivalent, and a flag plus a real value for that field is refused. Weakening a checked rule (its check, severity, a binding, or scope) needs because: one sentence, kept in history. On a replica this queues instead of writing ('queued for the main machine' is not an error). Prefer this over remember for an existing item that merely changed; retract, with its own reason, is for one that is simply wrong. Refuses, with the exact reason, on remember's grounds, plus a dropped field or an unexplained weakening. Replies with the revised id and event sequence, or the refusal text.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The id of the existing item to correct. | |
| key | No | Omit to keep the current key; pass "" to clear it (see `clear_key` below for the spelling that reaches this server from an assistant). | |
| tags | No | Replaces the whole tag list. Omit to keep the current tags; pass an empty list to clear them on purpose - the same omit-keeps/empty-clears convention as severity/project/expires/key/falsifier, spelled with a list: omitted means unmentioned, an empty array means deliberately cleared, a real list replaces the whole set. | |
| text | No | New text, replacing the whole body. Omit to keep the current text unchanged. For a SMALL correction to a long item, prefer `append` or `replace_from`/`replace_to` below - retyping a 290-character rule to fix one word is friction on exactly the maintenance this memory needs most, and it is the reason corrections get skipped. | |
| always | No | Replaces whether this item is bound Always - see `moments`' own note. | |
| append | No | Add this to the END of the current text, with one space between. Refused together with `text` (say what the body is, or say what to add to it, never both). The result still goes through the whole gate, so a 300-character limit is enforced on what comes out, not on what you typed. | |
| because | No | Required when this revise WEAKENS a Rule/Orientation that carries a check: clearing or changing the check, lowering or clearing severity, removing a binding (target, moment or Always), or narrowing scope from global to one project. Say in one sentence why - it is written into this item's own history (see `history`), the same way retract's reason is, so the owner can read later why a rule that could refuse a write lost its teeth. Blank or missing on one of those five is refused outright. Accepted and stored on any other revise too, but never required for one. | |
| expires | No | Omit to keep the current expiry; pass "" to clear it (see `clear_expires` below for the spelling that reaches this server from an assistant). | |
| moments | No | Replaces the moment bindings. Give this, `targets`, and/or `always` TOGETHER to replace the WHOLE binding list in one call - when none of the three are given, the existing bindings are kept untouched. See RememberArgs' own note on which moments actually fire - a NEW answer/ claim_done binding is refused here too, though one the item already carried stays correctable. | |
| project | No | Omit to keep the current project; pass "" to make it global (see `clear_project` below for the spelling that reaches this server from an assistant). | |
| targets | No | Replaces the target bindings - see `moments`' own note on how the three binding fields combine. | |
| severity | No | One of: irreversible, costly, house_style. Omit to keep the current value; pass "" to clear it (see `clear_severity` below for the spelling of a clear that actually reaches this server from an assistant). | |
| clear_key | No | Set true to clear key - same fix and convention as `clear_severity` above. Refused, naming the conflict, if `key` is also given here as a real, non-empty value. | |
| falsifier | No | Omit to keep the current falsifier; pass "" to clear it (a Rule or Orientation left with none is refused, same as at creation - see `clear_falsifier` below for the spelling that reaches this server from an assistant). | |
| check_kind | No | One of: path_exists, contains, absent, absent_all, forbidden, requires. Omit all four check_* fields to keep the current check untouched; pass check_kind as "" to clear it (refused if check_path/check_literal/check_literals is also given) - see `clear_check` below for the spelling that reaches this server from an assistant. Give check_kind plus whichever of check_path/check_literal/check_literals the kind takes, together, to replace the check wholesale - see RememberArgs' own check_kind note for what each kind needs and which to prefer. | |
| check_path | No | See check_kind's own note on the omit/clear/replace convention, and RememberArgs' own note on check_path for the directory shape contains/absent/absent_all also accept (every regular file DIRECTLY inside it, never a subdirectory). Refused outright if check_kind is "forbidden" - that kind carries no path at all. | |
| replace_to | No | What `replace_from` becomes. Pass an empty string to delete the substring. | |
| clear_check | No | Set true to clear the check - the same clear `check_kind: ""` above documents, same fix and convention as `clear_severity`'s own doc comment (see there for the defect and the evidence). Refused, naming the conflict, together with a non-empty check_kind, or with check_path/check_literal/check_literals - clearing takes none of the four; give a real check_kind (plus whatever it needs) to replace the check instead. | |
| replace_from | No | Replace the FIRST occurrence of this substring in the current text with `replace_to`. Refused unless `replace_to` is given too, refused together with `text`, and refused when the substring is not actually in the current text - a silent no-op would report success while changing nothing. | |
| check_literal | No | See check_kind's own note on the omit/clear/replace convention. | |
| clear_expires | No | Set true to clear expires - same fix and convention as `clear_severity` above. Refused, naming the conflict, if `expires` is also given here as a real, non-empty value. | |
| clear_project | No | Set true to clear project (make it global) - same fix and convention as `clear_severity` above. Refused, naming the conflict, if `project` is also given here as a real, non-empty value. | |
| check_literals | No | The set form of check_literal, for check_kind absent_all or forbidden - see RememberArgs' own note on why this is a repeatable field rather than a delimited string. Same omit/clear/replace convention as check_kind: an empty list here reads the same as omitting it, since a list has no separate way to say 'given, but deliberately empty'. | |
| clear_severity | No | Set true to clear severity - the same clear `severity: ""` above documents, run through the identical code path, never a second mechanism. THE DEFECT THIS FIXES, bitten twice (2026-09-09 and 2026-09-11): an assistant's tool-call layer drops an empty-string argument before it ever reaches this server (the field arrives as though it was never mentioned, or the call itself is rejected before that), and a literal '""' arrives as two quote characters, not an empty value - so the one documented way to clear a field was never actually reachable from an assistant. Both sessions gave up, retracted the rule and stored a fresh one with no check, silently losing its history. This flag is the one that works from an assistant; the empty string above still works for a caller that can send one (the JSON-RPC harness). Refused, naming the conflict, if `severity` is ALSO given here as a real, non-empty value - say one or the other, never both. | |
| clear_falsifier | No | Set true to clear falsifier - same fix and convention as `clear_severity` above (still refused outright on a Rule/Orientation, same as `falsifier: ""` above, by the same ground that guards creation). Refused, naming the conflict, if `falsifier` is also given here as a real, non-empty value. | |
| new_collection_named_by_owner | No | THE OWNER JUST NAMED A NEW COLLECTION - repeat that name here, exactly as he gave it. Same field, same rule and same one flow as on remember: only after nothing fitted, you showed him the refusal and he answered with a name. It must match the project (or key) this call files the item under. |