🧠 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% 本地部署的知识管理需求

⚠️ 已知限制

FTS5-only 中文搜索：当前使用 SQLite FTS5 unicode61 tokenizer + 单字展开。中文搜索能"搜到"但不如专用分词器（如 jieba）"精准"。如需更高精度，建议配置向量 embedding provider（Ollama/OpenAI 等）。
API 文档标记：GET /health/ready 和 GET /health/live 为计划中的端点，尚未实现。

✨ 更新日志

🐛 v3.3.1 Bug 修复 + 安全加固 (2026-05-13)

✅ cortex version 命令 — 新增版本号查询
✅ HTTP 服务器安全加固 — ReadTimeout/WriteTimeout/ReadHeaderTimeout/MaxHeaderBytes
✅ channel 双 close 防护 — StopAutoBackup()/watcher.Stop() 使用 sync.Once 防 panic
✅ 文件监听内存泄漏修复 — debounceMap 定时清理过期条目
✅ 中文搜索健壮性 — expandChineseQuery 改用 strings.HasSuffix 代替字节索引
✅ 回归测试 — 10/10 包通过，go vet 零警告

🚀 v3.3 中文搜索修复 + 文件监听 + 性能优化 (2026-05-13)

✅ 中文搜索修复 — 从 2-gram 改为单字分词，FTS5 中文搜索正常匹配
✅ 文件排除规则 — 自动跳过 50+ 种二进制/多媒体扩展名，索引失败降 95%，提速 3.5x
✅ cortex watch 命令 — 基于 fsnotify 的文件监听，变更自动增量索引
✅ cortex_health MCP 工具 — 第 7 个 MCP 工具，健康检测 + 文档统计
✅ 搜索结果展示优化 — Content 存原文（无空格），标题用文件名代替"section"
✅ PDF/DOCX 中文搜索 — PDF 和 Word 文件添加中文分词支持
✅ 配置热加载 — cortex serve 修改 config.yaml 自动生效，无需重启
✅ 配置向导默认认证 — cortex setup 首次配置自动开启 auth_enabled: true
✅ 自动定时备份 — 24h 间隔自动备份，保留最近 10 份
✅ 全量重建 — --force 标志跳过内容哈希，新分词/新规则即时生效
✅ 断点续传修复 — 中断后状态保持 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

🔥 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 和 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

⚡ 快速开始

# 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. 文件监听（自动增量索引）
cortex watch ~/my-docs                    # 文件变更自动重新索引

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

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

# 8. 配置热加载（serve 模式下自动启用）
cortex serve                              # 修改 config.yaml 无需重启

# 9. 知识库去重
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_health`	健康检测 + 状态统计	`GET /health`

🏗️ 系统架构

┌──────────────────────────────────────────────────────────┐
│                      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）

🔧 配置

# ~/.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 精确匹配
索引吞吐量（FTS5-only）	> 1000 files/min（优化后 ~460 files/s）
全量索引（18k 文件）	~40 秒
索引失败率	< 5%（优化后，自动跳过二进制/多媒体）
实时进度反馈	动态进度条 · 速度/ETA/当前文件
中断恢复	Checkpoint 自动保存，重启续跑
文件监听	`cortex watch` · fsnotify 实时增量索引
单文件超时保护	5 分钟 Embedding 超时
配置热加载	`cortex serve` 修改配置无需重启
自动备份	24h 间隔 · 保留最近 10 份
内存占用	~30 MB / 进程
二进制大小	34.2 MB (strip 优化)
测试覆盖率	10/10 包通过 · 全部核心逻辑有测试
MCP 工具	7 个（search/context/memory×4/health）
Bug 状态	0 · FG 循环验证通过

🤝 贡献

🐛 发现 Bug？提交 Issue
💡 有好想法？讨论区
⭐ 项目对你有帮助？点个 Star 支持

📄 许可证

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

⭐ Star History

💬 社区 & 支持

⭐ 给个 Star — 支持项目最好的方式
🐛 报告 Bug — 提交 Issue
💡 功能建议 — 发起 Discussion
📣 分享推荐 — 在掘金、知乎、V2EX 推荐 Cortex
🤝 贡献代码 — 阅读 CONTRIBUTING.md

🔗 相关资源

MCP 协议规范 — AI Agent 通信标准
Ollama — 本地 LLM & Embedding
OpenCode — AI Agent 框架
Awesome MCP Servers — MCP 服务器资源列表

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

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

Name		Name	Last commit message	Last commit date
Latest commit History 91 Commits
.github		.github
.opencode		.opencode
.vscode		.vscode
cmd/cortex		cmd/cortex
deploy		deploy
docs		docs
downloads		downloads
internal		internal
scripts		scripts
test_framework		test_framework
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.en.md		README.en.md
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum

Folders and files

Latest commit

History

Repository files navigation

🧠 Cortex

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

📊 产品对比

🎯 适用场景

⚠️ 已知限制

✨ 更新日志

🐛 v3.3.1 Bug 修复 + 安全加固 (2026-05-13)

🚀 v3.3 中文搜索修复 + 文件监听 + 性能优化 (2026-05-13)

🔥 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 核心功能

⚡ 快速开始

✨ 核心特性

🚀 单二进制

🔌 MCP 原生

🧠 记忆系统

🔍 混合搜索

⚡ L1+L2 缓存

📊 Prometheus

🗑️ 三层去重

🔒 安全加固

🐳 Docker 优化

🔌 MCP 工具一览

🏗️ 系统架构

📡 REST API

🔧 配置

📦 支持的文件格式

🛠️ 开发

📊 性能

🤝 贡献

📄 许可证

⭐ Star History

💬 社区 & 支持

🔗 相关资源

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages