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
| Name | In | Type | Required | Constraints |
|---|---|---|---|---|
name | path | string | yes | One of resolve_entity, claims_and_sources_context, facts_context, combined_context. |
layers | query | sources, claims or facts, repeatable | no | The processing layers the call may read. Default: every layer the deployment serves. |
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.0is accepted,trueis not); entity_idsmust be an array of UUID strings, with no duplicates;timemust be an object in one of the four modes;documentsmust be a closed documents filter object, and every tag it names must be registered;- length, item-count and range bounds from the descriptor apply;
- for every context operation,
candidate_kmay not be smaller thank.
The parameters of each operation are listed in Assured operations.
Response
200 with the operation's result:
| Operation | Result |
|---|---|
resolve_entity | Envelope, grain fact |
claims_and_sources_context | Envelope, grain evidence |
facts_context | Envelope, grain fact |
combined_context | ContextBundle/v2 |
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
| Status | detail | Cause |
|---|---|---|
403 | credential may not perform this operation | The credential's scope is not write. |
404 | the operation name, as a string | No active operation has that name. |
422 | {"code": "invalid_parameter", "message": "<name>"} | A required argument is missing; the message is its name. |
422 | {"code": "invalid_parameter", "message": "unknown argument(s): …"} | An argument the operation does not take. |
422 | {"code": "invalid_parameter", "message": "invalid <name>: …"} | Wrong type, a malformed UUID, or a bad time or documents object. |
422 | {"code": "unknown_tag", "message": "unknown tags: …", "tags": [...]} | documents.tags names a tag that is not registered; nothing was searched. |
422 | {"code": "invalid_parameter", "message": "<name> violates maxLength=8192"} (and similar) | A length, item-count, uniqueness or range bound. |
422 | {"code": "invalid_parameter", "message": "candidate_k cannot be smaller than k"} | All three context operations. |
422 | validation list | The body is not a JSON object. |
409 | {"code": "layer_unavailable", "layer": "facts", "status": "disabled", "message": "…"} | The operation, an argument or layers needs a layer the deployment does not process. |
422 | {"code": "invalid_parameter", "message": "…"} | layers leaves none of the operation's layers, or excludes one an argument needs (such as facts for entity_ids). |
503 | model provider unavailable | Embedding the query failed at the model provider. Retry later. |
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". All three context helpers accept
query, k, candidate_k, time and documents (a
DocumentSearchFilters or the same object as a dict, such as
{"tags": {"all": ["project:billing-migration"]}}); an unregistered tag
raises remember.UnknownTag. facts_context also accepts hops,
predicate and entity_ids; resolve_entity takes name. Use
run_operation to set evidence_per_fact on facts_context, entity_ids
on claims_and_sources_context, or entity_ids, hops and predicate
on combined_context.