# https://github.com/topoteretes/cognee 项目说明书

生成时间：2026-06-20 17:41:19 UTC

## 目录

- [核心平台与 API (remember / recall / forget / improve)](#page-1)
- [后端基础设施: LLM、数据库、Pipeline 与检索](#page-2)
- [前端、可视化与 UI](#page-3)
- [部署、评估框架、扩展与已知问题](#page-4)

<a id='page-1'></a>

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

### 相关页面

相关主题：[后端基础设施: LLM、数据库、Pipeline 与检索](#page-2), [部署、评估框架、扩展与已知问题](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [cognee/__init__.py](https://github.com/topoteretes/cognee/blob/main/cognee/__init__.py)
- [cognee/api/v1/remember/remember.py](https://github.com/topoteretes/cognee/blob/main/cognee/api/v1/remember/remember.py)
- [cognee/api/v1/recall/recall.py](https://github.com/topoteretes/cognee/blob/main/cognee/api/v1/recall/recall.py)
- [cognee/api/v1/forget/forget.py](https://github.com/topoteretes/cognee/blob/main/cognee/api/v1/forget/forget.py)
- [cognee/api/v1/improve/improve.py](https://github.com/topoteretes/cognee/blob/main/cognee/api/v1/improve/improve.py)
- [cognee/api/v1/add/add.py](https://github.com/topoteretes/cognee/blob/main/cognee/api/v1/add/add.py)
- [cognee/tasks/summarization/README.md](https://github.com/topoteretes/cognee/blob/main/cognee/tasks/summarization/README.md)
- [cognee-mcp/src/server.py](https://github.com/topoteretes/cognee/blob/main/cognee-mcp/src/server.py)
- [examples/README.md](https://github.com/topoteretes/cognee/blob/main/examples/README.md)
</details>

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

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 场景中的协作关系：

```mermaid
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 方式显式指定数据集，避免按名称解析时的歧义。

## 常见失败模式

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

## See Also

- [Summarization Module（摘要模块）](https://github.com/topoteretes/cognee/blob/main/cognee/tasks/summarization/README.md)
- [Examples & Guides（示例与指南）](https://github.com/topoteretes/cognee/blob/main/examples/README.md)
- [MCP Server（Model Context Protocol 服务）](https://github.com/topoteretes/cognee/blob/main/cognee-mcp/README.md)

---

<a id='page-2'></a>

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

### 相关页面

相关主题：[核心平台与 API (remember / recall / forget / improve)](#page-1), [部署、评估框架、扩展与已知问题](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [cognee-mcp/src/server.py](https://github.com/topoteretes/cognee/blob/main/cognee-mcp/src/server.py)
- [cognee-mcp/src/retrieval_utils.py](https://github.com/topoteretes/cognee/blob/main/cognee-mcp/src/retrieval_utils.py)
- [README.md](https://github.com/topoteretes/cognee/blob/main/README.md)
- [examples/README.md](https://github.com/topoteretes/cognee/blob/main/examples/README.md)
- [cognee/tasks/summarization/README.md](https://github.com/topoteretes/cognee/blob/main/cognee/tasks/summarization/README.md)
- [cognee/tasks/codingagents/README.md](https://github.com/topoteretes/cognee/blob/main/cognee/tasks/codingagents/README.md)
- [cognee/tasks/web_scraper/README.md](https://github.com/topoteretes/cognee/blob/main/cognee/tasks/web_scraper/README.md)
- [examples/pocs/disambiguation/README.md](https://github.com/topoteretes/cognee/blob/main/examples/pocs/disambiguation/README.md)
- [cognee-starter-kit/README.md](https://github.com/topoteretes/cognee/blob/main/cognee-starter-kit/README.md)
</details>

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

## 1. 后端基础设施总览

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

```mermaid
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](https://github.com/topoteretes/cognee/blob/main/README.md)。MCP `cognify` 工具同时暴露 `LLM_RATE_LIMIT_ENABLED`（默认 `False`）和 `LLM_RATE_LIMIT_REQUESTS`（默认 60）两个节流开关 资料来源：[cognee-mcp/src/server.py:60-120](https://github.com/topoteretes/cognee/blob/main/cognee-mcp/src/server.py)。

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

## 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](https://github.com/topoteretes/cognee/blob/main/README.md)；后端烟雾测试脚本集中在 `examples/database_examples/` 中 资料来源：[examples/README.md:1-60](https://github.com/topoteretes/cognee/blob/main/examples/README.md)。

## 4. 任务 Pipeline 与检索

### 4.1 任务 Pipeline

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

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

### 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](https://github.com/topoteretes/cognee/blob/main/cognee-mcp/src/server.py)。`retrieval_utils.py` 在后端完成图节点到字典的归一化（`normalize_node`、`_node_id`），屏蔽不同图数据库返回结构的差异，使前端/上层调用方只看到统一的节点 ID 与属性 资料来源：[cognee-mcp/src/retrieval_utils.py:1-60](https://github.com/topoteretes/cognee/blob/main/cognee-mcp/src/retrieval_utils.py)。

### 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](https://github.com/topoteretes/cognee/blob/main/README.md)。托管与自托管通过 `await cognee.serve()` 触发，并提供 Modal、Railway、Fly.io、Render、Daytona 一键脚本（见 `distributed/deploy/`） 资料来源：[README.md:80-140](https://github.com/topoteretes/cognee/blob/main/README.md)。

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

## See Also

- [cognee/tasks/summarization/README.md](https://github.com/topoteretes/cognee/blob/main/cognee/tasks/summarization/README.md) — 摘要任务细节
- [cognee/tasks/codingagents/README.md](https://github.com/topoteretes/cognee/blob/main/cognee/tasks/codingagents/README.md) — 编码规则抽取
- [examples/pocs/disambiguation/README.md](https://github.com/topoteretes/cognee/blob/main/examples/pocs/disambiguation/README.md) — 实体消歧 POC
- [examples/README.md](https://github.com/topoteretes/cognee/blob/main/examples/README.md) — 完整示例索引
- [issue #2842](https://github.com/topoteretes/cognee/issues/2842) — LLM 端点配置陷阱
- [issue #2845/#2846/#2847](https://github.com/topoteretes/cognee/issues/2845) — ACL 与共享数据集系列问题

---

<a id='page-3'></a>

## 前端、可视化与 UI

### 相关页面

相关主题：[核心平台与 API (remember / recall / forget / improve)](#page-1), [后端基础设施: LLM、数据库、Pipeline 与检索](#page-2)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/topoteretes/cognee/blob/main/README.md)
- [cognee-mcp/src/server.py](https://github.com/topoteretes/cognee/blob/main/cognee-mcp/src/server.py)
- [cognee-mcp/src/retrieval_utils.py](https://github.com/topoteretes/cognee/blob/main/cognee-mcp/src/retrieval_utils.py)
- [examples/README.md](https://github.com/topoteretes/cognee/blob/main/examples/README.md)
- [cognee/tasks/summarization/README.md](https://github.com/topoteretes/cognee/blob/main/cognee/tasks/summarization/README.md)
- [cognee/tasks/codingagents/README.md](https://github.com/topoteretes/cognee/blob/main/cognee/tasks/codingagents/README.md)
</details>

# 前端、可视化与 UI

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

## 架构总览

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

```mermaid
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` 实现,核心逻辑包括:

1. **资源 URI 注册**:声明 `_VISUALIZE_APP_URI`,MCP 客户端可识别其作为 UI 资源。
2. **图谱 HTML 注入**:`_GRAPH_VIZ_OVERRIDES` 会在返回的 HTML 中插入 `<head>` 之前的覆盖逻辑,从而自定义图谱渲染样式。
3. **多用户路由**:当 `ENABLE_BACKEND_ACCESS_CONTROL=true` 时,`(user, dataset)` 对应独立的图数据库上下文,因此工具在未显式提供 `dataset_name` 时调用 `_agent_scoped_default_dataset()` 来解析 Agent 作用域内的默认数据集;在 API 模式下显式传参会被拒绝,以避免在错误的数据子图上渲染。
4. **多用户图渲染**:通过 `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](https://github.com/topoteretes/cognee/releases/tag/v1.1.1)()`

## See Also

- [持久化与多租户记忆](#)(相关 wiki 页面)
- [MCP 集成](#)(相关 wiki 页面)
- [知识图谱与检索模式](#)(相关 wiki 页面)

---

<a id='page-4'></a>

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

### 相关页面

相关主题：[核心平台与 API (remember / recall / forget / improve)](#page-1), [后端基础设施: LLM、数据库、Pipeline 与检索](#page-2), [前端、可视化与 UI](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/topoteretes/cognee/blob/main/README.md)
- [examples/README.md](https://github.com/topoteretes/cognee/blob/main/examples/README.md)
- [cognee-mcp/src/server.py](https://github.com/topoteretes/cognee/blob/main/cognee-mcp/src/server.py)
- [cognee-mcp/src/retrieval_utils.py](https://github.com/topoteretes/cognee/blob/main/cognee-mcp/src/retrieval_utils.py)
- [cognee/tasks/summarization/README.md](https://github.com/topoteretes/cognee/blob/main/cognee/tasks/summarization/README.md)
- [cognee/tasks/codingagents/README.md](https://github.com/topoteretes/cognee/blob/main/cognee/tasks/codingagents/README.md)
- [cognee/tasks/web_scraper/README.md](https://github.com/topoteretes/cognee/blob/main/cognee/tasks/web_scraper/README.md)
- [examples/pocs/disambiguation/README.md](https://github.com/topoteretes/cognee/blob/main/examples/pocs/disambiguation/README.md)
</details>

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

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

## 一、部署选项与基础设施

cognee 在顶层 README 中明确将自身定位为"可靠的智能体基础设施（Reliable and Trustworthy Agents）"，并提供托管与自托管两条路径。托管方案为 [Cognee Cloud](https://www.cognee.ai)，可通过 `await cognee.serve()` 在本地触发；自托管则通过 `distributed/deploy/` 下的脚本对接多个 PaaS 平台 [资料来源：[README.md](https://github.com/topoteretes/cognee/blob/main/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](https://github.com/topoteretes/cognee/blob/main/cognee-mcp/src/server.py)]。当后端为 OpenAI 兼容 API 时，社区反馈 LiteLLM 可能忽略自定义 `LLM_ENDPOINT` 而回落至 `api.openai.com`，这是部署到私有网关时需重点验证的失败模式（issue #2842）。

```mermaid
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](https://github.com/topoteretes/cognee/blob/main/examples/README.md)]。

`examples/` 按四个梯度组织：

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

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

## 三、扩展点与集成模式

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

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

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

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

## 四、已知问题与故障模式

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

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

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

## See Also

- 核心管线模块：`cognee/tasks/summarization/`、`cognee/tasks/codingagents/`、`cognee/tasks/web_scraper/`
- 示例目录索引：[examples/README.md](https://github.com/topoteretes/cognee/blob/main/examples/README.md)
- MCP 工具参考：[cognee-mcp/src/server.py](https://github.com/topoteretes/cognee/blob/main/cognee-mcp/src/server.py)
- 部署脚本目录：[distributed/deploy/](https://github.com/topoteretes/cognee/tree/main/distributed/deploy)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: topoteretes/cognee; human_manual_source: deepwiki_human_wiki -->