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.
include_referencesboolDefault 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. Set to False to restore the exact prior answer text.
userobjectRuns retrieval under a specific user context.
llm_configLLMConfigLLM 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_configEmbeddingConfigEmbedding 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.

​
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):
sourceTypeKey attributes
"graph"ResponseGraphEntrytext (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"ResponseQAEntrytime, qa_id, question, context, answer, feedback_text, feedback_score
"trace"ResponseAgentTraceEntrysession agent-trace fields
"graph_context"ResponseGraphContextEntrycontent
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.