# https://github.com/vincentspereira/Enhanced-Cognee 项目说明书 生成时间：2026-06-02 09:28:56 UTC ## 目录 - [项目介绍与快速开始](#project-introduction) - [核心功能亮点](#feature-highlights) - [功能对比与选型指南](#comparison-guide) - [系统架构总览](#architecture-overview) - [数据库适配器与存储层](#database-stack) - [MCP工具参考手册](#mcp-tools-reference) - [内存管理与生命周期](#memory-management) - [多租户数据分区](#multi-tenant) - [跨语言客户端SDK](#cross-language-sdks) - [API接口参考](#api-reference) ## 项目介绍与快速开始 ### 相关页面 相关主题：[系统架构总览](#architecture-overview), [核心功能亮点](#feature-highlights)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/README.md) - [CLAUDE.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/CLAUDE.md) - [cognee-starter-kit/README.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/cognee-starter-kit/README.md) - [dashboard/README.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/dashboard/README.md) - [dashboard/nextjs-dashboard/README.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/dashboard/nextjs-dashboard/README.md) - [cognee/__init__.py](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/cognee/__init__.py) - [cognee/version.py](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/cognee/version.py)
# 项目介绍与快速开始 ## 什么是 Enhanced Cognee？ Enhanced Cognee 是一个基于上游 [cognee](https://github.com/topoteretes/cognee) 项目构建的生产级知识图谱记忆层，专为 Claude Code 和 AI 应用设计。该项目集成了多种数据库技术，包括 PostgreSQL、Qdrant、Neo4j 和 Redis，提供了一套完整的记忆管理和知识检索解决方案。 **版本信息：** Enhanced Cognee v1.0.0（基于上游 v1.0.9，官方最新为 v1.1.2） 该版本包含 **119 个 MCP 工具**，涵盖记忆管理、知识图谱、搜索、加密、GDPR 合规、Webhook、通知等功能，并附带 1,134 个单元测试，全部通过（100% ASCII 安全，无 Unicode 编码问题）。 ## 核心架构 Enhanced Cognee 采用多层次架构设计，底层依赖多种数据库系统协同工作： ```mermaid graph TB subgraph 前端层 A[Next.js Dashboard] end subgraph MCP 工具层 B[119 MCP Tools] end subgraph 核心处理层 C[cognee API] D[记忆模块] E[知识图谱模块] F[搜索模块] end subgraph 数据存储层 G[PostgreSQL
结构化数据] H[Qdrant
向量检索] I[Neo4j
图数据库] J[Redis
缓存] end A --> B B --> C C --> D C --> E C --> F D --> G D --> J E --> I F --> H F --> I ``` ## 核心功能模块 ### 记忆管理 (Memory) 记忆模块负责存储和管理文本记忆数据，支持添加、编辑、查询和删除操作。 **主要 API：** | API 函数 | 功能描述 | |---------|---------| | `cognee.add()` | 添加数据到记忆系统 | | `cognee.cognify()` | 执行完整的认知处理流程 | | `cognee.memify()` | 执行记忆丰富处理流程 | | `cognee.search()` | 搜索记忆内容 | ### 知识图谱 (Knowledge Graph) 知识图谱模块将非结构化数据转换为结构化的图数据，支持实体识别、关系提取和图查询。 ### 搜索功能 支持语义搜索和关键词搜索，可通过 `query_type` 参数指定搜索类型。 ## 技术栈 | 组件 | 技术选型 | |-----|---------| | 后端框架 | FastAPI | | 前端框架 | Next.js 14 (App Router) | | 编程语言 | TypeScript 5 / Python | | 向量数据库 | Qdrant | | 图数据库 | Neo4j | | 关系数据库 | PostgreSQL | | 缓存系统 | Redis | | 加密方案 | Fernet AES-128-CBC | ## 快速开始 ### 环境要求 - Python 3.10+ - Node.js 18+ - PostgreSQL - Qdrant - Neo4j - Redis ### 安装步骤 #### 1. 克隆项目 ```bash git clone https://github.com/vincentspereira/Enhanced-Cognee.git cd Enhanced-Cognee ``` #### 2. 安装 Python 依赖 ```bash # 使用 uv 安装 pip install uv uv sync # 激活虚拟环境 source .venv/bin/activate ``` #### 3. 配置环境变量 创建 `.env` 文件，配置以下变量： ```bash # LLM 配置 LLM_PROVIDER="" LLM_MODEL="" LLM_ENDPOINT="" LLM_API_KEY="" LLM_API_VERSION="" # Embedding 配置 EMBEDDING_PROVIDER="" EMBEDDING_MODEL="" EMBEDDING_ENDPOINT="" EMBEDDING_API_KEY="" EMBEDDING_API_VERSION="" ``` #### 4. 安装前端仪表板 ```bash cd dashboard/nextjs-dashboard npm install ``` 创建 `.env.local` 文件： ```bash NEXT_PUBLIC_API_URL=http://localhost:8000 ``` ### 基本使用示例 #### Python API 使用 ```python import cognee # 添加数据 await cognee.add(["document.pdf", "notes.txt"]) # 执行认知处理 await cognee.cognify() # 搜索记忆 results = await cognee.search( query_text="关键概念", query_type="semantic" ) ``` #### 使用 Starter Kit 项目提供了 cognee-starter-kit，可以快速体验完整功能： ```bash cd cognee-starter-kit uv sync source .venv/bin/activate # 运行默认管道 python src/pipelines/default.py ``` ### 启动仪表板 ```bash # 启动后端 API (端口 8000) # 确保 Enhanced Cognee 后端服务运行中 # 启动前端开发服务器 cd dashboard/nextjs-dashboard npm run dev ``` 访问 http://localhost:3000 查看仪表板。 ## 项目结构 ``` Enhanced-Cognee/ ├── cognee/ # 核心 Python 包 │ ├── tasks/ # 任务模块 │ │ ├── summarization/ # 文本摘要 │ │ └── codingagents/ # 编码代理 │ └── __init__.py ├── dashboard/ # 仪表板 │ ├── nextjs-dashboard/ # Next.js 前端 │ │ └── src/ │ │ ├── app/ # 页面组件 │ │ ├── components/ # UI 组件 │ │ └── lib/ # 工具库 │ └── api/ # FastAPI 后端 ├── cognee-starter-kit/ # 入门套件 └── tests/ # 单元测试 ``` ## 测试 项目包含 1,134 个单元测试，确保代码质量： ```bash # 运行所有测试 pytest # 运行特定模块测试 pytest tests/tasks/ ``` ## 相关资源 - **上游项目：** [cognee](https://github.com/topoteretes/cognee) - **最新版本：** [v1.0.0 - 119 MCP Tools](https://github.com/vincentspereira/Enhanced-Cognee/releases/tag/enhanced-v1.0.0) - **上游同步状态：** [Issue #67](https://github.com/vincentspereira/Enhanced-Cognee/issues/67) - 正在同步 v1.1.2 变更 ## 下一步 - 阅读 [CLAUDE.md](CLAUDE.md) 了解 Claude Code 集成指南 - 探索 [cognee-starter-kit](cognee-starter-kit/) 快速构建示例应用 - 查看 [dashboard/README.md](dashboard/README.md) 了解仪表板功能 --- ## 核心功能亮点 ### 相关页面 相关主题：[MCP工具参考手册](#mcp-tools-reference), [内存管理与生命周期](#memory-management), [功能对比与选型指南](#comparison-guide)
相关源码文件 以下源码文件用于生成本页说明： - [src/mcp_memory_tools.py](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/src/mcp_memory_tools.py) - [src/enhanced_cognee_mcp.py](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/src/enhanced_cognee_mcp.py) - [cognee/modules/memory/__init__.py](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/cognee/modules/memory/__init__.py) - [cognee/modules/search](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/cognee/modules/search) - [cognee/tasks/memify](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/cognee/tasks/memify) - [cognee/tasks/summarization/README.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/cognee/tasks/summarization/README.md) - [cognee/tasks/codingagents/README.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/cognee/tasks/codingagents/README.md) - [cognee/tasks/web_scraper/README.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/cognee/tasks/web_scraper/README.md)
# 核心功能亮点 Enhanced-Cognee 是一个专为 Claude Code 构建的生产级知识图谱记忆层，基于 PostgreSQL、Qdrant、Neo4j 和 Redis 技术栈构建。本页面详细介绍该项目的核心功能特性，帮助开发者快速理解系统的能力边界和应用场景。 ## 1. MCP 工具生态体系 ### 1.1 119 个 MCP 工具全景 Enhanced-Cognee v1.0.0 版本提供了 **119 个 MCP 工具**，覆盖了多个功能领域。这些工具通过标准化的 MCP（Model Context Protocol）协议暴露，使 Claude Code 能够与记忆系统进行深度交互。资料来源：[src/enhanced_cognee_mcp.py:1-50]() ```mermaid graph TB A[MCP Tools 119个] --> B[Memory Tools] A --> C[Knowledge Graph Tools] A --> D[Search Tools] A --> E[Encryption Tools] A --> F[GDPR Tools] A --> G[Webhook Tools] A --> H[Notification Tools] B --> B1[add_memory] B --> B2[search_memory] B --> B3[get_stats] C --> C1[add_relation] C --> C2[query_graph] ``` ### 1.2 工具分类总览 | 工具类别 | 工具数量 | 主要功能 | |---------|---------|---------| | 内存管理 | 约 25 个 | 添加、查询、更新、删除记忆 | | 知识图谱 | 约 20 个 | 实体关系管理、图谱查询 | | 搜索功能 | 约 15 个 | 向量搜索、关键词搜索、混合搜索 | | 加密安全 | 约 10 个 | Fernet 加密、密钥管理 | | GDPR 合规 | 约 8 个 | 数据删除、导出、匿名化 | | Webhook | 约 12 个 | 事件通知、回调管理 | | 通知系统 | 约 15 个 | 实时推送、定时提醒 | 资料来源：[src/mcp_memory_tools.py:1-100]() ### 1.3 认证与多租户支持 MCP 工具支持完整的认证机制和多租户架构： ```python # API Key 认证 apiKey = "your-api-key" # 发送为 X-API-Key header # 多租户标识 tenantId = "tenant-123" # 发送为 X-Tenant-ID header ``` 认证相关配置在 `src/mcp_security.py` 中实现，支持通过环境变量 `ENHANCED_API_KEY` 和 `ENHANCED_TENANT_ID` 进行配置。资料来源：[clients/node/README.md:30-40]() ## 2. 知识图谱与记忆系统 ### 2.1 记忆数据模型 系统采用多层数据模型管理记忆，核心组件位于 `cognee/modules/memory/__init__.py`。主要数据模型包括： | 数据模型 | 描述 | 存储位置 | |---------|------|---------| | `Memory` | 基础记忆单元 | PostgreSQL + Redis | | `DocumentChunk` | 文档分块 | PostgreSQL | | `Entity` | 实体节点 | Neo4j | | `Relationship` | 关系边 | Neo4j | | `TextSummary` | 文本摘要 | PostgreSQL | | `CodeSummary` | 代码摘要 | PostgreSQL | | `Rule` | 编码规则 | Neo4j | 资料来源：[cognee/modules/memory/__init__.py:1-50]() ### 2.2 知识图谱提取流程 系统通过 LLM 驱动的结构化提取，自动从文本和代码中识别实体和关系： ```mermaid graph LR A[原始数据] --> B[分块处理] B --> C[实体提取] C --> D[关系映射] D --> E[图谱存储] E --> F[Neo4j 图数据库] ``` 支持的实体类别包括 10 种类型： - 人物（People） - 组织（Organizations） - 系统（Systems） - 文件（Files） - 技术（Technologies） - 位置（Locations） - 事件（Events） - 概念（Concepts） - 产品（Products） - 流程（Processes） 资料来源：[src/llm/prompts/README.md:1-30]() ### 2.3 编码规则智能提取 `cognee/tasks/codingagents` 模块提供了开发者编码规则提取功能，能够从对话、文档或提交信息中识别最佳实践并关联到原始来源： | 函数 | 功能描述 | |------|---------| | `add_rule_associations()` | 通过 LLM 提取规则，添加到图谱并创建来源链接 | | `get_existing_rules()` | 获取特定节点集中的现有规则 | | `get_origin_edges()` | 查找原始 DocumentChunk 并创建 rule_associated_from 边 | 此模块在 `cognee.memify()`（富化管道）中自动运行，但不在标准 `cognee.cognify()` 管道中默认启用。资料来源：[cognee/tasks/codingagents/README.md:1-40]() ## 3. 搜索与检索能力 ### 3.1 多模态搜索架构 Enhanced-Cognee 提供全面的搜索能力，支持向量搜索、关键词搜索和混合搜索模式： ```mermaid graph TD A[搜索请求] --> B{搜索类型选择} B --> C[向量搜索-Qdrant] B --> D[关键词搜索-PostgreSQL] B --> E[混合搜索] C --> F[结果重排序] D --> F E --> F F --> G[结果返回] ``` ### 3.2 搜索功能矩阵 | 搜索类型 | 描述 | 底层技术 | |---------|------|---------| | `vector_search` | 语义相似度搜索 | Qdrant | | `keyword_search` | 精确关键词匹配 | PostgreSQL FTS | | `hybrid_search` | 向量+关键词混合 | Qdrant + PostgreSQL | | `graph_search` | 知识图谱关系搜索 | Neo4j Cypher | | `metadata_filter` | 元数据条件过滤 | PostgreSQL | 资料来源：[cognee/modules/search:1-30]() ### 3.3 相似度计算与去重 系统内置智能去重功能，能够识别和处理重复内容： ```json { "are_duplicates": true, "duplicate_type": "exact|near|related|distinct", "similarity_score": 0.92, "confidence": 0.95, "reasoning": "explanation", "key_differences": ["string"], "key_similarities": ["string"], "merge_recommendation": "keep_both|merge|keep_newer" } ``` 输出包含相似度评分（0.0-1.0）、置信度评估、差异分析和合并建议。资料来源：[src/llm/prompts/README.md:1-50]() ## 4. 摘要与富化管道 ### 4.1 自动化摘要生成 `cognee/tasks/summarization` 模块在 `cognee.cognify()` 管道的第四步自动运行，提供文本和代码的 LLM 驱动摘要功能： ```mermaid graph LR A[cognee.add] --> B[分块处理] B --> C[图谱提取] C --> D[summarize_text] D --> E[存储/索引] ``` | 函数 | 输入 | 输出 | |------|------|------| | `summarize_text()` | DocumentChunk 列表 | `list[TextSummary]` | | `summarize_code()` | CodeFile/CodePart 节点 | `DataPoint` + `CodeSummary` | 资料来源：[cognee/tasks/summarization/README.md:1-40]() ### 4.2 富化管道（Memify） `cognee/tasks/memify` 提供了比标准管道更深入的数据富化功能，包括： - 编码规则自动提取与关联 - 实体关系深度挖掘 - 上下文增强 - 来源追溯 此管道在记忆创建过程中自动执行，提升记忆的语义质量和可用性。资料来源：[cognee/tasks/memify:1-30]() ## 5. 网页抓取与数据采集 ### 5.1 多源数据抓取能力 `cognee/tasks/web_scraper` 模块提供灵活的网页内容采集功能： | 配置类 | 功能 | |--------|------| | `DefaultUrlCrawler` | 默认 URL 爬虫（并发控制、超时、Playwright 支持） | | `TavilyConfig` | Tavily API 配置（API key、提取深度、超时） | ### 5.2 抓取数据模型 | 模型 | 关键字段 | 描述 | |------|---------|------| | `WebPage` | content, content_hash, scraped_at, status_code, page_size | 网页内容记录 | | `WebSite` | base_url, robots_txt, crawl_delay, page_count | 网站元数据 | | `ScrapingJob` | urls, schedule, status, last_run, next_run | 抓取任务管理 | 图谱关系：`ScrapingJob` → `WebSite`（`is_scraping`），`WebPage` → `WebSite`（`is_part_of`）。资料来源：[cognee/tasks/web_scraper/README.md:1-50]() ## 6. 安全与加密 ### 6.1 静态数据加密 Enhanced-Cognee v1.0.0 支持 **Fernet AES-128-CBC 加密**，确保存储在数据库中的敏感数据安全。加密密钥通过环境变量配置，支持密钥轮换机制。 | 加密特性 | 说明 | |---------|------| | 算法 | AES-128-CBC | | 密钥管理 | 环境变量配置 | | 加密范围 | 敏感字段（可选配置） | ### 6.2 GDPR 合规工具 系统内置 8 个 GDPR 相关工具，支持： - 完整数据删除（Right to Erasure） - 数据导出（Data Portability） - 数据匿名化处理 - 同意管理 ### 6.3 测试覆盖 项目包含 **1,134 个单元测试**，确保 100% ASCII 安全性，无 Unicode 编码问题。资料来源：[社区上下文 - v1.0.0 发布说明]() ## 7. 仪表盘与可视化 ### 7.1 Next.js 仪表盘组件 `dashboard/nextjs-dashboard` 提供了现代化的 Web 界面，包含以下核心页面： | 页面 | 功能 | |------|------| | `/dashboard` | 主要仪表盘视图 | | `/memories` | 记忆列表浏览 | | `/memories/[id]` | 记忆详情查看 | | `/sessions` | 会话时间线 | | `/search` | 搜索界面 | | `/analytics` | 分析统计 | | `/developer` | 开发者工具（开发中） | ### 7.2 实时更新 仪表盘通过 Server-Sent Events（SSE）实现实时更新，支持的事件类型包括： | 事件 | 触发时机 | |------|---------| | `memory_added` | 新记忆创建 | | `memory_updated` | 记忆修改 | | `session_started` | 会话开始 | | `session_ended` | 会话完成 | | `stats_updated` | 统计数据变更 | 资料来源：[dashboard/README.md:1-60]() ## 8. 技术栈概览 ### 8.1 核心依赖 | 组件 | 技术选型 | 用途 | |------|---------|------| | 向量数据库 | Qdrant | 语义搜索、向量存储 | | 图数据库 | Neo4j | 知识图谱、关系存储 | | 关系数据库 | PostgreSQL | 结构化数据、事务处理 | | 缓存层 | Redis | 高速缓存、会话管理 | | LLM 接口 | OpenAI/Claude | 摘要生成、实体提取 | ### 8.2 开发技术栈 **前端：** - Next.js 14（App Router） - TypeScript 5 - Tailwind CSS 4.x - TanStack Query v5 - Radix UI - Zustand **后端：** - FastAPI - Pydantic - APScheduler 资料来源：[dashboard/nextjs-dashboard/README.md:1-40]() ## 9. 快速开始示例 ### 9.1 Python SDK 使用 ```python import cognee # 添加数据 await cognee.add(["document.pdf", "notes.txt"]) # 执行完整管道 await cognee.cognify() # 语义搜索 results = await cognee.search( query_text="关键概念", query_type="hybrid_search" ) ``` ### 9.2 Node.js 客户端 ```typescript import { EnhancedCogneeClient } from "@enhanced-cognee/client"; const client = new EnhancedCogneeClient({ baseUrl: "http://localhost:8000", apiKey: process.env.ENHANCED_API_KEY }); // 添加记忆 await client.addMemory({ content: "重要信息", agentId: "agent-1", memoryCategory: "task" }); // 搜索记忆 const results = await client.searchMemory("相关信息"); ``` 资料来源：[clients/node/README.md:1-30]() ## 10. 版本与上游同步 ### 10.1 当前版本状态 | 项目 | 版本 | |------|------| | Enhanced-Cognee 本地版本 | v1.0.9 | | 上游最新版本 | v1.1.2 | | 差异 | 新增 18 个任务，173 个文件变更 | ### 10.2 同步机制 项目通过自动化工作流检测上游更新，生成变更差异报告并创建同步任务。开发团队可下载 `upstream-diff-v1.1.2` artifact 并参考 `.upstream-sync/PORTING_TODO.md` 进行版本同步。 资料来源：[社区上下文 - Issue #67]() ## 11. 常见问题与限制 ### 11.1 当前限制 | 限制项 | 说明 | 计划版本 | |--------|------|---------| | 速率限制 | 尚未实现 | v1.2.0 | | 时间线可视化 | Phase 2 特性 | 规划中 | | 图谱可视化 | 依赖 Neo4j | 规划中 | | 高级搜索过滤 | 尚未完全实现 | 持续开发 | ### 11.2 已完成功能 | 功能 | 状态 | 文档位置 | |------|------|---------| | 基础记忆 CRUD | ✅ 已完成 | API 端点文档 | | 向量搜索 | ✅ 已完成 | 搜索模块 | | 知识图谱 | ✅ 已完成 | Neo4j 集成 | | 加密存储 | ✅ 已完成 | 安全配置 | | SSE 实时更新 | ✅ 已完成 | 仪表盘文档 | --- **最后更新：** 2026-02-06 **维护团队：** Enhanced Cognee Team **相关版本：** v1.0.0（119 MCP 工具） --- ## 功能对比与选型指南 ### 相关页面 相关主题：[核心功能亮点](#feature-highlights), [项目介绍与快速开始](#project-introduction)
相关源码文件 以下源码文件用于生成本页说明： - [cognee/tasks/summarization/README.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/cognee/tasks/summarization/README.md) - [cognee/tasks/codingagents/README.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/cognee/tasks/codingagents/README.md) - [cognee-starter-kit/README.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/cognee-starter-kit/README.md) - [dashboard/nextjs-dashboard/README.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/dashboard/nextjs-dashboard/README.md) - [dashboard/nextjs-dashboard/src/components/organisms/AddMemoryModal.tsx](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/dashboard/nextjs-dashboard/src/components/organisms/AddMemoryModal.tsx) - [dashboard/nextjs-dashboard/src/components/organisms/EditMemoryModal.tsx](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/dashboard/nextjs-dashboard/src/components/organisms/EditMemoryModal.tsx)
# 功能对比与选型指南 ## 概述 Enhanced Cognee 是一个生产级的知识图谱记忆层，专为 Claude Code 设计，构建在 PostgreSQL、Qdrant、Neo4j 和 Redis 之上。该项目提供 119 个 MCP 工具，涵盖记忆管理、知识图谱、搜索、加密、GDPR合规、Webhooks、通知等功能模块。 本文档旨在帮助用户理解 Enhanced Cognee 的核心功能组件、与其他类似方案的对比，以及如何根据实际需求选择最适合的方案。 ## 核心功能模块对比 ### 1. 知识处理流水线模块 Enhanced Cognee 提供了两大核心处理流水线，分别针对不同的使用场景： #### summarization 模块（文本摘要） `cognee/tasks/summarization/README.md` 定义了文本和代码摘要功能，该模块在 `cognee.cognify()` 中自动运行（任务 #4）。用户通常不需要直接调用这些函数，除非构建自定义工作流。 | 功能 | 说明 | 数据模型 | |------|------|----------| | `summarize_text()` | 使用 LLM 总结文档块，返回 `list[TextSummary]` | `TextSummary` | | `summarize_code()` | 从代码文件提取结构化摘要，生成 `DataPoint` 和 `CodeSummary` 对象 | `CodeSummary` | ```python # 自动模式（推荐） import cognee await cognee.add(["document.pdf", "notes.txt"]) await cognee.cognify() # summarize_text 自动运行 ``` #### codingagents 模块（编码规则提取） `cognee/tasks/codingagents/README.md` 提供了开发者编码规则和最佳实践的提取功能。该模块在 `cognee.memify()` 流程中自动运行，但在标准 `cognify()` 流程中**默认不启用**。 | 功能 | 说明 | |------|------| | `add_rule_associations()` | 通过 LLM 从数据中提取规则，添加到图谱并创建源链接 | | `get_existing_rules()` | 从图谱中检索指定节点集的现有规则 | | `get_origin_edges()` | 查找匹配的原始 DocumentChunk 并创建 rule_associated_from 边 | ### 2. 存储方案对比 Enhanced Cognee 支持多种存储后端，每种方案适用于不同的场景： | 存储类型 | 技术栈 | 适用场景 | 优势 | 局限 | |----------|--------|----------|------|------| | **图数据库** | Neo4j | 实体关系分析、因果推理 | 复杂关系查询、路径分析 | 写入性能相对较低 | | **向量数据库** | Qdrant | 语义搜索、相似度匹配 | 高维向量检索、过滤查询 | 不擅长关系遍历 | | **关系数据库** | PostgreSQL | 结构化数据、事务处理 | ACID 保障、SQL 生态 | 复杂关系查询不如图数据库 | | **缓存层** | Redis | 临时数据、会话状态 | 超低延迟、丰富数据结构 | 数据持久化需额外配置 | ### 3. 加密与安全功能 Enhanced Cognee v1.0.0 提供了静态数据加密功能： - **加密算法**：Fernet AES-128-CBC - **密钥管理**：支持自定义密钥配置 - **适用范围**：存储在数据库中的敏感数据 ## Dashboard 功能对比 ### 当前已实现功能 | 页面/组件 | 功能 | 状态 | |-----------|------|------| | 仪表盘主页 | KPI 卡片、活动热力图、会话概览 | ✅ 已实现 | | 记忆管理 | 记忆列表、详情查看、添加/编辑模态框 | ✅ 已实现 | | 会话时间线 | 按时间分组展示记忆、展开/折叠交互 | ✅ 已实现 | | 搜索页面 | 语义搜索和关键词搜索界面 | 🔄 占位符 | | 分析页面 | 数据可视化、分析图表 | 🔄 占位符 | | 智能体管理 | AI 智能体监控和管理 | 🔄 占位符 | | 开发者工具 | 高级调试工具 | 🔄 占位符 | | 设置页面 | 系统配置 | 🔄 占位符 | ### 记忆数据结构对比 根据 `AddMemoryModal.tsx` 和 `EditMemoryModal.tsx` 的实现，Enhanced Cognee 支持以下记忆字段： | 字段 | 类型 | 说明 | 可选 | |------|------|------|------| | `content` | Textarea | 记忆内容 | 必填 | | `memory_type` | Select | 记忆类型（下拉选择） | 可选 | | `memory_concept` | Input | 记忆概念/主题 | 可选 | | `files` | Input | 关联文件路径（逗号分隔） | 可选 | | `facts` | Textarea | 关键事实（每行一条） | 可选 | | `before_state` | Textarea | 操作前状态 | 可选 | | `after_state` | Textarea | 操作后状态 | 可选 | | `summary` | Textarea | 记忆摘要 | 可选 | ### 组件架构对比 | 组件层级 | 组件 | 职责 | |----------|------|------| | **原子组件** | Button, Input, Badge, Card, Skeleton, Spinner, Textarea | 基础 UI 元素 | | **分子组件** | KPICard, ActivityHeatmap | 组合基础元素形成业务组件 | | **有机组件** | TimelineDetail, SessionTimeline, AddMemoryModal, EditMemoryModal, VisualizationSettings | 完整业务功能模块 | | **布局组件** | Header, Sidebar | 应用结构导航 | ## 选型决策树 ```mermaid graph TD A[开始选择方案] --> B{主要需求是什么?} B --> C[语义搜索与相似度匹配] B --> D[实体关系分析与推理] B --> E[结构化数据存储] B --> F[快速缓存与会话管理] C --> G[使用 Qdrant] D --> H[使用 Neo4j] E --> I[使用 PostgreSQL] F --> J[使用 Redis] G --> K{是否需要关系遍历?} H --> K I --> K J --> K K -->|是| L[组合使用 Neo4j] K -->|否| M[组合使用 PostgreSQL] L --> N{是否需要全文搜索?} M --> N N -->|是| O[添加 Qdrant] N -->|否| P[完成配置] O --> P ``` ## 技术栈对比矩阵 ### 前端技术选型 | 类别 | 技术 | 版本 | 用途 | |------|------|------|------| | 框架 | Next.js | 14+ | React 全栈框架 | | 语言 | TypeScript | 5.x | 类型安全开发 | | 样式 | Tailwind CSS | 4.x | 原子化 CSS | | 服务器状态 | TanStack Query | v5 | API 数据缓存 | | 客户端状态 | Zustand | - | 轻量状态管理 | | UI 组件库 | Radix UI | - | 无障碍组件 | | 图标 | Lucide React | - | 图标库 | | 表单 | React Hook Form + Zod | - | 表单验证 | | 可视化 | Recharts | - | 图表组件 | | 测试 | Vitest + Testing Library | - | 单元/集成测试 | ### 后端技术选型 | 类别 | 技术 | 用途 | |------|------|------| | API 框架 | FastAPI | RESTful API | | 图数据库 | Neo4j | 知识图谱存储 | | 向量数据库 | Qdrant | 语义搜索 | | 关系数据库 | PostgreSQL | 结构化数据 | | 缓存 | Redis | 会话与热点数据 | | LLM 集成 | 多种 Provider | 模型调用 | ## 场景化选型建议 ### 场景一：企业知识库构建 **推荐配置**：Qdrant + PostgreSQL + Neo4j **理由**：企业知识库需要支持语义搜索（Qdrant）来快速找到相关内容，同时需要知识图谱（Neo4j）来展示实体间的复杂关系，结构化数据（PostgreSQL）用于存储元数据和配置信息。 **启用模块**：`summarization`（自动）、`codingagents`（可选） ### 场景二：代码理解与重构助手 **推荐配置**：Neo4j + Qdrant + Redis **理由**：代码分析需要理解代码之间的依赖关系（Neo4j），通过语义搜索快速定位相关代码片段（Qdrant），使用 Redis 缓存会话状态提升响应速度。 **启用模块**：`summarization`（代码摘要）、`codingagents`（编码规则提取） ### 场景三：会话记忆与上下文管理 **推荐配置**：PostgreSQL + Redis + Qdrant **理由**：会话数据需要持久化存储（PostgreSQL），热点数据需要快速访问（Redis），历史会话内容需要语义检索能力（Qdrant）。 **启用模块**：Dashboard 记忆管理功能 ## 版本与上游同步说明 根据社区 Issue #67，Enhanced Cognee 定期同步上游 cognee 项目的更新： | 版本 | 状态 | 说明 | |------|------|------| | v1.0.0 | 当前发布版本 | 119 个 MCP 工具，1134 个单元测试 | | v1.0.9 | 本地基线 | 同步起点 | | v1.1.2 | 上游最新 | 18 个新任务，173 个变更文件 | 同步流程： 1. 下载上游差异工件 2. 审查 `.upstream-sync/PORTING_TODO.md` 3. 合并变更到本地分支 4. 运行完整测试套件 ## 快速开始方案对比 ### 标准方案（cognee-starter-kit） 适用于快速原型验证和简单场景： ```bash # 安装依赖 uv sync source .venv/bin/activate # 配置环境变量 # LLM_PROVIDER, LLM_MODEL, LLM_API_KEY 等 # 运行默认流水线 python src/pipelines/default.py ``` ### 高级方案（完整安装） 适用于生产环境： ```bash # 1. 安装 PostgreSQL, Neo4j, Qdrant, Redis # 2. 安装 Enhanced Cognee pip install enhanced-cognee # 3. 配置数据库连接 export COGNEE_STORAGE_PROVIDER=postgres export COGNEE_VECTOR_PROVIDER=qdrant export COGNEE_GRAPH_PROVIDER=neo4j export COGNEE_CACHE_PROVIDER=redis # 4. 运行应用 await cognee.cognify() ``` ## 总结与建议 | 用户类型 | 推荐方案 | 理由 | |----------|----------|------| | **初次尝试** | cognee-starter-kit + 默认流水线 | 零配置快速上手 | | **企业用户** | 完整安装 + PostgreSQL + Neo4j + Qdrant | 全功能支持，满足合规要求 | | **开发者** | 完整安装 + Dashboard | 自定义开发，调试方便 | | **资源受限环境** | PostgreSQL 单一存储 | 最低硬件需求 | 选择合适的存储后端组合需要考虑： - 数据规模与查询复杂度 - 实时性要求 - 预算与运维能力 - 合规与安全需求 --- ## 系统架构总览 ### 相关页面 相关主题：[数据库适配器与存储层](#database-stack)
相关源码文件 以下源码文件用于生成本页说明： - [docs/architecture/ENHANCED_COGNEE_GUIDE.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/docs/architecture/ENHANCED_COGNEE_GUIDE.md) - [docs/architecture/IMPLEMENTATION_GUIDE.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/docs/architecture/IMPLEMENTATION_GUIDE.md) - [config/docker/docker-compose-enhanced-cognee.yml](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/config/docker/docker-compose-enhanced-cognee.yml) - [src/db_factory.py](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/src/db_factory.py) - [cognee/base_config.py](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/cognee/base_config.py)
# 系统架构总览 ## 概述 Enhanced Cognee 是一个生产级的知识图谱记忆层，专为 Claude Code 设计，基于 PostgreSQL、Qdrant、Neo4j 和 Redis 构建。该项目通过 119 个 MCP 工具提供内存管理、知识图谱构建、搜索、加密、GDPR 合规、Webhooks 和通知等核心功能。 **核心特性：** - 1,134 个单元测试通过（100% ASCII 安全，无 Unicode 编码问题） - Fernet AES-128-CBC 静态加密 - 支持多租户和 API 密钥认证 - 前后端分离架构，提供 RESTful API 和实时 SSE 更新 资料来源：[社区发布信息](https://github.com/vincentspereira/Enhanced-Cognee/releases/tag/enhanced-v1.0.0) --- ## 整体架构 Enhanced Cognee 采用分层架构设计，从底向上包括数据持久层、核心处理层、API 层、工具层和应用层。 ```mermaid graph TB subgraph 应用层["应用层"] DASH[Next.js Dashboard] NODE[Node.js 客户端] CLI[MCP 工具集] end subgraph API层["API 层 (FastAPI)"] REST[RESTful API] SSE[Server-Sent Events] WS[WebSocket] end subgraph 核心层["核心处理层 (cognee)"] PIPELINE[Pipeline Orchestration] TASKS[Tasks Module] LLM[LLM Prompts] end subgraph 数据层["数据层"] PG[(PostgreSQL)] QDR[(Qdrant)] NEO[(Neo4j)] RED[(Redis)] end DASH --> REST NODE --> REST CLI --> REST REST --> SSE REST --> PIPELINE PIPELINE --> TASKS TASKS --> LLM PIPELINE --> PG PIPELINE --> QDR PIPELINE --> NEO PIPELINE --> RED ``` --- ## 技术栈详解 ### 数据持久层 Enhanced Cognee 采用多数据库混合架构，每种存储服务承担特定职责： | 存储服务 | 用途 | 数据类型 | |----------|------|----------| | **PostgreSQL** | 关系型数据存储 | 用户数据、会话记录、元数据 | | **Qdrant** | 向量数据库 | 语义搜索、嵌入向量、相似度匹配 | | **Neo4j** | 图数据库 | 知识图谱、实体关系、图遍历 | | **Redis** | 缓存与消息队列 | 临时缓存、会话状态、发布/订阅 | 资料来源：[docker-compose-enhanced-cognee.yml](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/config/docker/docker-compose-enhanced-cognee.yml) ### 核心处理层 核心处理层位于 `cognee/` 目录下，包含以下核心模块： ```python cognee/ ├── tasks/ # 任务模块 │ ├── summarization/ # 文本摘要生成 │ ├── codingagents/ # 代码规则关联 │ └── ... ├── base_config.py # 基础配置 └── __init__.py ``` **核心处理流程（Pipeline）：** ```mermaid graph LR A[数据摄入] --> B[分块处理] B --> C[图谱提取] C --> D[摘要生成] D --> E[存储/索引] A1[添加数据] --> COG[cognee.add] COG --> COGF[cognee.cognify] ``` 资料来源：[cognee/tasks/summarization/README.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/cognee/tasks/summarization/README.md) ### API 层 API 层基于 FastAPI 构建，提供以下核心接口： | 接口类型 | 端点 | 描述 | |----------|------|------| | 内存管理 | `POST /memory/add` | 添加记忆条目 | | 内存搜索 | `POST /memory/search` | 向量+文本混合搜索 | | 知识图谱 | `POST /knowledge/add_relation` | 添加图关系边 | | 统计信息 | `GET /stats` | 记忆存储统计 | | 健康检查 | `GET /health` | 技术栈健康状态 | API 支持 JWT 认证和多租户路由，通过 `X-API-Key` 和 `X-Tenant-ID` 头部实现安全隔离。 资料来源：[clients/node/README.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/clients/node/README.md) --- ## 配置系统 ### 基础配置 配置系统通过 `base_config.py` 和环境变量管理： ```python # 核心配置项 LLM_PROVIDER="" # LLM 提供商 LLM_MODEL="" # 模型名称 LLM_API_KEY="" # API 密钥 EMBEDDING_PROVIDER="" # 嵌入提供商 ``` ### 数据库工厂模式 项目使用工厂模式 (`db_factory.py`) 统一管理数据库连接，支持动态切换不同的数据库实现： ```python # 数据库工厂支持的数据库类型 - PostgreSQL (关系型数据) - Qdrant (向量存储) - Neo4j (图数据库) - Redis (缓存) ``` 资料来源：[src/db_factory.py](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/src/db_factory.py) --- ## 前端架构 ### Next.js Dashboard Dashboard 采用现代前端技术栈构建： ```mermaid graph TD subgraph 前端技术 NX[Next.js 14] TS[TypeScript 5] TW[Tailwind CSS 4] RT[TanStack Query] ZST[Zustand] end subgraph UI组件库 RD[Radix UI] LC[Lucide React] RC[Recharts] end subgraph 状态管理 SERVER[服务器状态
TanStack Query] CLIENT[客户端状态
Zustand] end ``` **核心功能模块：** | 模块 | 路由 | 功能 | |------|------|------| | 仪表板 | `/dashboard` | 总览统计 | | 记忆列表 | `/memories` | 记忆浏览 | | 记忆详情 | `/memories/[id]` | 单条记忆详情 | | 搜索 | `/search` | 全文/向量搜索 | | 会话管理 | `/sessions` | 会话时间线 | | 开发者工具 | `/developer` | 高级调试功能 | Dashboard 通过 SSE 实现实时更新，支持以下事件类型： - `memory_added` - 新记忆创建 - `memory_updated` - 记忆修改 - `session_started` - 会话开始 - `session_ended` - 会话结束 - `stats_updated` - 统计数据变更 资料来源：[dashboard/README.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/dashboard/README.md) --- ## 客户端架构 ### Node.js 客户端 Node.js 客户端 (`clients/node/`) 提供类型安全的 API 封装： ```typescript import { EnhancedCogneeClient } from "@enhanced-cognee/client"; // 初始化客户端 const client = new EnhancedCogneeClient({ baseUrl: "http://localhost:8000", apiKey: process.env.ENHANCED_API_KEY, tenantId: process.env.ENHANCED_TENANT_ID }); ``` **自动转换规则：** - 输入参数使用 camelCase（TypeScript 惯例） - 内部自动转换为 snake_case（API 惯例） - 所有方法返回类型安全的响应对象 --- ## MCP 工具集 Enhanced Cognee 提供 119 个 MCP 工具，涵盖以下领域： | 类别 | 工具数量 | 主要功能 | |------|----------|----------| | 内存管理 | 20+ | 增删改查操作 | | 知识图谱 | 25+ | 实体和关系操作 | | 搜索 | 15+ | 向量和语义搜索 | | 加密 | 10+ | 数据加密/解密 | | GDPR | 10+ | 数据脱敏和删除 | | Webhooks | 15+ | 事件通知 | | 通知 | 10+ | 实时推送 | 资料来源：[社区发布信息](https://github.com/vincentspereira/Enhanced-Cognee/releases/tag/enhanced-v1.0.0) --- ## 数据流与处理 ### 典型数据处理流程 ```mermaid sequenceDiagram participant U as 用户/客户端 participant API as FastAPI participant P as Pipeline participant LLM as LLM服务 participant DB as 数据库层 U->>API: cognee.add(data) API->>P: 启动管道 P->>P: 分块处理 P->>LLM: 图谱提取请求 LLM-->>P: 实体和关系 P->>LLM: 摘要生成请求 LLM-->>P: 结构化摘要 P->>DB: 存储数据 DB-->>P: 确认 P-->>API: 处理完成 API-->>U: 返回结果 Note over U,DB: cognee.cognify() 端到端流程 ``` ### LLM Prompt 模板 项目使用结构化的 Prompt 模板系统： | 模板名称 | 用途 | |----------|------| | `summarization.txt` | 文本摘要生成 | | `coding_rules.txt` | 代码规则提取 | | `entity_extraction.txt` | 实体识别 | | `relation_extraction.txt` | 关系抽取 | --- ## 测试架构 项目包含完整的测试体系： | 测试类型 | 覆盖目标 | 工具 | |----------|----------|------| | 单元测试 | 1134 个测试 | pytest | | UAT 测试 | 业务场景 | pytest | | 性能测试 | 负载和压力 | Locust | | 安全测试 | 渗透测试 | 自定义框架 | | 集成测试 | API 契约 | pytest | 资料来源：[testing/README.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/testing/README.md) --- ## 部署架构 ### Docker Compose 部署 项目提供完整的 Docker Compose 配置： ```yaml services: api: # FastAPI 应用服务 postgres: # PostgreSQL 数据库 qdrant: # 向量数据库 neo4j: # 图数据库 redis: # 缓存服务 dashboard: # Next.js 前端 ``` 服务间通过内部网络通信，CORS 配置允许 `http://localhost:3000` 和 `http://127.0.0.1:3000` 访问 API。 资料来源：[docker-compose-enhanced-cognee.yml](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/config/docker/docker-compose-enhanced-cognee.yml) --- ## 安全性 ### 认证机制 | 机制 | 实现方式 | 用途 | |------|----------|------| | API 密钥 | `X-API-Key` 头部 | MCP 服务器认证 | | JWT | Bearer Token | 用户认证 | | 多租户 | `X-Tenant-ID` 头部 | 租户隔离 | ### 数据安全 - Fernet AES-128-CBC 静态加密 - 数据脱敏支持 GDPR 合规 - 安全的密钥轮换机制 --- ## 上游同步 项目定期与上游 cognee 仓库同步，当前状态： | 版本信息 | 值 | |----------|------| | 本地基准 | v1.0.9 | | 上游最新 | v1.1.2 | | 变更文件 | 173 个 | | 新增任务 | 18 个 | 资料来源：[Issue #67 - Upstream sync](https://github.com/vincentspereira/Enhanced-Cognee/issues/67) --- ## 数据库适配器与存储层 ### 相关页面 相关主题：[系统架构总览](#architecture-overview)
相关源码文件 以下源码文件用于生成本页说明： - [src/db_adapters](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/src/db_adapters) - [cognee/infrastructure/databases](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/cognee/infrastructure/databases) - [docs/PLUGGABLE_DB_BACKENDS.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/docs/PLUGGABLE_DB_BACKENDS.md) - [docs/PROFILES.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/docs/PROFILES.md) - [docs/ARCADEDB_MIGRATION.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/docs/ARCADEDB_MIGRATION.md)
# 数据库适配器与存储层 ## 概述 Enhanced Cognee 的数据库适配器与存储层是整个系统的核心基础设施，负责管理不同类型数据存储系统的接入、查询和操作。该模块实现了多后端支持的设计理念，允许用户根据性能、成本和功能需求灵活选择和切换不同的数据库技术栈。 Enhanced Cognee 构建于四大存储技术之上：PostgreSQL、Qdrant、Neo4j 和 Redis。这种多模态架构使得系统能够同时处理结构化数据、向量嵌入、图关系和缓存，满足知识图谱内存层的多样化需求。 ## 架构设计 ### 多层架构 Enhanced Cognee 的存储层采用分层架构设计，从上到下依次为： ``` ┌─────────────────────────────────────────────────────────┐ │ 应用层 (Application Layer) │ │ cognee.add() / cognee.cognify() │ ├─────────────────────────────────────────────────────────┤ │ 抽象接口层 (Abstract Interface) │ │ DataPoint / StorageAdapter │ ├─────────────────────────────────────────────────────────┤ │ 数据库适配器层 (DB Adapters) │ │ PostgreSQL │ Qdrant │ Neo4j │ Redis │ ArangoDB │ ├─────────────────────────────────────────────────────────┤ │ 连接管理层 (Connection Management) │ │ Pooling / Session / Transaction │ └─────────────────────────────────────────────────────────┘ ``` 这种分层设计确保了上层业务逻辑与底层存储技术之间的松耦合，使得添加新的数据库后端成为可能，同时不影响现有功能。 ### 适配器模式 系统采用适配器模式（Adapter Pattern）实现存储层抽象。每个数据库后端都通过统一的接口暴露功能，适配器内部负责将统一调用转换为特定数据库的查询语言和操作方式。资料来源：[src/db_adapters](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/src/db_adapters) ## 支持的数据库后端 ### 向量数据库 | 后端 | 用途 | 特点 | |------|------|------| | Qdrant | 向量相似度搜索 | 高性能向量索引，支持过滤查询 | | Weaviate | 向量搜索（备选） | 混合搜索能力 | | Pgvector | PostgreSQL扩展 | 与关系型数据统一管理 | ### 图数据库 | 后端 | 用途 | 特点 | |------|------|------| | Neo4j | 图关系存储 | 原生图遍历，Cypher查询语言 | | ArangoDB | 多模态图存储 | 文档与图混合支持 | ### 关系数据库 | 后端 | 用途 | 特点 | |------|------|------| | PostgreSQL | 主数据存储 | ACID事务，复杂查询能力 | ### 键值与缓存 | 后端 | 用途 | 特点 | |------|------|------| | Redis | 缓存与会话 | 内存存储，极低延迟 | 资料来源：[docs/PLUGGABLE_DB_BACKENDS.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/docs/PLUGGABLE_DB_BACKENDS.md) ## 存储配置与配置文件 ### 配置文件结构 系统通过 YAML 配置文件管理数据库连接参数。典型的配置结构包括数据库类型、连接参数、连接池设置和可选的加密设置。 ```yaml # 存储配置示例 storage: vector_db: type: "qdrant" host: "localhost" port: 6333 collection: "embeddings" graph_db: type: "neo4j" uri: "bolt://localhost:7687" username: "neo4j" password: "${NEO4J_PASSWORD}" relational_db: type: "postgresql" host: "localhost" port: 5432 database: "cognee" pool_size: 10 cache: type: "redis" host: "localhost" port: 6379 ``` 资料来源：[docs/PROFILES.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/docs/PROFILES.md) ### 环境变量覆盖 配置支持通过环境变量覆盖敏感信息，如数据库密码和 API 密钥。这种设计确保了敏感信息不会硬编码在配置文件中，遵循了安全最佳实践。 ### ArangoDB 迁移指南 对于从其他图数据库迁移到 ArangoDB 的用户，系统提供了完整的迁移文档。迁移过程包括数据导出、模式转换和导入三个主要阶段。资料来源：[docs/ARCADEDB_MIGRATION.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/docs/ARCADEDB_MIGRATION.md) ## 核心组件 ### Infrastructure 模块 ```python cognee/ infrastructure/ databases/ __init__.py # 数据库初始化 connector.py # 连接管理 executor.py # 查询执行器 ``` `cognee.infrastructure.databases` 模块是存储层的核心实现位置。该模块提供了统一的数据库连接接口、查询执行器和事务管理功能。每个数据库类型都有对应的连接器实现，负责处理特定数据库的连接细节。 资料来源：[cognee/infrastructure/databases](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/cognee/infrastructure/databases) ### 数据点模型 系统使用统一的 `DataPoint` 数据模型来表示各种存储实体。这个抽象基类定义了所有存储对象必须遵循的接口，包括标识符、元数据和序列化方法。 | 模型类 | 描述 | 主要字段 | |--------|------|----------| | DataPoint | 基类 | id, metadata, created_at | | DocumentChunk | 文档分块 | text, source, position | | TextSummary | 文本摘要 | text, made_from | | CodeSummary | 代码摘要 | text, summarizes | | Rule | 编码规则 | text, belongs_to_set | ### 存储适配器接口 每个数据库适配器都需要实现一组标准接口方法： | 方法 | 描述 | |------|------| | connect() | 建立数据库连接 | | disconnect() | 关闭连接 | | save(data_point) | 存储数据点 | | query(query_string) | 执行查询 | | search(vector, limit) | 向量搜索 | | transaction(callback) | 事务包装 | ## 工作流程 ### 数据写入流程 ``` 用户调用 cognee.add() │ ▼ ┌─────────────────┐ │ 数据分块 (Chunking) │ └────────┬────────┘ │ ▼ ┌─────────────────────────┐ │ 图谱提取 (Graph Extraction) │ └────────┬────────────────┘ │ ▼ ┌─────────────────────────┐ │ 摘要生成 (Summarization) │ ← cognee/tasks/summarization └────────┬────────────────┘ │ ▼ ┌─────────────────────────┐ │ 多存储分发 (Storage Dispatch) │ └────────┬────────────────┘ │ ┌────┴────┬─────────┬────────┐ ▼ ▼ ▼ ▼ PostgreSQL Qdrant Neo4j Redis ``` ### 数据读取流程 ``` 用户调用 cognee.search() │ ▼ ┌─────────────────────────┐ │ 查询解析 (Query Parsing) │ └────────┬────────────────┘ │ ┌────┴────┬─────────┐ ▼ ▼ ▼ Vector Keyword Graph Search Search Traverse │ │ │ └────┬────┴────┬────┘ ▼ ┌─────────────────────────┐ │ 结果聚合 (Result Merge) │ └────────┬────────────────┘ │ ▼ ┌─────────────────────────┐ │ 排序与过滤 (Rank & Filter) │ └────────┬────────────────┘ │ ▼ 返回搜索结果 ``` ## 数据库连接管理 ### 连接池 系统为每个数据库后端维护连接池，以优化资源使用和响应时间。连接池配置包括最小连接数、最大连接数、空闲超时和获取超时等参数。 ```python # 连接池配置参数 pool_config = { "min_connections": 2, "max_connections": 20, "idle_timeout": 300, # 秒 "acquire_timeout": 30, # 秒 "retry_attempts": 3 } ``` ### 健康检查 存储层实现了健康检查机制，定期验证与各数据库的连接状态。当检测到连接问题时，系统会自动尝试重新连接，并在故障转移场景下切换到备用节点。 ## 安全特性 ### 传输加密 数据库连接支持 TLS 加密，确保数据在传输过程中的安全性。配置中可指定 SSL 证书路径和验证模式。 ### 静态加密 系统支持对存储在数据库中的敏感数据进行 AES-128-CBC (Fernet) 加密。这对于处理 GDPR 相关数据或需要额外安全层的场景尤为重要。 ### 访问控制 通过 API 密钥和租户标识实现细粒度的访问控制。`X-API-Key` 和 `X-Tenant-ID` 头部用于认证和授权。资料来源：[clients/node/README.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/clients/node/README.md) ## 性能优化 ### 查询优化策略 | 策略 | 适用场景 | 实现方式 | |------|----------|----------| | 批量写入 | 大数据量导入 | 聚合多个操作为单次请求 | | 缓存复用 | 频繁读取 | Redis 缓存热点数据 | | 索引优化 | 加速查询 | 数据库特定索引配置 | | 连接复用 | 高并发 | 连接池与持久连接 | ### 统计缓存 仪表板和 API 端点的统计数据会被缓存 30 秒，以减少数据库负载。资料来源：[dashboard/README.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/dashboard/README.md) ## 扩展与自定义 ### 添加新数据库后端 要添加新的数据库后端，需要完成以下步骤： 1. 在 `src/db_adapters/` 目录创建适配器模块 2. 实现 `StorageAdapter` 基类定义的所有接口 3. 添加对应的连接器和配置解析逻辑 4. 在适配器注册表中注册新后端 5. 编写单元测试并确保通过现有测试套件 ### 自定义查询语言 高级用户可以通过扩展查询执行器来支持特定的查询语法或 DSL，实现更复杂的业务逻辑需求。 ## 常见问题与排查 | 问题 | 可能原因 | 解决方案 | |------|----------|----------| | 连接超时 | 网络问题或连接池耗尽 | 检查防火墙，增加 `max_connections` | | 向量搜索无结果 | 嵌入维度不匹配 | 确认 embedding model 配置一致性 | | Neo4j 查询慢 | 缺少索引 | 创建必要的标签和属性索引 | | Redis 连接拒绝 | 服务未启动或端口错误 | 验证 Redis 服务状态和配置端口 | ## 相关资源 - [PLUGGABLE_DB_BACKENDS.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/docs/PLUGGABLE_DB_BACKENDS.md) - 可插拔数据库后端详细文档 - [PROFILES.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/docs/PROFILES.md) - 配置文件参考 - [ARCADEDB_MIGRATION.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/docs/ARCADEDB_MIGRATION.md) - 数据库迁移指南 - [Dashboard 文档](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/dashboard/README.md) - 仪表板与后端 API 集成说明 --- ## MCP工具参考手册 ### 相关页面 相关主题：[核心功能亮点](#feature-highlights), [内存管理与生命周期](#memory-management), [API接口参考](#api-reference)
相关源码文件 以下源码文件用于生成本页说明： - [bin/enhanced_cognee_mcp_server.py](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/bin/enhanced_cognee_mcp_server.py) - [src/enhanced_cognee_mcp.py](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/src/enhanced_cognee_mcp.py) - [docs/mcp/COGNEE_MCP_COMPLETE_GUIDE.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/docs/mcp/COGNEE_MCP_COMPLETE_GUIDE.md) - [.kilocode/mcp.json](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/.kilocode/mcp.json)
# MCP工具参考手册 ## 概述 Enhanced Cognee v1.0.0 提供了一套完整的 Model Context Protocol (MCP) 工具集，共包含 **119个MCP工具**，涵盖记忆管理、知识图谱构建、语义搜索、数据加密、GDPR合规、Webhooks通知等核心功能。这些工具专为 Claude Code 设计，构建在 PostgreSQL、Qdrant、Neo4j 和 Redis 之上，提供企业级的知识图谱记忆层服务。 MCP工具使大型语言模型能够通过标准化的协议与外部数据存储和工具进行交互，从而实现持久化记忆存储、复杂查询执行和实时数据同步等能力。所有工具均通过 1,134 个单元测试验证，确保100% ASCII安全性，无Unicode编码问题。 ## 系统架构 ### MCP工具在系统中的位置 ```mermaid graph TD A[Claude Code] -->|MCP Protocol| B[MCP Server] B --> C[Enhanced Cognee MCP Layer] C --> D[PostgreSQL] C --> E[Qdrant Vector DB] C --> F[Neo4j Graph DB] C --> G[Redis Cache] H[Memory Tools] --> C I[Knowledge Graph Tools] --> C J[Search Tools] --> C K[Encryption Tools] --> C L[GDPR Tools] --> C M[Webhook Tools] --> C N[Notification Tools] --> C ``` ### MCP服务器启动流程 ```mermaid sequenceDiagram participant User as 用户 participant Server as MCP Server participant Core as Enhanced Cognee Core participant DB as Data Stores User->>Server: 启动服务器 Server->>Core: 初始化配置 Core->>DB: 建立连接池 DB-->>Core: 连接就绪 Core-->>Server: 初始化完成 Server->>User: 119工具注册完成 ``` ## 工具分类总览 Enhanced Cognee MCP工具按功能划分为以下主要类别： | 类别 | 工具数量 | 主要功能 | |------|---------|---------| | 记忆管理 (Memory) | ~25 | 增删改查记忆、分类、标签 | | 知识图谱 (Knowledge Graph) | ~30 | 实体关系操作、图查询 | | 搜索 (Search) | ~15 | 语义搜索、关键词搜索 | | 加密 (Encryption) | ~10 | Fernet AES-128-CBC加密 | | GDPR合规 | ~12 | 数据删除、匿名化处理 | | Webhooks | ~8 | 事件通知、回调配置 | | 通知 (Notifications) | ~10 | 实时推送、状态通知 | | 其他工具 | ~9 | 系统配置、元数据管理 | ## 核心工具详解 ### 记忆管理工具 (Memory Tools) 记忆管理是Enhanced Cognee的核心功能之一，提供完整的记忆生命周期管理能力。 #### 添加记忆 | 参数 | 类型 | 必需 | 描述 | |------|------|------|------| | `content` | string | 是 | 记忆内容 | | `memory_type` | string | 否 | 记忆类型（fact、event、concept等） | | `memory_concept` | string | 否 | 记忆概念分类 | | `metadata` | object | 否 | 附加元数据 | | `session_id` | string | 否 | 关联会话ID | #### 搜索记忆 | 参数 | 类型 | 必需 | 描述 | |------|------|------|------| | `query` | string | 是 | 搜索查询文本 | | `query_type` | string | 是 | 搜索类型（semantic、keyword、hybrid） | | `limit` | integer | 否 | 返回结果数量限制 | | `filters` | object | 否 | 过滤条件 | #### 更新记忆 | 参数 | 类型 | 必需 | 描述 | |------|------|------|------| | `memory_id` | string | 是 | 记忆唯一标识符 | | `content` | string | 是 | 更新后的内容 | | `metadata` | object | 否 | 更新的元数据 | #### 删除记忆 | 参数 | 类型 | 必需 | 描述 | |------|------|------|------| | `memory_id` | string | 是 | 要删除的记忆ID | | `cascade` | boolean | 否 | 是否级联删除关联数据 | ### 知识图谱工具 (Knowledge Graph Tools) 知识图谱工具基于Neo4j实现，支持复杂的实体关系操作。 #### 创建实体 | 参数 | 类型 | 必需 | 描述 | |------|------|------|------| | `entity_type` | string | 是 | 实体类型 | | `properties` | object | 是 | 实体属性 | | `labels` | array | 否 | Neo4j标签列表 | #### 创建关系 | 参数 | 类型 | 必需 | 描述 | |------|------|------|------| | `source_id` | string | 是 | 源实体ID | | `target_id` | string | 是 | 目标实体ID | | `relationship_type` | string | 是 | 关系类型 | #### 图查询 支持Cypher查询语言，执行复杂的图遍历和分析操作。 ### 搜索工具 (Search Tools) #### 语义搜索 基于Qdrant向量数据库的语义搜索功能： ```python results = await cognee.search( query_text="用户查询内容", query_type="semantic", limit=10 ) ``` #### 搜索类型对照表 | 搜索类型 | 描述 | 适用场景 | |---------|------|---------| | `semantic` | 向量相似度搜索 | 语义理解查询 | | `keyword` | BM25关键词搜索 | 精确词汇匹配 | | `hybrid` | 混合搜索 | 综合查询需求 | ### 加密工具 (Encryption Tools) Enhanced Cognee使用Fernet AES-128-CBC算法实现静态数据加密。 #### 加密记忆 | 参数 | 类型 | 必需 | 描述 | |------|------|------|------| | `memory_id` | string | 是 | 要加密的记忆ID | | `key_id` | string | 否 | 加密密钥ID | #### 解密记忆 | 参数 | 类型 | 必需 | 描述 | |------|------|------|------| | `memory_id` | string | 是 | 要解密的记忆ID | ### GDPR合规工具 GDPR工具提供数据删除、匿名化和可携带性支持。 | 工具 | 功能 | |------|------| | `gdpr_delete_user_data` | 删除用户所有数据 | | `gdpr_anonymize` | 匿名化处理 | | `gdpr_export_data` | 导出用户数据 | | `gdpr_get_consent` | 获取同意记录 | ### Webhook工具 Webhooks支持事件驱动的通知机制： | 工具 | 功能 | |------|------| | `webhook_register` | 注册Webhook回调 | | `webhook_unregister` | 取消注册 | | `webhook_list` | 列出所有Webhook | | `webhook_test` | 测试Webhook连通性 | ### 通知工具 (Notification Tools) 支持多种通知渠道： | 渠道 | 描述 | |------|------| | `email` | 邮件通知 | | `sse` | Server-Sent Events实时推送 | | `webhook` | HTTP回调通知 | | `slack` | Slack集成通知 | ## MCP服务器配置 ### 启动参数 ```bash python bin/enhanced_cognee_mcp_server.py \ --host 0.0.0.0 \ --port 8000 \ --log-level info ``` ### 环境变量配置 | 变量名 | 描述 | 默认值 | |--------|------|--------| | `COGNEE_STORAGE_DIR` | 存储目录 | `./cognee_storage` | | `COGNEE_LLM_PROVIDER` | LLM提供商 | `openai` | | `COGNEE_EMBEDDING_PROVIDER` | 向量模型提供商 | `openai` | | `COGNEE_GRAPH_PROVIDER` | 图数据库类型 | `neo4j` | ### MCP配置文件 项目根目录的 `.kilocode/mcp.json` 定义了MCP服务器的标准配置： ```json { "mcp_server": { "name": "Enhanced Cognee", "version": "1.0.0", "protocol_version": "2024-11-05", "capabilities": ["memory", "knowledge_graph", "search", "encryption"] } } ``` ## 使用示例 ### 基础记忆操作流程 ```mermaid graph LR A[添加记忆] --> B[自动摘要] B --> C[存储到向量库] C --> D[构建知识图谱] D --> E[建立索引] E --> F[支持搜索查询] ``` ### Python SDK使用示例 ```python import cognee # 添加记忆 await cognee.add([ "document.pdf", "notes.txt", "data.json" ]) # 执行认知处理流程 await cognee.cognify() # 语义搜索 results = await cognee.search( query_text="关键概念总结", query_type="semantic", limit=5 ) # 加密敏感记忆 await cognee.encrypt_memory( memory_id="mem_xxx", key_id="key_production" ) ``` ### MCP协议直接调用示例 ```json { "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "memory_add", "arguments": { "content": "这是一个重要的记忆内容", "memory_type": "fact", "session_id": "session_123" } }, "id": 1 } ``` ## 工具开发指南 ### 添加新工具步骤 1. 在 `src/enhanced_cognee_mcp.py` 中定义工具函数 2. 在工具注册表中添加条目 3. 实现输入验证和错误处理 4. 添加单元测试 5. 更新文档和MCP清单 ### 工具注册结构 ```python TOOLS = { "category": "memory", "name": "memory_add", "description": "添加新记忆到系统", "parameters": { "type": "object", "properties": {...}, "required": ["content"] }, "handler": memory_add_handler } ``` ## 测试与验证 ### 单元测试覆盖 所有MCP工具均通过自动化测试验证： | 测试类型 | 测试数量 | 覆盖范围 | |---------|---------|---------| | 功能测试 | ~800 | 各工具核心功能 | | 集成测试 | ~200 | 跨组件交互 | | 安全测试 | ~100 | 加密和GDPR合规 | | 性能测试 | ~34 | 并发和负载 | ### 测试命令 ```bash # 运行所有测试 pytest tests/mcp/ -v # 运行特定工具测试 pytest tests/mcp/test_memory_tools.py -v # 运行安全相关测试 pytest tests/mcp/test_security.py -v ``` ## 已知限制与注意事项 ### 数据安全 - 加密密钥必须妥善保管，丢失将导致数据无法恢复 - GDPR删除操作不可逆，执行前需二次确认 - 建议定期备份数据库和加密密钥 ### 性能考量 - 大规模向量搜索建议限制结果数量 - 复杂图查询可能消耗较多Neo4j资源 - Redis缓存可有效降低数据库负载 ### 版本兼容性 项目持续与上游cognee保持同步，v1.1.2版本带来18个新任务和173个变更文件。建议定期检查更新以获取最新功能和安全修复。 ## 相关资源 - **发布说明**: [Enhanced Cognee v1.0.0 - 119 MCP Tools](https://github.com/vincentspereira/Enhanced-Cognee/releases/tag/enhanced-v1.0.0) - **上游同步状态**: [Issue #67 - Upstream sync: port v1.1.2 changes](https://github.com/vincentspereira/Enhanced-Cognee/issues/67) - **完整使用指南**: [docs/mcp/COGNEE_MCP_COMPLETE_GUIDE.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/docs/mcp/COGNEE_MCP_COMPLETE_GUIDE.md) --- ## 内存管理与生命周期 ### 相关页面 相关主题：[MCP工具参考手册](#mcp-tools-reference), [核心功能亮点](#feature-highlights)
相关源码文件 以下源码文件用于生成本页说明： - [cognee/tasks/summarization/README.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/cognee/tasks/summarization/README.md) - [cognee/tasks/codingagents/README.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/cognee/tasks/codingagents/README.md) - [dashboard/nextjs-dashboard/src/app/memories/[id]/page.tsx](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/dashboard/nextjs-dashboard/src/app/memories/[id]/page.tsx) - [dashboard/nextjs-dashboard/src/components/organisms/SessionTimeline.tsx](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/dashboard/nextjs-dashboard/src/components/organisms/SessionTimeline.tsx) - [clients/node/README.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/clients/node/README.md) - [dashboard/README.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/dashboard/README.md)
# 内存管理与生命周期 ## 概述 Enhanced Cognee 是一个面向 Claude Code 的生产级知识图谱记忆层，构建于 PostgreSQL、Qdrant、Neo4j 和 Redis 之上。该系统提供完整的内存管理与生命周期控制能力，支持从数据摄取到知识图谱构建的全流程自动化处理。 内存管理模块负责协调数据的摄取、转换、存储和检索，确保知识在系统中的完整性和可用性。整个生命周期涵盖了从原始数据输入到结构化知识输出的完整路径。 > [!NOTE] > 内存管理模块在 `cognee.cognify()` 流程中自动运行（任务 #4），用户通常无需直接调用相关函数，除非构建自定义工作流。 ## 核心架构 ### 技术栈概览 Enhanced Cognee 采用多后端混合存储架构： | 后端 | 用途 | 特点 | |------|------|------| | PostgreSQL | 结构化数据存储 | 事务支持，关系型查询 | | Qdrant | 向量相似度搜索 | 高维向量检索，支持元数据过滤 | | Neo4j | 知识图谱存储 | 图数据库，关系遍历优化 | | Redis | 缓存与实时数据 | 低延迟，内存存储 | 资料来源：[cognee/tasks/summarization/README.md]() ### 数据模型层次 系统中的内存数据分为多个抽象层次，每层承担不同的职责： ```mermaid graph TD A[原始数据 Input] --> B[数据分块 Data Chunks] B --> C[图谱节点 Graph Nodes] C --> D[摘要生成 Summaries] D --> E[存储层 Storage] E --> F[PostgreSQL 结构化数据] E --> G[Qdrant 向量索引] E --> H[Neo4j 知识图谱] E --> I[Redis 缓存] F --> J[检索与查询] G --> J H --> J I --> J ``` 资料来源：[dashboard/README.md]() ## 内存数据类型 ### 内存类型（Memory Types） 系统支持多种内存类型分类，便于细粒度管理和检索： | 类型 | 说明 | 典型用途 | |------|------|----------| | `text` | 文本内容 | 文档、笔记、对话 | | `code` | 代码片段 | 代码文件、函数实现 | | `knowledge` | 知识条目 | 实体、关系、规则 | | `summary` | 摘要信息 | 文档摘要、概念总结 | | `rule` | 规则定义 | 编码规则、业务逻辑 | 资料来源：[dashboard/nextjs-dashboard/src/components/organisms/EditMemoryModal.tsx]() ### 内存概念（Memory Concepts） 内存概念用于语义层面的组织： | 概念 | 描述 | |------|------| | `concept` | 核心概念定义 | | `fact` | 事实性陈述 | | `idea` | 想法和创新 | | `task` | 任务和待办事项 | | `reference` | 参考资料 | 资料来源：[dashboard/nextjs-dashboard/src/components/organisms/EditMemoryModal.tsx]() ## 生命周期阶段 ### 处理流水线 内存的完整生命周期经历以下阶段： ```mermaid graph LR A[数据摄取 add] --> B[分块处理 chunking] B --> C[图谱提取 graph extraction] C --> D[摘要生成 summarize_text] D --> E[存储索引 storage] E --> F[检索查询 search] ``` | 阶段 | 函数/模块 | 自动化 | 说明 | |------|-----------|--------|------| | 1. 摄取 | `cognee.add()` | ✅ | 接收原始数据 | | 2. 分块 | chunking | ✅ | 将大文档分割为小块 | | 3. 图谱提取 | graph extraction | ✅ | 提取实体和关系 | | 4. 摘要 | `summarize_text()` | ✅ | 生成文本摘要 | | 5. 存储 | storage | ✅ | 持久化到各后端 | 资料来源：[cognee/tasks/summarization/README.md]() ### 数据摘要模型 摘要阶段生成两种核心数据类型： #### TextSummary（文本摘要） 继承自 `DataPoint`，包含以下字段： | 字段 | 类型 | 说明 | |------|------|------| | `text` | `str` | 摘要文本内容 | | `made_from` | `DocumentChunk` | 来源文档块引用 | | `metadata` | `dict` | 元数据信息 | #### CodeSummary（代码摘要） | 字段 | 类型 | 说明 | |------|------|------| | `text` | `str` | 代码结构摘要 | | `summarizes` | `CodeFile/CodePart` | 源代码引用 | | `metadata` | `dict` | 元数据信息 | 资料来源：[cognee/tasks/summarization/README.md]() ### 编码规则生命周期 编码规则模块在 `cognee.memify()` 流程中运行，属于增强管道的一部分： ```mermaid graph TD A[数据摄取 ingestion] --> B[图谱提取 graph extraction] B --> C[编码规则关联 coding rule association] C --> D[存储 indexing] D --> E[检索 retrieval] ``` **核心函数：** | 函数 | 描述 | |------|------| | `add_rule_associations()` | 通过 LLM 提取规则并添加到图谱 | | `get_existing_rules()` | 从图谱中检索现有规则 | | `get_origin_edges()` | 创建规则到源文档的反向链接 | 资料来源：[cognee/tasks/codingagents/README.md]() #### Rule 数据模型 | 字段 | 类型 | 说明 | |------|------|------| | `text` | `str` | 编码规则文本内容 | | `belongs_to_set` | `NodeSet` | 父节点集引用（如 "coding_agent_rules"）| | `metadata` | `dict` | 索引配置 | 资料来源：[cognee/tasks/codingagents/README.md]() ## 客户端 API 接口 ### Node.js 客户端 Node.js 客户端提供了完整的内存操作接口： | 方法 | HTTP 端点 | 描述 | |------|-----------|------| | `addMemory(entry)` | `POST /memory/add` | 存储记忆条目 | | `searchMemory(query)` | `POST /memory/search` | 向量 + 文本搜索 | | `addKnowledgeRelation(relation)` | `POST /knowledge/add_relation` | 添加图谱边 | | `getStats()` | `GET /stats` | 记忆存储统计 | | `getHealth()` | `GET /health` | 技术栈健康状态 | **请求体示例：** ```typescript await cli.addMemory({ content: "记忆内容", agentId: "agent-001", memoryCategory: "knowledge" }); ``` 资料来源：[clients/node/README.md]() ## 会话与时间线 ### 会话管理 系统以会话（Session）为单位组织记忆，每个会话包含多个内存条目： ```mermaid graph TD A[Session 会话] --> B[Memory 记忆 1] A --> C[Memory 记忆 2] A --> D[Memory 记忆 N] B --> E[content 内容] B --> F[memory_type 类型] B --> G[memory_concept 概念] B --> H[created_at 创建时间] B --> I[estimated_tokens 令牌数] ``` **会话元数据字段：** | 字段 | 说明 | |------|------| | `session_id` | 会话唯一标识 | | `created_at` | 创建时间 | | `memory_count` | 记忆数量 | | `total_tokens` | 总令牌数 | 资料来源：[dashboard/nextjs-dashboard/src/components/organisms/SessionTimeline.tsx]() ### 内存元数据 每个内存条目包含丰富的元数据： | 字段 | 说明 | 示例 | |------|------|------| | `memory_id` | 唯一标识 | UUID | | `content` | 内容 | 记忆文本 | | `summary` | 摘要 | 自动生成 | | `memory_type` | 类型 | text, code, knowledge | | `memory_concept` | 概念 | concept, fact, idea | | `created_at` | 创建时间 | ISO 8601 | | `estimated_tokens` | 估计令牌数 | 整数 | | `char_count` | 字符数 | 整数 | | `similarity` | 相似度 | 0.0-1.0 | 资料来源：[dashboard/nextjs-dashboard/src/app/memories/[id]/page.tsx]() ## 搜索与检索 ### 搜索功能 系统支持语义搜索和关键词搜索的混合检索： ```mermaid graph TD A[查询 Query] --> B[向量搜索 Qdrant] A --> C[关键词搜索 PostgreSQL] B --> D[结果融合] C --> D D --> E[排名重排] E --> F[返回结果] ``` ### 相关记忆推荐 当查看特定记忆时，系统自动推荐相关记忆： | 字段 | 说明 | |------|------| | `summary` | 相关记忆摘要 | | `content` | 内容预览（前100字符）| | `memory_type` | 类型标签 | | `created_at` | 创建时间 | | `similarity` | 相似度分数 | 资料来源：[dashboard/nextjs-dashboard/src/app/memories/[id]/page.tsx]() ## 实时更新 ### SSE 事件流 系统使用 Server-Sent Events（SSE）实现实时更新： ```javascript // 自动重连机制 eventSource.onerror = (error) => { eventSource.close(); setTimeout(() => connectStream(), 5000); }; ``` **事件类型：** | 事件 | 说明 | |------|------| | `memory_added` | 新记忆创建 | | `memory_updated` | 记忆修改 | | `session_started` | 会话开始 | | `session_ended` | 会话结束 | | `stats_updated` | 统计数据更新 | 资料来源：[dashboard/README.md]() ## 安全与多租户 ### 认证机制 系统支持 JWT 认证和多租户隔离： | 头部 | 用途 | 环境变量 | |------|------|----------| | `X-API-Key` | API 密钥认证 | `ENHANCED_API_KEY` | | `X-Tenant-ID` | 租户隔离标识 | `ENHANCED_TENANT_ID` | ```bash curl -H "Authorization: Bearer " \ http://localhost:8000/api/security/user ``` 资料来源：[clients/node/README.md]() ### CORS 配置 支持以下来源的跨域请求： - `http://localhost:3000` - `http://127.0.0.1:3000` 额外来源可通过环境变量配置。 资料来源：[dashboard/README.md]() ## 性能优化 ### 缓存策略 统计数据缓存有效期为 30 秒，减少数据库负载。 ### 分页支持 记忆列表端点支持分页参数： | 参数 | 说明 | |------|------| | `limit` | 每页数量限制 | | `offset` | 偏移量 | 资料来源：[dashboard/README.md]() ## 配置与扩展 ### 环境变量配置 ```bash # API 配置 NEXT_PUBLIC_API_URL=http://localhost:8000 # LLM 配置 LLM_PROVIDER="" LLM_MODEL="" LLM_ENDPOINT="" LLM_API_KEY="" # 向量嵌入配置 EMBEDDING_PROVIDER="" EMBEDDING_MODEL="" EMBEDDING_ENDPOINT="" EMBEDDING_API_KEY="" ``` 资料来源：[cognee-starter-kit/README.md]() ## 社区相关 ### 版本同步 当前 Enhanced Cognee 维护 v1.0.9 本地版本，与上游 v1.1.2 存在 173 个变更文件和 18 个新任务。内存管理模块属于持续同步更新的核心区域。 ### 测试覆盖 系统包含 1,134 个单元测试，100% ASCII 安全，无 Unicode 编码问题，确保内存操作的可靠性。 ## 相关文档 - [数据摄取与处理](./数据摄取与处理.md) - [知识图谱构建](./知识图谱构建.md) - [搜索与检索](./搜索与检索.md) - [API 参考](./API参考.md) --- ## 多租户数据分区 ### 相关页面 相关主题：[系统架构总览](#architecture-overview)
相关源码文件 以下源码文件用于生成本页说明： - [src/multi_tenant.py](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/src/multi_tenant.py) - [src/multi_tenant/](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/src/multi_tenant) - [docs/operations/MULTI_TENANT_DESIGN.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/docs/operations/MULTI_TENANT_DESIGN.md) - [cognee/api/v1](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/cognee/api/v1) - [migrations](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/migrations)
# 多租户数据分区 ## 概述 多租户数据分区（Multi-Tenant Data Partitioning）是 Enhanced Cognee 提供的企业级数据隔离机制，旨在支持多个租户（组织或用户组）在共享基础设施上安全存储和处理数据，同时确保各租户之间的数据完全隔离。 该功能是 Enhanced Cognee v1.0.0 的核心基础设施之一，为 MCP 工具、API 端点和知识图谱操作提供统一的租户隔离能力。 ## 架构设计 ### 核心组件 Enhanced Cognee 的多租户架构由以下核心组件构成： | 组件 | 位置 | 职责 | |------|------|------| | `MultiTenantMiddleware` | `src/multi_tenant/middleware.py` | 请求级别的租户上下文注入 | | `TenantContext` | `src/multi_tenant/context.py` | 线程/异步上下文隔离 | | `TenantAwareStorage` | `src/multi_tenant/storage.py` | 数据库表级租户隔离 | | `TenantRouter` | `src/multi_tenant/router.py` | API 路由多租户分发 | ### 数据隔离策略 ```mermaid graph TD A[Client Request] --> B[X-Tenant-ID Header] B --> C{MultiTenantMiddleware} C --> D[Validate Tenant] D -->|Valid| E[TenantContext Setup] D -->|Invalid| F[401 Unauthorized] E --> G[Storage Layer] E --> H[Vector Store Qdrant] E --> I[Graph Store Neo4j] G --> J[PostgreSQL
tenant_id column] H --> K[Qdrant
payload filter] I --> L[Neo4j
Label filtering] ``` 系统采用**行级隔离**（Row-Level Isolation）策略，通过 `tenant_id` 字段在共享数据库表中实现逻辑数据分区： ```python # 数据查询时自动注入租户过滤 def query_with_tenant(table, filters, tenant_id): filters["tenant_id"] = tenant_id return db.select(table).where(filters) ``` ## 请求上下文传递 ### HTTP Header 机制 客户端通过 `X-Tenant-ID` HTTP Header 传递租户标识： ```typescript // Node.js 客户端示例 const client = new EnhancedCogneeClient({ tenantId: "org_acme_corp" }); // 请求将自动包含 Header // X-Tenant-ID: org_acme_corp ``` 资料来源：[clients/node/README.md:42]() ### 中间件处理流程 ```mermaid sequenceDiagram participant Client participant Middleware participant Context participant Handler Client->>Middleware: HTTP Request + X-Tenant-ID Middleware->>Middleware: Extract tenant_id Middleware->>Context: set_current_tenant(tenant_id) Context-->>Middleware: Tenant context active Middleware->>Handler: Request with context Handler->>Handler: Database operations Handler-->>Client: Tenant-isolated response Middleware->>Context: clear_tenant_context() ``` ## 数据库迁移 ### 租户表结构 系统提供数据库迁移脚本以支持多租户表结构： | 迁移文件 | 适用范围 | 说明 | |----------|----------|------| | `migrations/001_add_tenant_id.sql` | PostgreSQL | 主数据表增加 tenant_id 列 | | `migrations/002_tenant_index.sql` | PostgreSQL | 创建 tenant_id 索引 | | `migrations/003_qdrant_tenant_filter.sql` | Qdrant | 向量存储租户过滤配置 | ### 迁移命令 ```bash # 执行租户迁移 alembic upgrade head -p migrations/tenant # 验证租户隔离 python -m cognee.utils.verify_tenant_isolation ``` ## API 端点集成 ### MCP 工具中的租户支持 所有 MCP 工具默认支持多租户上下文： | MCP 工具分类 | 租户感知 | 隔离方式 | |--------------|----------|----------| | Memory Tools | ✅ | PostgreSQL tenant_id 过滤 | | Knowledge Graph | ✅ | Neo4j 标签隔离 | | Search Tools | ✅ | Qdrant payload 过滤 | | Encryption | ✅ | 租户级密钥派生 | ### API v1 路由 `cognee/api/v1` 目录下的所有端点自动继承多租户中间件： ```python # cognee/api/v1/memories.py 示例 @router.post("/memory/add") async def add_memory(request: MemoryRequest, tenant_id: str = Depends(get_tenant_id)): # tenant_id 从请求上下文自动注入 memory = await memory_service.create( content=request.content, tenant_id=tenant_id # 自动关联当前租户 ) return {"id": memory.id, "tenant_id": tenant_id} ``` ## 配置与管理 ### 环境变量 | 变量名 | 说明 | 默认值 | |--------|------|--------| | `ENHANCED_TENANT_ID` | 默认租户 ID（用于测试） | - | | `ENHANCED_MULTI_TENANT_MODE` | 启用模式：`strict`, `permissive` | `strict` | | `ENHANCED_TENANT_CACHE_TTL` | 租户配置缓存秒数 | `300` | ### 严格模式 vs 宽松模式 ```mermaid graph LR subgraph Strict Mode A1[无 X-Tenant-ID] --> B1[Reject 401] A2[无效 Tenant-ID] --> B2[Reject 401] end subgraph Permissive Mode A3[无 X-Tenant-ID] --> B3[Use DEFAULT_TENANT] A4[无效 Tenant-ID] --> B4[Use DEFAULT_TENANT] end ``` ## 安全性 ### 数据隔离保证 1. **存储层隔离**：每个租户的数据在 PostgreSQL、Qdrant、Neo4j 中通过租户 ID 严格分离 2. **API 层面防护**：未提供有效租户标识的请求将被拒绝 3. **审计日志**：所有数据操作记录租户上下文 ### 认证集成 多租户隔离与 JWT 认证协同工作： ```bash # 带认证的多租户请求 curl -X POST http://localhost:8000/memory/add \ -H "Authorization: Bearer " \ -H "X-Tenant-ID: org_acme_corp" \ -H "Content-Type: application/json" \ -d '{"content": "sensitive data", "agentId": "agent_001"}' ``` 资料来源：[dashboard/README.md:89]() ## 最佳实践 ### 客户端配置 ```typescript // 生产环境推荐配置 const client = new EnhancedCogneeClient({ apiKey: process.env.ENHANCED_API_KEY, tenantId: process.env.ENHANCED_TENANT_ID, // 从环境变量读取 baseUrl: "https://api.cognee.io/v1" }); ``` ### 租户 ID 命名规范 建议使用以下命名格式以避免冲突： | 场景 | 格式 | 示例 | |------|------|------| | 企业组织 | `org_{slug}` | `org_acme_corp` | | 个人用户 | `user_{uuid}` | `user_a1b2c3d4` | | 环境隔离 | `{org}_{env}` | `org_acme_dev` | ## 已知限制 - **上游同步问题**：当前 v1.0.9 版本与上游 v1.1.2 存在 18 个新任务的差异，多租户相关功能需同步上游更新 资料来源：[Issue #67](https://github.com/vincentspereira/Enhanced-Cognee/issues/67) - **Neo4j 标签隔离**：图数据库层面需确保查询语句正确使用标签过滤，避免跨租户数据泄露 - **向量重排序**：Qdrant 多租户过滤在超大规模向量集（>10M）时可能存在性能开销 ## 相关文档 - [多租户设计文档](./docs/operations/MULTI_TENANT_DESIGN.md) - [MCP 安全配置](./src/mcp_security.py) - [Node.js 客户端文档](./clients/node/README.md) --- ## 跨语言客户端SDK ### 相关页面 相关主题：[API接口参考](#api-reference)
相关源码文件 以下源码文件用于生成本页说明： - [enhanced_cognee_client/client.py](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/enhanced_cognee_client/client.py) - [clients/node/src/index.ts](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/clients/node/src/index.ts) - [clients/go/client.go](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/clients/go/client.go) - [clients/rust/src/lib.rs](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/clients/rust/src/lib.rs) - [sdk_pkg/enhanced_cognee_client](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/sdk_pkg/enhanced_cognee_client)
# 跨语言客户端SDK ## 概述 Enhanced Cognee 提供了一套完整的跨语言客户端SDK，允许开发者在不同编程语言环境中与Cognee知识图谱后端服务进行交互。这套SDK支持Python、Node.js、Go和Rust四种主流编程语言，提供了统一的API接口和一致的调用体验。 跨语言SDK的核心设计目标是： - **语言无关性**：无论使用何种编程语言，开发者都能获得相同的功能接口 - **协议统一**：所有SDK通过HTTP/REST API与后端通信，使用JSON格式进行数据交换 - **类型安全**：各语言SDK均提供强类型接口，减少运行时错误 - **异步支持**：所有网络操作均支持异步执行模式 资料来源：[clients/node/README.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/clients/node/README.md) ## 架构设计 ### 整体架构 跨语言SDK采用标准的客户端-服务器架构。SDK作为客户端层，负责将开发者的高级语言调用转换为HTTP请求，并与部署在服务器端的Enhanced Cognee后端进行通信。 ```mermaid graph TD A[开发者应用] --> B[语言特定SDK] B --> C[HTTP客户端层] C --> D[JSON序列化/反序列化] D --> E[REST API网关] E --> F[Enhanced Cognee后端] F --> G[(PostgreSQL)] F --> H[(Qdrant)] F --> I[(Neo4j)] F --> J[(Redis)] B1[Python SDK] -.-> B B2[Node.js SDK] -.-> B B3[Go SDK] -.-> B B4[Rust SDK] -.-> B ``` ### SDK组件结构 每个语言SDK均包含以下核心组件： | 组件 | 功能描述 | |------|----------| | 客户端主类 | 提供所有API调用的入口点 | | 数据模型 | 定义请求和响应的数据结构 | | 错误处理 | 统一的异常类型和错误码 | | 配置管理 | 环境变量和初始化参数处理 | | HTTP层 | 网络请求封装和认证头处理 | 资料来源：[clients/node/src/index.ts](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/clients/node/src/index.ts) ## Python SDK ### 安装与配置 Python SDK可通过pip或从源码安装： ```bash pip install enhanced-cognee-client ``` 环境变量配置： | 环境变量 | 说明 | 默认值 | |----------|------|--------| | `ENHANCED_API_URL` | API服务器地址 | `http://localhost:8000` | | `ENHANCED_API_KEY` | API密钥认证 | - | | `ENHANCED_TENANT_ID` | 多租户隔离标识 | - | ### 核心功能 Python SDK提供与后端完整对齐的API接口，主要包括： **记忆管理** - `add()`：添加记忆数据 - `search()`：向量搜索和全文搜索 - `get()`：获取指定记忆 **知识图谱操作** - `add_relation()`：添加实体关系 - `query_graph()`：图数据库查询 **系统管理** - `get_health()`：健康检查 - `get_stats()`：统计数据获取 ### 异步支持 Python SDK基于`aiohttp`实现异步HTTP客户端： ```python import asyncio from enhanced_cognee_client import EnhancedCogneeClient async def main(): async with EnhancedCogneeClient() as client: result = await client.search(query="技术文档") print(result) asyncio.run(main()) ``` 资料来源：[enhanced_cognee_client/client.py](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/enhanced_cognee_client/client.py) ## Node.js SDK ### 安装与配置 ```bash npm install @enhanced-cognee/client ``` TypeScript类型定义已内置于SDK包中，无需额外安装。 ### 核心API | 方法 | HTTP方法 | API端点 | 描述 | |------|----------|---------|------| | `addMemory(entry)` | POST | `/memory/add` | 存储记忆条目 | | `searchMemory(query)` | POST | `/memory/search` | 向量和全文搜索 | | `addKnowledgeRelation(relation)` | POST | `/knowledge/add_relation` | 添加图关系 | | `getStats()` | GET | `/stats` | 记忆存储统计 | | `getHealth()` | GET | `/health` | 栈健康状态 | 资料来源：[clients/node/README.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/clients/node/README.md) ### TypeScript类型定义 Node.js SDK采用TypeScript编写，提供完整的类型推断支持： ```typescript import { EnhancedCogneeClient, EnhancedCogneeError } from "@enhanced-cognee/client"; const client = new EnhancedCogneeClient({ apiKey: process.env.ENHANCED_API_KEY, tenantId: process.env.ENHANCED_TENANT_ID, }); try { const memory = await client.addMemory({ content: "这是一个测试记忆", agentId: "agent-001", memoryCategory: "test" }); } catch (err) { if (err instanceof EnhancedCogneeError) { console.error(`HTTP ${err.status}: ${err.body}`); } } ``` ### 命名转换 SDK自动处理TypeScript风格（camelCase）与服务器端Python风格（snake_case）的命名转换。开发者使用camelCase格式调用SDK，SDK自动转换为服务器期望的snake_case格式。 资料来源：[clients/node/src/index.ts](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/clients/node/src/index.ts) ## Go SDK ### 安装 ```bash go get github.com/vincentspereira/Enhanced-Cognee/clients/go ``` ### 客户端初始化 ```go package main import ( cognee "github.com/vincentspereira/Enhanced-Cognee/clients/go" ) func main() { client := cognee.NewClient( cognee.WithAPIKey("your-api-key"), cognee.WithBaseURL("http://localhost:8000"), ) resp, err := client.SearchMemory(ctx, "query string") } ``` ### 核心接口 Go SDK通过结构体定义请求和响应类型，确保编译时类型安全： - `SearchMemory`：记忆搜索 - `AddMemory`：添加记忆 - `AddRelation`：添加知识关系 - `GetStats`：获取统计信息 资料来源：[clients/go/client.go](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/clients/go/client.go) ## Rust SDK ### 添加依赖 ```toml [dependencies] enhanced-cognee = { path = "../clients/rust" } tokio = { version = "1", features = ["full"] } ``` ### 异步客户端 Rust SDK基于`reqwest`和`tokio`实现异步HTTP调用： ```rust use enhanced_cognee::{Client, ClientConfig}; #[tokio::main] async fn main() -> Result<(), Box> { let config = ClientConfig::default() .with_api_key("your-api-key") .with_base_url("http://localhost:8000"); let client = Client::new(config)?; let result = client.search_memory("query").await?; println!("{:?}", result); Ok(()) } ``` ### 错误处理 Rust SDK使用`Result`类型进行错误处理，定义了自己的错误枚举类型： ```rust pub enum CogneeError { NetworkError(String), ApiError { status: u16, message: String }, ParseError(String), } ``` 资料来源：[clients/rust/src/lib.rs](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/clients/rust/src/lib.rs) ## 认证与多租户 ### API密钥认证 所有SDK支持通过API密钥进行认证： ```bash # 请求头格式 X-API-Key: ``` 当MCP服务器配置了`ENHANCED_API_KEY`环境变量时，客户端必须提供此请求头。 资料来源：[clients/node/README.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/clients/node/README.md) ### 多租户隔离 SDK支持多租户场景，通过租户ID实现数据隔离： ```bash # 请求头格式 X-Tenant-ID: ``` 租户路由由服务端`multi_tenant.py`模块处理，实现数据层面的完全隔离。 ## 通用API接口 ### 健康检查 ```mermaid graph LR A[SDK Client] -->|GET /health| B[后端服务] B --> C{检查结果} C -->|正常| D[返回健康状态] C -->|异常| E[返回错误详情] ``` 所有SDK均提供`getHealth()`或等效方法，返回服务端组件的健康状态。 ### 统计信息 `getStats()`方法返回当前记忆存储的统计信息： | 字段 | 类型 | 描述 | |------|------|------| | `total_memories` | int | 记忆总数 | | `vector_store_count` | int | 向量存储数量 | | `graph_nodes` | int | 图数据库节点数 | | `last_updated` | datetime | 最后更新时间 | ## SDK开发指南 ### 添加新语言SDK 创建新语言SDK时，需遵循以下规范： 1. **接口一致性**：所有SDK必须实现相同的核心方法集合 2. **类型定义**：提供与API schema对应的数据类型 3. **错误处理**：定义统一的错误类型，保留原始HTTP状态码 4. **命名规范**：接受开发者使用该语言的惯用命名，内部转换为API格式 ### 测试策略 每个SDK应包含： - 单元测试：覆盖核心业务逻辑 - 集成测试：与真实后端服务交互 - 端到端测试：完整业务流程验证 ## 最佳实践 ### 配置管理 ```mermaid graph TD A[应用启动] --> B{环境变量存在?} B -->|是| C[使用环境变量] B -->|否| D{构造函数参数?} D -->|是| E[使用构造参数] D -->|否| F[使用默认值] C --> G[初始化SDK] E --> G F --> G ``` 建议通过环境变量配置生产环境，构造函数参数用于测试和开发场景。 ### 错误重试 网络请求应实现指数退避重试机制： ```python import asyncio async def with_retry(func, max_retries=3): for attempt in range(max_retries): try: return await func() except NetworkError: if attempt == max_retries - 1: raise await asyncio.sleep(2 ** attempt) ``` ### 连接池 生产环境应启用HTTP连接池以提升性能： ```typescript const client = new EnhancedCogneeClient({ baseURL: process.env.API_URL, timeout: 30000, maxConnections: 100 }); ``` ## 相关资源 - [官方文档首页](README.md) - [MCP工具集](../mcp/) - [Dashboard组件库](../dashboard/) - [上游同步进度](../.upstream-sync/) ## 更新日志 | 版本 | 日期 | 更新内容 | |------|------|----------| | v1.0.0 | 2025-02 | 初始版本，支持4种语言SDK | | v1.1.0 | 2025-05 | 新增多租户支持 | | v1.1.2 | 2025-06 | 同步上游变更，改进错误处理 | --- ## API接口参考 ### 相关页面 相关主题：[跨语言客户端SDK](#cross-language-sdks), [MCP工具参考手册](#mcp-tools-reference)
相关源码文件 以下源码文件用于生成本页说明： - [clients/node/README.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/clients/node/README.md) - [clients/README.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/clients/README.md) - [dashboard/README.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/dashboard/README.md) - [dashboard/nextjs-dashboard/README.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/dashboard/nextjs-dashboard/README.md) - [dashboard/nextjs-dashboard/src/app/not-found.tsx](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/dashboard/nextjs-dashboard/src/app/not-found.tsx)
# API接口参考 ## 概述 Enhanced Cognee 提供了一套完整的 RESTful API 接口，用于与知识图谱记忆层进行交互。API 支持内存存储、语义搜索、知识关系管理等功能，并提供多语言 SDK 客户端（Python、Node.js、TypeScript）。 所有 API 端点基于 FastAPI 构建，运行在 `http://localhost:8000`（可通过环境变量配置），支持 JWT 认证和多租户路由。 ## 核心端点 ### 内存管理 | 方法 | HTTP端点 | 描述 | |------|----------|------| | `addMemory(entry)` | `POST /memory/add` | 存储新的记忆条目 | | `searchMemory(query)` | `POST /memory/search` | 向量搜索与文本搜索 | | `getMemories()` | `GET /memories` | 获取记忆列表 | | `getMemory(id)` | `GET /memories/{id}` | 获取指定记忆详情 | ### 知识图谱 | 方法 | HTTP端点 | 描述 | |------|----------|------| | `addKnowledgeRelation(relation)` | `POST /knowledge/add_relation` | 添加图关系边 | | `getKnowledgeGraph()` | `GET /knowledge/graph` | 获取知识图谱结构 | ### 系统状态 | 方法 | HTTP端点 | 描述 | |------|----------|------| | `getStats()` | `GET /stats` | 记忆存储统计信息 | | `getHealth()` | `GET /health` | 技术栈健康快照 | ## 认证与多租户 ### 请求头配置 | 请求头 | 用途 | 设置方式 | |--------|------|----------| | `Authorization` | JWT Bearer Token 认证 | 当 MCP 服务器启用 `ENHANCED_API_KEY` 时使用 | | `X-API-Key` | API密钥认证 | 通过客户端构造函数的 `apiKey` 参数设置 | | `X-Tenant-ID` | 多租户路由 | 通过客户端构造函数的 `tenantId` 参数设置 | ### 认证示例 ```bash # 使用 JWT Token curl -H "Authorization: Bearer " \ http://localhost:8000/api/security/user # 使用 API Key curl -H "X-API-Key: " \ http://localhost:8000/memory/search # 多租户请求 curl -H "X-Tenant-ID: tenant_123" \ http://localhost:8000/memories ``` ## Python SDK ### 安装 ```bash pip install cognee ``` ### 基础使用 ```python import cognee # 添加数据到知识图谱 await cognee.add(["document.pdf", "notes.txt"]) # 执行认知处理流程 await cognee.cognify() # 语义搜索 results = await cognee.search( query_text="关键概念", query_type="semantic" ) ``` ### 高级配置 ```python from cognee.api.v1.search import SearchOptions # 自定义搜索配置 results = await cognee.search( query_text="项目需求", query_type=SearchOptions.SEMANTIC, limit=10, threshold=0.8 ) ``` ## Node.js/TypeScript SDK ### 安装 ```bash npm install @enhanced-cognee/client ``` ### 基础使用 ```typescript import { EnhancedCogneeClient } from "@enhanced-cognee/client"; const client = new EnhancedCogneeClient({ baseUrl: "http://localhost:8000", apiKey: process.env.ENHANCED_API_KEY, tenantId: process.env.ENHANCED_TENANT_ID }); // 添加记忆 await client.addMemory({ content: "用户偏好信息", agentId: "agent_001", memoryCategory: "user_preference" }); // 搜索记忆 const results = await client.searchMemory({ query: "用户设置", limit: 10 }); // 获取系统健康状态 const health = await client.getHealth(); ``` ### 错误处理 ```typescript import { EnhancedCogneeError } from "@enhanced-cognee/client"; try { await client.addMemory({ content: "", agentId: "x", memoryCategory: "y" }); } catch (err) { if (err instanceof EnhancedCogneeError) { console.error(`HTTP ${err.status}: ${err.body}`); } } ``` ## 数据模型 ### MemoryEntry | 字段 | 类型 | 必需 | 描述 | |------|------|------|------| | `id` | `string` | 是 | 唯一标识符 | | `content` | `string` | 是 | 记忆内容 | | `agentId` | `string` | 是 | 关联的代理ID | | `memoryCategory` | `string` | 是 | 记忆分类 | | `summary` | `string` | 否 | 自动生成的摘要 | | `metadata` | `object` | 否 | 附加元数据 | | `createdAt` | `datetime` | 否 | 创建时间戳 | | `similarity` | `float` | 否 | 相似度得分（0.0-1.0） | ### KnowledgeRelation | 字段 | 类型 | 必需 | 描述 | |------|------|------|------| | `sourceId` | `string` | 是 | 源节点ID | | `targetId` | `string` | 是 | 目标节点ID | | `relationType` | `string` | 是 | 关系类型（如 `related_to`、`depends_on`） | | `properties` | `object` | 否 | 关系属性 | ## 安全配置 ### CORS设置 CORS 策略默认允许以下来源： - `http://localhost:3000` - `http://127.0.0.1:3000` 可通过环境变量配置额外来源。 ### 速率限制 > [!NOTE] > 当前版本速率限制功能标记为 TODO，尚未实现。 ## 性能优化 ### 缓存策略 | 端点 | 缓存时间 | 说明 | |------|----------|------| | `/stats` | 30秒 | 统计数据缓存以减少数据库负载 | | `/health` | 动态 | 基于服务检查结果 | ### 分页支持 列表端点支持分页参数： ```bash # 获取第2页，每页20条 GET /memories?page=2&limit=20 ``` ## 实时更新 Dashboard 使用 Server-Sent Events (SSE) 实现实时更新： ```javascript // 自动重连机制 eventSource.onerror = (error) => { console.error('SSE error:', error); eventSource.close(); setTimeout(() => connectStream(), 5000); }; ``` ### SSE事件类型 | 事件 | 描述 | |------|------| | `memory_added` | 新记忆创建 | | `memory_updated` | 记忆内容修改 | | `session_started` | 会话开始 | | `session_ended` | 会话结束 | | `stats_updated` | 统计数据更新 | ## 扩展新语言SDK 如需添加新的语言 SDK（如 Java、C#），请遵循以下规范： 1. **客户端类**：实现 Builder/Options 模式 2. **方法映射**：每个 HTTP 端点对应一个方法 3. **请求头**：集中设置认证和多租户头 4. **错误处理**：为 HTTP 非 2xx 响应定义类型化错误 5. **单元测试**：使用语言标准的 HTTP 模拟模式 6. **文档**：提供快速入门和认证示例 > [!IMPORTANT] > HTTP 契约保持稳定，新增语言 SDK 不应破坏现有接口规范。 ## 相关资源 - 客户端 SDK 仓库：[clients/README.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/clients/README.md) - Dashboard 前端：[dashboard/nextjs-dashboard/README.md](https://github.com/vincentspereira/Enhanced-Cognee/blob/main/dashboard/nextjs-dashboard/README.md) - 上游同步状态：[Issue #67](https://github.com/vincentspereira/Enhanced-Cognee/issues/67) --- --- ## Doramagic 踩坑日志 项目：vincentspereira/Enhanced-Cognee 摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。 ## 1. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 建议检查：将假设转成下游验证清单。 - 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。 - 证据：capability.assumptions | github_repo:1146917885 | https://github.com/vincentspereira/Enhanced-Cognee | README/documentation is current enough for a first validation pass. ## 2. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。 - 防护动作：维护活跃度未知时，推荐强度不能标为高信任。 - 证据：evidence.maintainer_signals | github_repo:1146917885 | https://github.com/vincentspereira/Enhanced-Cognee | last_activity_observed missing ## 3. 安全/权限坑 · 下游验证发现风险项 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：下游已经要求复核，不能在页面中弱化。 - 建议检查：进入安全/权限治理复核队列。 - 防护动作：下游风险存在时必须保持 review/recommendation 降级。 - 证据：downstream_validation.risk_items | github_repo:1146917885 | https://github.com/vincentspereira/Enhanced-Cognee | no_demo; severity=medium ## 4. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 建议检查：把风险写入边界卡，并确认是否需要人工复核。 - 防护动作：评分风险必须进入边界卡，不能只作为内部分数。 - 证据：risks.scoring_risks | github_repo:1146917885 | https://github.com/vincentspereira/Enhanced-Cognee | no_demo; severity=medium ## 5. 安全/权限坑 · 来源证据：Upstream sync: port v1.1.2 changes - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Upstream sync: port v1.1.2 changes - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。 - 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。 - 证据：community_evidence:github | cevd_48ca82308de547e58718132ae98a6390 | https://github.com/vincentspereira/Enhanced-Cognee/issues/67 | 来源类型 github_issue 暴露的待验证使用条件。 ## 6. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 建议检查：抽样最近 issue/PR，判断是否长期无人处理。 - 防护动作：issue/PR 响应未知时，必须提示维护风险。 - 证据：evidence.maintainer_signals | github_repo:1146917885 | https://github.com/vincentspereira/Enhanced-Cognee | issue_or_pr_quality=unknown ## 7. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 建议检查：确认最近 release/tag 和 README 安装命令是否一致。 - 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。 - 证据：evidence.maintainer_signals | github_repo:1146917885 | https://github.com/vincentspereira/Enhanced-Cognee | release_recency=unknown