内容
="center">
<img alt="Cortex Logo" src="./assets/cortex-logo.svg" width="800" />
</p>
<p align="center">
<a href="https://github.com/lleontor705/cortex/actions/workflows/ci.yml"><img src="https://github.com/lleontor705/cortex/actions/workflows/ci.yml/badge.svg" alt="持续集成" /></a>
<a href="https://github.com/lleontor705/cortex/releases/latest"><img src="https://img.shields.io/github/v/release/lleontor705/cortex?label=发布版本&color=2ac3de" alt="发布版本" /></a>
<a href="https://github.com/lleontor705/cortex/blob/master/LICENSE"><img src="https://img.shields.io/badge/许可证-MIT-bb9af7.svg" alt="许可证" /></a>
<a href="https://goreportcard.com/report/github.com/lleontor705/cortex"><img src="https://goreportcard.com/badge/github.com/lleontor705/cortex" alt="Go 报告卡" /></a>
</p>
<p align="center">
<a href="docs/INSTALLATION.md">安装</a> •
<a href="docs/AGENT-SETUP.md">代理设置</a> •
<a href="docs/BENCHMARKS.md">基准测试</a> •
<a href="docs/ARCHITECTURE.md">架构</a> •
<a href="docs/RECOMMEND">推荐</a>;
<a href="ING.md">贡献>
</p>
---
Cortex** — 大层，负责记忆、感知和认知。
您的程代理在会话结束所有内容。 **Cortex 给了它一个大脑**带有知识图、向量时间推理。单个 Go 二进制文件。零云依赖。
```
代理（Claude Code / Cursor / Gemini CLI / Codex / VS Code / OpenCode / ...）
| MCP stdio
Cortex（单个 Go 二进制文件）
|
SQLite + FTS5 + 知识图 + 向量搜索 + 评分
```
## 为什么选择 Cortex？
| | Cortex | Mem0 | Zepiti | claude-m|---|:---:|:---:|:---:|
| **单个二进制文件** | Go | Python + Neo4j/Qdrant | Python + Neo4j | TS + Python + ChromaDB |
| **知识图** | SQLite 原生 | Neo4j（云） | Neo4j（云） | 否 |
| **向量搜索** | Ollama（本地）或 OpenAI | Qdrant/Pinecone | Neo4j 向量 | ChromaDB |
| **时间推理** | 内置 | 否 | Graphiti | 否 |
| **隐私** | 100% 本地 | 云选项 | 云选项 | 本地 |
| **代理锁定** | 无（MCP） | LangChain 中心 | Python SDK | 仅 Claude |
| **设置** | `go install` | pip + docker | pip + docker | npm + bun + uv |
## 快速入门
```bash
# 安装
brew install lleontor705/tap/cortex # macOS / Linux
go install github.com/lleontor705/cortex/cmd/cortex@latest # 所有平台
# 设置您的代理
cortex setup claude-code # 或：opencode, gemini-cli, codex
```
就这样。无需 Node.js，无需 Python，无需 Docker。 **一个二进制文件，一个 SQLite 文件。**
<details>
<summary>VS Code、Cursor、Windsurf 和其他 MCP 客户端的设置</summary>
| 代理 | 设置 |
|-------|-------|
| VS Code (Copilot) | `code --add '{"name":"cortex","command":"cortex","argscp"]}'` |
| Cursor | 添加到 `.cursor/m` |
| Windsurf到 MCP 配置代理配置、内存协议生存：[docs/AGSETUP.md/AGENT-SET)
</details>
<detailssummary>从 Engram 迁移？</summary>
cortex import --ram --path ~/.eng.db
```
兼容。14 个 Engram MCP完全相同。C 8 个工具。脚本：[`igrate-from-engram.sh`](scripts/migrate-from-engram.sh)
</details>
## 工作原理
```
1. 重要工作（修复 bug决策等）。
2.调用 mem_save ->、类型、什么/哪里/学到了什么. Cortex 持久化到 SQLite，带有 FTS索引和自动嵌入. 实体自动提取（文件、URL、包、符号）。
5. 代理通过知识图（mem_relate）关联观察结果。
6. 下一个会话：代理搜索内存 -> FTS5 + 向量 + 图表增强。
```
## 功能
### 内存引擎
- **全文搜索（FTS5）**，带有 BM25和主题关键词查找 **向量搜索通过 Ollama（本地）或 OpenAI混合 FTS5 + 余弦相似度与 R融合。
-图**，带有类型`references`、`relates_to`、`followssupersedes`、`contradicts`）和 BFS 遍历。
- **时间推理 按特定日期搜索，带有有效性窗口的边。
- **重要性评分** — `base + typeBonus + + recencyBonus agePenalty`制 [0.0, 5.0 智能
- **** — 从观察自动提取文件、URL、包、符号。
- **内存巩固** — 跨会话查找和合并重复主题键。
- **项目 DNA** — 自动生成结构化的项目摘要（决策、模式、陷阱）。
- **自动归档** — 定期软删除旧的低重要性观察结果 开发人员体验
-式 TUI**带有搜索、图形查看器、健康仪表板的 屏 BubbleTea 终端 UI。
- **健康检查** — `cortex doctor` 验证数据库、FTS5、图形、向量和孤儿检测。
- **批量重索引 `cortex reindex` 为所有观察结果生成- **代理无关** — MCP 客户端：Claude Code、Cursor、Gemini CLI、Codex、VS Code、OpenCode、Windsurf、Antigravity
## 基准测试
在 [LOCOMO](https://github.com/search/locomo) 2024）上评估 — 1,986，涵盖 10 个长期对话：
| 搜索模式 | 单跳 | 时间 | 与相比 |
|-------------|:---------:|:---------:|:--------:|:-----------:|
| 仅 FTS5 | 0.002 | 0.001 | 0.000 | — |
| **+ Ollama**（本地，免费） | **0.025** | **0.016** | **0.026** | **12-16 倍** |
| **+ OpenAI**（云） | **0.026** | **0.016** | **0.037**13-37 倍** |
> 检索的 F1 token 重叠。C找到相关内存 — 代理的 LLM 在此基础上生成答案。
| 提供商 | 成本 | 隐私 | 延迟 | 最适合 |
|----------|:----:|:-------:|:-------:|----------|
| **Ollama** | $0 | 100% 本地 | ~90ms | 默认（推荐） |
| OpenAI | ~$0.02/1 | 云 | ~ 最大时间质量 |
| 无 | $0地 | <1ms | 快速启动，仅限完整的 方法论 和 可[docs/BENCHMARKS.md](docsCHMARKS.md) | 提供商指南：[RECOMMENDATIONS.md](docs/RECOMM)
## MCP 22）
<details>
<summary><strong>14 个核心工具</strong> Engram 兼容>
| 工具 | 目的 |
|------|| `mem_save` |结果，格式/Why/Where |
| `mem_search 带有筛选器的 + 可选的图形| `mem_context 最近会话上下文聚合 `mem_session_summary`话结束时综合保存 |
| `mem_get_ | 按 ID 获取 |
| `mem_save_prompt` | 保存用户提示上下文使用 |
|` | 按观察结果 |
| `mem_suggest_topic_key`变主题的稳定| `mem_session | 注册会话开始 |
| `mem_session_end`标记会话完成 |
mem_capture_passive` | 从代理输出中提取学习结果 |
| `mem_delete` | 软或硬删除 |
| `mem_stats` | 内存系统统计信息 |
| `mem_timeline` | 围绕观察结果的时间顺序钻取 |
</details>
### 8 个 Cortex 独家工具
| 工具 | 目的 |
|------|---------|
| `mem_relate` | 在观察结果之间创建类型化关系 |
| `mem_graph` | 遍历知识图（BFS，深度 1-10） |
| `mem_score` | 获取/重新计算重要性分数 |
| `mem_search_hybrid` | FTS5 + 向量搜索，带有 RRF 融合 |
| `mem_search_temporal` | 按特定日期搜索 |
| `mem_consolidate` | 查找重复主题键以合并 |
| `mem_project_dna` | 生成结构化项目摘要 |
| `mem_archive` | 软删除观察结果 |
## 命令行界面
```bash
cortex setup [agent] # 安装代理集成
cortex search <query> # 搜索内存
cortex save <title> <content> # 保存内存
cortex tui # 启动交互式终端 UI
cortex doctor # 健康检查（数据库、FTS5、图、向量）
cortex reindex [--project P] # 生成向量嵌入
cortex gc [--days N] # 垃圾回收已归档的观察结果
cortex serve # 启动 HTTP REST API（端口 7438）
cortex mcp [--tools=PROFILE] # 启动 MCP 服务器（stdio）
cortex stats # 内存统计信息
cortex export [--project P] # 导出到 JSON
cortex import --from-engram # 从 Engram 数据库导入
cortex migrate <up|down> # 管理数据库迁移
```
## 配置
```yaml
# cortex.yaml
database:
path: cortex.db
pragma:
journal_mode: WAL
search:
default_limit: 20
embedding_provider: ollama # ollama | none
memory:
auto_archive_days: 90
min_archive_score: 0.1
lifecycle:
enable_auto_archive: true
```
环境变量覆盖：`CORTEX_DATABASE_PATH`、`CORTEX_SEARCH_EMBEDDING_PROVIDER` 等。
## 架构
```
cmd/cortex/ 命令行界面入口
internal/
app/ 依赖连接（配置 -> 数据库 -> 存储 -> MCP）
mcp/ 22 个 MCP 工具处理程序
http/ REST API 服务器（17 个端点）
tui/ BubbleTea 终端 UI（12 个屏幕）
embedding/ Ollama + OpenAI 嵌入服务
domain/
memory/ 观察结果 CRUD、去重、主题键更新
graph/ 带有 BFS 遍历的知识图
scoring/ 重要性评分公式
temporal/ 时间边有效性 + 矛盾处理
dna/ 项目 DNA 生成
entity/ 实体提取（文件、URL、包、符号）
lifecycle/ 自动归档服务
store/
sqlite/ 观察结果存储 + 向量存储
search/ FTS5 搜索 + 图表邻居扩展
graph/ 带有时间过滤的边存储
scoring/ 重要性分数存储
session/ 会话生命周期存储
entity/ 实体链接存储
migration/ 版本跟踪的 SQL 迁移（001-009）
bench/ 基准测试框架（LOCOMO、DMR、LongMemEval）
```
完整的架构细节：[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
## 文档
| 文档 | 描述 |
|-----|-------------|
| [安装](docs/INSTALLATION.md) | Homebrew、go install、二进制文件、Docker |
| [代理设置](docs/AGENT-SETUP.md) | 每个代理的配置 + 内存协议 |
| [架构](docs/ARCHITECTURE.md) | 设计、评分公式、图、API、模式 |
| [基准测试](docs/BENCHMARKS.md) | LOCOMO/DMR 结果、方法论、可重复性 |
| [推荐](docs/RECOMMENDATIONS.md) | 嵌入提供商指南、性能调优 |
| [插件](docs/PLUGINS.md) | Claude Code 钩子 + OpenCode TypeScript 插件 |
| [比较](docs/COMPARISON.md) | Cortex vs Engram vs claude-mem |
| [贡献](CONTRIBUTING.md) | 贡献工作流程 + 标准 |
## 许可证
MIT
---
<p align="center">
建立在 <a href="https://github.com/Gentleman-Programming/engram">Engram</a> 的基础上<br>
<em>增强了知识图、向量搜索、时间推理和项目 DNA</em><br>
<em>适用于下一代 AI 编程助手。</em>
</p>
