> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognee.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Rust SDK Recall

> recall in cognee-rust: auto-routed, session-aware retrieval over graph and session memory.

## 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](https://docs.cognee.ai/rust/core-concepts/main-operations/legacy-operations/search.md).

## 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](https://docs.cognee.ai/rust/configuration/llm-and-embedding.md#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`](https://docs.cognee.ai/rust/configuration/search), 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](https://docs.cognee.ai/rust/configuration/search.md#recall-warm-up-short-circuit)).
Recall is session-aware (reads
session history when given a `--session-id`; a completion recall without one
uses the [default session](https://docs.cognee.ai/rust/core-concepts/sessions-and-caching.md)) 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:

```ts theme={null}
const result = await c.recall("Who is Alice?", {
  llmConfig: { llm_provider: "openai", llm_model: "gpt-4o", llm_api_key: "sk-..." },
});
```

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](https://docs.cognee.ai/rust/configuration.md#precedence)
(`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

> [card] [Search](https://docs.cognee.ai/rust/core-concepts/main-operations/legacy-operations/search.md)
>
> The retrieval strategies recall routes to

> [card] [Sessions](https://docs.cognee.ai/rust/core-concepts/sessions-and-caching.md)
>
> Default sessions and session memory

> [card] [Search configuration](https://docs.cognee.ai/rust/configuration/search.md)
>
> Retriever and routing settings


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.