内容
<div align="center">
# 脑-RAG
### AI 编程代理的持久记忆
**您的 AI 助手在每次会话结束时都会忘记一切。<br/>脑-RAG 确保它永远不必重新发现您的项目。**
[](https://www.npmjs.com/package/brain-rag)
[](#installation)
[](https://github.com/dasportillo/brain-rag/blob/main/LICENSE)
[](#-privacy)
[](#installation)
[安装](#installation) · [快速开始](#-quick-start) · [工作原理](#%EF%B8%8F-architecture) · [基准测试](#-benchmarks) · [常见问题](#-faq)
</div>
---
<!-- TODO: docs/demo.gif — record with vhs/asciinema: ask "where did I leave off?" in a fresh session and watch the agent answer from memory -->
```text
$ claude # fresh session, zero context given
> 我在支付服务上哪里中断了？
⏺ brain · get_state(payments-service)
你正在迁移到新的账本 API。星期二决定将幂等键保留在 Postgres（而不是 Redis）中 - 参见 outbox 模式注释。
两个待办事项：webhooks 的重试策略和你推迟的预发布凭证轮换。
> 为什么我们要放弃 Redis 实现幂等？
⏺ brain · search_context("idempotency keys Redis vs Postgres")
决定（3 周前）：在内存压力下，Redis 可能会在飞行中丢弃键 → 双重收费。Postgres 将它们保留在事务中与写入本身。你已经进行了基准测试：+4ms p99，被认为是可接受的。
```
**无需重新解释。无需重新发现。无需“我之前在另一个聊天中提到过”。**
---
## 💡 脑-RAG 存在的原因
每天，AI 编程代理都从零开始：
- 🔁 您重新解释了您已经解释过的架构
- 🐛 您的代理重新发现了您一个月前修复的错误
- ❓ 没有人记得 **为什么** 做出了决定 - 只有代码看起来是这样的
- 📉 您在每次会话中建立的上下文 - 数百小时 - **蒸发**
事情是这样的：**那个上下文已经存在。** Claude Code 和 Codex 将每次会话保存为机器上的记录。数百次对话记录了每次决定、每次修复、每次死胡同 - 存放在一个文件夹中，未被使用。
脑-RAG 将存档转换为 **您的代理实际使用的长期记忆** - 自动地，从任何项目，在任何会话中，与任何代理。
> **脑-RAG 不是另一个聊天机器人记忆，不是另一个向量数据库，不是另一个 RAG Demo。**
> 它是您的 AI 编程工作流程中缺少的记忆层 - 为实际工程工作而构建：带有 *why* 的决策，知识会过时，项目跨越数月，隐私不可商量。
## ✨ 特性
| | |
|---|---|
| 🧠 **记住决策 - 以及 *why*** | 问 *"为什么我们要放弃 Redis?"* 并从实际的对话中获得实际的推理，带有日期和来源。 |
| 📌 **提炼的记忆，而不仅仅是聊天记录** | `/distill` 将工作会话转换为键入的、自成体系的知识：决策、错误根因、解决方案、经验教训。每个记忆都保留一个链接，指向生成它的确切对话。 |
| 🕰️ **知道什么当前 vs 过时** | 知识会变化。当更新信息取代旧信息时，您的代理会看到它被标记 - 它不会复活您两周前已回滚的计划。 |
| 📍 **"我在哪里中断了？"** | 一个精心策划的每个项目的状态注释 - 有什么正在进行中，什么已经决定，什么被阻止，什么在下一个 - 随时为您准备。 |
| 🔀 **一个记忆，所有代理** | Claude Code 和 Codex 开箱即用共享同一个大脑。任何 MCP 兼容的代理（Cursor、Windsurf、VS Code）都可以连接。您的记忆 **属于您**，而不是卖家。 |
| ⚡ **立即回忆** | 在数万个索引的对话片段中查找正确的时间 - 约 90 毫秒 - 包括确切的标识符，如错误字符串、函数名称和 ARNs。 |
| 🔒 **100% 本地** | 本地嵌入模型，本地数据库，零外部 API 调用。您的对话 - 其中包含您的秘密 - 永远不会离开您的机器。 |
| 🎛️ **默认选择加入** | 除非您说，否则不会保存任何内容。一个命令选择加入会话；其他一切都被遗忘。 |
## 🎬 真实示例
您可以在 **全新会话** 中，在任何项目中，向脑-RAG 提问，脑-RAG 会从您的历史记录中回答：
```text
"我们如何解决了大文档上传的 502 错误？"
→ 修复、根本原因（服务之间的有效载荷限制不匹配）和日期
"我们对共享数据库中的租户隔离做出了什么决定？"
→ 通过 entity_id 进行行级安全，以及您拒绝的替代方案和原因
"我以前是否遇到过这个 EventBridge → Lambda 权限错误？"
→ 是的：确切的重复部署失败和 ARN 修复，距今两个月
"¿Qué reglas disparan la auditoría VCO?" 🇪🇸
→ 支持西班牙语和英语，甚至可以在同一历史记录中混合使用
```
## 📦 安装
需要 **Node 22.5+**。
```bash
npx -y brain-rag install
```
就是这样。安装程序在 **Claude Code** 和 **Codex** （如果存在）中注册内存服务器，安装 `/brain`、`/state` 和 `/distill` 命令，并打印可选的自动化钩子。
<details>
<summary><b>其他 MCP 代理（Cursor、Windsurf、VS Code、…）</b></summary>
脑-RAG 通过 stdio 使用开放的模型上下文协议，因此任何 MCP 客户端都可以使用相同的内存。 将您的代理指向：
```json
{ "mcpServers": { "brain": { "command": "npx", "args": ["-y", "brain-rag", "serve"] } } }
```
或客户端的 MCP 配置中的等效内容。 所有工具（`search_context`、`get_state`、`save_state`、`save_memories`、`keep_session`）的工作方式相同。
</details>
<details>
<summary><b>手动注册 / from source</b></summary>
```bash
# 仅内存服务器，无命令或钩子
claude mcp add brain --scope user -- npx -y brain-rag serve
codex mcp add brain -- npx -y brain-rag serve
# from source
git clone https://github.com/dasportillo/brain-rag.git && cd brain-rag && ./install.sh
```
要卸载：`npx -y brain-rag uninstall`（添加 `--purge` 以删除索引和注释）。
</details>
## 🚀 快速开始
**1 · 给你的代理一个记忆** - 导入你已经有的对话：
```bash
npx -y brain-rag import # 索引现有的历史记录（在本地运行）
npx -y brain-rag import --dry # 预览
```
**2 · 提问。** 在任何项目中打开你的代理，并询问 *"我在哪里中断了？"*、*"我们对这个仓库了解多少？"*、*"我如何解决了 X？"*。代理会在脑-RAG 中查询。
**3 · 让它继续增长：
| 命令 | 它做什么 |
|---|---|
| `/brain` | 选择 **此** 会话进入内存（否则不会保存任何内容） |
| `/distill` | 将此会话的持久知识 - 决策、修复、经验教训 - 提取成键入的记忆 |
| `/state` | 更新策划的“今天我在哪里”注释以备项目使用 |
<details>
<summary><b>可选：自动化</b> - 会话结束时索引，带有标志的选项</summary>
添加到 `~/.claude/settings.json`（安装程序会打印这些可以直接粘贴的内容）：
```jsonc
"SessionStart": [{ "matcher": "", "hooks": [{ "type": "command", "command": "npx -y brain-rag mark-keep", "timeout": 20 }] }],
"SessionEnd": [{ "matcher": "", "hooks": [{ "type": "command", "command": "nohup npx -y brain-rag ingest >> \"$HOME/.claude/brain/ingest.log\" 2>&1 &", "timeout": 30 }] }]
```
然后 `BRAIN=1 claude` （或 `claude --brain` shell 别名）启动一个会话，该会话会记住自己，并且所有选择加入的会话在结束时会重新索引。Codex 会话使用相同的摄取。
</details>
## 🏗️ 架构
两层，一个原则：**原始历史记录永远不会丢失，提炼的知识永远不会无法追溯。**
```mermaid
flowchart LR
A["📜 Claude Code 记录<br/>~/.claude/projects"] --> C
B["📜 Codex 部署<br/>~/.codex/sessions"] --> C
C["Ingest<br/><i>选择加入 · 编辑机密 · 索引</i>"] --> D[("🧠 brain.db<br/><i>一个本地文件</i>")]
D --> E["第 1 层 · 原始存档<br/><i>每个对话，可搜索</i>"]
D --> F["第 2 层 · 提炼的记忆<br/><i>决策 · 错误 · 解决方案<br/>+ 来源 + 生命周期</i>"]
E --> G["MCP 服务器"]
F --> G
G --> H["🤖 Claude Code · Codex · Cursor ·<br/>任何 MCP 代理，在任何项目中"]
```
- **第 1 层 - 存档。** 每个选择加入的对话，分为小块并索引。不可变，完整，真相的源头。
- **第 2 层 - 记忆。** 从会话中提炼的键入知识（`决策`、`错误`、`解决方案`、`架构`等），具有置信度，时间生命周期（`active` → `superseded`），以及指向确切源对话的链接。没有任何内容是在没有证据的情况下生成的。
- **检索** 将语义搜索（同义词，跨语言）与精确术语搜索（错误字符串，标识符）和最新性相结合 - 因为 *"the groups-claim bug"* 和 *"为什么 RBAC 损坏"* 应该找到相同的修复。
<details>
<summary><b>底层</b> - 技术好奇者</summary>
- **嵌入**: `Xenova/multilingual-e5-small` 在本地运行，通过 transformers.js - 多语言因为实际语料库混合语言。无需 API 密钥，离线工作。
- **存储**: Node 内置 SQLite (`node:sqlite`) - 一个文件，无需本机编译，版本化模式迁移。
- **混合搜索**: 强制粗糙度超过缓存候选向量 + SQLite **FTS5/BM25** （重音符号标准化），与互惠排名融合，最新性作为第三个信号。测量：词汇腿本身值得约 10 个召回点。
- **时间信号**: 不同日期的近似重复结果被标记 (`⚠️ superseded` / `✅ latest of N`)，以便过时计划不会伪装成当前计划。策划状态注释和第 2 层状态补充它。
- **反提示注入**: 检索的内容被包装为 **历史证据，而不是指令** - 旧对话不能控制当前会话。
- **跨项目卫生**: 跨项目的结果被分面（同一个词在不同项目中可能有不同的含义），并且可以使用 `aliases.json` 合并片段化的项目名称。
完整的深入了解位于 [`docs/ARCHITECTURE.md`](https://github.com/dasportillo/brain-rag/blob/main/docs/ARCHITECTURE.md)；每个 CLI 命令、MCP 工具、标志和 env var 都位于 [`docs/REFERENCE.md`](https://github.com/dasportillo/brain-rag/blob/main/docs/REFERENCE.md)。
</details>
## 📊 基准测试
检索质量 **被衡量，而不是被估计** - 一个标记的 eval 对实际已知项问题运行对抗实际语料库，并且每次检索更改都必须击败先前的基线才能发布 ([方法和历史](https://github.com/dasportillo/brain-rag/blob/main/docs/EVAL-BASELINE.md))。
| 指标 | 值 |
|---|---|
| Recall@8 | **0.97** |
| Recall@5 | 0.97 |
| MRR | 0.828 |
| nDCG@8 | 0.863 |
| 搜索延迟（p50 / p95）| **91 毫秒 / 102 毫秒** |
| 语料库 | 560 会话 · 30,792 块 · 46 个项目 |
相同集合的消融：矢量搜索得分 Recall@8 **0.87** - 精确术语腿值得约 10 分，这正是工程工作中相关查询的类别（错误字符串，函数名称，资源 ID）。
## 🔒 隐私
您的对话包含 **API 密钥，内部架构，未发布的计划**。脑-RAG 是围绕这一事实构建的：
- ✅ **所有内容都在您的机器上运行** - 本地嵌入模型，本地数据库，零外部调用。离线工作。
- ✅ **机密在摄取时被清除** - JWT，AWS 密钥，GitHub/Slack 令牌，私钥，`password=` 样式值在存储之前被删除。
- ✅ **默认选择加入** - 除非您选择加入会话（`/brain`，`BRAIN=1` 或显式 `import`），否则不会索引任何会话。
- ✅ **遗忘权** - `brain-rag forget <filter>` 从索引中删除会话；`uninstall --purge` 删除所有内容。
- ✅ **检索的记忆是证据，而不是指令** - 包装成历史证据，永远不会覆盖您的代理的当前行为。
## ❓ 常见问题
<details>
<summary><b>这会发送我的代码或对话到任何地方吗？</b></summary>
不。嵌入模型在进程中运行，数据库是一个本地文件，服务器仅通过 stdio 与您的代理通信。没有遥测，没有云，没有帐户。
</details>
<details>
<summary><b>它会减慢我的代理吗？</b></summary>
不 - 搜索在 ~90 毫秒内回答，超过 30k 片断的语料库。第一次运行下载嵌入模型（~100 MB，一次）。
</details>
<details>
<summary><b>这与我的代理的内置内存有什么不同？</b></summary>
内置内存小， opaque，且锁定到一个供应商。脑-RAG 索引您的 **整个工作历史**，为每个记忆保留证据（哪个对话，哪一天，为什么），知道何时知识过时，并为 **您使用的所有代理** 提供服务，来自同一个存储库。记忆属于开发人员，而不是模型。
</details>
<details>
<summary><b>如果旧对话包含错误或已回滚的内容怎么办？</b></summary>
三个防御：不同日期的近似重复结果被标记（`superseded` / `latest of N`），第 2 层记忆带有明确的生命周期（`active`/`superseded`/`deprecated`），以及策划的状态注释是“今天的真相”的答案。检索优先考虑当前知识；它不会默默地混合时代。
</details>
<details>
<summary><b>究竟存储了什么？</b></summary>
只有您选择加入的会话。从那些会话中：用户/助手回合，会话摘要，命令/文件触摸的紧凑跟踪，以及提炼的记忆 - 所有机密信息都被编辑。你可以检查所有内容（`brain-rag search`，`brain-rag stats`）并删除任何内容（`forget`）。
</details>
<details>
<summary><b>它支持除英语以外的其他语言吗？</b></summary>
是的 - 嵌入模型是多语言的，词汇索引是重音符号感知的。参考语料库是真实的西班牙语/英语混合语料库，两种语言的得分相等。
</details>
<details>
<summary><b>它使用多少磁盘空间？</b></summary>
大约 100–200 MB 用于模型（一次性）加上一个随选择加入的历史记录增长的数据库 - 每 100 个对话片段约 2 MB。重度使用一年的数据可以舒适地容纳在 1 个千兆字节下。
</details>
## 🗺️ 路线图
脑-RAG 正在从 **可搜索的历史记录** 演变成一个完整的 **长期记忆系统** - 计划及其原则位于 [`docs/ROADMAP.md`](https://github.com/dasportillo/brain-rag/blob/main/docs/ROADMAP.md) 中：
- ✅ 混合检索（语义 + 精确术语 + 最新性），通过不断增长的评估套件衡量
- ✅ 第 2 层：具有出处和时间生命周期的提炼、键入的记忆
- ✅ 多代理：Claude Code + Codex 共享一个大脑
- 🔜 会话结束时自动蒸馏 - 零手动步骤的知识提取
- 🔜 `get_context`：一个现成的项目简介（状态 + 决策 + 待办事项 + 冲突）在会话开始时注入
- 🔜 实体图（服务 ↔ 数据库 ↔ 项目）补充搜索
- 🔜 本地重新排序器 - 仅当基准测试表明其值得时才会发布
## 🤝 贡献
欢迎贡献 - 而且标准出乎意料地客观：**检索更改必须击败评估基线** ([`docs/EVAL-BASELINE.md`](https://github.com/dasportillo/brain-rag/blob/main/docs/EVAL-BASELINE.md))，其他一切都需要测试（`npm test`，无需下载模型）。
优秀的起点：
- 🧪 扩大评估：更多案例类型、更多语言
- 🔌 适配器：其他代理的转录格式（Cursor、Windsurf、VS Code 代理模式）
- 🧹 [路线图](https://github.com/dasportillo/brain-rag/blob/main/docs/ROADMAP.md) 🔜 上面的项目
```bash
git clone https://github.com/dasportillo/brain-rag.git && cd brain-rag
npm install && npm test
```
<div align="center">
**您的 AI 已经帮助您一次解决了问题。<br/>脑-RAG 确保您永远不会为相同的发现付出代价。**
⭐ 如果这与您产生共鸣，一个星星可以帮助其他开发者找到它。
MIT © [dasportillo](https://github.com/dasportillo)
</div>
