SmartMemory
Guides

Holding Decisions for Review

Make a replacement of a decision wait for a person. See what is waiting, approve, reject, restore a replaced decision, and retract one.

Holding Decisions for Review

A decision is a rule your team or your agents rely on, such as "We charge $40 a seat." When a new decision replaces an old one, you may want a person to say yes first. This guide shows how to make replacements wait, how to answer them, and how to undo one that went through.

For what a decision is and how its states work, read Decision Memory.

The short version

  • A workspace has one switch for this, review.supersession. It has two values: retire (a replacement applies at once) and propose (a replacement waits for a person).
  • In propose, the old rule stays in force. The new rule is not stored, not searchable and not in any list until someone approves it.
  • The waiting replacement lands in the same review queue that holds conflicting facts.
  • Turning the hold off (retire) is an admin action. Anyone with edit rights can turn it on.
  • A person approves, rejects or closes it. Approving puts the new rule in force exactly once.
  • A replaced rule can be restored, and any rule can be retracted. Neither of those waits for review.

Which workspaces hold by default

The switch is read from the workspace first, then from its team, then from the default.

  • A personal workspace defaults to retire.
  • A team workspace nobody configured defaults to propose. From 2.0.2, replacements of decisions in those workspaces wait for a person. If you want the old behavior, set the workspace to retire.
  • A plain Lite install defaults to retire. See Lite below.

If the setting cannot be read, a replacement fails with an error. It never guesses.

Turn hold-for-review on or off

Python

from smartmemory_client import SmartMemoryClient

c = SmartMemoryClient(api_key="...", workspace_id="ws_pricing")
c.get_supersession_policy()              # {"policy": "propose", "source": "workspace", ...}
c.set_supersession_policy("propose")     # hold replacements for a person
c.set_supersession_policy("retire")      # apply replacements at once (needs a workspace admin)
c.set_supersession_policy(None)          # inherit from the team or the default (needs a workspace admin when that value is retire)

JavaScript

await client.workspaces.getSupersessionPolicy(workspaceId);
await client.workspaces.setSupersessionPolicy(workspaceId, 'propose');
await client.workspaces.setSupersessionPolicy(workspaceId, 'retire');
await client.workspaces.setSupersessionPolicy(workspaceId, null); // inherit

Changing the switch needs permission to edit the workspace's settings. An API key or an agent may only tighten it (set propose). Loosening it back to retire needs a signed-in person.

In the web app, an admin finds the same switch on the Decisions screen under the review rule.

What happens when a decision would be replaced

Replace a decision as you always did. In a propose workspace the answer says it is waiting:

Python

r = c.supersede_decision(old_id, "We now charge $45 a seat.", reason="price change")
r["status"]       # "held_for_review"
r["review_id"]    # the review that decides it
r["new_decision_id"]   # None, nothing was stored

c.list_decisions()     # still shows "We charge $40 a seat."

JavaScript

const r = await client.decisions.supersede(oldId, {
  new_content: 'We now charge $45 a seat.',
  reason: 'price change',
});
r.status;           // 'held_for_review'
r.review_id;        // the review that decides it
r.new_decision_id;  // null

await client.decisions.list(); // still shows "We charge $40 a seat."

MCP

decision_supersede answers "held for review (review id ...)" and tells the assistant to say the change is waiting for a person and that the old rule applies until then.

Two kinds of replacement are held:

  • Someone or something calls "replace this decision" directly: the SDKs, the REST route POST /memory/decisions/{id}/supersede, the web app, or the MCP tool decision_supersede.
  • The background reader notices in a new note that a rule has changed ("we now charge $45").

Sending the same replacement again gives the same review, not a second one.

See what is waiting

Python

reviews = c.list_conflict_reviews()["items"]   # status="open" by default

JavaScript

const { items } = await client.reasoning.listReviews({ status: 'open' });

MCP

Ask the assistant to call review_queue_list. It is available on the hosted connector and on the local one.

A waiting rule replacement is a review with trigger: "supersession_proposal" and proposal.kind: "decision". Read it like this:

  • conflict.existing_fact is the rule in force.
  • conflict.new_fact is the waiting replacement. It is not in force.
  • proposal.path says where it came from: explicit (a direct call), pipeline (the note reader) or stored (a declared rule, see What is not held yet).

Use status="resolved" to see answered reviews, with who answered, when and why.

In the web app, open Decisions and its review queue. The waiting rule shows beside the rule in force, labelled "waiting, not in force", with where it came from. The rule it would replace carries a "replacement waiting for review" badge.

Approve, reject or keep both

Python

c.settle_conflict_review(review_id, "keep_b", "approved by finance")   # approve
c.settle_conflict_review(review_id, "keep_a", "not this quarter")      # reject
c.settle_conflict_review(review_id, "keep_both", "no change")          # close

JavaScript

await client.reasoning.settleReview(reviewId, { action: 'keep_b', reason: 'approved by finance' });
await client.reasoning.settleReview(reviewId, { action: 'keep_a', reason: 'not this quarter' });
await client.reasoning.settleReview(reviewId, { action: 'keep_both', reason: 'no change' });

MCP

review_queue_settle(review_id, action, reason) with the same three actions. By default an assistant cannot settle a review. The tool answers that only a person or an API key can approve, and the review stays open. If a person sets the workspace to let anyone approve, the hosted connector's answer is recorded as connector:<user id>, not as the person, and the local connector's as local:mcp.

ActionWhat happens
keep_b (approve)The new rule goes in force and the old one is marked replaced. This happens once. Answering keep_b again returns the same receipt. A different answer afterwards is refused.
keep_a (reject)The old rule stays. Nothing new is written.
keep_bothFor a rule replacement this closes the review with no change. The proposed rule is not added. The web app labels it "Close, no change".

A reason is required. The service records who answered, taken from the sign-in, not from anything in the request.

A stale review

A review goes stale when the rule it would replace changed or ended after the review was filed, for example someone retracted it. Approving a stale review answers 409 and replaces nothing. Propose the replacement again if it is still wanted.

Who may approve

A team workspace holds replaced decisions for review, so somebody has to approve them. By default a person signed in to the SmartMemory app can approve, and so can an API key with write access to the workspace. A team that works only through API keys can approve its own held changes this way, even with the key that proposed the change. The review log names the key that approved it, as api_key:<key id>, so you can see which key it was.

The assistant on a hosted connector cannot approve by default, and neither can an agent. They are refused with a message that says how to approve, and the review stays open. A key or member who cannot write cannot settle either. Another workspace cannot see or settle your reviews: a guessed review id answers "not found".

The workspace setting review.approval changes this. It takes three values:

ValueWho can settle
person_onlyA signed-in person only. API keys are refused.
person_or_key (default)A signed-in person or an API key with write access
anyoneAny caller with write access, agents and the hosted assistant included

To make approval person-only, set review.approval to person_only. An API key can then no longer approve, and its refusal says that a person can set person_or_key to let keys approve again.

The hosted assistant can approve only when the workspace is set to anyone. Its answer is then recorded as connector:<user id>, not as the person.

Only a signed-in workspace owner or admin can loosen the setting (from person_only to person_or_key, or to anyone, or back to the default). An API key, an agent or the hosted assistant can only tighten it to person_only. Every answer records who gave it, so you can tell a person from a key or an assistant in the review log.

Python

c.get_review_approval()                 # policy person_or_key, source default
c.set_review_approval("person_only")    # keys can no longer approve
c.set_review_approval("anyone")         # needs a signed-in workspace admin
c.set_review_approval(None)             # back to the default

JavaScript

await client.workspaces.getReviewApproval(workspaceId);
await client.workspaces.setReviewApproval(workspaceId, 'person_only');

On a local store. A local store has no sign-in and no API keys, so it keeps person_only as its default and the app says who is answering. A call that names a person settles, for example settle_conflict_review(review_id, action="keep_b", reason="ok", actor="human:reviewer"). The local connector is not a person, so its settle is refused by default. To let it settle, a person runs:

smartmemory-core --data-dir ~/.smartmemory review-settings --approval anyone

The local connector's review_approval_get and supersession_policy_get read the store's own settings. Its set tools can only tighten them, and a loosening call answers with the command above.

Restore a replaced decision

If a newer decision wrongly replaced a rule that is still in force, restore it in one step. The original record comes back, with its history.

Python

c.list_decisions(status="superseded")                      # find it
c.restore_decision(old_id, reason="the price change was a mistake")

JavaScript

await client.decisions.list({ status: 'superseded' });
await client.decisions.restore(oldId, 'the price change was a mistake');

The same call is POST /memory/decisions/{decision_id}/restore with {"reason": "..."}, and the local MCP tool decision_restore. The web app has a Restore button on a replaced rule that asks for a reason first.

Rules for restoring:

  • Only the owner of the rule can restore it. A teammate who can only read it gets 403 not_owner.
  • Only a rule retired by a replacement can be restored. Active, retracted and pending rules get 409 not_retired. A scheduled or dated retirement gets 409 scheduled.
  • The replacement stays active. Only the link between the two is undone, and it is kept as a record of who undid it and why.
  • If the replacement was itself replaced since, the restore is refused with 409 replaced_again.
  • A restore is not held for review. It takes effect at once.

Retract a decision

Retracting says a rule is no longer valid.

c.retract_decision(decision_id, reason="no longer our policy")
await client.decisions.retract(decisionId, 'no longer our policy');

The local MCP tool is decision_retract. The web app has a Retract button on an active rule that asks for a reason. A retraction is not held for review.

On the hosted connector, decision_retract and decision_restore are not offered. Use the SDKs or the web app for those two.

Look at replaced and retracted rules

By default lists show rules in force. Ask for the others by state: active, superseded, retracted or pending.

c.list_decisions(status="superseded")
c.list_decisions(status="retracted")
await client.decisions.list({ status: 'superseded' });

On both MCP connectors use decision_list(status="superseded"). An unknown state is refused and the answer names the four.

Lite

A plain Lite install replaces decisions at once (retire) until you turn the hold on. The setting lives in the store itself, in a lite_settings table inside memory.db in the data directory. You make it once and every process that opens that store reads it, the background worker included. There is nothing to set in your app's code and no restart.

review-settings is a smartmemory-core command (the smartmemory command does not have it):

smartmemory-core --data-dir ~/.smartmemory review-settings --hold on
hold for review: on (review.supersession=propose)
who may approve: person_only (default)
learned names after a delete: drop (default)

Run review-settings with no option to print the three settings. --hold off applies replacements at once again and --hold unset goes back to the Lite default. A new process reads the setting back as on. With the hold on, everything above works against the local review queue:

from pathlib import Path
from smartmemory.tools.factory import create_lite_memory
from smartmemory.models.decision import Decision

# Open the store you ran review-settings on. A store you never set starts at the default (retire).
sm = create_lite_memory(data_dir=str(Path.home() / ".smartmemory"))

old = sm.add_decision("We charge $40 a seat.", decision_type="policy").decision_id
held = sm.supersede_decision(old, Decision(content="We now charge $45 a seat."), reason="price change")
held.status, held.review_id                          # "held_for_review", "conflict_..."
[d.content for d in sm.get_active_decisions()]       # ["We charge $40 a seat."]
sm.settle_conflict_review(held.review_id, action="keep_b", reason="approved", actor="human:me")
[d.content for d in sm.get_active_decisions()]       # ["We now charge $45 a seat."]

What is not held yet

Hold-for-review covers the calls above. These ways of changing a rule do not wait for a person yet:

  • Not a hold, a refusal: the general replace calls. In a propose workspace the general replace calls (POST /memory/{id}/supersede, POST /memory/{id}/supersede-link, the MCP tool memory_supersede and the local supersede call) are refused when either record is a decision. They raise GeneralReplaceRefused, name the decisions call to use instead, and write nothing: both records stay as they were and no review is filed. A plain note is replaced as before, and a retire workspace is unchanged. Use the decisions route to replace a decision.
  • A rule that takes effect later than its note, and a note that only amends a rule, are stored in force at once.
  • A declared rule (proposal.path is stored) is stored and in force while its review waits. Rejecting the review does not remove it.
  • Retract and restore are never held.
  • Nothing sends an alert or a webhook when a review is waiting. Check the queue.
  • There are no Studio or Insights screens for reviews, and no command line for them. Use the web app, the SDKs or MCP.

On this page