Agent Skills › topoteretes/cognee › cognee-recall

cognee-recall

GitHub

Cognee记忆查询技能,支持recall/search API。涵盖搜索类型选择、自动路由机制、数据集/节点集作用域限定、上下文获取及结果调试。

.agents/skills/cognee-recall/SKILL.md topoteretes/cognee

触发场景

使用cognee.recall或search进行记忆查询 配置搜索策略或路由规则 限定查询的数据集或会话范围 调试查询结果为空或异常

安装

npx skills add topoteretes/cognee --skill cognee-recall -g -y
更多选项

非标准路径

npx skills add https://github.com/topoteretes/cognee/tree/main/.agents/skills/cognee-recall -g -y

不安装直接使用

npx skills use topoteretes/cognee@cognee-recall

指定 Agent (Claude Code)

npx skills add topoteretes/cognee --skill cognee-recall -a claude-code -g -y

安装 repo 全部 skill

npx skills add topoteretes/cognee --all -g -y

预览 repo 内 skill

npx skills add topoteretes/cognee --list

SKILL.md

Frontmatter
{
    "name": "cognee-recall",
    "description": "Use when querying cognee memory with recall() (or search()) — picking a search type, understanding auto-routing, scoping to datasets, node sets or sessions, getting context or citations instead of an answer, reading the results, or debugging empty or unexpected results."
}

Query memory with recall()

recall() is cognee's query API. It picks a search strategy, searches the graph and (with a session) the session cache, and returns a list of tagged results.

import cognee

results = await cognee.recall("Where was Einstein born?")
for r in results:
    print(r.source, r.text)  # e.g. "graph", "Einstein was born in Ulm."

Without datasets it covers every dataset the user can read, but dataset routing (always on, no off switch) scores those datasets against the query on their global context index and searches only the best DATASET_ROUTING_TOP_K (default 1), plus any dataset that has no index yet. A dataset farther than DATASET_ROUTING_DISTANCE_CUTOFF (cosine distance, default 0.8) is skipped, and when none is within it all are searched; datasets within DATASET_ROUTING_TIE_MARGIN (default 0.001) of the last routed one are searched too. A routed search that finds nothing is widened to the rest. The search log prints every dataset's distance. Routing assumes one embedding model across datasets; after an EMBEDDING_MODEL change it logs a warning and every readable dataset is searched. Pass datasets=["research"] (names) or dataset_ids=[...] (UUIDs, which win) to pin the scope yourself; an explicit scope is never routed.

Use it

How the search type is picked

  1. An explicit query_type=SearchType.X always wins.
  2. With no usable LLM key nothing can write an answer, so on both paths HYBRID_COMPLETION, GRAPH_COMPLETION and RAG_COMPLETION run with only_context=True (the assembled prompt instead of an answer), and a routed TEMPORAL or BROAD becomes HYBRID_COMPLETION with only_context=True; a routed CODE needs no LLM and runs as it is.
  3. Without an explicit type, the router (auto_route=True, the default). It is five regex rules, first match wins, no LLM call:
    • the whole query is one "quoted phrase" → CHUNKS_LEXICAL
    • mentions coding rules/standards/conventions or code-review guidelines → CODING_RULES
    • code phrasing right next to an identifier (what calls parse_config, where is CodeRetriever defined, callers of foo()) → CODE, running its ask operation over the identifiers
    • opens with how many / total number of → BROAD
    • an absolute date behind a time preposition (in 2019, before 1900, on 7 November 1867) → TEMPORAL
  4. Everything else → HYBRID_COMPLETION.

A routed type (never a pinned one) that the backend rejects, or a routed CHUNKS_LEXICAL / CODING_RULES / CODE / BROAD that returns nothing, is retried once as HYBRID_COMPLETION. So is a routed CODE with no matching symbol or no code graph, and a routed BROAD that cannot write a working query, hits a limit or finds no document text; any other "no data" is not retried. The router never picks CYPHER.

from cognee import SearchType

await cognee.recall("What changed in v2?", query_type=SearchType.GRAPH_COMPLETION)

Search types

The full list is cognee/modules/search/types/SearchType.py; the type-to-retriever table is cognee/modules/retrieval/README.md.

Type LLM? Use for
HYBRID_COMPLETION (default) yes General questions: document passages plus entity neighbourhoods, then an answer
GRAPH_COMPLETION yes Answers from graph relationships
GRAPH_COMPLETION_COT, _CONTEXT_EXTENSION, _DECOMPOSITION yes Harder multi-hop questions (more LLM calls)
GRAPH_SUMMARY_COMPLETION yes Summarizes the retrieved graph edges at query time (extra LLM call), then answers
RAG_COMPLETION yes Classic chunk RAG
TEMPORAL yes Time questions; hybrid retrieval reranked by the dates in the question
CHUNKS no Raw passages by vector similarity
CHUNKS_LEXICAL no Keyword / exact-phrase match
SUMMARIES no Document summaries
CODE no Code-graph operations via code_query={...}; needs scope="code" in recall
SKILLS no Discover skill playbooks; exactly one dataset
CYPHER no Raw Cypher. Off by default; ALLOW_CYPHER_QUERY=true enables it. It can write, so only pass user-authored queries deliberately
NATURAL_LANGUAGE yes LLM writes Cypher, then runs it (same flag)
GRAPH_REPORT partly Graph insight report: hubs, cross-set links, suggested questions
FEELING_LUCKY yes An LLM picks the type
AGENTIC_COMPLETION yes Multi-step loop with skills/tools; exactly one dataset. Use search() for its parameters

Scope: which sources are searched

scope is one of, or a list of: graph, session, session_first, trace, session_context, all, tools, code. all means graph + session + trace + session_context; tools and code are never included implicitly.

When scope is omitted:

You pass Sources
session_id only Session first; a session hit skips the graph
session_id + datasets Session and graph both contribute
session_id + query_type Graph only — pinning a type drops the session
no session_id Graph only

Session and trace search is keyword overlap, not embeddings.

Filters and knobs

  • top_k=15: per dataset, not in total. The default HYBRID caps each lane at min(top_k, 10); set chunks_top_k / entities_top_k / facts_top_k in retriever_specific_config to go higher.
  • node_name=["AI"] (+ node_name_filter_operator="OR"|"AND"): restricts graph/chunk/completion types to data remembered with that node_set. SUMMARIES, CHUNKS_LEXICAL, GRAPH_REPORT, CYPHER, NATURAL_LANGUAGE, CODE and SKILLS ignore it; CODING_RULES treats it as the rules node-set name.
  • system_prompt / system_prompt_path: change the answering prompt.
  • response_model=MyPydanticModel: structured answer, on r.structured.
  • include_references=True: attach the document chunks that support each graph edge used (needs EDGE_EVIDENCE_ENABLED=true, the default).
  • only_context=True: return what the LLM would have received instead of an answer. r.text is the rendered user prompt, r.system_prompt the system prompt. Pin query_type when you use it.
  • retriever_specific_config={...}: retriever-only options. For the agentic extras (skills, tools, max_iter) and node_type, call cognee.search() instead, which takes them as parameters.

Reading the results

Each item is a Pydantic model with a source discriminator: graph, session, trace, session_context, code, tools, skills, or system. Graph items carry text (always renderable), search_type, kind, score, dataset_id / dataset_name, metadata, raw, and structured. A system item is a status marker, not data (see "memory warming up" below).

When a query sounds procedural ("how do I…", "runbook", "steps to…") and exactly one dataset is targeted, recall also runs a small SKILLS lookup and appends hits with source="skills". Disable with SKILL_GATE_ENABLED=false.

Pitfalls

  • Permissions change what you get back. With no datasets, recall searches only datasets the user can read, so a user without grants gets one source="system" memory_warming_up marker from a graph-only recall (with only_context=True or RECALL_WARMUP_SHORTCIRCUIT=false it gets []; with session sources included only the graph lane is empty, and session and trace hits still come back). Asking for a dataset id the user cannot read raises PermissionDeniedError (HTTP 403). Dataset names resolve only among the user's own datasets, so a name that is not theirs (even one shared with them) raises DatasetNotFoundError; use dataset_ids for shared datasets. See the cognee-permissions skill.
  • "Memory warming up". On an empty graph, a graph-only recall (no session sources, not only_context) returns one source="system" item with status="memory_warming_up" (or "build_failed" plus error_message) instead of results; a multi-source recall just returns no graph results. Wait for the remember to finish, or check why it failed.
  • Hybrid silently becomes graph completion when you pass neighborhood_depth or feedback_influence > 0 (including a nonzero DEFAULT_FEEDBACK_INFLUENCE), or the chunk collection is missing. node_name stays on hybrid, which filters to that node set. search() also defers for a custom node_type or node_name with node_type=None; recall() has no node_type. wide_search_top_k and triplet_distance_penalty with hybrid raise InvalidHybridSearchConfig; pin GRAPH_COMPLETION to use them.
  • SKILLS and AGENTIC_COMPLETION need exactly one dataset. For SKILLS, search() raises unless exactly one dataset is given. recall() runs SKILLS per dataset with access control on (zero datasets gives [], not an error) and raises only with access control off and not exactly one dataset. For AGENTIC_COMPLETION only search() checks it up front, so call it through search() with one dataset.
  • code_query without scope="code" raises, and scope="tools" also needs TOOL_CALLS_ENABLED=true.
  • Latency. Most completion types make one LLM call; COT, DECOMPOSITION, CONTEXT_EXTENSION, GRAPH_SUMMARY_COMPLETION, TEMPORAL, FEELING_LUCKY (one call to pick the type, then the chosen type's) and AGENTIC_COMPLETION (a loop of up to max_iter, default 6) make more. NATURAL_LANGUAGE makes one (no answer call) and retries only on an empty or failed query, up to 3 attempts. With CACHING and AUTO_FEEDBACK on (defaults), each answered turn adds one analysis call, even without a session_id. Set AUTO_FEEDBACK=false for low-latency reads (see the cognee-performance skill).

recall() or search()?

Use recall(). Drop to cognee.search() only for agentic parameters (skills, tools, max_iter, node_type) as first-class arguments, raw SearchResult objects, or a pinned type with no router. search() never searches the session cache; its session_id only adds conversation history to the prompt. Full guide: docs/recall-vs-search.md.

How it works

recall() resolves scope and search type, then calls the same authorized search search() uses: datasets resolve through the permission layer with read, one search per dataset runs concurrently, and results are normalized and tagged.

  • Entry point, scope and type resolution: cognee/api/v1/recall/recall.py
  • Router: cognee/api/v1/recall/query_router.py
  • Skill gate: cognee/api/v1/recall/skill_gate.py
  • Result types: cognee/modules/recall/types/RecallResponse.py, SearchResultItem.py
  • Scope names: cognee/memory/entries.py:normalize_scope
  • Warm-up config (RECALL_WARMUP_*): cognee/modules/recall/config.py
  • Core search and fan-out: cognee/modules/search/methods/search.py
  • Hybrid fallback rules: cognee/modules/search/methods/hybrid_deferral.py
  • Registry: cognee/modules/search/methods/get_search_type_retriever_instance.py

Examples in examples/guides/: recall_core.py, hybrid_retrieval_recall.py, references_example.py, temporal_recall.py, sessions.py.

Extending it

Adding a search type, per cognee/modules/retrieval/README.md:

  1. Write the retriever in cognee/modules/retrieval/ (subclass BaseRetriever or a completion base).
  2. Add the SearchType member and its search_core_registry entry.
  3. Add a row to the README table. A unit test (cognee/tests/unit/modules/retrieval/retriever_readme_index_test.py) fails if the table and registry disagree.
  4. Optional: add it to SEARCH_TYPE_CHOICES in cognee/cli/config.py for the CLI, or a regex rule to query_router.py for auto-routing. Never route a type that can write.

版本历史

  • 525b1d1 当前 2026-11-02 22:49

    新增数据集自动路由功能(含相似度截止和并列扩展),增加CODE和BROAD搜索路由规则,优化无LLM环境下的处理逻辑及重试机制。

  • 37f788b 2026-10-19 05:49

同 Skill 集合

.agents/skills/cognee-cli/SKILL.md
.agents/skills/cognee-community/SKILL.md
.agents/skills/cognee-custom-graph-models/SKILL.md
.agents/skills/cognee-custom-pipelines/SKILL.md
.agents/skills/cognee-docker/SKILL.md
.agents/skills/cognee-forget/SKILL.md
.agents/skills/cognee-improve-sessions/SKILL.md
.agents/skills/cognee-ingestion/SKILL.md
.agents/skills/cognee-integrations/SKILL.md
.agents/skills/cognee-migrations/SKILL.md
.agents/skills/cognee-performance/SKILL.md
.agents/skills/cognee-permissions/SKILL.md
.agents/skills/cognee-server/SKILL.md
.agents/skills/company-brain-company-qa/SKILL.md
.agents/skills/company-brain-follow-up-agent/SKILL.md
.agents/skills/google-workspace-memory/SKILL.md
.agents/skills/multiagent-memory-setup/SKILL.md
.agents/skills/personalized-email/SKILL.md
.agents/skills/self-hosted-companion/SKILL.md
.claude/skills/cognee-cli/SKILL.md
.claude/skills/cognee-community/SKILL.md
.claude/skills/cognee-docker/SKILL.md
.claude/skills/cognee-integrations/SKILL.md
.claude/skills/cognee-permissions/SKILL.md
.claude/skills/cognee-server/SKILL.md
examples/demos/skill_feedback_loop/skills/skill-feedback-writer/SKILL.md
examples/demos/skill_feedback_loop/skills/pr-comment-evaluator/SKILL.md
examples/demos/skill_feedback_loop/skills/diff-risk-explainer/SKILL.md

元信息

文件数
0
版本
525b1d1
Hash
13994db1
收录时间
2026-10-19 05:49

首页 - Wiki
Copyright © 2011-2026 iteam. Current version is 2.156.0. UTC+08:00, 2026-11-18 08:17
浙ICP备14020137号-1