Assured operation routes

Assured operations are the four fixed retrievals RememberStack guarantees: resolve_entity, claims_and_sources_context, facts_context and combined_context. Two routes expose them. The CLI and the MCP server read the same registry, so the tools they offer always match these routes.

What each operation takes and returns is described in Assured operations. This page covers the HTTP side.

GET /operations

Return the descriptors of the four operations this deployment serves.

Scope: read.

Parameters

None.

Response

200 with an array of ToolDescriptor, ordered by the registry. Each descriptor carries the operation's name, description, closed input_schema (JSON Schema, additionalProperties: false), result_schema, result_contract (envelope or context_bundle_v2), output_grain, answer_intent, version and implementation_plan_hash. mutates is false on all four.

[
  {
    "name": "resolve_entity",
    "description": "Resolve a name to ranked current survivor candidates; never silently guess.",
    "input_schema": {
      "type": "object",
      "properties": {"name": {"type": "string", "minLength": 1}},
      "additionalProperties": false,
      "required": ["name"]
    },
    "result_schema": {"...": "the Envelope JSON Schema"},
    "result_contract": "envelope",
    "output_grain": "fact",
    "answer_intent": "identity",
    "mutates": false,
    "version": 1,
    "implementation_plan_hash": "fcf8f8bd08efe28d62af572dbd4f81601b03f1744d993021225454b55748059a"
  }
]

Example

curl -s "$REMEMBER_API_URL/operations" \
  -H "Authorization: Bearer $REMEMBER_API_KEY"

from remember import Client
 
memory = Client()
for descriptor in memory.list_operations():
    print(descriptor.name, descriptor.version, descriptor.result_contract)

POST /operations/{name}

Run one assured operation over a JSON object of arguments.

Scope: read. The route checks the operation's descriptor, and all four declare themselves read-only (mutates: false). See HTTP API conventions.

Parameters

Request body

A JSON object whose keys are the operation's parameters. An empty body is the empty object. Arguments are checked against the descriptor before anything runs:

• unknown keys are refused;
• a required key that is missing is refused;
• strings must be JSON strings; integers must be JSON integers (a whole-number float such as 3.0 is accepted, true is not);
• entity_ids must be an array of UUID strings, with no duplicates;
• time must be an object in one of the four modes;
• length, item-count and range bounds from the descriptor apply;
• for claims_and_sources_context, candidate_k may not be smaller than k.

The parameters of each operation are listed in Assured operations.

Response

200 with the operation's result:

An answer of "nothing found" is still 200. The envelope's negative field says which kind of nothing: unknown_entity, known_empty or boundary. See Reading a result.

Errors

Example

curl -s -X POST "$REMEMBER_API_URL/operations/facts_context" \
  -H "Authorization: Bearer $REMEMBER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Who owns the billing migration?",
       "time": {"mode": "current"}}'

from remember import Client
 
memory = Client()
 
# The generic form:
result = memory.run_operation(
    name="facts_context",
    arguments={"query": "Who owns the billing migration?"},
)
 
# The named helpers:
people = memory.resolve_entity("Dana")
said = memory.claims_and_sources_context("billing migration cutover date")
held = memory.facts_context("Who owns the billing migration?", hops=1)
both = memory.combined_context("billing migration status", time={"mode": "current"})

run_operation returns an Envelope, or a ContextBundleV2 when the body says "contract": "ContextBundle/v2". The helpers pass only some parameters: facts_context takes query, time, hops, predicate and entity_ids; combined_context takes query and time; claims_and_sources_context takes query; resolve_entity takes name. Use run_operation for the rest (k, candidate_k, evidence_per_fact, and entity_ids on the other operations).