What is the recall operation
recall is the main read entry point of the memory API. It picks a retrieval strategy for the query (auto-routing), reads the sources you ask for (graph, session, trace, session context) and returns the results to the caller. Underneath, it runs search.
Auto-routing
Queries memory with auto-routing: when no query type is given,recall
picks the retrieval strategy by the first matching rule: a
quoted phrase → CHUNKS_LEXICAL, coding-rules wording → CODING_RULES, a time
preposition before an absolute date → TEMPORAL, anything else →
HYBRID_COMPLETION. A routed type that the backend rejects, or a lexical or
rules search that finds nothing, is retried as HYBRID_COMPLETION (a lexical search returns its top-ranked chunks even when none contains the phrase, so it comes back empty only for a phrase made of stop words).
Routing without an LLM
Routing also honours what the deployment can run. With no usable LLM (the provider needs anLLM_API_KEY that is not set; see
Supported LLM providers),
recall still routes: CHUNKS_LEXICAL and CODING_RULES run as they are, and
any other routed type falls back to HYBRID_COMPLETION. The fallback, and an
explicit HYBRID_COMPLETION, GRAPH_COMPLETION or RAG_COMPLETION, then
returns the prompt it would have sent the LLM, built
from the retrieved context, instead of an answer (only_context). An explicit
query type is never rerouted. No rule routes to CYPHER or NATURAL_LANGUAGE;
requested explicitly with
ALLOW_CYPHER_QUERY=false, they are refused.
The CLI and the bindings build their search orchestrator with
SearchBuilder, which sets these constraints from the LLM and
search.allow_cypher_query. A SearchOrchestrator built by hand allows
everything unless given with_routing_constraints. This is a breaking change
for callers of cognee_search::route_query, which now takes
&RoutingConstraints (pass &RoutingConstraints::default() for the previous
behaviour); RouteDecision gains an only_context field.
Warm-up, sessions and when auto-routing applies
When no pipeline has run on the datasets, or no build there ever completed and the latest one failed, a graph-only recall returns asystem note saying so instead of searching
(configuration).
Recall is session-aware (reads
session history when given a --session-id; a completion recall without one
uses the default session) and graph-backed. Results are
returned to the caller (printed to stdout by the CLI).
The CLI auto-routes whenever --query-type is omitted, but the bindings do so
only with autoRoute: true (default false), and the Rust api::recall only
with auto_route = true. Without it, a recall with no query type runs
HYBRID_COMPLETION (it ran GRAPH_COMPLETION before).
Scopes
Thescope picks the sources: graph, session, trace,
session_context, all, or auto (the default). all is graph,
session, trace and session_context, in that order. With a session id and
no query type, auto reads the session and then the graph: with no dataset
filter a session hit skips the graph, with one both contribute. Without a
session id, or with a query type, auto reads the graph only. session_first
asks for the short-circuit explicitly, whatever else the call carries.
graph_context is a deprecated alias of graph. An explicit empty scope list
runs no source and returns nothing; only an absent scope means auto. An
unknown name fails with an error listing the unknown and the valid names
(Unknown recall scope(s): ['foo']. Valid values: ['all', 'auto', ...]).
session_context returns the session’s active guidance block (the lessons
improve() stored) as one entry, {content, context_profile}, rendered
read-only for the context_profile option (qa, the default, or agent);
it is empty without a session id or stored guidance. tools and code are
valid names that fail with “not supported yet” before any source runs
(SDK-1537). The tools_trigger option (always | on_empty) is validated,
and has no effect until the tools source exists.
Whose session entries are read
Thesession, trace and session_context sources read the session cache,
which is keyed by the session’s owner. By default they read the caller’s own
entries. A caller that can read the session’s dataset reads its owner’s
entries instead, when it sets the session_cache_user_id option to the id
resolve_session_cache_user_id resolves from the session records and the
caller’s readable datasets. The
bindings do this themselves when the handle has a ReadableDatasets hook
(HandleState::with_readable_datasets), which a build with dataset
permissions attaches; without one (the OSS build, and the CLI) only the
caller’s own entries are read.
Scoping by node name
Thenode_name option scopes the graph search, read according to the
node_type option: without node_type (equivalent to NodeSet) the names are
node-set tags, and with a graph node type’s class name (Entity,
TextDocument, …) they name nodes of that type and their one-hop neighbours.
The router then picks only a type that applies the scope (TEMPORAL and
CODING_RULES apply node sets only; a lexical pick becomes HYBRID_COMPLETION
with only_context), and an explicit query type that cannot apply it fails
when the graph search runs, after the warm-up note (a graph that was never
built answers its note first). CHUNKS and RAG_COMPLETION apply node-set
names only: a graph node_type needs a graph-scoped chunk search that is not
ported, so they refuse it rather than match the names against node-set tags.
Names with an empty node_type fail before any source runs, whatever the
scope. Session sources are not scoped by node_name. The verbose option is
forwarded to the graph search, whose response then keeps its context and graph.
CLI and binding options
The CLI and the bindings expose these options.cognee-cli recall takes
--scope (repeatable), --context-profile, --tools-trigger, --node-type,
--node-name (repeatable) and --verbose (which also prints the graph
search’s response after the items, under search_response in JSON). The
bindings’ recall opts take scope, contextProfile, toolsTrigger,
nodeType, nodeName, nodeNameFilterOperator and verbose (the Python
binding also accepts the snake_case spellings). An unknown scope or
tools_trigger, a tools / code scope and node names with an empty
node_type are validation errors on every surface.
Per-call LLM and embedding models
A recall (and a search) can run with its own LLM and embedding model through theengine_override option, built with
ComponentManager::build_engines_with_overrides from an llm and an
embedding config section; the bindings take them as the llmConfig /
embeddingConfig opts, objects keyed by the settings’ flat names (llm_model,
llm_api_key, embedding_dimensions, …) or canonical keys (llm.model). A
key that names no setting of the section is ignored with a warning, so a
misspelled key changes nothing; a non-object, or a known key with a value of
the wrong type, is a validation error:
.env file) gave it, else the
section’s default. The environment is not read again: the values come from the
configuration’s env layer
(Settings::env_layer), captured when it was read from the environment. A
value set in code or loaded from a file is not inherited. The cache of built
engines is keyed by a digest of the configs, never their plain text.
embedding.api_key binds EMBEDDING_API_KEY and then LLM_API_KEY, so with
only LLM_API_KEY set the embedder keeps that key under an llm_config with
another key. The call’s LLM also decides routing: one without a key answers
completion types with only_context. An embedding model whose width differs
from the configured one fails before anything is searched. The engines are
built through the deployment’s component registry, so any registered provider
can be selected, and are cached per configuration. The CLI has no per-call
overrides; it has the configuration.
recall ≈ auto-routed search. rustdoc: api::recall.
Related
Search
The retrieval strategies recall routes to
Sessions
Default sessions and session memory
Search configuration
Retriever and routing settings