🧠 Cortex
AI Agent 的第二大脑 — 本地知识库 · 单二进制 · MCP 原生
Cortex 是一个为 AI Agent 设计的本地知识库引擎。单二进制文件部署，原生支持 MCP 协议，内置混合搜索（向量+BM25）和Agent 记忆系统。100% 本地运行，零外部依赖。
给 Claude Code、OpenCode 等 AI Agent 装上永久记忆 🧠
GitHub 仓库 ·
🎨 营销落地页 ·
本地预览 ·
📖 深度技术文章
⬆️ 点击查看完整营销落地页（小米/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)
- ✅ **断点续传修复** — 中断后状态保持 `running`，下次运行自动恢复（修复：之前中断会错误标记为 completed）
- ✅ **实时进度条** — `cortex index` 显示动态进度条 `[████░░] 45%`，含速度、ETA、当前文件
- ✅ **Ctrl+C 安全退出** — 信号处理保存进度后优雅退出，不丢失已索引数据
- ✅ **全局超时** — `cortex index --timeout 30m` 超时自动保存进度退出
- ✅ **单文件超时** — Embedding 调用 5 分钟超时保护，防止卡死
- ✅ **`--force` 重新索引** — `cortex index --force path` 从头开始（忽略 checkpoint）
- ✅ **`--workers` 控制并发** — `cortex index --workers 32` 覆盖默认 16 个 worker
- ✅ **默认 16 workers** — I/O 密集型索引任务，吞吐量提升
### 🔥 v3.0.1 启动性能优化 (2026-05-07)
- ✅ **HNSW 按需加载** — `initStorageLight()` 跳过向量索引构建，所有 CLI 命令启动 <0.5s
- ✅ **默认切到 FTS5-only 模式** — `embedding.provider: none`，索引速度提升 28x，零外部依赖
- ✅ **根目录清理** — 从 39 项精简至 27 项，规划文档移入 `docs/planning/`，部署配置移入 `deploy/`，编译产物移入 `bin/`
- ✅ **文件组织规则** — 全局 AGENTS.md 新增 6 条强制规则，涵盖根目录守则、构建产出、临时文件、AI 文件生成
### 🚀 v3.1 多 Provider + 配置向导 (2026-05-07)
- ✅ **`cortex setup` 交互式向导** — 网络检测 → 选择 Provider → 输入 API Key → 选择模型 → 测试连接 → 写入配置
- ✅ **9 个 Embedding Provider** — 本地: none / ollama / onnx；国际: OpenAI / Cohere / Voyage AI；国内: 阿里DashScope / 智谱GLM / 百度ERNIE
- ✅ **工厂模式** — `NewProviderFromConfig()` 根据配置自动创建对应 Provider，无需修改 main.go
- ✅ **百度 OAuth2** — 自动缓存 access_token（30天有效期），自动刷新
- ✅ **默认模型 all-minilm** — 23MB，比 nomic-embed-text 快 30x
- ✅ **自动网络检测** — 离线时自动隐藏 API 选项，仅显示本地模式
### 💰 v3.0 商业化版本 (2026-05-06)
- ✅ **套餐系统** — Free (≤1GB) / Pro / Enterprise 三级
- ✅ **存储追踪** — `cortex usage` 查看用量和套餐
- ✅ **License Key** — 许可证生成/激活/验证系统
- ✅ **中文分词优化** — CJK 2-gram 分词器，搜索质量提升
- ✅ **搜索结果高亮** — CLI 匹配关键词用颜色标记
- ✅ **Web Admin 记忆管理** — 管理界面支持写入和搜索记忆
- ✅ **启动无警告** — `PRAGMA table_info` 智能迁移
- ✅ **测试覆盖** — 10/10 包通过，新增 storage/index 测试
### 🚀 v2.4 全面迭代完成 (2026-05-06)
- ✅ **三层去重体系** — 内容哈希 + 向量语义 (-46 chunks) + MinHash 近似去重
- ✅ **6 个 MCP 工具** — 新增 `cortex_memory_delete_batch` 批量删除
- ✅ **11 个 Storage 子接口** — DocumentStore / Searcher / CacheStore / UserStore 等
- ✅ **索引排除规则** — 自动跳过 `node_modules/.git/.opencode/` 等噪声目录
- ✅ **Web 管理界面** — `/admin` 嵌入式单页 (Go embed)，已接线可用
- ✅ **Docker 多阶段构建** — 镜像从 500MB → 30MB
- ✅ **CLI JSON 输出** — `--json` 标志支持结构化输出
- ✅ **MCP 错误码标准化** — 统一 `IsError` 协议响应
- ✅ **暴力破解防护** — `/auth` 端点 IP 级令牌桶限流 (5 req/s)
- ✅ **二进制优化** — `-ldflags="-s -w"` 压缩至 **34.2 MB**
- ✅ **分页搜索 / Grafana 监控模板 / Release 自动化 / 54 项迭代**
- ✅ 详见 [SYSTEM_EVALUATION.md](./SYSTEM_EVALUATION.md)
### 🔥 v2.3 迭代升级 (2026-05-06)
- ✅ **7 个 P0 紧急 Bug 修复** — Float32FromBytes 位转换、索引进度竞争、HNSW 并发、API Key 泄露、Token 过期等
- ✅ **10 项安全加固** — MCP 参数校验、密码策略增强、BM25 评分修正、ConfigWatcher 热加载、路径规范化
- ✅ **12 项质量提升** — 缓存 LRU 改造、余弦相似度收敛、RRF k 值配置化、死代码清理、Prometheus 自定义 Registry
- ✅ **CI/CD 全面升级** — Go 1.25 同步、govulncheck、测试覆盖率、Makefile 增强、VSCode 调试配置
- ✅ **29 项优化总计** — 详见 [TEST_REPORT.md](./TEST_REPORT.md) 和 [ITERATION_PLAN.md](./ITERATION_PLAN.md)
### 🧠 v2.2 MCP 记忆工具 (2026-05-05)
- ✅ **5 个 MCP 工具** — `cortex_search` / `cortex_context` / `cortex_memory_write` / `cortex_memory_search` / `cortex_memory_delete`
- ✅ **嵌入式零依赖模式** — `embedding.provider: none`，无需 Ollama，FTS5 全文搜索
- ✅ **纯 Go SQLite 驱动** — 改用 `modernc.org/sqlite`，无需 CGO/gcc，`go build` 即用
- ✅ **MCP 优雅关闭** — Signal 处理，Ctrl+C 安全退出
- ✅ **MCP 单元测试** — 11 个测试用例，覆盖全部工具边界条件
### 🔥 v2.1 生产环境修复 (2026-04-25)
- ✅ **L1+L2 两级缓存** — 内存 + SQLite 缓存，搜索速度提升 10x
- ✅ **Graceful Shutdown** — 优雅关闭，30s 内处理完现有请求
- ✅ **请求超时控制** — 默认 30s，搜索 60s，索引 5min
- ✅ **API 限流** — 令牌桶算法，100 req/s，突发 200
- ✅ **36 个测试用例** — 覆盖存储/认证/搜索核心模块
### ✨ v2.0 核心功能
- ✅ **记忆系统 API** — 完整的记忆写入/搜索/上下文/删除接口
- ✅ **认证持久化** — 用户/Token/APIKey 存储到 SQLite，重启不丢失
- ✅ **Prometheus 监控** — 39 个指标，端口 9090
---
## ⚡ 快速开始
```bash
# 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 │
└──────────────────────────────────────────────────────────┘
```
**技术栈：**
- **语言**: Go 1.25+ — 单二进制跨平台（纯 Go，无 CGO）
- **存储**: SQLite + WAL — 零配置嵌入式存储
- **向量**: HNSW — 高性能近似最近邻搜索
- **嵌入**: Ollama / ONNX / None（FTS5-only）
- **协议**: MCP SDK — AI Agent 原生通信
- **监控**: Prometheus — 39 个内置指标 + Grafana 模板
---
## 📡 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） |
---
## 🔧 配置
```yaml
# ~/.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) | ✅ | 结构化提取 |
---
## 🛠️ 开发
```bash
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 循环验证通过 |
---
## 🤝 贡献
- 🐛 发现 Bug？[提交 Issue](https://github.com/lh123aa/cortex/issues)
- 💡 有好想法？[讨论区](https://github.com/lh123aa/cortex/discussions)
- ⭐ 项目对你有帮助？点个 Star 支持
## 📄 许可证
**MIT License** — 可自由使用、修改、商业化。
---
## ⭐ Star History
[](https://star-history.com/#lh123aa/cortex&Date)
---
## 💬 社区 & 支持
- ⭐ **给个 Star** — 支持项目最好的方式
- 🐛 **报告 Bug** — [提交 Issue](https://github.com/lh123aa/cortex/issues)
- 💡 **功能建议** — [发起 Discussion](https://github.com/lh123aa/cortex/discussions)
- 📣 **分享推荐** — 在掘金、知乎、V2EX 推荐 Cortex
- 🤝 **贡献代码** — 阅读 [CONTRIBUTING.md](CONTRIBUTING.md)
## 🔗 相关资源
- [MCP 协议规范](https://modelcontextprotocol.io) — AI Agent 通信标准
- [Ollama](https://ollama.ai) — 本地 LLM & Embedding
- [OpenCode](https://opencode.ai) — AI Agent 框架
- [Awesome MCP Servers](https://github.com/lh123aa/awesome-mcp-servers) — MCP 服务器资源列表
---
Cortex 不是「又一个知识库工具」，而是 AI Agent 时代的基础设施。
在 MCP 协议生态快速发展的当下，它解决了一个真实且普遍的需求——给 AI Agent 装上持久记忆。单二进制、零配置、MCP 原生、MIT 开源，任何人都可以自由使用。
---
🧠 Cortex v3.0 — 让 AI Agent 拥有记忆
单二进制 · 零配置 · MCP 原生 · 完全本地 · MIT 开源
