Skip to main content
A minimal guide to querying Cognee memory. The current top-level flow uses cognee.recall(), while the lower-level cognee.search() API remains available when you need direct retriever control. Before you start:
  • Complete Quickstart to understand basic operations
  • Ensure you have LLM Providers configured for LLM-backed retrieval types
  • Run cognee.remember(...) or otherwise build the graph before querying it
  • Keep at least one dataset with read permission for the user running the search

​
Code in Action

await cognee.remember(
    [
        "Alice moved to Paris in 2010. She works as a software engineer.",
        "Bob lives in New York. He is a data scientist.",
        "Alice and Bob met at a conference in 2015.",
    ],
    self_improvement=False,
)

answers = await cognee.recall(query_text="What are the main themes in my data?")
for answer in answers:
    print(answer)
When you call recall() without an explicit query_type, Cognee uses its default auto-routing behavior to choose the best retrieval strategy for the query. To learn more about that routing behavior and the available lower-level search types, see Recall and Search Types.

​
Parameters Reference

All examples below assume you are inside an async function. Import helpers when needed: 
from cognee import SearchType
from cognee.modules.engine.models.node_set import NodeSet
  • query_text (str, required): The question or phrase to search for. 
    answers = await cognee.recall(query_text="Who owns the rollout plan?")
  • query_type (SearchType, optional): Sets the retrieval mode. With recall(), omitting it enables auto-routing by default; if you pass it explicitly, that strategy is used directly. See Search Types for the full list and Retrievers for how each type maps to a retriever. To pick a type by latency and accuracy, see the speed vs. accuracy comparison. 
    await cognee.recall(
    query_text="List coding guidelines",
    query_type=SearchType.CODING_RULES,
)
  • top_k (int, optional, default: 15): Maximum number of results to return. 
    await cognee.recall(query_text="Summaries please", top_k=3)
  • system_prompt_path (str, optional, default: "answer_simple_question.txt"): Path to a prompt file packaged with your project. 
    await cognee.recall(
    query_text="Explain the roadmap in bullet points",
    system_prompt_path="prompts/bullets.txt",
)
  • system_prompt (Optional[str]): Inline prompt string. Overrides system_prompt_path when set. 
    await cognee.recall(
    query_text="Give me a confident answer",
    system_prompt="Answer succinctly and state confidence at the end.",
)
  • only_context (bool, optional, default: False): Skip the LLM completion step and return the retrieved context directly. This avoids the final LLM call and is useful when you want to inspect or reuse the context yourself. 
    import asyncio
import cognee

async def main():
    results = await cognee.recall(
        query_text="What did we promise the client?",
        only_context=True,
    )

    if isinstance(results, str):
        # Single-dataset searches may unwrap to a plain string.
        print(results)
    elif results and isinstance(results[0], dict):
        # With access control enabled, each item is grouped by dataset.
        for dataset_result in results:
            print("Dataset:", dataset_result["dataset_name"])
            print("Context:", dataset_result["search_result"])
    else:
        # Otherwise, results is typically a list of context strings.
        for context_text in results:
            print(context_text)

asyncio.run(main())
    only_context=True works with any search type. For LLM-completion types (GRAPH_COMPLETION, RAG_COMPLETION, etc.) it returns the text that would have been sent to the LLM. For retrieval-only types (CHUNKS, SUMMARIES) the behavior is effectively unchanged because no final LLM call is made.
  • wide_search_top_k (int, optional, default: 100): Caps initial candidate retrieval for graph-completion retrievers before ranking. Increase for broader recall on large graphs.
  • triplet_distance_penalty (float, optional, default: 6.5): Penalty applied in graph retrieval ranking. Controls how triplet distance influences final result ordering.
  • retriever_specific_config (dict, optional): Per-retriever options. Examples: response_model for typed LLM output; max_iter for GRAPH_COMPLETION_COT; context_extension_rounds for GRAPH_COMPLETION_CONTEXT_EXTENSION. See the API reference for full keys. 
    await cognee.recall(
    query_text="What is the current state of the project?",
    query_type=SearchType.GRAPH_COMPLETION,
    datasets=["project_memory"],
    retriever_specific_config={
        "include_global_context_index": True,
        "global_context_index_top_k": 3,
    },
)
    Use include_global_context_index after building the index with cognee.improve(..., build_global_context_index=True). See Global Context Index.
  • verbose (bool, optional, default: False): When true, results include text_result, context_result, and objects_result fields alongside the answer.
  • include_references (bool, optional, default: True): When true, completion-style answers (GRAPH_COMPLETION, RAG_COMPLETION, etc.) get a deterministic Evidence: block appended to the answer text, citing the source chunks or graph context. Set to False to restore the exact prior answer text. See Citation and Source Tracking for details. 
    # Disable the appended Evidence block
await cognee.recall(
    query_text="What did we promise the client?",
    include_references=False,
)
These options scope retrieval to specific node sets. Set both node_type and node_name to filter — use the same names you passed to cognee.add(..., node_set=[...]). See NodeSets for background.
  • node_type (Optional[Type], optional, default: NodeSet): The graph model to search. Leave as NodeSet unless you have a custom node model.
  • node_name (Optional[List[str]]): Names of the node sets to include. 
    from cognee.modules.engine.models.node_set import NodeSet

await cognee.recall(
    query_text="What discounts did TechSupply offer?",
    node_type=NodeSet,
    node_name=["vendor_conversations"],
)
  • node_name_filter_operator (str, optional, default: "OR"): Controls how multiple node-set names are combined. "OR" returns results connected to any of the listed node sets; "AND" returns results connected to all of them. 
    # OR (default) — results touching any of the listed node sets
await cognee.recall(
    query_text="Summarize procurement rules",
    node_type=NodeSet,
    node_name=["procurement_policies", "purchase_history"],
    node_name_filter_operator="OR",
)

# AND — results that belong to every listed node set
await cognee.recall(
    query_text="What topics span both domains?",
    node_type=NodeSet,
    node_name=["procurement_policies", "purchase_history"],
    node_name_filter_operator="AND",
)
Node-set filtering applies to graph-completion search types (GRAPH_COMPLETION, GRAPH_COMPLETION_COT, GRAPH_COMPLETION_CONTEXT_EXTENSION, GRAPH_SUMMARY_COMPLETION, TEMPORAL) and to CHUNKS. For CHUNKS, the filter is applied to the underlying vector search by matching the chunk’s belongs_to_set payload against node_name using node_name_filter_operator; node_type is not used. It has no effect on SUMMARIES, RAG_COMPLETION, CYPHER, or NATURAL_LANGUAGE.
  • session_id (Optional[str]): Links this recall to a conversation session. With recall(), passing session_id by itself makes Cognee search session cache entries first; if nothing matches, it falls through to graph retrieval. When session_id is reused across completion-style recalls, previous Q&A turns can also be included in the prompt context. If omitted while caching is enabled, Cognee writes to default_session. 
    # Session-first recall: checks session cache before graph search
await cognee.recall(
    query_text="Where does Alice live?",
    session_id="conversation_1"
)

# Add datasets when you want to force graph-backed recall in session-aware flows
await cognee.recall(
    query_text="What does she do for work?",
    datasets=["people_demo"],
    session_id="conversation_1"
)
    See Sessions Guide for complete examples. To record feedback on answers, see the Feedback System.
  • datasets (Optional[Union[list[str], str]]): Limit search to specific dataset names. 
    await cognee.recall(
    query_text="Key risks",
    datasets=["risk_register", "exec_summary"],
)
  • dataset_ids (Optional[Union[list[UUID], UUID]]): Same as datasets, using UUIDs instead of names. 
    from uuid import UUID
await cognee.recall(
    query_text="Customer feedback",
    dataset_ids=[UUID("aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee")],
)
    With backend access control enabled, datasets=["name"] resolves names only within datasets owned by the current user. If Bob is searching Alice’s shared dataset shared_dataset, searching by name can fail even when Bob has read access. Use dataset_ids=[shared_id] for shared datasets the user did not create.
  • user (Optional[User]): The user to run the search as. Required for multi-tenant flows or background jobs. 
    from cognee.modules.users.methods import get_user
user = await get_user(user_id)
await cognee.recall(query_text="Team OKRs", user=user)
    When ENABLE_BACKEND_ACCESS_CONTROL=true:
    • Result shape: Searches run only on datasets the user can access. Results are returned as a list of per-dataset objects (dataset_name, dataset_id, search_result). Use verbose=True to include text_result, context_result, and objects_result in each item.
    • Parallel execution: Multiple datasets are searched concurrently using asyncio.gather() — total time is roughly that of the slowest single-dataset search.
    • If no user is given, get_default_user() is used (created if missing); an error is raised only if this user lacks dataset permissions.
    • If datasets is not set, all datasets readable by the user are searched. An error is raised if none are accessible or if a requested dataset is forbidden.
    PermissionDeniedError will be raised unless you search with the same user that added the data or grant access to the default user.
    When ENABLE_BACKEND_ACCESS_CONTROL=false:
    • Dataset filters (datasets, dataset_ids) are ignored — all data is searched.
    • Results are returned as a plain list (e.g. ["answer1", "answer2"]). If only one dataset is searched and the retriever returns a list, Cognee may unwrap one level for backwards compatibility.

​
Citation and Source Tracking

Provenance is available at two levels:
  1. Dataset level — when ENABLE_BACKEND_ACCESS_CONTROL=true, results are wrapped with dataset_name and dataset_id.
  2. Chunk/summary level — CHUNKS and SUMMARIES results include an id you can use to look up the item in the graph.

​
Evidence block (include_references)

For completion-style answers (GRAPH_COMPLETION, RAG_COMPLETION, and similar), Cognee appends a short Evidence: block to the answer text by default (include_references=True). It lists the chunks or graph context the answer was grounded in — for example, - chunk 2 of document policy.pdf: "…".
  • Deterministic and in-process: the block is assembled locally from the retrieved payloads or graph context. There is no extra LLM call and no prompt injection — it is appended after completion generation.
  • Response schema unchanged: Evidence is added to the answer text only. Return types and result shapes are the same as before, and non-string response_model paths are unaffected.
  • Graceful degradation: chunk-level evidence is used when the vector payload carries document_name/document_id. Older indexes that predate these fields fall back to entity → chunk → document graph traversal where the backend supports it, or omit the Evidence block silently (no errors) when neither is available.
  • Opting out: set include_references=False to restore the exact previous answer text. This is useful when you compare against stored snapshots or evaluation baselines, which will otherwise diff against the new Evidence block.
# Default: answer text includes an appended "Evidence:" block
await cognee.recall(query_text="What is the refund policy?")

# Restore the exact prior output (no Evidence block)
await cognee.recall(
    query_text="What is the refund policy?",
    include_references=False,
)
Search results do not include raw source file paths. Evidence can show document names when reference metadata is available, but raw_data_location stays on the Document node. To trace a result back to the original stored file path, use dataset provenance or query the graph by id.
SearchType.CHUNKS returns a list of dicts with these fields:
FieldTypeDescription
idstrChunk UUID
textstrRaw chunk text
chunk_indexintPosition of this chunk within the source document
chunk_sizeintToken count of this chunk
cut_typestrHow the boundary was chosen (sentence_end, paragraph_end, etc.)
import asyncio
import cognee
from cognee import SearchType

async def main():
    await cognee.add("path/to/policy.pdf", dataset_name="docs")
    await cognee.cognify(datasets=["docs"])

    results = await cognee.recall(
        query_text="What is the refund policy?",
        query_type=SearchType.CHUNKS,
    )

    for chunk in results:
        print("Text:        ", chunk["text"])
        print("Chunk index: ", chunk["chunk_index"])
        print("Chunk ID:    ", chunk["id"])  # UUID for graph lookups
        print()

asyncio.run(main())
SearchType.SUMMARIES returns a list of dicts with these fields:
FieldTypeDescription
idstrSummary UUID
textstrSummary text
results = await cognee.recall(
    query_text="What is the refund policy?",
    query_type=SearchType.SUMMARIES,
)

for summary in results:
    print("Summary:", summary["text"])
    print("ID:     ", summary["id"])
For CHUNKS and SUMMARIES, recall() (and the lower-level cognee.search()) use query_text as a retrieval query, not as an identifier lookup. Passing a chunk or summary id as the query searches for semantically similar content and can return unrelated results (or nothing) — not that specific item.For most workflows, keep the id as provenance metadata and use normal recall() queries to retrieve related content. If you need to inspect a specific chunk, summary, or graph node during debugging, query the databases directly:
import asyncio
from cognee.infrastructure.databases.graph import get_graph_engine
from cognee.infrastructure.databases.vector import get_vector_engine

async def main():
    item_id = "your-chunk-or-summary-uuid"  # the `id` returned by a CHUNKS or SUMMARIES search

    # From the graph: returns the node's properties, or None if not found
    graph_engine = await get_graph_engine()
    node = await graph_engine.get_node(item_id)
    print(node)

    # From the vector store: choose the collection for the search type
    vector_engine = get_vector_engine()
    collection = "DocumentChunk_text"  # CHUNKS results
    # collection = "TextSummary_text"  # SUMMARIES results

    rows = await vector_engine.retrieve(collection, [item_id])
    if rows:
        print(rows[0].payload["text"])

asyncio.run(main())
Use get_node(node_id) / get_nodes(node_ids) for graph lookups and retrieve(collection_name, data_point_ids) for vector-store lookups. Use DocumentChunk_text for CHUNKS IDs and TextSummary_text for SUMMARIES IDs.
get_graph_engine() is async (use await); get_vector_engine() is synchronous, but its retrieve method is async. With ENABLE_BACKEND_ACCESS_CONTROL=true, these getters return the default databases — direct lookups bypass the per-dataset isolation applied by recall().
When ENABLE_BACKEND_ACCESS_CONTROL=true, every result is wrapped with dataset information:
import asyncio
import cognee
from cognee import SearchType

async def main():
    results = await cognee.recall(
        query_text="What is the refund policy?",
        query_type=SearchType.CHUNKS,
        datasets=["docs"],
    )

    for dataset_result in results:
        print("Dataset:   ", dataset_result["dataset_name"])
        print("Dataset ID:", dataset_result["dataset_id"])
        for chunk in dataset_result["search_result"]:
            print("  Text:", chunk["text"])
            print("  Chunk ID:", chunk["id"])

asyncio.run(main())
When ENABLE_BACKEND_ACCESS_CONTROL=false, results are a plain list with no dataset_name or dataset_id wrapper.
For modes that return a generated answer (GRAPH_COMPLETION, RAG_COMPLETION, etc.), use verbose=True to receive the raw retrieved objects alongside the answer:
results = await cognee.recall(
    query_text="Summarize the launch timeline",
    verbose=True,
)

for result in results:
    print("Answer:         ", result.get("text_result"))
    print("Context passed: ", result.get("context_result"))
    print("Source objects: ", result.get("objects_result"))

​
Full Example

import asyncio
import cognee


async def main():
    # Start clean (optional in your app)
    await cognee.forget(everything=True)
    # Prepare knowledge base
    await cognee.remember(
        [
            "Alice moved to Paris in 2010. She works as a software engineer.",
            "Bob lives in New York. He is a data scientist.",
            "Alice and Bob met at a conference in 2015.",
        ],
        self_improvement=False,
    )

    # Make sure you've already run cognee.remember(...) so the graph has content
    answers = await cognee.recall(query_text="What are the main themes in my data?")
    for answer in answers:
        print(answer)

if __name__ == "__main__":
    asyncio.run(main())

import asyncio
import cognee

async def main():
    # Start clean (optional)
    await cognee.prune.prune_data()
    await cognee.prune.prune_system(metadata=True)

    await cognee.add(
        [
            "Alice moved to Paris in 2010. She works as a software engineer.",
            "Bob lives in New York. He is a data scientist.",
            "Alice and Bob met at a conference in 2015.",
        ]
    )
    await cognee.cognify()

    answers = await cognee.recall(query_text="What are the main themes in my data?")
    for answer in answers:
        print(answer)

if __name__ == "__main__":
    asyncio.run(main())
recall() is the current high-level retrieval entry point. It routes the query to the best available retrieval strategy and can still use graph-backed search under the hood.

​
Additional Examples

Additional examples are available on our GitHub.

Custom Prompts

Learn about custom prompts for tailored answers

Permission Snippets

Multi-tenant deployment patterns

API Reference

Explore all search types and parameters

Sessions

Enable conversational memory with sessions

Agent Memory Decorator

Attach retrieval to an agent function boundary