cortex

Cortex Logo

Go MIT v3.0 Go Report Card Tests Iteration Complete Bug 0 MCP Build Stars

🧠 Cortex

AI Agent 的第二大脑 — 本地知识库 · 单二进制 · MCP 原生

Cortex 是一个为 AI Agent 设计的本地知识库引擎。单二进制文件部署，原生支持 MCP 协议，内置混合搜索（向量+BM25）和Agent 记忆系统。100% 本地运行，零外部依赖。

给 Claude Code、OpenCode 等 AI Agent 装上永久记忆 🧠

GitHub 仓库 · 🎨 营销落地页 · 本地预览 · 📖 深度技术文章

Terminal Demo
⬆️ 点击查看完整营销落地页（小米/Mimo 风格）

📊 产品对比 · ⚡ 快速开始 · ✨ 核心特性 · 🏗️ 系统架构 · 📡 API · 🔧 配置
🌐 English Version · 🛠️ 开发 · 📋 测试报告 · 📋 迭代计划 · 📋 评估报告 · 📊 Grafana

📊 产品对比

功能 🚀 Cortex Mem0 AnythingLLM ChromaDB Qdrant Dify
📦 部署
部署方式 ✅ 单二进制
下载即用		 ⚠️ pip/Docker
需 Python 环境		 ⚠️ Docker/Desktop
需 Node.js		 ⚠️ pip/Docker
需 Python		 ✅ 单二进制
下载即用		 ⚠️ Docker Compose
多服务部署
外部依赖 ✅ 零依赖
可选 Ollama		 ❌ 需 LLM API ❌ 需 LLM API ✅ 无 ✅ 无 ❌ 多服务
🤖 AI Agent 集成
MCP 协议原生 ✅ 原生支持
cortex mcp		 ⚠️ 插件集成 ✅ 支持 ❌ 不支持 ❌ 不支持 ✅ 支持
MCP 工具数 🔧 5 个
搜索/上下文/记忆		 🔧 1-2 个 🔧 1 个 — — 🔧 1-2 个
Agent 记忆系统 ✅ 内置
长期记忆+RAG		 ✅ 专注
多层记忆		 ❌ 仅对话 ❌ 向量库 ❌ 向量库 ⚠️ 基础记忆
🔍 搜索
搜索类型 ✅ 混合搜索
向量+BM25+RRF		 ✅ 混合搜索 ✅ 向量搜索 ✅ 向量/混合 ✅ 混合搜索 ⚠️ 依赖后端
文件格式 📄 MD/PDF/DOCX
+代码文件		 — 纯记忆 ✅ 多格式 — 纯向量 — 纯向量 ✅ 多格式
📊 运维
内置监控 ✅ Prometheus
39 指标		 ⚠️ Dashboard ⚠️ 基础 ❌ 无 ❌ 无 ✅ Grafana
缓存加速 ✅ L1+L2 两级
内存+SQLite		 ⚠️ 基础缓存 ⚠️ 基础缓存 ❌ 无 ✅ 内存 ⚠️ 基础
隐私保护 ✅ 完全本地
100% 离线		 ⚠️ 本地/云 ✅ 完全本地 ✅ 完全本地 ✅ 完全本地 ⚠️ 本地/云
开源协议 ✅ MIT
商用自由		 ✅ Apache 2.0 ✅ MIT ✅ Apache 2.0 ✅ Apache 2.0 ⚠️ 附加条款

Cortex 的核心差异化：它是唯一一个同时具备「单二进制部署 + MCP 原生 + 内置记忆系统 + 混合搜索 + Prometheus 监控」的工具，专为 AI Agent 场景设计。

🎯 适用场景

场景 说明
🤖 AI Agent 记忆 让 Claude Code / OpenCode / Cursor 等 Agent 跨会话记住用户偏好和历史
📚 团队知识库 将团队 Wiki、技术文档、项目规范索引为可搜索的 RAG 知识库
🔍 代码库语义搜索 索引 Go/Python/JS 等代码，用自然语言搜索函数、类和实现
🏢 企业内部文档 员工手册、产品文档、培训材料的本地私密检索，数据不出内网
🧪 RAG 应用后端 作为 RAG pipeline 的检索层，提供 REST API 和 MCP 双协议接入
🔐 隐私敏感场景 金融、医疗、法律等需要 100% 本地部署的知识管理需求

✨ 更新日志

🚀 v3.2 进度系统 + 防卡死 + 性能优化 (2026-05-07)

🔥 v3.0.1 启动性能优化 (2026-05-07)

🚀 v3.1 多 Provider + 配置向导 (2026-05-07)

💰 v3.0 商业化版本 (2026-05-06)

🚀 v2.4 全面迭代完成 (2026-05-06)

🔥 v2.3 迭代升级 (2026-05-06)

🧠 v2.2 MCP 记忆工具 (2026-05-05)

🔥 v2.1 生产环境修复 (2026-04-25)

✨ v2.0 核心功能

⚡ 快速开始

# 1. 下载二进制
# macOS/Linux
curl -fsSL https://github.com/lh123aa/cortex/releases/latest/download/cortex-linux-amd64.zip | unzip -
chmod +x cortex

# Windows
# Invoke-WebRequest -Uri "..." -OutFile "cortex.zip"

# 2. 运行配置向导（选择 embedding provider）
./cortex setup

# 3. 索引文档（显示实时进度条，支持断点续传）
cortex index ~/my-docs

# 4. 高级索引选项
cortex index ~/my-docs --force           # 从头重新索引
cortex index ~/my-docs --timeout 30m     # 30 分钟超时
cortex index ~/my-docs --workers 32      # 32 个并发 worker

# 5. 启动 MCP 服务器（供 AI Agent 使用）
cortex mcp

# 6. 搜索
cortex search "如何实现 Go 并发"

# 7. 知识库去重
cortex dedup                    # 内容哈希去重
cortex dedup --mode vector      # 向量语义去重

# 8. 查看用量
cortex usage                    # 存储用量和套餐信息

✨ 核心特性

🚀 单二进制

下载即运行，无 Python/Node/Docker 依赖
curl → cortex mcp

🔌 MCP 原生

5 个 MCP 工具，AI Agent 开箱即用
cortex_search · cortex_memory_write

🧠 记忆系统

长期记忆 + RAG 上下文
Agent 跨会话记住用户偏好

🔍 混合搜索

向量语义 + BM25 关键词
RRF 融合排序，精准召回

⚡ L1+L2 缓存

内存 + SQLite 两级缓存
搜索速度提升 10x

📊 Prometheus

39 个监控指标
:9090/metrics

🗑️ 三层去重

内容哈希 + 向量语义 + MinHash
cortex dedup 一键清理

🔒 安全加固

IP 限流 / 密码策略 / Header认证
路径保护 / 文件大小限制

🐳 Docker 优化

多阶段构建
镜像 ~30MB

🔌 MCP 工具一览

工具 说明 对应 REST API
cortex_search 混合搜索（向量 + BM25） GET /v1/search
cortex_context RAG 上下文组装 GET /v1/context
cortex_memory_write 写入记忆条目 POST /v1/memory
cortex_memory_search 搜索记忆条目 GET /v1/memory/search
cortex_memory_delete 删除单条记忆 DELETE /v1/memory/:id
cortex_memory_delete_batch 批量删除记忆 —

🏗️ 系统架构

┌──────────────────────────────────────────────────────────┐
│                      Cortex CLI                          │
├──────────────────────────────────────────────────────────┤
│  index  │  search  │  context  │  serve  │     mcp       │
├──────────────────────────────────────────────────────────┤
│                  混合搜索引擎                              │
│      向量搜索 (HNSW)     │      FTS5 (BM25)              │
├──────────────────────────────────────────────────────────┤
│               L1+L2 两级缓存 (v2.1)                       │
│          go-cache (内存)   │     SQLite                   │
├──────────────────────────────────────────────────────────┤
│                    SQLite 存储层                           │
│    文档表   │  分块表   │  向量表   │  缓存表   │  用户表  │
├──────────────────────────────────────────────────────────┤
│                  MCP 协议 · REST API                      │
│     5 个 MCP 工具  │  15+ REST 端点  │  Prometheus       │
└──────────────────────────────────────────────────────────┘

技术栈：

📡 REST API

类别 端点 方法 说明
搜索 /v1/search GET 混合搜索（向量 + FTS）
  /v1/context GET RAG 上下文构建
记忆 /v1/memory POST 写入单条记忆
  /v1/memory/batch POST 批量写入记忆
  /v1/memory/search GET 搜索记忆
  /v1/memory/context GET 记忆 RAG 上下文
  /v1/memory/:id DELETE 删除记忆
认证 /auth/register POST 注册用户
  /auth/login POST 登录
  /auth/logout POST 登出
监控 /health GET 健康检查
  /metrics GET Prometheus 指标（:9090）

🔧 配置

# ~/.cortex/config.yaml
cortex:
  db_path: ~/.cortex/cortex.db
  log_level: info

embedding:
  provider: none              # none | ollama | openai | cohere | voyage | dashscope | zhipu | baidu
  auto_update: true           # 联网时自动检查最新模型

  # 本地 Ollama（离线场景默认）
  ollama:
    base_url: http://localhost:11434
    model: all-minilm         # 推荐: all-minilm(23MB), nomic-embed-text(137MB)

  # 国外 API
  openai:
    api_key: sk-xxx
    model: text-embedding-3-small
    dimension: 512
  cohere:
    api_key: co-xxx
    model: embed-multilingual-v3.0
    dimension: 1024
  voyage:
    api_key: pa-xxx
    model: voyage-3-lite
    dimension: 512

  # 国内 API
  dashscope:
    api_key: sk-xxx
    model: text-embedding-v2
    dimension: 1536
  zhipu:
    api_key: xxx
    model: embedding-3
    dimension: 2048
  baidu:
    api_key: xxx
    secret_key: xxx
    model: Embedding-V1
    dimension: 384

index:
  workers: 4
  max_tokens: 512

search:
  cache_ttl: 5m
  default_top_k: 10

prometheus:
  enabled: true
  port: 9090

📦 支持的文件格式

格式 支持 分块方式
Markdown (.md) ✅ 层级分块，标题路径追溯
PDF (.pdf) ✅ 文本提取，自动分块
Word (.docx) ✅ 段落解析，结构保持
纯文本 (.txt) ✅ 按行/段落分块
代码 (.go/.py/.js/.ts/.java 等) ✅ 按函数/类分块
配置 (.yaml/.json/.toml/.ini) ✅ 结构化提取

🛠️ 开发

git clone https://github.com/lh123aa/cortex.git
cd cortex
go build -o cortex ./cmd/cortex   # 纯 Go，无需 CGO
./cortex serve
go test ./...                     # 109 个测试
./cortex dedup                    # 一键去重

📊 性能

指标 值
记忆写入 < 200ms / 条
记忆搜索 P50 < 50ms（缓存命中 < 1ms）
记忆搜索 P95 < 100ms
RAG 上下文 精确 Token 裁剪
删除操作 < 50ms / 条
缓存命中率 > 60%（L1+L2 两级）
MinHash 去重 ~12μs / chunk (102k ops/sec)
向量去重效果 46/689 chunks 移除 (6.7%)
启动时间（全部 CLI 命令） < 0.5s（FTS5-only 模式，HNSW 按需异步加载）
FTS5 搜索 P50 < 50ms（20k 分块）
FTS5 搜索 P95 < 200ms（20k 分块）
索引吞吐量（FTS5-only） > 1000 files/min
实时进度反馈 动态进度条 · 速度/ETA/当前文件
中断恢复 Checkpoint 自动保存，重启续跑
单文件超时保护 5 分钟 Embedding 超时
内存占用 ~30 MB / 进程
二进制大小 34.2 MB (strip 优化)
测试覆盖率 10/10 包通过 · 全部核心逻辑有测试
Bug 状态 0 · FG 循环验证通过

🤝 贡献

📄 许可证

MIT License — 可自由使用、修改、商业化。

⭐ Star History

Star History Chart

💬 社区 & 支持

🔗 相关资源

Cortex 不是「又一个知识库工具」，而是 AI Agent 时代的基础设施。
在 MCP 协议生态快速发展的当下，它解决了一个真实且普遍的需求——给 AI Agent 装上持久记忆。单二进制、零配置、MCP 原生、MIT 开源，任何人都可以自由使用。

🧠 Cortex v3.0 — 让 AI Agent 拥有记忆
单二进制 · 零配置 · MCP 原生 · 完全本地 · MIT 开源

Star Fork Follow