Skip to main content

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 an LLM_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 a system 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

The scope 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

The session, 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

The node_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 the engine_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:
Each replaces the whole configured section for the call: a setting it leaves out takes the value the environment (or .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.

Search

The retrieval strategies recall routes to

Sessions

Default sessions and session memory

Search configuration

Retriever and routing settings