Guide · Agent skill
How to use cognee-recall: query Cognee memory with recall()
Updated · written with AI from the project's own documentation and checked against our catalogue data
The cognee-recall skill teaches an AI agent how to query cognee, an open-source memory system that stores information as a graph. It covers calling recall(), which search type gets picked automatically, how to narrow searches to datasets, node sets or sessions, and how to read the tagged results. After this guide you will know how to install the skill, how to phrase requests that trigger it, and how to start diagnosing empty or unexpected results.
Query Cognee Memory with recall()topoteretes/cognee · Apache-2.0 Download the skill Quick start
- 1Install cognee. Make sure Python has the cognee library installed, since the skill assumes it is set up.
- 2Configure an LLM key. Most search types need an LLM API key. Without one, the default falls back to plain vector search (CHUNKS).
- 3Install the skill. Unzip the downloaded ZIP into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
- 4Ask a natural question. Describe what you want, such as which search type to use or why results are empty, and mention cognee or recall().
- 5Run a scoped recall. Pass datasets by name or dataset_ids by UUID, and add node_name or a session_id to narrow the search.
- 6Read the tagged results. Check each item's source field, and treat system items as status markers rather than data.
What the cognee-recall skill makes the agent do
recall() is cognee's query API. It picks a search strategy, searches the graph and, when a session is given, the session cache, then returns a list of tagged results. The skill gives an agent the knowledge to call it correctly.
Without a datasets argument, recall() searches every dataset the user can read. Passing datasets with names or dataset_ids with UUIDs narrows the search, which the source notes is also faster. dataset_ids wins if both are given.
- Choose a search type, or let the router choose one.
- Scope the search to datasets, node sets or sessions.
- Ask for context or citations instead of a generated answer.
- Read results and diagnose empty or unexpected output.
import cognee
results = await cognee.recall('Where was Einstein born?')
for r in results:
print(r.source, r.text)Install the cognee-recall skill
Download the ZIP from this page. Unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder to share it with one codebase.
If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills. The skill's only file is SKILL.md.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into .claude/skills/ inside your project
- Claude apps: Settings → Capabilities → Skills, then upload
Trigger the skill with natural requests
The skill's description lists the situations it covers, so ask the agent in those terms. Requests about picking a search type, scoping to datasets, node sets or sessions, getting citations, reading results, or debugging empty results should all match.
Name cognee, recall() or search() in your request when you can. This makes it clear which API you mean.
- Which cognee search type should I use to answer questions about my project docs?
- Scope my recall to the research dataset and only the node set called AI.
- Why does my cognee recall return an empty list?
- Give me the source chunks as citations instead of an answer from recall().
Choose a search type
An explicit query_type always wins. Without a usable LLM key, the default is CHUNKS, which is plain vector search. Otherwise a router with three regex rules runs first match wins and makes no LLM call: a query that is a single quoted phrase goes to CHUNKS_LEXICAL, a query about coding rules, standards, conventions or code-review guidelines goes to CODING_RULES, and an absolute date after a time preposition such as in 2019 goes to TEMPORAL. Everything else uses HYBRID_COMPLETION, the default.
Pin the type yourself when you know what you need. Note that pinning GRAPH_COMPLETION, for example, is a deliberate choice, and the router never picks CYPHER.
- HYBRID_COMPLETION (default, needs LLM): general questions
- GRAPH_COMPLETION (needs LLM): answers from graph relationships
- CHUNKS (no LLM): raw passages by vector similarity
- CHUNKS_LEXICAL (no LLM): keyword or exact-phrase match
- TEMPORAL (needs LLM): time questions
- SUMMARIES (no LLM): document summaries
from cognee import SearchType
await cognee.recall('What changed in v2?', query_type=SearchType.GRAPH_COMPLETION)Narrow the search with scope, filters and knobs
Scope controls which sources are searched. When scope is omitted, a session_id alone searches the session first and a session hit skips the graph. Adding datasets with a session_id lets session and graph both contribute. Pinning query_type with a session_id drops the session, so only the graph is searched.
top_k applies per dataset, not in total. Use node_name to restrict graph, chunk and completion searches to data remembered with a given node_set. Use only_context to see what the LLM would have received, and include_references to attach the document chunks that support each graph edge.
- top_k=15: per dataset; default hybrid caps each lane at min(top_k, 10)
- node_name=['AI'] with node_name_filter_operator 'OR' or 'AND'
- only_context=True: returns the prompt context; pin query_type when using it
- include_references=True: needs EDGE_EVIDENCE_ENABLED=true, which is the default
- response_model: structured answer on r.structured
Read the results and debug empty output
Each result carries a source field such as graph, session, trace or system. Graph items include text, search_type, score and dataset details. A system item is a status marker, not data. On an empty graph, a graph-only recall can return one system item with status memory_warming_up, or build_failed with an error_message. Wait for the remember step to finish, or check why it failed.
Permissions also change what you get back. A user without access gets a memory_warming_up marker when searching with no datasets. Asking for a dataset ID the user cannot read raises PermissionDeniedError (HTTP 403). A dataset name that is not theirs, even a shared one, raises DatasetNotFoundError, so use dataset_ids for shared datasets. The skill cross-references the cognee-permissions skill for this.
- Empty result on a new graph: wait for remember to finish
- build_failed status: read error_message
- 403 PermissionDeniedError: check the dataset ID and grants
- DatasetNotFoundError on a shared dataset: pass dataset_ids instead of the name
- Hybrid behaving like graph completion: check neighborhood_depth and feedback_influence settings
Safety notes: scripts, network and Cypher
This skill runs no scripts and uses no network access, according to its listing. It is documentation that teaches an agent how to call a Python library you have installed.
The CYPHER search type runs raw Cypher and is off by default. It is enabled only when ALLOW_CYPHER_QUERY=true is set. The source warns that Cypher can write to the graph, so only pass user-authored queries deliberately and never run untrusted input through it.
- No scripts are run by the skill itself
- No network use is listed for the skill
- CYPHER can write to the graph; keep ALLOW_CYPHER_QUERY off unless needed
What people use it for
- Choosing between HYBRID_COMPLETION, GRAPH_COMPLETION and CHUNKS for a project's document questions
- Limiting recall to one shared dataset by its dataset_ids when names do not resolve
- Getting source passages with include_references for citations instead of a generated answer
- Debugging why a new graph returns memory_warming_up instead of results
Frequently asked questions
Do I need an LLM API key to use cognee recall?
Most search types need one. Without a usable LLM key, recall() falls back to CHUNKS, which is plain vector search and does not need an LLM.
Is the cognee-recall skill free?
The skill is listed under the Apache-2.0 licence. This page does not state pricing for cognee or any LLM provider you use with it.
What does the skill need to run?
It needs Python with the cognee library installed, an LLM API key for LLM-based search types, and access to the relevant datasets. Shared datasets need dataset_ids.
Why does my cognee recall return empty results?
Common causes in the source are an empty graph that is still warming up, a dataset you cannot read, or a name that does not resolve to one of your datasets. Check for a memory_warming_up or build_failed system item first.
Does the skill only write to memory?
No. It covers querying only. It does not cover storing or ingesting data into cognee.
How is cognee-recall different from calling recall() directly?
The skill gives an agent the rules for choosing search types, scopes and reading results, so it does not have to work them out from the API each time. It does not add new features to cognee itself.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you are building an app or agent on cognee and need to query stored memory, or if you are debugging empty or unexpected recall results. Skip it if you only need to store or ingest data, or if you have no cognee installation and LLM key, since most search types depend on both.
Download the skill