Skip to main content

​
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,
    **kwargs,
) -> 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.
  • 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.

​
Parameters

​
query_text
str
required
Natural-language query to run against memory.
​
query_type
SearchType | None
default:"None"
Forces a specific retrieval strategy instead of using auto-routing.
​
datasets
list[str] | None
default:"None"
Restricts graph retrieval to the named datasets. Dataset names are resolved only against datasets owned by the current user.
​
dataset_ids
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.
​
top_k
int
default:"15"
Maximum number of results to return.
​
auto_route
bool
default:"True"
When True, Cognee chooses a retrieval strategy automatically if query_type is not set.
​
scope
str | list[str] | None
default:"None"
Controls whether retrieval uses session, graph, or the default automatic combination logic.

​
Additional keyword options

OptionTypeWhat it does
system_promptstrOverrides the system prompt used for completion-style answers.
system_prompt_pathstrLoads the system prompt from a file path.
node_namelist[str]Restricts retrieval to matching node names or node sets.
node_name_filter_operatorstrControls how node_name filters are combined.
only_contextboolReturns retrieved context without generating the final LLM answer.
session_idstrEnables session-aware retrieval and session-cache lookup.
wide_search_top_kintExpands the candidate set used before final ranking in graph retrieval.
triplet_distance_penaltyfloatAdjusts ranking for triplet-based retrieval paths.
feedback_influencefloatApplies stored feedback weights during ranking where supported.
verboseboolReturns additional retrieval details from lower-level search flows.
retriever_specific_configdictPasses advanced configuration directly to the selected retriever.
userobjectRuns retrieval under a specific user context.

​
Return value

recall() returns a list of RecallResponse items. Depending on the request, results may come from session memory, permanent graph retrieval, or both. 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.