> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognee.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# recall()
> Query memory with the v1.0 retrieval API
# cognee.recall()
```python theme={null}
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](/core-concepts/main-operations/recall#examples-and-details) 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](/core-concepts/main-operations/recall) and [Search Basics](/guides/search-basics).
## Prerequisites
`recall()` only reads from memory that already exists — it does not initialize anything on its own. Populate memory first with [`remember()`](/python-api/remember) (or the legacy [`add()`](/python-api/add) + [`cognify()`](/python-api/cognify) sequence). The first ingestion run creates the relational, vector, and graph databases and the default user.
```python theme={null}
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
Natural-language query to run against memory.
Forces a specific retrieval strategy instead of using auto-routing.
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.
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.
Maximum number of results to return.
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.
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()`](/python-api/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`](#additional-keyword-options)). 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.
```python theme={null}
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)`](/python-api/search) 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](/core-concepts/main-operations/recall#what-recall-returns).
## Examples
```python theme={null}
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"]`.
## Related
See also [SearchType](/python-api/search-type) and [search()](/python-api/search) when you need lower-level retrieval control.