cognee.recall()

async def recall(
    query_text: str,
    query_type: SearchType | None = None,
    *,
    datasets: list[str] | None = None,
    dataset_ids: list[UUID] | None = None,
    top_k: int = 15,
    auto_route: bool = True,
    scope: str | list[str] | None = None,
    # plus the keyword-only options listed under "Additional keyword options"
) -> list[RecallResponse]

Description

recall() is the main retrieval entry point in Cognee v1.0.

It auto-routes queries by default when you do not specify query_type. Routing is rule-based (no LLM call) and falls back to GRAPH_COMPLETION when no cue matches — see Auto-routing behavior for the full cue-to-search-type mapping and when to override.
It can search the permanent graph, session memory, or both.
It returns RecallResponse items sourced from graph retrieval, session retrieval, or both depending on the request.

For the full behavior walkthrough, see Recall and Search Basics.

Prerequisites

recall() only reads from memory that already exists — it does not initialize anything on its own. 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.

import cognee

await cognee.remember("Einstein was born in Ulm.")  # creates databases + ingests
results = await cognee.recall("Where was Einstein born?")

Calling recall() before any data has been ingested raises RecallPreconditionError (a CogneeValidationError, HTTP 422) with the message “Recall prerequisites not met: no database/default user found.” It is 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.

Parameters

str

required

Natural-language query to run against memory.

SearchType | None

default:"None"

Forces a specific retrieval strategy instead of using auto-routing.

list[str] | None

default:"None"

Restricts graph retrieval to the named datasets. Dataset names are resolved only against datasets owned by the current user. When both datasets and dataset_ids are omitted, retrieval spans every dataset the current user has read access to — not just a single default dataset. Pass this to narrow the search to specific datasets.

list[UUID] | None

default:"None"

Restricts graph retrieval by dataset UUIDs instead of names. Use this for shared datasets that the current user can access but did not create. When provided, this takes precedence over datasets and the name-to-UUID lookup is skipped. Leaving both datasets and dataset_ids unset searches all of the user’s readable datasets.

int

default:"15"

Maximum number of results to return.

bool

default:"True"

When True, Cognee chooses a retrieval strategy automatically if query_type is not set, using the rule-based query router. Set it to False to always use GRAPH_COMPLETION. An explicit query_type always takes precedence over routing.

str | list[str] | None

default:"None"

Controls whether retrieval uses session, graph, or the default automatic combination logic.

Additional keyword options

Option	Type	What it does
`system_prompt`	`str`	Overrides the system prompt used for completion-style answers.
`system_prompt_path`	`str`	Loads the system prompt from a file path.
`node_name`	`list[str]`	Restricts retrieval to matching node names or node sets.
`node_name_filter_operator`	`str`	Controls how `node_name` filters are combined.
`only_context`	`bool`	Returns retrieved context without generating the final LLM answer.
`session_id`	`str`	Enables session-aware retrieval and session-cache lookup.
`wide_search_top_k`	`int`	Expands the candidate set used before final ranking in graph retrieval.
`triplet_distance_penalty`	`float`	Adjusts ranking for triplet-based retrieval paths.
`feedback_influence`	`float`	Applies stored feedback weights during ranking where supported.
`verbose`	`bool`	Returns additional retrieval details from lower-level search flows.
`retriever_specific_config`	`dict`	Passes advanced configuration directly to the selected retriever.
`include_references`	`bool`	Default `False`. When set to `True`, appends a deterministic `Evidence:` block to completion-style answers, assembled in-process (no extra LLM call) from the retrieved chunks or graph context. The response schema is unchanged and the block is omitted silently when no usable references exist.
`user`	`object`	Runs retrieval under a specific user context.
`llm_config`	`LLMConfig`	LLM settings to install into the current async context for this retrieval operation. Uses the active context config or global LLM config when omitted. Import from `cognee.infrastructure.llm.config`.
`embedding_config`	`EmbeddingConfig`	Embedding settings to install into the current async context for this retrieval operation. Uses the active context config or global embedding config when omitted. Import from `cognee.infrastructure.databases.vector.embeddings.config`.

recall() accepts only the parameters documented above — it has no catch-all **kwargs. Passing an unsupported keyword such as node_type raises TypeError: recall() got an unexpected keyword argument 'node_type'. To restrict retrieval to specific nodes or node sets, use node_name (a list[str]). node_type is a legacy search() parameter and is not exposed on recall().

Return value

recall() returns a list of RecallResponse items. Depending on the request, results may come from session memory, permanent graph retrieval, or both. These items are Pydantic objects, not plain dictionaries — read fields with attribute access (result.text), not result.get("text") or result["text"]. Calling .get() on a result raises AttributeError: 'ResponseGraphEntry' object has no attribute 'get'. The concrete type of each item is set by its source field (import from cognee.modules.recall.types.RecallResponse):

`source`	Type	Key attributes
`"graph"`	`ResponseGraphEntry`	`text` (renderable answer, context, chunk text, or structured output), `kind`, `search_type`, `score`, `dataset_id`, `dataset_name`, `metadata`, `raw` (normalized payload for this item), `structured`
`"session"`	`ResponseQAEntry`	`time`, `qa_id`, `question`, `context`, `answer`, `feedback_text`, `feedback_score`
`"trace"`	`ResponseAgentTraceEntry`	session agent-trace fields
`"graph_context"`	`ResponseGraphContextEntry`	`content`

Source provenance in `metadata`

For chunk and summary results (CHUNKS, CHUNKS_LEXICAL, SUMMARIES), the metadata dict carries stable source identifiers so you can map a result back to the data you ingested and inspect the exact cited chunk. Only the keys present in the underlying payload are included:

`metadata` key	Type	Meaning
`data_id`	`str`	Id of the ingested `Data` item (cognify sets `Document.id = data.id`, so a chunk’s `document_id` is the `data_id`).
`chunk_id`	`str`	The chunk’s own node id — use it to look up the exact cited chunk.
`chunk_index`	`int`	0-based position of the chunk within its document.
`document_name`	`str`	Name of the source document.

Completion-style results (e.g. GRAPH_COMPLETION) carry an empty metadata dict; for those, the same ids are surfaced inline in the Evidence: block instead (see include_references). When include_references=True, each evidence bullet is rendered as - chunk N of document NAME (data_id: …, chunk_id: …): "snippet". This is an additive response-schema change — no DB migration is required, since document_id is already stored on chunks.

results = await cognee.recall("What does Cognee do?")

for result in results:
    if result.source == "graph":
        print(result.text)   # answer or chunk text
        print(result.raw)    # normalized payload for this item
    elif result.source == "session":
        print(result.answer)

The text_result, context_result, and objects_result keys come from the legacy search(verbose=True) API, which returns plain dicts. recall() does not produce those keys. For a graph-backed recall item, result.text is the display-ready value. result.raw preserves the normalized payload for that item; for completion-style searches, it is not the same thing as objects_result.

For the full breakdown of session-hit shapes, graph-backed wrappers, and per-search-type payloads, see Recall — What recall returns.

Examples

import cognee

results = await cognee.recall(
    "What does Cognee do?",
    datasets=["docs"],
    top_k=5,
)

for result in results:
    print(result)

With backend access control enabled, datasets=["name"] only resolves dataset names owned by the current user. If a dataset was created by Alice and shared with Bob, Bob should query it with dataset_ids=[shared_id], not datasets=["name"].

See also SearchType and search() when you need lower-level retrieval control.

​cognee.recall()

​Description

​Prerequisites

​Parameters

​Additional keyword options

​Return value

​Source provenance in metadata

​Examples

​Related

cognee.recall()

Description

Prerequisites

Parameters

Additional keyword options

Return value

Source provenance in `metadata`

Examples

Related