什么是 Enhanced Cognee？

Enhanced Cognee 是一个基于上游 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 采用多层次架构设计，底层依赖多种数据库系统协同工作：

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<br/>结构化数据]
        H[Qdrant<br/>向量检索]
        I[Neo4j<br/>图数据库]
        J[Redis<br/>缓存]
    end
    
    A --> B
    B --> C
    C --> D
    C --> E
    C --> F
    D --> G
    D --> J
    E --> I
    F --> H
    F --> I

核心功能模块

记忆管理 (Memory)

记忆模块负责存储和管理文本记忆数据，支持添加、编辑、查询和删除操作。

主要 API：

知识图谱 (Knowledge Graph)

知识图谱模块将非结构化数据转换为结构化的图数据，支持实体识别、关系提取和图查询。

搜索功能

支持语义搜索和关键词搜索，可通过 query_type 参数指定搜索类型。

技术栈

快速开始

环境要求

• Python 3.10+
• Node.js 18+
• PostgreSQL
• Qdrant
• Neo4j
• Redis

安装步骤

#### 1. 克隆项目

git clone https://github.com/vincentspereira/Enhanced-Cognee.git
cd Enhanced-Cognee

#### 2. 安装 Python 依赖

# 使用 uv 安装
pip install uv
uv sync

# 激活虚拟环境
source .venv/bin/activate

#### 3. 配置环境变量

创建 .env 文件，配置以下变量：

# 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. 安装前端仪表板

cd dashboard/nextjs-dashboard
npm install

创建 .env.local 文件：

NEXT_PUBLIC_API_URL=http://localhost:8000

基本使用示例

#### Python API 使用

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，可以快速体验完整功能：

cd cognee-starter-kit
uv sync
source .venv/bin/activate

# 运行默认管道
python src/pipelines/default.py

启动仪表板

# 启动后端 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 个单元测试，确保代码质量：

# 运行所有测试
pytest

# 运行特定模块测试
pytest tests/tasks/

相关资源

• 上游项目： cognee
• 最新版本： v1.0.0 - 119 MCP Tools
• 上游同步状态： Issue #67 - 正在同步 v1.1.2 变更

下一步

• 阅读 CLAUDE.md 了解 Claude Code 集成指南
• 探索 cognee-starter-kit 快速构建示例应用
• 查看 dashboard/README.md 了解仪表板功能

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

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 工具分类总览

资料来源：src/mcp_memory_tools.py:1-100

1.3 认证与多租户支持

MCP 工具支持完整的认证机制和多租户架构：

# 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。主要数据模型包括：

资料来源：cognee/modules/memory/__init__.py:1-50

2.2 知识图谱提取流程

系统通过 LLM 驱动的结构化提取，自动从文本和代码中识别实体和关系：

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 模块提供了开发者编码规则提取功能，能够从对话、文档或提交信息中识别最佳实践并关联到原始来源：

此模块在 cognee.memify()（富化管道）中自动运行，但不在标准 cognee.cognify() 管道中默认启用。资料来源：cognee/tasks/codingagents/README.md:1-40

3. 搜索与检索能力

3.1 多模态搜索架构

Enhanced-Cognee 提供全面的搜索能力，支持向量搜索、关键词搜索和混合搜索模式：

graph TD
    A[搜索请求] --> B{搜索类型选择}
    B --> C[向量搜索-Qdrant]
    B --> D[关键词搜索-PostgreSQL]
    B --> E[混合搜索]
    C --> F[结果重排序]
    D --> F
    E --> F
    F --> G[结果返回]

3.2 搜索功能矩阵

资料来源：cognee/modules/search:1-30

3.3 相似度计算与去重

系统内置智能去重功能，能够识别和处理重复内容：

{
  "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 驱动摘要功能：

graph LR
    A[cognee.add] --> B[分块处理]
    B --> C[图谱提取]
    C --> D[summarize_text]
    D --> E[存储/索引]

资料来源：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 模块提供灵活的网页内容采集功能：

5.2 抓取数据模型

图谱关系：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 加密，确保存储在数据库中的敏感数据安全。加密密钥通过环境变量配置，支持密钥轮换机制。

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 界面，包含以下核心页面：

7.2 实时更新

仪表盘通过 Server-Sent Events（SSE）实现实时更新，支持的事件类型包括：

资料来源：dashboard/README.md:1-60

8. 技术栈概览

8.1 核心依赖

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 使用

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 客户端

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 当前版本状态

10.2 同步机制

项目通过自动化工作流检测上游更新，生成变更差异报告并创建同步任务。开发团队可下载 upstream-diff-v1.1.2 artifact 并参考 .upstream-sync/PORTING_TODO.md 进行版本同步。

资料来源：社区上下文 - Issue #67

11. 常见问题与限制

11.1 当前限制

11.2 已完成功能

概述

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）。用户通常不需要直接调用这些函数，除非构建自定义工作流。

# 自动模式（推荐）
import cognee
await cognee.add(["document.pdf", "notes.txt"])
await cognee.cognify()  # summarize_text 自动运行

#### codingagents 模块（编码规则提取）

cognee/tasks/codingagents/README.md 提供了开发者编码规则和最佳实践的提取功能。该模块在 cognee.memify() 流程中自动运行，但在标准 cognify() 流程中默认不启用。

2. 存储方案对比

Enhanced Cognee 支持多种存储后端，每种方案适用于不同的场景：

3. 加密与安全功能

Enhanced Cognee v1.0.0 提供了静态数据加密功能：

• 加密算法：Fernet AES-128-CBC
• 密钥管理：支持自定义密钥配置
• 适用范围：存储在数据库中的敏感数据

Dashboard 功能对比

当前已实现功能

记忆数据结构对比

根据 AddMemoryModal.tsx 和 EditMemoryModal.tsx 的实现，Enhanced Cognee 支持以下记忆字段：

组件架构对比

选型决策树

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

技术栈对比矩阵

前端技术选型

后端技术选型

场景化选型建议

场景一：企业知识库构建

推荐配置：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 项目的更新：

同步流程：

1. 下载上游差异工件
2. 审查 .upstream-sync/PORTING_TODO.md
3. 合并变更到本地分支
4. 运行完整测试套件

快速开始方案对比

标准方案（cognee-starter-kit）

适用于快速原型验证和简单场景：

# 安装依赖
uv sync
source .venv/bin/activate

# 配置环境变量
# LLM_PROVIDER, LLM_MODEL, LLM_API_KEY 等

# 运行默认流水线
python src/pipelines/default.py

高级方案（完整安装）

适用于生产环境：

# 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()

总结与建议

选择合适的存储后端组合需要考虑：

• 数据规模与查询复杂度
• 实时性要求
• 预算与运维能力
• 合规与安全需求

概述

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 更新

资料来源：社区发布信息

概述

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

支持的数据库后端

向量数据库

图数据库

关系数据库

键值与缓存

资料来源：docs/PLUGGABLE_DB_BACKENDS.md

存储配置与配置文件

配置文件结构

系统通过 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

环境变量覆盖

配置支持通过环境变量覆盖敏感信息，如数据库密码和 API 密钥。这种设计确保了敏感信息不会硬编码在配置文件中，遵循了安全最佳实践。

ArangoDB 迁移指南

对于从其他图数据库迁移到 ArangoDB 的用户，系统提供了完整的迁移文档。迁移过程包括数据导出、模式转换和导入三个主要阶段。资料来源：docs/ARCADEDB_MIGRATION.md

核心组件

Infrastructure 模块

cognee/
  infrastructure/
    databases/
      __init__.py          # 数据库初始化
      connector.py         # 连接管理
      executor.py          # 查询执行器

cognee.infrastructure.databases 模块是存储层的核心实现位置。该模块提供了统一的数据库连接接口、查询执行器和事务管理功能。每个数据库类型都有对应的连接器实现，负责处理特定数据库的连接细节。

资料来源：cognee/infrastructure/databases

数据点模型

系统使用统一的 DataPoint 数据模型来表示各种存储实体。这个抽象基类定义了所有存储对象必须遵循的接口，包括标识符、元数据和序列化方法。

存储适配器接口

每个数据库适配器都需要实现一组标准接口方法：

工作流程

数据写入流程

用户调用 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) │
└────────┬────────────────┘
         │
         ▼
    返回搜索结果

数据库连接管理

连接池

系统为每个数据库后端维护连接池，以优化资源使用和响应时间。连接池配置包括最小连接数、最大连接数、空闲超时和获取超时等参数。

# 连接池配置参数
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

性能优化

查询优化策略

统计缓存

仪表板和 API 端点的统计数据会被缓存 30 秒，以减少数据库负载。资料来源：dashboard/README.md

扩展与自定义

添加新数据库后端

要添加新的数据库后端，需要完成以下步骤：

1. 在 src/db_adapters/ 目录创建适配器模块
2. 实现 StorageAdapter 基类定义的所有接口
3. 添加对应的连接器和配置解析逻辑
4. 在适配器注册表中注册新后端
5. 编写单元测试并确保通过现有测试套件

自定义查询语言

高级用户可以通过扩展查询执行器来支持特定的查询语法或 DSL，实现更复杂的业务逻辑需求。

常见问题与排查

相关资源

• PLUGGABLE_DB_BACKENDS.md - 可插拔数据库后端详细文档
• PROFILES.md - 配置文件参考
• ARCADEDB_MIGRATION.md - 数据库迁移指南
• Dashboard 文档 - 仪表板与后端 API 集成说明

概述

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工具在系统中的位置

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服务器启动流程

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 Tools)

记忆管理是Enhanced Cognee的核心功能之一，提供完整的记忆生命周期管理能力。

#### 添加记忆

#### 搜索记忆

#### 更新记忆

#### 删除记忆

知识图谱工具 (Knowledge Graph Tools)

知识图谱工具基于Neo4j实现，支持复杂的实体关系操作。

#### 创建实体

#### 创建关系

#### 图查询

支持Cypher查询语言，执行复杂的图遍历和分析操作。

搜索工具 (Search Tools)

#### 语义搜索

基于Qdrant向量数据库的语义搜索功能：

results = await cognee.search(
    query_text="用户查询内容",
    query_type="semantic",
    limit=10
)

#### 搜索类型对照表

加密工具 (Encryption Tools)

Enhanced Cognee使用Fernet AES-128-CBC算法实现静态数据加密。

#### 加密记忆

#### 解密记忆

GDPR合规工具

GDPR工具提供数据删除、匿名化和可携带性支持。

Webhook工具

Webhooks支持事件驱动的通知机制：

通知工具 (Notification Tools)

支持多种通知渠道：

MCP服务器配置

启动参数

python bin/enhanced_cognee_mcp_server.py \
    --host 0.0.0.0 \
    --port 8000 \
    --log-level info

环境变量配置

MCP配置文件

项目根目录的 .kilocode/mcp.json 定义了MCP服务器的标准配置：

{
  "mcp_server": {
    "name": "Enhanced Cognee",
    "version": "1.0.0",
    "protocol_version": "2024-11-05",
    "capabilities": ["memory", "knowledge_graph", "search", "encryption"]
  }
}

使用示例

基础记忆操作流程

graph LR
    A[添加记忆] --> B[自动摘要]
    B --> C[存储到向量库]
    C --> D[构建知识图谱]
    D --> E[建立索引]
    E --> F[支持搜索查询]

Python SDK使用示例

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协议直接调用示例

{
  "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清单

工具注册结构

TOOLS = {
    "category": "memory",
    "name": "memory_add",
    "description": "添加新记忆到系统",
    "parameters": {
        "type": "object",
        "properties": {...},
        "required": ["content"]
    },
    "handler": memory_add_handler
}

测试与验证

单元测试覆盖

所有MCP工具均通过自动化测试验证：

测试命令

# 运行所有测试
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
• 上游同步状态: Issue #67 - Upstream sync: port v1.1.2 changes
• 完整使用指南: docs/mcp/COGNEE_MCP_COMPLETE_GUIDE.md

概述

Enhanced Cognee 是一个面向 Claude Code 的生产级知识图谱记忆层，构建于 PostgreSQL、Qdrant、Neo4j 和 Redis 之上。该系统提供完整的内存管理与生命周期控制能力，支持从数据摄取到知识图谱构建的全流程自动化处理。

内存管理模块负责协调数据的摄取、转换、存储和检索，确保知识在系统中的完整性和可用性。整个生命周期涵盖了从原始数据输入到结构化知识输出的完整路径。

[!NOTE]

内存管理模块在 cognee.cognify() 流程中自动运行（任务 #4），用户通常无需直接调用相关函数，除非构建自定义工作流。

核心架构

技术栈概览

Enhanced Cognee 采用多后端混合存储架构：

资料来源：cognee/tasks/summarization/README.md

数据模型层次

系统中的内存数据分为多个抽象层次，每层承担不同的职责：

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）

系统支持多种内存类型分类，便于细粒度管理和检索：

资料来源：dashboard/nextjs-dashboard/src/components/organisms/EditMemoryModal.tsx

内存概念（Memory Concepts）

内存概念用于语义层面的组织：

资料来源：dashboard/nextjs-dashboard/src/components/organisms/EditMemoryModal.tsx

生命周期阶段

处理流水线

内存的完整生命周期经历以下阶段：

graph LR
    A[数据摄取 add] --> B[分块处理 chunking]
    B --> C[图谱提取 graph extraction]
    C --> D[摘要生成 summarize_text]
    D --> E[存储索引 storage]
    E --> F[检索查询 search]

资料来源：cognee/tasks/summarization/README.md

数据摘要模型

摘要阶段生成两种核心数据类型：

#### TextSummary（文本摘要）

继承自 DataPoint，包含以下字段：

#### CodeSummary（代码摘要）

资料来源：cognee/tasks/summarization/README.md

编码规则生命周期

编码规则模块在 cognee.memify() 流程中运行，属于增强管道的一部分：

graph TD
    A[数据摄取 ingestion] --> B[图谱提取 graph extraction]
    B --> C[编码规则关联 coding rule association]
    C --> D[存储 indexing]
    D --> E[检索 retrieval]

核心函数：

资料来源：cognee/tasks/codingagents/README.md

#### Rule 数据模型

资料来源：cognee/tasks/codingagents/README.md

客户端 API 接口

Node.js 客户端

Node.js 客户端提供了完整的内存操作接口：

请求体示例：

await cli.addMemory({
  content: "记忆内容",
  agentId: "agent-001",
  memoryCategory: "knowledge"
});

资料来源：clients/node/README.md

会话与时间线

会话管理

系统以会话（Session）为单位组织记忆，每个会话包含多个内存条目：

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 令牌数]

会话元数据字段：

资料来源：dashboard/nextjs-dashboard/src/components/organisms/SessionTimeline.tsx

内存元数据

每个内存条目包含丰富的元数据：

资料来源：[dashboard/nextjs-dashboard/src/app/memories/[id]/page.tsx]()

搜索与检索

搜索功能

系统支持语义搜索和关键词搜索的混合检索：

graph TD
    A[查询 Query] --> B[向量搜索 Qdrant]
    A --> C[关键词搜索 PostgreSQL]
    B --> D[结果融合]
    C --> D
    D --> E[排名重排]
    E --> F[返回结果]

相关记忆推荐

当查看特定记忆时，系统自动推荐相关记忆：

资料来源：[dashboard/nextjs-dashboard/src/app/memories/[id]/page.tsx]()

实时更新

SSE 事件流

系统使用 Server-Sent Events（SSE）实现实时更新：

// 自动重连机制
eventSource.onerror = (error) => {
    eventSource.close();
    setTimeout(() => connectStream(), 5000);
};

事件类型：

资料来源：dashboard/README.md

安全与多租户

认证机制

系统支持 JWT 认证和多租户隔离：

curl -H "Authorization: Bearer <token>" \
     http://localhost:8000/api/security/user

资料来源：clients/node/README.md

CORS 配置

支持以下来源的跨域请求：

• http://localhost:3000
• http://127.0.0.1:3000

额外来源可通过环境变量配置。

资料来源：dashboard/README.md

性能优化

缓存策略

统计数据缓存有效期为 30 秒，减少数据库负载。

分页支持

记忆列表端点支持分页参数：

资料来源：dashboard/README.md

配置与扩展

环境变量配置

# 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 编码问题，确保内存操作的可靠性。

相关文档

• 数据摄取与处理
• 知识图谱构建
• 搜索与检索
• API 参考

概述

多租户数据分区（Multi-Tenant Data Partitioning）是 Enhanced Cognee 提供的企业级数据隔离机制，旨在支持多个租户（组织或用户组）在共享基础设施上安全存储和处理数据，同时确保各租户之间的数据完全隔离。

该功能是 Enhanced Cognee v1.0.0 的核心基础设施之一，为 MCP 工具、API 端点和知识图谱操作提供统一的租户隔离能力。

架构设计

核心组件

Enhanced Cognee 的多租户架构由以下核心组件构成：

数据隔离策略

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<br/>tenant_id column]
    H --> K[Qdrant<br/>payload filter]
    I --> L[Neo4j<br/>Label filtering]

系统采用行级隔离（Row-Level Isolation）策略，通过 tenant_id 字段在共享数据库表中实现逻辑数据分区：

# 数据查询时自动注入租户过滤
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 传递租户标识：

// Node.js 客户端示例
const client = new EnhancedCogneeClient({
  tenantId: "org_acme_corp"
});

// 请求将自动包含 Header
// X-Tenant-ID: org_acme_corp

资料来源：clients/node/README.md:42

中间件处理流程

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()

数据库迁移

租户表结构

系统提供数据库迁移脚本以支持多租户表结构：

迁移命令

# 执行租户迁移
alembic upgrade head -p migrations/tenant

# 验证租户隔离
python -m cognee.utils.verify_tenant_isolation

API 端点集成

MCP 工具中的租户支持

所有 MCP 工具默认支持多租户上下文：

API v1 路由

cognee/api/v1 目录下的所有端点自动继承多租户中间件：

# 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}

配置与管理

环境变量

严格模式 vs 宽松模式

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 认证协同工作：

# 带认证的多租户请求
curl -X POST http://localhost:8000/memory/add \
  -H "Authorization: Bearer <jwt_token>" \
  -H "X-Tenant-ID: org_acme_corp" \
  -H "Content-Type: application/json" \
  -d '{"content": "sensitive data", "agentId": "agent_001"}'

资料来源：dashboard/README.md:89

最佳实践

客户端配置

// 生产环境推荐配置
const client = new EnhancedCogneeClient({
  apiKey: process.env.ENHANCED_API_KEY,
  tenantId: process.env.ENHANCED_TENANT_ID,  // 从环境变量读取
  baseUrl: "https://api.cognee.io/v1"
});

租户 ID 命名规范

建议使用以下命名格式以避免冲突：

已知限制

• 上游同步问题：当前 v1.0.9 版本与上游 v1.1.2 存在 18 个新任务的差异，多租户相关功能需同步上游更新 资料来源：Issue #67
• Neo4j 标签隔离：图数据库层面需确保查询语句正确使用标签过滤，避免跨租户数据泄露
• 向量重排序：Qdrant 多租户过滤在超大规模向量集（>10M）时可能存在性能开销

相关文档

• 多租户设计文档
• MCP 安全配置
• Node.js 客户端文档

概述

Enhanced Cognee 提供了一套完整的跨语言客户端SDK，允许开发者在不同编程语言环境中与Cognee知识图谱后端服务进行交互。这套SDK支持Python、Node.js、Go和Rust四种主流编程语言，提供了统一的API接口和一致的调用体验。

跨语言SDK的核心设计目标是：

• 语言无关性：无论使用何种编程语言，开发者都能获得相同的功能接口
• 协议统一：所有SDK通过HTTP/REST API与后端通信，使用JSON格式进行数据交换
• 类型安全：各语言SDK均提供强类型接口，减少运行时错误
• 异步支持：所有网络操作均支持异步执行模式

资料来源：clients/node/README.md

架构设计

整体架构

跨语言SDK采用标准的客户端-服务器架构。SDK作为客户端层，负责将开发者的高级语言调用转换为HTTP请求，并与部署在服务器端的Enhanced Cognee后端进行通信。

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均包含以下核心组件：

资料来源：clients/node/src/index.ts

Python SDK

安装与配置

Python SDK可通过pip或从源码安装：

pip install enhanced-cognee-client

环境变量配置：

核心功能

Python SDK提供与后端完整对齐的API接口，主要包括：

记忆管理

• add()：添加记忆数据
• search()：向量搜索和全文搜索
• get()：获取指定记忆

知识图谱操作

• add_relation()：添加实体关系
• query_graph()：图数据库查询

系统管理

• get_health()：健康检查
• get_stats()：统计数据获取

异步支持

Python SDK基于aiohttp实现异步HTTP客户端：

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

Node.js SDK

安装与配置

npm install @enhanced-cognee/client

TypeScript类型定义已内置于SDK包中，无需额外安装。

核心API

资料来源：clients/node/README.md

TypeScript类型定义

Node.js SDK采用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

Go SDK

安装

go get github.com/vincentspereira/Enhanced-Cognee/clients/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

Rust SDK

添加依赖

[dependencies]
enhanced-cognee = { path = "../clients/rust" }
tokio = { version = "1", features = ["full"] }

异步客户端

Rust SDK基于reqwest和tokio实现异步HTTP调用：

use enhanced_cognee::{Client, ClientConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    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类型进行错误处理，定义了自己的错误枚举类型：

pub enum CogneeError {
    NetworkError(String),
    ApiError { status: u16, message: String },
    ParseError(String),
}

资料来源：clients/rust/src/lib.rs

认证与多租户

API密钥认证

所有SDK支持通过API密钥进行认证：

# 请求头格式
X-API-Key: <your-api-key>

当MCP服务器配置了ENHANCED_API_KEY环境变量时，客户端必须提供此请求头。

资料来源：clients/node/README.md

多租户隔离

SDK支持多租户场景，通过租户ID实现数据隔离：

# 请求头格式
X-Tenant-ID: <tenant-identifier>

租户路由由服务端multi_tenant.py模块处理，实现数据层面的完全隔离。

通用API接口

健康检查

graph LR
    A[SDK Client] -->|GET /health| B[后端服务]
    B --> C{检查结果}
    C -->|正常| D[返回健康状态]
    C -->|异常| E[返回错误详情]

所有SDK均提供getHealth()或等效方法，返回服务端组件的健康状态。

统计信息

getStats()方法返回当前记忆存储的统计信息：

SDK开发指南

添加新语言SDK

创建新语言SDK时，需遵循以下规范：

1. 接口一致性：所有SDK必须实现相同的核心方法集合
2. 类型定义：提供与API schema对应的数据类型
3. 错误处理：定义统一的错误类型，保留原始HTTP状态码
4. 命名规范：接受开发者使用该语言的惯用命名，内部转换为API格式

测试策略

每个SDK应包含：

• 单元测试：覆盖核心业务逻辑
• 集成测试：与真实后端服务交互
• 端到端测试：完整业务流程验证

最佳实践

配置管理

graph TD
    A[应用启动] --> B{环境变量存在?}
    B -->|是| C[使用环境变量]
    B -->|否| D{构造函数参数?}
    D -->|是| E[使用构造参数]
    D -->|否| F[使用默认值]
    C --> G[初始化SDK]
    E --> G
    F --> G

建议通过环境变量配置生产环境，构造函数参数用于测试和开发场景。

错误重试

网络请求应实现指数退避重试机制：

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连接池以提升性能：

const client = new EnhancedCogneeClient({
  baseURL: process.env.API_URL,
  timeout: 30000,
  maxConnections: 100
});

相关资源

• 官方文档首页
• MCP工具集
• Dashboard组件库
• 上游同步进度

更新日志

概述

Enhanced Cognee 提供了一套完整的 RESTful API 接口，用于与知识图谱记忆层进行交互。API 支持内存存储、语义搜索、知识关系管理等功能，并提供多语言 SDK 客户端（Python、Node.js、TypeScript）。

所有 API 端点基于 FastAPI 构建，运行在 http://localhost:8000（可通过环境变量配置），支持 JWT 认证和多租户路由。

核心端点

内存管理

知识图谱

系统状态

认证与多租户

请求头配置

认证示例

# 使用 JWT Token
curl -H "Authorization: Bearer <token>" \
     http://localhost:8000/api/security/user

# 使用 API Key
curl -H "X-API-Key: <api_key>" \
     http://localhost:8000/memory/search

# 多租户请求
curl -H "X-Tenant-ID: tenant_123" \
     http://localhost:8000/memories

Python SDK

安装

pip install cognee

基础使用

import cognee

# 添加数据到知识图谱
await cognee.add(["document.pdf", "notes.txt"])

# 执行认知处理流程
await cognee.cognify()

# 语义搜索
results = await cognee.search(
    query_text="关键概念",
    query_type="semantic"
)

高级配置

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

安装

npm install @enhanced-cognee/client

基础使用

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();

错误处理

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

KnowledgeRelation

安全配置

CORS设置

CORS 策略默认允许以下来源：

• http://localhost:3000
• http://127.0.0.1:3000

可通过环境变量配置额外来源。

速率限制

[!NOTE]

当前版本速率限制功能标记为 TODO，尚未实现。

性能优化

缓存策略

分页支持

列表端点支持分页参数：

# 获取第2页，每页20条
GET /memories?page=2&limit=20

实时更新

Dashboard 使用 Server-Sent Events (SSE) 实现实时更新：

// 自动重连机制
eventSource.onerror = (error) => {
    console.error('SSE error:', error);
    eventSource.close();
    setTimeout(() => connectStream(), 5000);
};

SSE事件类型

扩展新语言SDK

如需添加新的语言 SDK（如 Java、C#），请遵循以下规范：

1. 客户端类：实现 Builder/Options 模式
2. 方法映射：每个 HTTP 端点对应一个方法
3. 请求头：集中设置认证和多租户头
4. 错误处理：为 HTTP 非 2xx 响应定义类型化错误
5. 单元测试：使用语言标准的 HTTP 模拟模式
6. 文档：提供快速入门和认证示例

[!IMPORTANT]

HTTP 契约保持稳定，新增语言 SDK 不应破坏现有接口规范。

相关资源

• 客户端 SDK 仓库：clients/README.md
• Dashboard 前端：dashboard/nextjs-dashboard/README.md
• 上游同步状态：Issue #67

Pitfall Log / 踩坑日志

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