Skip to main content

​
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 by default: for permanent memory, recall() runs graph retrieval — not plain embedding similarity. GRAPH_COMPLETION is the fallback when auto-routing does not choose a more specific strategy.
  • Source tagging: each recall result includes a source field so you can tell whether it came from "session", "graph", "trace", or "graph_context".

​
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

  1. 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.
  2. 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.
  3. 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 normalized graph result objects tagged with source="graph".
  • 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() only reads from memory — it never initializes anything itself. Populate memory first with remember() (or the legacy add() + cognify() sequence). The first ingestion run creates the relational, vector, and graph databases and the default user.
If you call recall() before any data exists, it raises RecallPreconditionError (HTTP 422), triggered by the underlying DatabaseNotCreatedError (“The database has not been created yet. Please call await setup() first.”) or UserNotFoundError. The fix is to run remember() (or add() + cognify()) first.recall() can also fail when the configured LLM provider (or LiteLLM proxy) reports that its token budget is exhausted. In that case it raises LLMPaymentRequiredError, which the API surfaces as HTTP 402 (Payment Required) with body {"error": "Token budget exhausted", "detail": "..."}. This error is terminal — Cognee does not retry budget-exhaustion failures — so treat a 402 as final for the request and prompt the user to top up their token budget rather than reissuing the call.recall() also accepts only its documented parameters — there is no catch-all **kwargs. Passing an unsupported keyword such as node_type raises a TypeError. Use node_name to scope retrieval to specific nodes or node sets; node_type belongs to the legacy search() API. See the recall() API reference for the full parameter list.
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.
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.
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.
  • 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, each graph result object’s text can contain a plain answer, retrieved context, chunk text, or rendered structured output.
  • Each recall result is tagged with source so callers can distinguish session, graph, trace, and graph-context 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.
When recall() returns session cache hits, the result is a list of ResponseQAEntry 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
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
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_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.
Use only_context=True when you want retrieval output without LLM summarization and without growing the session cache.
  • Scoping is exclusive. When you pass datasets (or dataset_ids), retrieval runs against only those datasets — Cognee does not pull from any other dataset, even ones the current user can read.
  • When you omit both, recall searches across all datasets the current user has read access to. Supply a dataset to narrow that down to a single knowledge base.
  • 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.
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.
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