cognee 项目说明书 - Doramagic.ai

Doramagic 项目包 · 项目说明书

cognee 项目

Cognee 是面向 AI 智能体的开源记忆平台，通过自托管的知识图谱引擎，为 AI 智能体提供跨会话的持久化长期记忆能力。

核心平台与 API (remember / recall / forget / improve)

Cognee 是一个面向 AI Agent 的开源记忆平台，提供了一组以认知行为为隐喻的核心 API：remember、recall、forget 和 improve。这四个函数构成了用户与 Cognee 知识图谱交互的主入口，对应"摄入—回忆—遗忘—改进"这一完整的记忆生命周期。cognee/init.py 将它们作为顶层异步函数导出，使调用者可以用最简洁的方式管理 Ag...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 remember —— 摄取与记忆

继续阅读本节完整说明和来源证据。

章节 recall —— 检索与回忆

继续阅读本节完整说明和来源证据。

章节 forget —— 遗忘与清理

继续阅读本节完整说明和来源证据。

Cognee 是一个面向 AI Agent 的开源记忆平台，提供了一组以认知行为为隐喻的核心 API：remember、recall、forget 和 improve。这四个函数构成了用户与 Cognee 知识图谱交互的主入口，对应"摄入—回忆—遗忘—改进"这一完整的记忆生命周期。cognee/__init__.py 将它们作为顶层异步函数导出，使调用者可以用最简洁的方式管理 Agent 的长期记忆。

平台定位与设计目标

Cognee 的核心目标是为 Agent 提供可持久化、可检索、可演化、可遗忘的长期记忆。与传统的向量数据库或文档检索系统相比，Cognee 强调"知识图谱 + 摘要"的双层结构：remember 负责将多模态数据转化为图谱与摘要节点；recall 在图谱上做多模态查询；forget 提供数据生命周期管理；improve 则利用用户反馈持续优化记忆质量。这种四元组设计模仿了人类记忆的认知过程，使 Agent 可以在多轮交互中保持上下文的连贯性与时效性。

核心 API 详解

remember —— 摄取与记忆

remember 是 Cognee 的数据摄入入口，对应底层 cognee.add + cognee.cognify 的组合封装。cognee/api/v1/remember/remember.py 中定义了异步函数签名，接受文本、文件路径或可迭代的数据集合。cognee/api/v1/add/add.py 则负责把原始数据登记到数据集（dataset）并写入存储层。摄入后，系统会执行分块、实体抽取、关系检测、图谱构建与摘要生成等步骤，最终将知识持久化到向量库与图数据库中。

recall —— 检索与回忆

recall 是与 remember 对偶的查询接口，定义于 cognee/api/v1/recall/recall.py。它支持多种搜索类型（SearchType），包括 GRAPH_COMPLETION、RAG_COMPLETION、CHUNKS、SUMMARIES、CODE、CYPHER 与 FEELING_LUCKY 等。在 cognee-mcp/src/server.py 的 MCP 服务器实现中可以看到，search_type 不区分大小写，top_k 默认值为 10，用于控制返回上下文的规模。GRAPH_COMPLETION 通过 LLM 结合图谱上下文进行综合回答，CHUNKS 则走纯向量相似度路径，速度最快。

forget —— 遗忘与清理

forget 提供了数据生命周期管理能力，定义于 cognee/api/v1/forget/forget.py。它允许用户按数据集、节点 ID 或过滤条件删除已摄入的记忆及其衍生数据。这对于满足隐私合规要求、清理过时信息或管理存储成本至关重要。

improve —— 反馈驱动的改进

improve 是 v1.1.0 引入的"持续学习"入口，定义于 cognee/api/v1/improve/improve.py。它接收用户对 recall 结果的反馈信号（如相关性评分、修正标注），并将这些信号写回图谱，用于调整检索排序权重或丰富实体描述。examples/guides/improve_quickstart.py 展示了如何在 V2 API 中调用 improve 步骤。

端到端工作流

下图为四元组 API 在典型 Agent 场景中的协作关系：

flowchart LR
    A[原始数据] --> B(remember)
    B --> C[(知识图谱 + 向量索引)]
    C --> D(recall)
    D --> E[Agent 回答]
    E --> F(improve)
    F --> C
    C --> G(forget)
    G --> H[清理数据集]

数据流说明：用户先调用 remember 将语料摄入并完成 cognify 流程；Agent 在对话中通过 recall 检索相关上下文；用户或 Agent 自身可调用 improve 把反馈回写至图谱；不再需要的数据则通过 forget 清理。

配置与多租户注意

API 行为受环境变量控制，关键变量包括 LLM_API_KEY、LLM_PROVIDER、LLM_MODEL、VECTOR_DB_PROVIDER 与 GRAPH_DATABASE_PROVIDER（参考 cognee-mcp/src/server.py 的环境变量说明）。在多租户场景下，cognee.add、cognee.search 与 cognee.cognify 都需要显式传入 user 参数以应用 ACL 权限，社区已报告过相关的解析问题（参见 issues #2845、#2846、#2847）。建议在共享数据集场景中优先使用 UUID 方式显式指定数据集，避免按名称解析时的歧义。

常见失败模式

JSON 解析错误：摄入非结构化文件时偶发 JSON 解析失败（issue #3079），建议在调用 remember 前先做格式校验。
LiteLLM 自定义端点被忽略：设置 LLM_ENDPOINT 时 LiteLLM 仍指向官方地址（issue #2842），需额外配置 OPENAI_API_BASE。
MCP 反应崩溃：在 cognee-mcp 的早期版本中存在 None 反应导致的崩溃（issue #3065），升级至 v1.1.2 之后已修复。
过时记忆难以回收：当前没有原生的"新鲜度策略"（issue #3004），需要结合 forget 手动维护。

后端基础设施: LLM、数据库、Pipeline 与检索

cognee 的后端基础设施由 LLM 网关、数据库适配层、任务 Pipeline 和多模式检索四个部分组成，负责把任意来源（文件、URL、SQL、音频/图像）转成可语义检索的知识图谱。cognee.add() → cognee.cognify() → cognee.memify() → cognee.search() 是其对外的端到端主流程；其中 cognify 在 ...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 4.1 任务 Pipeline

继续阅读本节完整说明和来源证据。

章节 4.2 多模式检索

继续阅读本节完整说明和来源证据。

章节 4.3 常见失败模式

继续阅读本节完整说明和来源证据。

1. 后端基础设施总览

cognee 的后端基础设施由 LLM 网关、数据库适配层、任务 Pipeline 和 多模式检索 四个部分组成，负责把任意来源（文件、URL、SQL、音频/图像）转成可语义检索的知识图谱。cognee.add() → cognee.cognify() → cognee.memify() → cognee.search() 是其对外的端到端主流程；其中 cognify 在 MCP 端被进一步拆解为：文档分类 → 权限校验 → 文本分块 → 实体抽取 → 关系发现 → 图谱构建（含 Embedding）→ 内容摘要资料来源：cognee-mcp/src/server.py:1-120。memify 进一步在图谱之上做规则蒸馏和实体规范化（见后文 §4）。

flowchart LR
  A[add 数据源] --> B[chunking 任务]
  B --> C[extract_graph 实体/关系抽取]
  C --> D[summarize_text 摘要]
  D --> E[(Graph DB + Vector DB)]
  E --> F[search 多模式检索]
  E --> G[memify 富化/规则/规范化]
  G --> E

2. LLM 网关与结构化输出

LLM 是 cognee 所有抽取与摘要任务的“推理引擎”，通过统一的网关对外屏蔽多供应商差异。README.md 指出 LLM_API_KEY 为必填环境变量，LLM_PROVIDER、LLM_MODEL、VECTOR_DB_PROVIDER、GRAPH_DATABASE_PROVIDER 为可选资料来源：README.md:1-80。MCP cognify 工具同时暴露 LLM_RATE_LIMIT_ENABLED（默认 False）和 LLM_RATE_LIMIT_REQUESTS（默认 60）两个节流开关资料来源：cognee-mcp/src/server.py:60-120。

社区中最常被报告的 LLM 配置问题集中在“自定义 OpenAI 兼容端点被忽略”上：仅设置 LLM_ENDPOINT 而不显式将 LLM_PROVIDER 切换为 openai/custom 时，调用仍会落到 api.openai.com 资料来源：issue #2842。在 cognee-mcp 中，graph_model_file / graph_model_name / custom_prompt 三个参数允许在不修改代码的前提下替换图模型和提示词资料来源：cognee-mcp/src/server.py:30-90。

3. 数据库与图引擎适配

后端在存储层把图数据库与向量数据库解耦，用户可独立替换：

维度	图数据库示例	向量数据库示例	入口
默认/自托管	Ladybug、Kuzu、Neo4j、Neptune Analytics	ChromaDB、PGVector	`database_examples/`
共享/多租户	Postgres 多用户图（v1.1.0）	—	`database_examples/`
实验/扩展	SurrealDB（社区请求中）	—	issue #226

各适配器遵循统一接口 get_graph_engine()，因此切换后端不需要改动 Pipeline 代码资料来源：README.md:60-120；后端烟雾测试脚本集中在 examples/database_examples/ 中资料来源：examples/README.md:1-60。

4. 任务 Pipeline 与检索

4.1 任务 Pipeline

cognee/tasks/ 下的任务可独立运行也可被 cognify / memify 串接：

summarization：在图谱抽取后运行，输出 TextSummary、CodeSummary 并附带 made_from / summarizes 引用资料来源：cognee/tasks/summarization/README.md:1-60。
codingagents：通过 add_rule_associations 从文本中蒸馏编码规则，并写入 Rule / RuleSet 节点；该任务默认在 memify 中启用资料来源：cognee/tasks/codingagents/README.md:1-80。
web_scraper：DefaultUrlCrawler + TavilyConfig 抓取 URL，并通过 web_scraper_task 将 WebPage/WebSite 写入图谱；运行需安装 APScheduler>=3.10 资料来源：cognee/tasks/web_scraper/README.md:1-60。
disambiguation（POC）：在抽取前先在 Entity_name 向量集合里查找候选实体，并将其注入到 LLM 提示词中以减少重复节点资料来源：examples/pocs/disambiguation/README.md:1-60。

4.2 多模式检索

MCP search 工具暴露了 6 种检索模式：GRAPH_COMPLETION、RAG_COMPLETION、CHUNKS、SUMMARIES、CODE、CYPHER，外加 FEELING_LUCKY 自动选择；top_k（默认 10）控制返回上下文长度资料来源：cognee-mcp/src/server.py:80-160。retrieval_utils.py 在后端完成图节点到字典的归一化（normalize_node、_node_id），屏蔽不同图数据库返回结构的差异，使前端/上层调用方只看到统一的节点 ID 与属性资料来源：cognee-mcp/src/retrieval_utils.py:1-60。

4.3 常见失败模式

现象	根因	触发条件
`cognee.add` 后 `cognify` 静默跳过	多租户 ACL 解析仅按 owner 过滤	非 owner 通过 `dataset_name` 共享数据（issue #2846/#2847）
`cognee.search` 抛 `DatasetNotFoundError`	名字解析未走 ACL 旁路	非 owner 按名字查询共享数据集（issue #2845）
`cognify` 上传报错	数据读取/解析阶段 JSON 异常	损坏或非文本文件（issue #3079）
LiteLLM 忽略 `LLM_ENDPOINT`	端点需配合 `LLM_PROVIDER` 使用	仅设置 `LLM_ENDPOINT`（issue #2842）

5. 部署与演进

README.md 推荐 uv pip install cognee 快速起步，Python 支持 3.10–3.14 资料来源：README.md:1-60。托管与自托管通过 await cognee.serve() 触发，并提供 Modal、Railway、Fly.io、Render、Daytona 一键脚本（见 distributed/deploy/）资料来源：README.md:80-140。

版本演进方面：v1.1.0 引入 Global Context Index 与 Postgres 多用户图资料来源：v1.1.0 release notes；v1.1.1.dev0 修复了 varchar 字段被静默截断的 schema 问题资料来源：v1.1.1.dev0 release notes；v1.1.2 聚焦检索质量与同步可靠性资料来源：v1.1.2 release notes；v1.2.0.dev1 在协作、检索与集成方面提供预览能力资料来源：v1.2.0.dev1 release notes。旧的 cognee-starter-kit/ 已被标记弃用，相关示例迁移到 examples/ 资料来源：cognee-starter-kit/README.md:1-10。

前端、可视化与 UI

Cognee 的前端、可视化与 UI 层为知识图谱提供了浏览器端的可交互界面,涵盖本地可视化启动、MCP(模型上下文协议)服务器内置的图谱渲染端点,以及与后端多用户/多租户访问控制联动的图谱路由逻辑。该层既服务于终端用户浏览记忆与图谱,也为 AI Agent 提供结构化的检索上下文。

章节 相关页面

继续阅读本节完整说明和来源证据。

架构总览

Cognee 的 UI 层在架构上分为三个组成部分:本地前端(Next.js 应用)、图谱可视化后端(visualize API)、以及 MCP UI 工具。三者在功能上互补,既可独立使用,也可通过 MCP 协议串联到 Claude、Cursor 等 AI 客户端中。

graph TB
    User[终端用户 / AI Agent] --> LocalUI["cognee-frontend (本地 Web)"]
    User --> MCPClient["MCP 客户端 (Claude / Cursor)"]
    MCPClient --> MCPServer["cognee-mcp/src/server.py"]
    LocalUI --> BackendAPI["cognee API v1 (visualize/search/cognify)"]
    MCPServer --> BackendAPI
    BackendAPI --> GraphDB["图数据库 (Ladybug / Neo4j / ...)"]
    BackendAPI --> VectorDB["向量数据库 (LanceDB / ChromaDB / ...)"]
    MCPServer -. injects .-> GraphVizUI["Cognee Workspace UI (visualize_graph_ui)"]

资料来源:README.md:1-100

本地前端与可视化示例

cognee-frontend 是一个独立的 Next.js 应用,可通过 examples/demos/start_local_ui_frontend_example.py 脚本一键启动。该脚本会同时拉起后端 API 与前端工作台,使用户能够上传文件、观察 cognify 进度并浏览生成的知识图谱。

入口	用途	示例路径
`start_local_ui_frontend_example.py`	启动后端 + 前端工作台	`examples/demos/`
`graph_visualization.py`	渲染已生成的图谱(轻量演示)	`examples/guides/`
`agent_memory_quickstart.py`	将 LLM Agent 与 cognee 记忆封装	`examples/guides/`
`pipeline_api_proposal.py`	探索 Pipeline API 形式	`examples/demos/`

资料来源:examples/README.md:1-120、examples/README.md:120-220、examples/README.md:220-300

examples/README.md 明确将上述脚本分类到 demos/(端到端功能演示)、guides/(聚焦式 how-to)与 pocs/(研究性 PoC)三个目录,贡献新示例时需遵循同一组织规范,确保 uv run python <path> 可在最小化环境下运行。

图谱可视化与摘要集成

可视化层不仅渲染实体-关系图,还消费 cognee.cognify() 流水线中产生的 TextSummary 与 CodeSummary 节点。summarization 模块在 cognify 流程的 Task #4 中自动运行,为图谱中的每个 DocumentChunk 和代码文件生成结构化摘要,从而在工作台中提供由概括到细节的层级导航。

数据模型	关键字段	来源模块
`TextSummary`	`text`、`made_from` (DocumentChunk)、`metadata`	`cognee/tasks/summarization`
`CodeSummary`	`text`、`summarizes` (CodeFile/CodePart)、`metadata`	`cognee/tasks/summarization`
`Rule`	`text`、`belongs_to_set` (NodeSet)	`cognee/tasks/codingagents`

资料来源:cognee/tasks/summarization/README.md:1-60、cognee/tasks/codingagents/README.md:1-80

CodeSummary 与 Rule 节点在工作台中通常以分组形式展示,允许开发者快速定位某段摘要对应的原始代码或规则提取来源。

MCP 可视化工具

cognee-mcp 服务器通过 visualize_graph_ui 工具将可视化能力暴露给 AI 客户端。该工具由 cognee-mcp/src/server.py 实现,核心逻辑包括:

资源 URI 注册:声明 _VISUALIZE_APP_URI,MCP 客户端可识别其作为 UI 资源。
图谱 HTML 注入:_GRAPH_VIZ_OVERRIDES 会在返回的 HTML 中插入 <head> 之前的覆盖逻辑,从而自定义图谱渲染样式。
多用户路由:当 ENABLE_BACKEND_ACCESS_CONTROL=true 时,(user, dataset) 对应独立的图数据库上下文,因此工具在未显式提供 dataset_name 时调用 _agent_scoped_default_dataset() 来解析 Agent 作用域内的默认数据集;在 API 模式下显式传参会被拒绝,以避免在错误的数据子图上渲染。
多用户图渲染:通过 visualize_multi_user_graph 选择正确的 per-dataset 引擎,避免在共享后端中"命中空数据库"。

资料来源:cognee-mcp/src/server.py:1-160、cognee-mcp/src/server.py:160-260、cognee-mcp/src/server.py:260-360

为支持检索型 UI 端点,cognee-mcp/src/retrieval_utils.py 提供了 normalize_node() 等适配函数,用于将不同图数据库(Kuzu、Neo4j、Neptune 等)返回的节点对象统一转换为普通字典,使 UI 层无需关心底层图后端差异。

部署与社区反馈

README.md 列出了多种部署渠道——Cognee Cloud(托管)、Modal(无服务器)、Railway / Fly.io / Render(PaaS)以及 Daytona(沙箱),其中 bash distributed/deploy/fly-deploy.sh 等脚本可一键启动包含 UI 的全栈部署。社区在 v1.1.1 发布说明中专门提到 "visualization UI and Story layout were reorganized",表明 UI 是 Cognee 每个里程碑持续投入的方向。

资料来源:README.md:100-200、README.md:200-280、v1.1.1 Release Notes()

部署、评估框架、扩展与已知问题

本页面聚焦于 cognee 的生产化能力：如何把它部署到不同平台、如何借助内置示例与评估脚本验证质量、如何通过模块化任务和 MCP 协议扩展行为，以及在社区中反复出现的已知问题与失败模式。

章节 相关页面

继续阅读本节完整说明和来源证据。

一、部署选项与基础设施

cognee 在顶层 README 中明确将自身定位为"可靠的智能体基础设施（Reliable and Trustworthy Agents）"，并提供托管与自托管两条路径。托管方案为 Cognee Cloud，可通过 await cognee.serve() 在本地触发；自托管则通过 distributed/deploy/ 下的脚本对接多个 PaaS 平台资料来源：[README.md]。

平台	适用场景	调用方式
Cognee Cloud	免运维托管服务	控制台注册或 `await cognee.serve()`
Modal	Serverless、自动扩缩容、GPU 工作负载	`bash distributed/deploy/modal-deploy.sh`
Railway	最简 PaaS、原生 Postgres	`railway init && railway up`
Fly.io	边缘部署、持久卷	`bash distributed/deploy/fly-deploy.sh`
Render	简单 PaaS、托管 Postgres	Render 一键部署按钮
Daytona	云沙箱（SDK 或 CLI）	`distributed/deploy/daytona_sandbox.py`

部署前必须配置 LLM 凭证。MCP 服务端明确要求设置 LLM_API_KEY，并支持 LLM_PROVIDER、LLM_MODEL、VECTOR_DB_PROVIDER、GRAPH_DATABASE_PROVIDER 等可选变量资料来源：[cognee-mcp/src/server.py]。当后端为 OpenAI 兼容 API 时，社区反馈 LiteLLM 可能忽略自定义 LLM_ENDPOINT 而回落至 api.openai.com，这是部署到私有网关时需重点验证的失败模式（issue #2842）。

flowchart LR
    A[客户端/Agent] --> B[MCP Server<br/>cognee-mcp]
    B --> C[cognee 核心库<br/>add / cognify / search]
    C --> D[(Graph DB<br/>Ladybug/Neo4j/Neptune)]
    C --> E[(Vector DB<br/>ChromaDB 等)]
    C --> F[LLM Provider<br/>OpenAI/Anthropic/Bedrock/Ollama]
    D -.可选.-> G[对象存储 S3]
    E -.可选.-> G

二、评估框架与示例体系

cognee 的质量保障主要落在三层：内嵌的 evals/ 目录、examples/ 下的端到端脚本，以及针对特定管道的基准请求。社区 issue #2913 建议为 GRAPH_COMPLETION、CHUNKS、TEMPORAL 等检索模式补充标准化的检索质量基准资料来源：[examples/README.md]。

examples/ 按四个梯度组织：

demos/ —— 端到端能力演示，包含多媒体处理、URL 爬取、dlt 摄取、单文档 Q&A、SQL→图谱迁移等资料来源：[examples/README.md]。
guides/ —— 聚焦单点功能的 how-to，例如 agent_memory_quickstart.py、recall_core.py、temporal_recall.py、custom_graph_model.py 资料来源：[examples/README.md]。
custom_pipelines/ —— 自定义管线组合，如采购推理、HR 简历分支、SQL→知识图谱迁移、组织架构图谱化资料来源：[examples/README.md]。
pocs/ —— 研究形态的概念验证，命名规约演进较快，包括消歧、提取后规范化、预取消歧三组脚本资料来源：[examples/README.md]。

运行示例需要先 uv sync --dev --all-extras --reinstall，再从 .env.example 复制出最小配置（至少设置 LLM_API_KEY），最后用 uv run python <脚本路径> 执行资料来源：[examples/README.md]。这意味着评估流水线在 CI 中可被直接驱动，前提是环境变量已注入。

三、扩展点与集成模式

cognee 通过三类机制支持扩展：模块化任务、MCP 协议、自定义图模型。

模块化任务：核心管线被拆分为独立的 Task 单元，可在自定义 Pipeline 中替换或重排。例如 summarize_text 在 cognee.cognify() 中作为步骤 #4 自动运行资料来源：[cognee/tasks/summarization/README.md]；而 add_rule_associations 由 memify() 自动调用，但不默认开启在 cognify() 中资料来源：[cognee/tasks/codingagents/README.md]。Web 抓取则暴露 web_scraper_task 与 DefaultUrlCrawler，依赖 APScheduler>=3.10 资料来源：[cognee/tasks/web_scraper/README.md]。

MCP 协议：服务端 cognee-mcp/src/server.py 把 cognify、search、save_interaction 等项目装为标准 MCP 工具，支持 GRAPH_COMPLETION、RAG_COMPLETION、CHUNKS、SUMMARIES、CODE、CYPHER、FEELING_LUCKY 七种检索类型与 top_k 调参；底层通过 retrieval_utils.normalize_node 把不同图后端节点形态归一化资料来源：[cognee-mcp/src/server.py, cognee-mcp/src/retrieval_utils.py]。

自定义图模型与提示词：用户可通过 graph_model_file + graph_model_name 注入自定义 Pydantic 图模型，也可在 MCP 工具调用中传入 custom_prompt 覆盖抽取提示资料来源：[cognee-mcp/src/server.py]。

社区中悬而未决的扩展方向包括：SurrealDB 后端（issue #226）、n8n 工作流集成（issue #800）、codify 对 JS/Go/Java 等多语言的覆盖（issue #740）、查询结果附带引用（issue #633）。

四、已知问题与故障模式

按出现频度与影响面排序，社区反馈集中于以下几类：

ACL 与多租户边界：issue #2845 报告 cognee.search 在非属主通过名称解析数据集时绕过 ACL；#2846 指出 cognee.add 对非属主在共享名空间下静默新建数据集；#2847 显示 cognify 管线会默默跳过非属主追加的数据。三者共同指向 owner-scope 与 ACL-scope 的解析不一致，需在升级到 v1.1.0 引入的 Postgres 多用户图后格外留意资料来源：[README.md]。
摄取阶段崩溃：issue #3079 报告上传文件触发 cognify 时出现 JSON 解析异常；issue #2842 报告自定义 LLM_ENDPOINT 被 LiteLLM 忽略。
检索质量与新鲜度：issue #2913 要求为多模式检索建立统一基准；issue #3004 提议为陈旧/被替代的记忆引入时间新鲜度策略。
类型与工程治理：issue #2681 提议在 CI 中强制 mypy 类型检查并逐步修复现有签名。
数据库模式治理：v1.1.1.dev0 修复了用户文本字段被 varchar 截断的问题，并加入放大列与早期校验的安全迁移资料来源：[README.md]。
运营与可靠性：v1.2.0.dev1 标注为"开发者构建"，部分内部 API 与预览能力尚未稳定；v1.1.2 的 release notes 聚焦于可靠性、检索质量与同步摄取的修复资料来源：[README.md]。

排查这些问题的通用建议：先用 examples/database_examples/ 中的 smoke test 隔离后端故障；用 evals/ 中的脚本对比 cognify() 与自定义管线的检索召回；若涉及多用户路径，优先复现 #2845–#2847 的 ACL 工作流，而非依赖 user= 参数隐式推断。

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 来源证据：Enhancement: Add retrieval quality benchmarks for different search modes

可能增加新用户试用和生产接入成本。

high 来源证据：[Bug]: JSON issue while adding the file for Cognify the data

可能增加新用户试用和生产接入成本。

high 来源证据：[Bug]: Duplicate content generated in BeautifulSoupLoader due to overlapping default extraction rules

可能增加新用户试用和生产接入成本。

high 失败模式：security_permissions: cognee.add silently creates a new owner-scoped dataset when non-owner uses an existing datase...

Developers may expose sensitive permissions or credentials: cognee.add silently creates a new owner-scoped dataset when non-owner uses an existing dataset name

Pitfall Log / 踩坑日志

项目：topoteretes/cognee

摘要：发现 32 个潜在踩坑项，其中 10 个为 high/blocking；最高优先级：安装坑 - 来源证据：Enhancement: Add retrieval quality benchmarks for different search modes。

1. 安装坑 · 来源证据：Enhancement: Add retrieval quality benchmarks for different search modes

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Enhancement: Add retrieval quality benchmarks for different search modes
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/topoteretes/cognee/issues/2913 | 来源类型 github_issue 暴露的待验证使用条件。

2. 安装坑 · 来源证据：[Bug]: JSON issue while adding the file for Cognify the data

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: JSON issue while adding the file for Cognify the data
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/topoteretes/cognee/issues/3079 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

3. 配置坑 · 来源证据：[Bug]: Duplicate content generated in BeautifulSoupLoader due to overlapping default extraction rules

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: Duplicate content generated in BeautifulSoupLoader due to overlapping default extraction rules
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/topoteretes/cognee/issues/3154 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

4. 安全/权限坑 · 失败模式：security_permissions: cognee.add silently creates a new owner-scoped dataset when non-owner uses an existing datase...

严重度：high
证据强度：source_linked
发现：Developers should check this security_permissions risk before relying on the project: cognee.add silently creates a new owner-scoped dataset when non-owner uses an existing dataset name
对用户的影响：Developers may expose sensitive permissions or credentials: cognee.add silently creates a new owner-scoped dataset when non-owner uses an existing dataset name
证据：failure_mode_cluster:github_issue | https://github.com/topoteretes/cognee/issues/2846 | cognee.add silently creates a new owner-scoped dataset when non-owner uses an existing dataset name

5. 安全/权限坑 · 失败模式：security_permissions: cognee.search ignores ACL when resolving dataset by name for non-owners

严重度：high
证据强度：source_linked
发现：Developers should check this security_permissions risk before relying on the project: cognee.search ignores ACL when resolving dataset by name for non-owners
对用户的影响：Developers may expose sensitive permissions or credentials: cognee.search ignores ACL when resolving dataset by name for non-owners
证据：failure_mode_cluster:github_issue | https://github.com/topoteretes/cognee/issues/2845 | cognee.search ignores ACL when resolving dataset by name for non-owners

6. 安全/权限坑 · 失败模式：security_permissions: cognify pipeline silently skips data added by non-owner users

严重度：high
证据强度：source_linked
发现：Developers should check this security_permissions risk before relying on the project: cognify pipeline silently skips data added by non-owner users
对用户的影响：Developers may expose sensitive permissions or credentials: cognify pipeline silently skips data added by non-owner users
证据：failure_mode_cluster:github_issue | https://github.com/topoteretes/cognee/issues/2847 | cognify pipeline silently skips data added by non-owner users

7. 安全/权限坑 · 来源证据：[Feature]: Temporal freshness policies for stale and superseded memories

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature]: Temporal freshness policies for stale and superseded memories
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/topoteretes/cognee/issues/3004 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

8. 安全/权限坑 · 来源证据：cognee.add silently creates a new owner-scoped dataset when non-owner uses an existing dataset name

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：cognee.add silently creates a new owner-scoped dataset when non-owner uses an existing dataset name
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/topoteretes/cognee/issues/2846 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

9. 安全/权限坑 · 来源证据：cognee.search ignores ACL when resolving dataset by name for non-owners

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：cognee.search ignores ACL when resolving dataset by name for non-owners
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/topoteretes/cognee/issues/2845 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

10. 安全/权限坑 · 来源证据：cognify pipeline silently skips data added by non-owner users

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：cognify pipeline silently skips data added by non-owner users
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/topoteretes/cognee/issues/2847 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

11. 安装坑 · 失败模式：installation: v1.0.8

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: v1.0.8
对用户的影响：Upgrade or migration may change expected behavior: v1.0.8
证据：failure_mode_cluster:github_release | https://github.com/topoteretes/cognee/releases/tag/v1.0.8 | v1.0.8

12. 安装坑 · 失败模式：installation: v1.0.9

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: v1.0.9
对用户的影响：Upgrade or migration may change expected behavior: v1.0.9
证据：failure_mode_cluster:github_release | https://github.com/topoteretes/cognee/releases/tag/v1.0.9 | v1.0.9

13. 安装坑 · 失败模式：installation: v1.1.0.dev1

严重度：medium
证据强度：source_linked
发现：Developers should check this installation risk before relying on the project: v1.1.0.dev1
对用户的影响：Upgrade or migration may change expected behavior: v1.1.0.dev1
证据：failure_mode_cluster:github_release | https://github.com/topoteretes/cognee/releases/tag/v1.1.0.dev1 | v1.1.0.dev1

14. 安装坑 · 来源证据：Relax the exact `ladybug==0.16.0` pin — blocks downstream updates (0.16.1 / 0.17.1 available)

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Relax the exact ladybug==0.16.0 pin — blocks downstream updates (0.16.1 / 0.17.1 available)
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/topoteretes/cognee/issues/2976 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

15. 配置坑 · 失败模式：configuration: LiteLLM ignores custom LLM_ENDPOINT for OpenAI-compatible APIs

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: LiteLLM ignores custom LLM_ENDPOINT for OpenAI-compatible APIs
对用户的影响：Developers may misconfigure credentials, environment, or host setup: LiteLLM ignores custom LLM_ENDPOINT for OpenAI-compatible APIs
证据：failure_mode_cluster:github_issue | https://github.com/topoteretes/cognee/issues/2842 | LiteLLM ignores custom LLM_ENDPOINT for OpenAI-compatible APIs

16. 配置坑 · 失败模式：configuration: [Bug]: JSON issue while adding the file for Cognify the data

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: [Bug]: JSON issue while adding the file for Cognify the data
对用户的影响：Developers may misconfigure credentials, environment, or host setup: [Bug]: JSON issue while adding the file for Cognify the data
证据：failure_mode_cluster:github_issue | https://github.com/topoteretes/cognee/issues/3079 | [Bug]: JSON issue while adding the file for Cognify the data

17. 配置坑 · 失败模式：configuration: [Feature]: Temporal freshness policies for stale and superseded memories

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: [Feature]: Temporal freshness policies for stale and superseded memories
对用户的影响：Developers may misconfigure credentials, environment, or host setup: [Feature]: Temporal freshness policies for stale and superseded memories
证据：failure_mode_cluster:github_issue | https://github.com/topoteretes/cognee/issues/3004 | [Feature]: Temporal freshness policies for stale and superseded memories

18. 配置坑 · 失败模式：configuration: v1.1.0

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: v1.1.0
对用户的影响：Upgrade or migration may change expected behavior: v1.1.0
证据：failure_mode_cluster:github_release | https://github.com/topoteretes/cognee/releases/tag/v1.1.0 | v1.1.0

19. 配置坑 · 失败模式：configuration: v1.1.1

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: v1.1.1
对用户的影响：Upgrade or migration may change expected behavior: v1.1.1
证据：failure_mode_cluster:github_release | https://github.com/topoteretes/cognee/releases/tag/v1.1.1 | v1.1.1

20. 配置坑 · 失败模式：configuration: v1.1.1.dev0

严重度：medium
证据强度：source_linked
发现：Developers should check this configuration risk before relying on the project: v1.1.1.dev0
对用户的影响：Upgrade or migration may change expected behavior: v1.1.1.dev0
证据：failure_mode_cluster:github_release | https://github.com/topoteretes/cognee/releases/tag/v1.1.1.dev0 | v1.1.1.dev0

21. 配置坑 · 来源证据：[Bug]: PostgresAdapter.get_neighborhood fails on PostgreSQL 16 — unnest(:seeds) needs text[] cast

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug]: PostgresAdapter.get_neighborhood fails on PostgreSQL 16 — unnest(:seeds) needs text[] cast
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/topoteretes/cognee/issues/2933 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

22. 能力坑 · 能力判断依赖假设

严重度：medium
证据强度：source_linked
发现：README/documentation is current enough for a first validation pass.
对用户的影响：假设不成立时，用户拿不到承诺的能力。
证据：capability.assumptions | https://github.com/topoteretes/cognee | README/documentation is current enough for a first validation pass.

23. 运行坑 · 失败模式：runtime: PR Review: feat/staging-bridge-fix — Fix None reactions crash

严重度：medium
证据强度：source_linked
发现：Developers should check this runtime risk before relying on the project: PR Review: feat/staging-bridge-fix — Fix None reactions crash
对用户的影响：Developers may hit a documented source-backed failure mode: PR Review: feat/staging-bridge-fix — Fix None reactions crash
证据：failure_mode_cluster:github_issue | https://github.com/topoteretes/cognee/issues/3065 | PR Review: feat/staging-bridge-fix — Fix None reactions crash

24. 运行坑 · 来源证据：PR Review: feat/staging-bridge-fix — Fix None reactions crash

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：PR Review: feat/staging-bridge-fix — Fix None reactions crash
对用户的影响：可能阻塞安装或首次运行。
证据：community_evidence:github | https://github.com/topoteretes/cognee/issues/3065 | 来源类型 github_issue 暴露的待验证使用条件。

25. 维护坑 · 失败模式：migration: v1.0.7

严重度：medium
证据强度：source_linked
发现：Developers should check this migration risk before relying on the project: v1.0.7
对用户的影响：Upgrade or migration may change expected behavior: v1.0.7
证据：failure_mode_cluster:github_release | https://github.com/topoteretes/cognee/releases/tag/v1.0.7 | v1.0.7

26. 维护坑 · 失败模式：migration: v1.1.0.dev0

严重度：medium
证据强度：source_linked
发现：Developers should check this migration risk before relying on the project: v1.1.0.dev0
对用户的影响：Upgrade or migration may change expected behavior: v1.1.0.dev0
证据：failure_mode_cluster:github_release | https://github.com/topoteretes/cognee/releases/tag/v1.1.0.dev0 | v1.1.0.dev0

27. 维护坑 · 失败模式：migration: v1.1.2

严重度：medium
证据强度：source_linked
发现：Developers should check this migration risk before relying on the project: v1.1.2
对用户的影响：Upgrade or migration may change expected behavior: v1.1.2
证据：failure_mode_cluster:github_release | https://github.com/topoteretes/cognee/releases/tag/v1.1.2 | v1.1.2

28. 维护坑 · 维护活跃度未知

严重度：medium
证据强度：source_linked
发现：未记录 last_activity_observed。
对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
证据：evidence.maintainer_signals | https://github.com/topoteretes/cognee | last_activity_observed missing

严重度：medium
证据强度：source_linked
发现：no_demo
证据：downstream_validation.risk_items | https://github.com/topoteretes/cognee | no_demo; severity=medium

30. 安全/权限坑 · 存在评分风险

严重度：medium
证据强度：source_linked
发现：no_demo
对用户的影响：风险会影响是否适合普通用户安装。
证据：risks.scoring_risks | https://github.com/topoteretes/cognee | no_demo; severity=medium

31. 维护坑 · issue/PR 响应质量未知

严重度：low
证据强度：source_linked
发现：issue_or_pr_quality=unknown。
对用户的影响：用户无法判断遇到问题后是否有人维护。
证据：evidence.maintainer_signals | https://github.com/topoteretes/cognee | issue_or_pr_quality=unknown

32. 维护坑 · 发布节奏不明确

严重度：low
证据强度：source_linked
发现：release_recency=unknown。
对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
证据：evidence.maintainer_signals | https://github.com/topoteretes/cognee | release_recency=unknown

来源：Doramagic 发现、验证与编译记录

cognee 项目

核心平台与 API (remember / recall / forget / improve)

平台定位与设计目标

核心 API 详解

remember —— 摄取与记忆

recall —— 检索与回忆

forget —— 遗忘与清理

improve —— 反馈驱动的改进

端到端工作流

配置与多租户注意

常见失败模式

See Also

后端基础设施: LLM、数据库、Pipeline 与检索

1. 后端基础设施总览

2. LLM 网关与结构化输出

3. 数据库与图引擎适配

4. 任务 Pipeline 与检索

4.1 任务 Pipeline

4.2 多模式检索

4.3 常见失败模式

5. 部署与演进

See Also

前端、可视化与 UI

架构总览

本地前端与可视化示例

图谱可视化与摘要集成

MCP 可视化工具

部署与社区反馈

See Also

部署、评估框架、扩展与已知问题

一、部署选项与基础设施

二、评估框架与示例体系

三、扩展点与集成模式

四、已知问题与故障模式

See Also

失败模式与踩坑日记

Pitfall Log / 踩坑日志

1. 安装坑 · 来源证据：Enhancement: Add retrieval quality benchmarks for different search modes

2. 安装坑 · 来源证据：[Bug]: JSON issue while adding the file for Cognify the data

3. 配置坑 · 来源证据：[Bug]: Duplicate content generated in BeautifulSoupLoader due to overlapping default extraction rules

4. 安全/权限坑 · 失败模式：security_permissions: cognee.add silently creates a new owner-scoped dataset when non-owner uses an existing datase...

5. 安全/权限坑 · 失败模式：security_permissions: cognee.search ignores ACL when resolving dataset by name for non-owners

6. 安全/权限坑 · 失败模式：security_permissions: cognify pipeline silently skips data added by non-owner users

7. 安全/权限坑 · 来源证据：[Feature]: Temporal freshness policies for stale and superseded memories

8. 安全/权限坑 · 来源证据：cognee.add silently creates a new owner-scoped dataset when non-owner uses an existing dataset name

9. 安全/权限坑 · 来源证据：cognee.search ignores ACL when resolving dataset by name for non-owners

10. 安全/权限坑 · 来源证据：cognify pipeline silently skips data added by non-owner users

11. 安装坑 · 失败模式：installation: v1.0.8

12. 安装坑 · 失败模式：installation: v1.0.9

13. 安装坑 · 失败模式：installation: v1.1.0.dev1

14. 安装坑 · 来源证据：Relax the exact `ladybug==0.16.0` pin — blocks downstream updates (0.16.1 / 0.17.1 available)

15. 配置坑 · 失败模式：configuration: LiteLLM ignores custom LLM_ENDPOINT for OpenAI-compatible APIs

16. 配置坑 · 失败模式：configuration: [Bug]: JSON issue while adding the file for Cognify the data

17. 配置坑 · 失败模式：configuration: [Feature]: Temporal freshness policies for stale and superseded memories

18. 配置坑 · 失败模式：configuration: v1.1.0

19. 配置坑 · 失败模式：configuration: v1.1.1

20. 配置坑 · 失败模式：configuration: v1.1.1.dev0

21. 配置坑 · 来源证据：[Bug]: PostgresAdapter.get_neighborhood fails on PostgreSQL 16 — unnest(:seeds) needs text[] cast

22. 能力坑 · 能力判断依赖假设

23. 运行坑 · 失败模式：runtime: PR Review: feat/staging-bridge-fix — Fix None reactions crash

24. 运行坑 · 来源证据：PR Review: feat/staging-bridge-fix — Fix None reactions crash

25. 维护坑 · 失败模式：migration: v1.0.7

26. 维护坑 · 失败模式：migration: v1.1.0.dev0

27. 维护坑 · 失败模式：migration: v1.1.2

28. 维护坑 · 维护活跃度未知

30. 安全/权限坑 · 存在评分风险

31. 维护坑 · issue/PR 响应质量未知

32. 维护坑 · 发布节奏不明确