RememberStackremember.dev/docs

Saved queries

A saved query is a SQL query stored in the deployment under a name, with its parameters described, so an agent or a script can run it without writing SQL. Every deployment ships with 19 of them, covering the questions people ask most: claims about an entity, documents that mention it, what changed since a date, why a fact is held. They run over the same query space as any SQL query: prepared, read-only views and functions, with every statement checked before it runs.

Setup is in the Quickstart.

Names

A saved query is addressed by a namespace and a name, written examples.claims_about. The shipped queries all have the namespace examples. Each one also has integer versions; a run uses the newest active version unless you ask for a specific one.

List them

import remember
 
client = remember.Client.from_env()
 
for query in client.list_saved_queries(namespace="examples"):
    print(f"{query['namespace']}.{query['name']} v{query['version']} — {query['description']}")

list_saved_queries(namespace=None, status=None) returns, for each saved query: query_id, namespace, name, version, status, description, origin, assurance, query_hash and the hash of the query space it was validated against. Without status, only active versions are listed.

CLI and MCP:

remember query list-saved --namespace examples
{"name": "list_saved_queries", "arguments": {"namespace": "examples"}}

The 19 shipped queries

Parameters are positional, in this order. IDs are UUID strings; instants are ISO 8601 timestamps with a time zone.

NameAnswersParametersRows at most
claims_verbatimClaims as asserted, found by meaning.search text20
claims_aboutClaims that mention an entity, newest first.entity ID50
claims_as_ofClaims whose stated time overlaps a window.from, to50
claims_hybrid_rrfClaims found by meaning and by words, fused.search text20
chunks_hybrid_rrfSource passages found by meaning and by words, fused.search text20
chunk_neighborsThe passages either side of one passage in its section.chunk ID5
documents_aboutDocuments that mention an entity, most mentions first.entity ID50
pages_aboutCompiled pages that cite an entity.entity ID50
relation_currentCurrent relations of an entity.entity ID50
observation_currentCurrent observations about an entity.entity ID50
identity_as_ofHow an entity's identity was decided, up to an instant.entity ID, instant100
entity_timelineAn entity's facts counted per day.entity ID200
explainWhy a fact is held: history, evidence, documents.fact ID100
multi_hop_contextClaims along a route between two entities that match a search.deployment ID, from entity ID, to entity ID, search text100
changed_sinceWhat the memory learned after an instant.instant100
graph_neighborhoodRelations within two hops of an entity.deployment ID, entity IDgraph budget
graph_pathRoutes of up to four hops between two entities.deployment ID, from entity ID, to entity IDgraph budget
graph_citation_pathCitation routes of up to six hops between two documents.deployment ID, from document ID, to document IDgraph budget
facts_by_tagCurrent facts supported by documents that carry a tag, with how many of those documents support each.tag name (any letter case)50

The graph queries take your deployment ID first. It is in every ingest result (deployment_id) and every SQL result.

Look at one

Before you rely on a saved query, read what it does:

detail = client.describe_saved_query(namespace="examples", name="documents_about")
print(detail["status"], detail["version"])
print(detail["sql"])
print(detail["parameter_schema"])
print(detail["declared_interpretation"])

The description holds the SQL, the parameter and result schemas, the declared interpretation, the default limits, the validation report, and who wrote and approved the version. Pass version= to see an older one.

remember query describe-saved examples documents_about

Run one

dana = client.resolve_entity("Dana").entities[0]
result = client.run_saved_query(
    namespace="examples",
    name="documents_about",
    parameters=[str(dana.entity_id)],
    max_rows=20,
)
columns = [column["name"] for column in result["columns"]]
for row in result["rows"]:
    print(dict(zip(columns, row)))

run_saved_query(namespace, name, parameters=(), version=None, max_rows=None) returns the same QueryResult/v1 dict as a SQL query, with a saved_query field naming the exact version that ran: query_id, namespace, name, version and query_hash. Record it next to any answer you keep.

The result is subject to the same limits as any SQL query. A max_rows you pass overrides the saved query's own default; the query's LIMIT still applies.

CLI and MCP:

remember query run-saved examples documents_about \
  --parameters '["0b6f2d8e-5c1a-4e3b-9d7f-1a2b3c4d5e6f"]' --max-rows 20
{
  "name": "run_saved_query",
  "arguments": {
    "namespace": "examples",
    "name": "documents_about",
    "parameters": ["0b6f2d8e-5c1a-4e3b-9d7f-1a2b3c4d5e6f"],
    "max_rows": 20
  }
}

Status: when a saved query runs

Every version has a status. Only active runs.

StatusMeaningRunning it
draftWritten, not approved. Not listed by default.Refused: saved_query_disabled.
activeApproved by an operator, validated against the current query space.Runs.
pending_revalidationThe query space changed since it was validated.Refused: saved_query_revalidation_pending.
deprecatedA newer version was activated.Refused unless another version is active.
disabledSwitched off by an operator.Refused: saved_query_disabled.
brokenFailed validation against the current query space.Refused: saved_query_disabled.

How a version moves:

  • The author of a version cannot approve it. Activation is a separate act by someone with authority, and the version records both people.
  • When the query space changes (an upgrade adds a column or a view), every active version moves to pending_revalidation in the same step. It runs again only after it is validated against the new query space.
  • Activating a new version deprecates the one it replaces. Old versions are kept; a caller who pinned version=2 either gets exactly version 2 or a refusal, never different SQL.

Errors when running:

CodeHTTPMeaning
saved_query_not_found404No such namespace.name, or no such version.
saved_query_disabled409The query or the requested version is not active.
saved_query_revalidation_pending409Validated against another version of the query space.
saved_query_incompatible409Written for a query space this deployment does not have.

All the SQL error codes can also occur; see Explore memory with SQL.

Change a shipped query

The shipped queries are starting points, not guarantees: the platform wrote them honestly, but what they mean is up to you. To change one, copy its SQL from describe_saved_query, edit the filters, and run your copy with open_query. Your copy is yours; the shipped version does not change.

The HTTP API, the client and the CLI can list, describe and run saved queries. They cannot create, approve or disable one yet.

Next