RememberStackremember.dev/docs

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

NameInTypeRequiredConstraints
namepathstringyesOne of resolve_entity, claims_and_sources_context, facts_context, combined_context.
layersquerysources, claims or facts, repeatablenoThe 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.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;
  • documents must 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_k may not be smaller than k.

The parameters of each operation are listed in Assured operations.

Response

200 with the operation's result:

OperationResult
resolve_entityEnvelope, grain fact
claims_and_sources_contextEnvelope, grain evidence
facts_contextEnvelope, grain fact
combined_contextContextBundle/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

StatusdetailCause
403credential may not perform this operationThe credential's scope is not write.
404the operation name, as a stringNo 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.
422validation listThe 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).
503model provider unavailableEmbedding 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.