Recall - Cognee Documentation

What is the recall operation

The .recall operation is the main retrieval entry point in Cognee v1.0. It searches memory using the best available source for the request.

Auto-routing by default: when you do not specify a search type, recall() classifies the query and picks the best retrieval strategy automatically.
Session-aware: with session_id, it can search session cache entries first and fall through to the permanent graph if needed.
Graph-backed: for permanent memory, recall() runs graph retrieval and returns contextual results.
Source tagging: when results are returned as dicts, they include _source metadata so you can tell whether they came from "session" or "graph".

Where recall fits

Use recall() as the default way to ask questions over memory in v1.0.
Use it after Remember has created either permanent or session memory.
Use explicit query_type only when you want to force a specific retrieval mode.
Use datasets to scope results to a specific knowledge base.

What happens under the hood

Check session scope
- If you pass session_id without datasets and without query_type, Cognee first searches the session cache directly.
- Session search is keyword-based over stored question, context, and answer fields.
Choose the retrieval strategy
- If query_type is provided, Cognee uses it directly.
- Otherwise, if auto_route=True, a rule-based router picks the best strategy based on your query. See Auto-routing behavior below for the kinds of patterns it recognizes.
- If auto_route=False, Cognee falls back to GRAPH_COMPLETION.
Run graph retrieval when needed
- If session search finds nothing, or if graph retrieval is requested, recall() queries the permanent knowledge graph.
- The retrieval strategy selected in step 2 determines how that graph query is executed.

After recall finishes

Session-only recall: you get matching session entries when cache hits exist, each tagged with _source="session".
Graph-backed recall: you get results from the permanent graph, tagged with _source="graph" when returned as dicts.
Hybrid behavior: with session_id plus graph-scoping inputs like datasets or query_type, recall uses the permanent graph path rather than session-only lookup.

Examples and details

Recall while indexing is still running

recall() can run while another dataset is still being ingested or indexed in the background.

There is no global lock that blocks retrieval while remember() is processing.
recall() only sees data that has already made it through indexing.
If a dataset is mid-run, results may be incomplete until that run reaches completion.

If you need to confirm a dataset is fully ready before querying it, check its status with cognee.datasets.get_status() or the indexing-status guidance on Remember.

Auto-routing behavior

The built-in router uses query patterns to choose an underlying search mode:

Summary-style prompts like “overview”, “summary”, or “key takeaways” bias toward summary retrieval.
Relationship questions like “how are X and Y connected?” bias toward graph context-extension retrieval.
Time-oriented questions like “when”, “before”, “after”, or year ranges bias toward temporal retrieval.
Code-focused queries like “coding rules” or async def bias toward coding-rules retrieval.
Exact quoted phrases bias toward lexical chunk search.

If you want direct control, pass query_type explicitly and bypass the router.

How recall relates to retrievers

Most users should think in terms of asking memory a question, not selecting a retriever manually.Under the hood, retrieval strategies — graph completion, summary, temporal, lexical, coding-rules — do the actual work. recall() is intentionally one layer above them:

you call recall()
Cognee chooses or accepts a query_type
the matching retriever runs underneath
the result comes back through the recall API

If you want to understand or control the lower-level retrieval behavior directly, see the lower-level search reference.

What recall returns

Session-only recall returns matching session cache entries.
Graph-backed recall returns the output of the underlying retrieval mode selected by the router or query_type.
Depending on the retrieval path, that can be a plain answer string, retrieved context, or structured result dictionaries.
Returned dict results are tagged with _source so callers can distinguish session from graph results.
only_context=True skips the final LLM answer-generation step and returns retrieved context instead.
verbose=True exposes extra retrieval details from the lower-level graph search path.

Session Results
Graph Results

When recall() returns session cache hits, the result is a list of session-entry objects tagged with _source="session".These entries follow the session QA shape documented in Sessions and Caching, with fields such as:

time
qa_id
question
context
answer
feedback_text
feedback_score
_source

When recall() falls through to graph retrieval, the top-level shape depends on access-control mode:

Situation	Top-level shape
`ENABLE_BACKEND_ACCESS_CONTROL=true`	A list of per-dataset objects containing `dataset_id`, `dataset_name`, and `search_result`
`ENABLE_BACKEND_ACCESS_CONTROL=false`	Usually a plain list of raw search payloads, without dataset wrapper fields
Single-dataset compatibility case	Some single-dataset results may unwrap one level for backwards compatibility

When recall() uses graph retrieval, the inner search_result payload follows the same shape rules as search():

Search type(s)	Default graph-backed shape	Notes
`GRAPH_COMPLETION`, `RAG_COMPLETION`, `TRIPLET_COMPLETION`, `GRAPH_COMPLETION_DECOMPOSITION`, `GRAPH_SUMMARY_COMPLETION`, `GRAPH_COMPLETION_COT`, `GRAPH_COMPLETION_CONTEXT_EXTENSION`	`str`	Natural-language answer. With `only_context=True`, returns the formatted context string instead. With `verbose=True`, returns a payload containing `text_result`, `context_result`, and `objects_result`.
`TEMPORAL`	`str`	Time-aware answer text. `only_context=True` returns retrieved temporal context instead of an answer.
`AGENTIC_COMPLETION`	`str`	Agentic answer text. Requires the resolved graph scope to contain exactly one dataset.
`CHUNKS`	`list[dict]`	Each chunk item includes `id`, `text`, `chunk_index`, `chunk_size`, and `cut_type`.
`CHUNKS_LEXICAL`	`list[dict]`	Ranked chunk-like results for lexical matching; may include scores in addition to chunk text/metadata.
`SUMMARIES`	`list[dict]`	Each summary item includes `id` and `text`.
`CYPHER`, `NATURAL_LANGUAGE`, `CODING_RULES`	`list[dict[str, Any]]`	Structured row/object results. For `CYPHER`, this is raw Cypher output. For `NATURAL_LANGUAGE`, it is executed graph-query output. For `CODING_RULES`, schema depends on the retrieved rule/context objects. `CYPHER` and `NATURAL_LANGUAGE` are disabled when `ALLOW_CYPHER_QUERY=false`.
`FEELING_LUCKY`	Varies	Returns the same shape as whichever search type the router selects.

For completion-style graph modes, verbose=True is the easiest way to inspect both the final answer and the retrieved source material. The verbose payload includes text_result (answer), context_result (formatted context sent to the LLM), and objects_result (raw retrieved objects).

Using only_context

Set only_context=True when you want the retrieved context without asking Cognee to produce a final answer.When only_context=True, Cognee stops after retrieval formatting:

the LLM answer is not generated
the final completion step is skipped
the returned value is the retrieved context rather than a synthesized answer

results = await cognee.recall(
    query_text="Tell me about NLP",
    only_context=True,
)

This is useful when you want to:

inspect what was retrieved before answer generation
feed the retrieved context into your own prompt or downstream logic
debug retrieval quality separately from answer quality

In other words, only_context=True keeps recall focused on retrieval output instead of answer generation.

Session cache reads and writes during recall

session_id makes recall session-aware, but the exact behavior depends on the recall mode.Session reads:

With session_id and no explicit query_type, recall() searches session-cache QA entries by keyword and returns matches tagged with _source="session".
If session_id is used with datasets or dataset_ids, recall can combine session lookup with graph retrieval.
If you pass an explicit query_type, the default path is graph-backed retrieval. Session history can still be used during the LLM completion step, but session-cache QA lookup is not part of the default source set unless you pass scope.

Graph-backed completion with session history:When graph-backed recall runs with session_id and the LLM completion step is enabled, Cognee loads prior session conversation history and prepends it to the completion prompt. If improve() has saved a graph_context snapshot for that session, that snapshot is also prepended as background knowledge.Session writes:When the LLM completion step runs through session-enabled graph retrieval, Cognee appends a new QA entry to the session cache with the question, stored context, and generated answer. The next compatible recall on the same session_id can see that entry.Using only_context=True:Pass only_context=True to skip the final LLM completion. Because the QA write happens during completion, only_context=True also avoids adding a new QA entry to the session cache.

# Session-aware recall with answer generation can write a new QA entry
answer = await cognee.recall(
    query_text="What did we decide about pricing?",
    session_id="chat-42",
)

# Returns retrieved context only; skips final LLM completion and QA write
context = await cognee.recall(
    query_text="What did we decide about pricing?",
    session_id="chat-42",
    only_context=True,
)

Use only_context=True when you want retrieval output without LLM summarization and without growing the session cache.

Dataset scoping

answers = await cognee.recall(
    query_text="Give me an overview of this dataset.",
    datasets=["product_docs"],
)

datasets limits graph retrieval to named datasets. With backend access control enabled, names are resolved only against datasets owned by the current user.
dataset_ids scopes retrieval by dataset UUID instead of name. Use this for shared datasets that the current user can access but did not create. When supplied, it takes precedence over datasets and the name-to-UUID resolution step is skipped.
With session_id plus either datasets or dataset_ids, recall becomes hybrid: session context is available, but graph retrieval is scoped to the selected dataset or dataset UUIDs.

If you set query_type=SearchType.AGENTIC_COMPLETION, the resolved graph scope must contain exactly one dataset. Passing multiple dataset names or UUIDs, or leaving scope broad enough to match multiple readable datasets, can raise 422 InvalidAgenticDatasetScope.

If Alice created shared_dataset and Bob only has permission to use it, Bob should query it with dataset_ids=[shared_id], not datasets=["shared_dataset"]. Name-based lookup can fail for non-owners even when they have read access.

Parameters

Basic Parameters
Advanced Parameters

Option	What it does
`query_text`	The natural-language query to answer.
`query_type`	Forces a specific underlying search type instead of using auto-routing.
`datasets`	Restricts graph retrieval to specific dataset names. Names are resolved only against datasets owned by the current user.
`dataset_ids`	Restricts graph retrieval by dataset UUIDs. Use this for shared datasets the current user did not create. Takes precedence over `datasets` when both are set.
`top_k`	Limits the number of returned results. Defaults to `10`.
`auto_route`	Enables the rule-based query router. Defaults to `True`.
`session_id`	Enables session-aware retrieval and session-cache lookup.
`only_context`	Returns retrieved context only. The final LLM answer is not generated.
`system_prompt` / `system_prompt_path`	Customizes the generation prompt.

Option	What it does
`node_name` / `node_name_filter_operator`	Restricts graph retrieval to matching node names or node sets.
`wide_search_top_k`	Expands the initial candidate set used by graph-completion retrieval before ranking.
`triplet_distance_penalty`	Adjusts scoring for triplet-based retrieval paths.
`feedback_influence`	Applies stored feedback weights during ranking where supported.
`verbose`	Returns extra retrieval details from the lower-level graph search path.
`retriever_specific_config`	Passes advanced configuration directly to the selected retriever.
`user`	Runs recall under a specific user context, affecting dataset access and session-cache lookup.

Under the hood — legacy operations

recall() runs Search under the hood for graph-backed retrieval.Use legacy Search directly when you need to select a specific retriever, inspect retrieval internals, or use advanced parameters not exposed by recall(). See also Search Basics for the full set of retrieval options.

recall() vs search(): when to use each

	`recall()`	`search()` (legacy)
Recommended for	Most v1.0 use cases	Advanced retriever control
Search type selection	Auto-routes by default; pass `query_type` to override	Always explicit; defaults to `GRAPH_COMPLETION`
Session behavior	Searches session-cache QA entries by keyword; falls through to graph on miss	`session_id` writes/reads conversation history only — no cache lookup
Source tagging	Results carry `_source` (`"session"` or `"graph"`)	No source tagging
Parameter surface	Compact; power-user options via `**kwargs`	Full surface — `neighborhood_depth`, `node_type`, `triplet_distance_penalty` with explicit defaults

Use recall() when you want to ask a question and get an answer. It handles routing, session lookup, and source attribution automatically.Use search() directly when you need a specific retriever, lower-level parameters such as neighborhood_depth or node_type, or when building custom pipelines.

Remember

Create permanent or session memory

Improve

Enrich the graph for better future recall

Documentation Index

​What is the recall operation

​Where recall fits

​What happens under the hood

​After recall finishes

​Examples and details

Remember

Improve

What is the recall operation

Where recall fits

What happens under the hood

After recall finishes

Examples and details