长期记忆系统

Cortex——宇宙蜂巢思维🧠

版本： 1.0（生产就绪混合堆栈）

一个隐私优先的本地长期记忆系统，用于具有混合GraphRAG检索的AI代理。

特性 • 快速开始 • 建筑 • 用法和工具

🎯 概述

Cortex是一种 本地隐私优先的“长期记忆” AI代理系统。它使用 混合GraphRAG 将语义搜索与基于图的推理相结合的架构。

它作为一个 模型上下文协议（MCP） 服务器，使其立即与Claude Desktop、Cursor、VSCode（GitHub Copilot）和其他AI客户端兼容。

✨ 主要特点

🚀 快速开始

您可以直接通过Docker或Python（推荐）运行Cortex。

🐳 选项1:Docker

不需要Python设置。在端口8000上运行MCP服务器。

# 1. Clone and start
git clone https://github.com/yourusername/cortex.git
cd Cortex
docker compose up -d

# 2. Verify it's running
curl http://localhost:8000/health
# Output: {"status": "healthy", "server": "Cortex MCP"}

🐍 选项2:Python手动设置（推荐）

🔌 连接MCP客户端

Cortex使用 模型上下文协议。服务器运行后（通常在 http://localhost:8000/mcp)，连接您最喜欢的AI编辑器。

🤖 克劳德桌面

将以下内容添加到您的配置文件中：

• 赢： %APPDATA%\Claude\claude_desktop_config.json
• 雨衣： ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "cortex": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

💻 VSCode（GitHub Copilot/Cline）

增添 .vscode/mcp.json 或扩展设置：

{
  "mcpServers": {
    "cortex": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

[！提示] 测试连接： 问你的人工智能“你的记忆状态如何？”或“存储这个：我正在做X项目”。

🎨 交互式可视化

Cortex生成 美丽的3D/2D交互式仪表板 探索你的知识图谱。了解记忆、主题和项目如何实时互连。

3D神经网络视图

通过动画数据流在沉浸式3D空间中探索您的知识图谱

2D战略概述

切换到2D模式进行精确导航和分析

特征：

• 🔄 切换3D/2D视图 只需单击一下
• 🎯 单击节点 查看详细信息（来源、时间戳、类别、连接）
• ✨ 动画粒子流 显示数据关系
• 🌌 星空背景 用于电影体验（3D模式）
• 📊 实时统计 显示节点和链接计数
• 🎨 颜色编码节点：记忆（红色）、主题（绿色）、项目（蓝色）

使用生成自己的仪表板 visualize_brain 工具或运行演示：

python demo_scenario.py
# Open demo_dashboard.html manually

🧠 建筑

Cortex实现了 混合GraphRAG 方法。它不仅匹配文本；它理解关系。

graph TD
    Client[AI Agent / Client] <-->|MCP Protocol| API[Cortex Server]
    
    subgraph "Cortex Core"
        API --> NLP["Intelligence Layer<br/>(spaCy + PII Filter)"]
        
        NLP -->|Entities| Graph["Associative Store<br/>(Kùzu Graph DB)"]
        NLP -->|Embeddings| Vector["Semantic Store<br/>(LanceDB)"]
        
        Graph <-->|Relations| Vector
    end
    
    subgraph "Performance"
        Cache["L1 Cache<br/>Embeddings + Queries"] -.-> API
        Monitor["Metrics & Stats"] -.-> API
    end

三层

1. 🔍 语义库（海马）： LanceDB + 快速嵌入.使用自动L2距离阈值（<0.85）处理向量相似性搜索。
2. 🕸️ 关联存储（Cortex）： 关於 图形数据库。将记忆链接到主题、项目和实体。允许2跳邻居遍历。
3. 🤖 智能层： Spacy自动提取人、器官、产品和 PII消毒 （编辑电子邮件、密钥等）。

🏃‍♂️ 用法和工具

您的AI代理将自动访问这些工具：

store_memory

通过自动实体提取和隐私清理保存信息。

{"content": "We chose FastAPI because of its async performance", "category": "decision", "project": "Backend-v2"}

recall

使用混合排名（矢量+图形分数）检索相关记忆。

{"query": "Why did we choose FastAPI?", "limit": 5}

visualize_brain

生成知识图的交互式D3.js仪表板。返回以下路径 dashboard.html.

get_system_stats

返回实时指标（缓存命中率、操作时间、内存使用情况）。

⚙️ 配置

通过环境变量配置Cortex（in .env 或Docker Compose）：

🔒 隐私和安全

Cortex是为敏感数据而设计的。

• 本地优先： 没有数据发送到OpenAI/Anthropic云进行存储。
• PII补救措施： 11种图案在储存前会自动剥离：
  • email, phone, ip_address, credit_card
  • api_keys （sk-…）， aws_keys, jwt_tokens
  • crypto_addresses, ssn, passwords

[！警告] 在Cortex清理数据时，始终确保存储目录(.cortex_storage)使用适当的文件系统权限进行保护。

🧪 开发与测试

我们保持100%的测试覆盖率。

# Run full suite
pytest tests/ -v

# Check coverage
pytest tests/ --cov=src/cortex

项目结构：

Cortex/
├── src/cortex/
│   ├── intelligence/  # NLP & Privacy logic
│   ├── storage/       # LanceDB & Kùzu wrappers
│   └── server.py      # MCP Implementation
├── tests/             # 40/40 Passing Tests
└── docker-compose.yml

🤝 贡献

欢迎投稿！请遵循 单例模式 用于 storage/manager.py 以确保螺纹安全。

1. 分叉与分支(feature/amazing-feature)
2. 测试 (pytest)
3. 带有描述的PR

⭐ 如果Cortex可以帮助您的AI代理记住，请启用此仓库！ ⭐

内置于❤️ 面向Agent AI的未来