​

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

• It auto-routes queries by default when you do not specify query_type. Routing is rule-based (no LLM call) and falls back to HYBRID_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.

​

Prerequisites

import cognee

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

​

Parameters

​

Additional keyword options

​

Structured output with response_model

from pydantic import BaseModel
import cognee
from cognee import SearchType

class NLPFacts(BaseModel):
    field_name: str
    parent_disciplines: list[str]

results = await cognee.recall(
    query_text="What is NLP and which disciplines does it belong to?",
    query_type=SearchType.GRAPH_COMPLETION,
    response_model=NLPFacts,
)

results[0].structured
# {'field_name': 'Natural Language Processing', 'parent_disciplines': [...]}

​

Return value

​

Warming-up marker

# "analytics" exists, but nothing has ever been ingested into it
results = await cognee.recall("What does Cognee do?", datasets=["analytics"])

results[0].source            # "system"
results[0].status            # "memory_warming_up"
results[0].text              # "Memory is still warming up: no knowledge graph data exists yet for the requested datasets."
results[0].datapoint_count   # 0
results[0].threshold         # 1 (the configured RECALL_WARMUP_THRESHOLD)

# the first cognify() for "analytics" errored
results = await cognee.recall("What does Cognee do?", datasets=["analytics"])

results[0].source            # "system"
results[0].status            # "build_failed"
results[0].text              # "Memory build failed: the last ingestion for the requested datasets
                             #  ended in an error (AuthenticationError: …). Fix the cause and
                             #  re-run remember() or cognify()."
results[0].error_class       # "AuthenticationError"
results[0].error_message     # PII-scrubbed message of the underlying error
results[0].datapoint_count   # 0

• The marker only appears when graph is the sole source. In a multi-source recall (for example a session-scoped call that reads both session memory and the graph), a cold graph contributes [] instead, so the other sources — and the tools on_empty fallback — behave exactly as if graph retrieval had returned nothing.
• only_context=True bypasses the check and always runs normal retrieval, since those callers expect context rather than a marker.
• Populated datasets are unaffected. A dataset with a completed graph-writing run reads as warm. So does one that has only been add()-ed but not yet cognified — staged-only datasets fail safe to warm, and a failed add() never produces a build_failed marker, since staging says nothing about the graph.
• A build still in flight reads as warm. The never-built verdict requires that no pipeline run exists at all, so once a first cognify() has started — a background run, for example — recall runs a normal search that comes back empty rather than returning a memory_warming_up marker.
• Only warm verdicts are cached. Both cold states are re-probed on every recall, so the first recall after a successful rebuild sees the truth immediately.
• The check fails open. A probe or configuration error falls through to a normal search, so it can never block a real answer.
• It can be turned off with RECALL_WARMUP_SHORTCIRCUIT=false (or cognee.config.set("recall_warmup_shortcircuit", False)), which restores the previous behavior exactly. See Recall warm-up for that variable and its two companions.

​

Skill gate

• Additive and fail-safe. The main lanes never wait on the gate, it never replaces or blocks the main answer, and any error in the lookup contributes nothing rather than failing the recall. A dataset with no skills ingested yet simply adds no entries.
• Single-dataset only. Skills are scoped per dataset, so the gate runs only when exactly one dataset is targeted through datasets or dataset_ids. Otherwise it is skipped silently.
• Skipped when it would be redundant. It does not run when "graph" is not in scope, when only_context=True, or when query_type is already SKILLS or AGENTIC_COMPLETION.
• It can be turned off with SKILL_GATE_ENABLED=false.

​

Source provenance in metadata

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)

​

Relevance in score

results = await cognee.recall(
    "Where is memory stored?",
    query_type=SearchType.CHUNKS,
)

# Closest match first — lower distance is better.
ranked = sorted(
    (r for r in results if getattr(r, "score", None) is not None),
    key=lambda r: r.score,
)

​

Examples

import cognee

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

for result in results:
    print(result)

​

Related