内容
# YourBrain (`yb`)
**一个本地优先的内存引擎，为AI编码代理提供持久、连贯的长期记忆，并具有一流的冲突解决能力。**
YourBrain 是一个单一的 Rust 二进制文件 (`yb`)，可以与任何支持 MCP 的 AI IDE 插件，并记住重要的事情 - 决策、约定、陷阱、您的偏好 - 并在它们增长时保持该记忆的连贯性。无需运行服务器，无需配置数据库，无需云依赖。默认情况下，所有内容都是本地的。
---
## 问题：代理 AI 存在失忆问题
今天的 AI 编码代理非常出色，但它们是**无状态的**。每次新的聊天都从零开始：
- **它们会忘记。** 架构决策、命名约定、上周修复的错误、您迁移出 Postgres 的事实 - 所有这些都在会话结束时消失。您一次又一次地重新解释相同的上下文。
- **它们会浪费令牌和时间。** 在每个提示中重新粘贴上下文会烧毁令牌（和钱），并使您变慢。
- **它们会产生幻觉和矛盾。** 没有可靠的记忆，代理会自信地陈述三次重构之前正确的事情 - 或从未正确的事情。
- **"记忆" 工具只是堆积如山。** 大多数附加记忆只是一个只追加的向量存储。它可以告诉您 *"关于 X 我说了什么？"* 但永远不会注意到 *"我们使用 JWT"* 之后被 *"我们切换到会话 cookie"* 替换。几个月后，记忆就会变成一堆相互冲突的半真半假。
MCP 给了代理**工具**。它没有给他们一个**连贯的长期记忆**。
## YourBrain 的功能 - 以及它的重要性
YourBrain 是内存层。您的代理在回答和学习某些持久的东西之前会调用它。
| 没有 YourBrain | 有 YourBrain |
|---|---|
| 每次会话都重新解释上下文 | 代理立即回忆之前的决策 |
| 记忆会悄悄过期 | 冲突被**检测和解决**在写入时 |
| 大提示，高令牌成本 | 令牌预算，压缩回忆 |
| 自信的幻觉 | 答案**与知识库进行事实核查** |
| 重复的问答重新计算 | **语义缓存** 重用可靠的答案 |
| 云锁定，隐私风险 | 100% 本地，单个二进制文件，您的数据保留原样 |
**区别在于冲突引擎。** 当新知识重复、取代或与之前存储的知识相矛盾时，YourBrain：
- 在写入时检测到它（重复 / 取代 / 矛盾），
- 自动解决安全案例，并询问人类解决模糊案例，
- 保留**审计时间线** 和 **关系图** （`取代`、`矛盾`、`补充`...），因此历史永远不会丢失。
## 功能
| 能力 | 它为您提供什么 |
|---|---|
| **冲突解决** | 基于规则的重复/取代/矛盾检测，具有自动解决阈值。更高的层级（NLI / LLM) 可以通过特征插件。 |
| **混合搜索** | SQLite **FTS5** 关键词搜索与 **向量** 相似性（互惠排名融合），按时间/重要性/置信度重新排序。 |
| **词法重新排序** | BM25 重新排序阶段在 RRF 融合之上锐化查询相关性（`Reranker` 特征）。 |
| **压缩** | 近乎无损的压缩，**保留代码、路径和 URL**，以及用于令牌高效回忆的 `摘要`/`标题` 级别。 |
| **动态令牌预算** | 选择加入查询感知提取摘要，将回忆压缩到紧密的预算（`Summarizer` 特征）。 |
| **护栏 / 事实核查** | `yb 验证` 检查草拟的答案是否支持知识库并标记不支持的声明（`Validator` 特征）。 |
| **语义缓存** | 基于知识库的分层缓存：先前问答 → 直接知识库答案 → 知识库基础，具有基于来源的**自动失效**。 |
| **语义嵌入** | 默认情况下无依赖哈希嵌入器；可选 **ONNX 句子转换器** （e5/MiniLM/BGE）用于真正的基于含义的回忆。 |
| **隐私** | 存储前剥离 `<private>...</private>` 块并编辑秘密（API 密钥，令牌，连接字符串）。 |
| **团队知识** | 支持/反对记忆（置信度 = 共识）。导出/导入为 JSONL。 |
| **IDE 集成** | **MCP 服务器** （`yb mcp`）用于 Cursor，Claude Code，VS Code 和 Trae，以及 **钩子** （`yb hook`）用于自动捕获。 |
## YourBrain 的比较
本地优先的代理内存空间是健康且不断增长的 - uteke 和 cavemem 等项目共享相同的"单一二进制文件，离线，MCP"的理念，并且在存储和检索内存方面非常出色。YourBrain 的重点是提升一个层次：保持内存**连贯和可靠**随着它的增长。
| | **YourBrain** | uteke | cavemem | Mem0 |
|---|---|---|---|---|
| 分发 | 单个 Rust 二进制文件 | 单个 Rust 二进制文件 (+Docker) | npm / Node (TS) | Python/JS SDK + SaaS |
| 离线 / 本地优先 | 是 | 是 | 是 | 部分（云嵌入） |
| MCP 服务器 | 是 - stdio, 12 种工具 | 是 - stdio + HTTP | 是 - stdio, 3 种工具 | 通过集成 |
| 混合搜索（FTS5 + 向量 + RRF） | 是（平面余弦） | 是（HNSW） | 是 | 语义 |
| 默认嵌入 | 哈希；ONNX 可选 | ONNX（EmbeddingGemma 768d） | 远程可选 | LLM / 云 |
| BM25 重新排序 + 动态令牌预算 | 是 | 衰减/显著性排名 | 可调排名器 | - |
| 代码安全压缩 | 是（3 个级别） | - | 是（〜75％） | - |
| **自动冲突检测 + 解决** | **是** （重复/取代/矛盾，自动或询问） | 类型边缘（手动） | 否（仅追加） | 有限的重复/更新 |
| **答案事实核查 / 护栏** | **是** (`yb_validate`) | 否 | 否 | 否 |
| **基于知识库的语义答案缓存** | **是** （分层 + 来源自动失效） | LRU 回忆缓存（性能） | 否 | 否 |
| **团队共识** （支持/反对） | **是** （拉普拉斯置信度，范围） | 作者归属/命名空间 | 否 | 按用户 |
| 关系图 + 审计时间线 | 是 | 是（丰富；图 API） | 时间线 | 有限 |
| 服务器/守护进程 + HTTP，文档引擎 | 路线图 | 是 | 网页查看器 | 云平台 |
| 许可证 | Apache-2.0 | Apache-2.0 | MIT | Apache-2.0 |
**诚实评价：** uteke 今天提供了更多的广度（HNSW，ONNX 默认，服务器模式，文档/维基引擎，基准测试工具）；cavemem 有一个漂亮的网页查看器和最广泛的一键式 IDE 安装程序。 **YourBrain 独特之处在于** coherence 层 - 自动冲突解决，基于知识库的答案验证和语义缓存 - 以便您的代理内存不会随着时间悄悄变成矛盾。
## 它是如何工作的
```
┌─────────────────────────────────────────┐
yb CLI ─────▶│ yb-core │
yb mcp ─────▶│ Brain (facade) │
yb hook ─────▶│ ├── classify (privacy + type) │
│ ├── compress (3 levels) │
│ ├── embed (Embedder trait) ──┐ │
│ ├── vector (VectorIndex trait) │ pluggable
│ ├── search (FTS5 + RRF + rerank)│ backends │
│ ├── budget / guardrail / cache │ │
│ ├── conflict (tiered) │ │
│ └── store (SQLite + FTS5) ◀──┘ │
└─────────────────────────────────────────┘
```
引擎仅依赖于 `Embedder` 和 `VectorIndex` **特征**。默认构建使用纯 Rust 实现（确定性特征哈希嵌入器和精确平面余弦索引），因此它**在任何地方编译和运行**，无需 C++/ONNX 工具链。生产 ONNX 嵌入器作为同一特征的插件 - 请参阅 [安装](docs/INSTALL.md)。
## 快速开始
```bash
# 1. 构建（需要 Rust 工具链 1.75+）
git clone <repo-url> yourbrain && cd yourbrain
cargo build --release # 二进制文件位于 ./target/release/yb （Windows 上为 yb.exe）
# 2. 存储和回忆知识
yb remember "后端 API 使用 Rust 和 Axum Web 框架" --tag backend
yb recall "后端如何构建"
# 3. 更新知识 → 检测冲突 → 解决
yb remember "身份验证现已迁移到会话 cookie 而不是 JWT"
# ↳ 检测到潜在取代... 解决方式：
yb resolve <conflict_id> --action replace
# 4. 将其集成到您的 IDE 中（以 Cursor 为例；请参阅 Claude/VS Code/Trae 文档）
yb install --ide cursor
```
完整的、按操作系统划分的构建和运行说明：**[docs/INSTALL.md](docs/INSTALL.md)**。
## 在您的 AI IDE 中使用它
YourBrain 使用 **模型上下文协议（MCP）**，因此它与任何支持 MCP 的客户端一起工作。`yb install` 会自动为 Cursor 和 Claude Code 生成配置；VS Code 和 Trae 需要一个单独的配置文件。
| IDE | 设置 | 自动捕获钩子 |
|---|---|---|
| **Cursor** | `yb install --ide cursor` | - （仅 MCP） |
| **Claude Code** | `yb install --ide claude-code` | 是 |
| **VS Code** （Copilot Agent） | `.vscode/mcp.json` （手动） | - |
| **Trae** | 设置 → MCP → 添加，或 `.trae/mcp.json` | - |
每种 IDE 的逐步指南，以及每个项目的调整：**[docs/IDE_SETUP.md](docs/IDE_SETUP.md)**。
连接后，代理将获得这些工具：`yb_remember`，`yb_recall`，`yb_resolve`，`yb_endorse`，`yb_dispute`，`yb_timeline`，`yb_get_full`，`yb_stats`，`yb_validate`，`yb_cache_get`，`yb_cache_put`，`yb_cache_clear`。
## 命令参考
| 命令 | 描述 |
|---|---|
| `yb remember <content> [--tag T]… [--room R] [--scope personal\|team]` | 存储记忆（带有冲突检查）。 |
| `yb recall <query> [--limit N] [--detail headline\|summary\|full] [--budget N] [--dynamic-budget]` | 搜索和检索。 |
| `yb resolve <id> --action replace\|keep_both\|discard_new\|merge [--content …]` | 解决冲突。 |
| `yb validate <answer> [--query Q]` | 用知识库核实答案。 |
| `yb cache get\|put\|clear [--query Q] [--answer A] [--threshold F] [--source-id ID]…` | 分层语义缓存。 |
| `yb list [--room R] [--limit N]` | 列出记忆。 |
| `yb get <id>` | 显示完整的记忆 + 关系。 |
| `yb forget <id>` | 存档记忆。 |
| `yb endorse <id> [--author A]` / `yb dispute <id> --reason R` | 团队共识。 |
| `yb conflicts` | 列出待解决的冲突。 |
| `yb timeline <id>` | 审计历史。 |
| `yb stats` | 统计数据和健康状况。 |
| `yb export [--scope team] [--out file]` / `yb import <file>` | JSONL 导出/导入。 |
| `yb reindex [--provider onnx] [--model KEY] [--yes]` | 重新嵌入所有记忆并重建索引（迁移嵌入器）。 |
| `yb config show` | 显示配置和路径。 |
| `yb mcp [flags]` | 启动 MCP stdio 服务器（请参阅 IDE 设置以获取每个项目的标志）。 |
| `yb install --ide cursor\|claude-code [flags]` | 生成 IDE 集成文件。 |
全局选项（任何命令）：`--db-memory <name>` （隔离项目），`--embedder <local\|onnx>` 和 `--embed-model <key>` （针对已重新索引的数据库）。
## 配置
配置位于 `<data_dir>/config.toml`。数据目录解析为：
- `YB_DATA_DIR` 环境变量（覆盖所有内容），否则
- Windows `%APPDATA%\yourbrain`，否则 `~/.yourbrain`。
每个选项都在 **[config.example.toml](config.example.toml)** 中记录。关键的调整：检索 (`[search]`， `[rerank]`），令牌预算 (`[token_budget]`），事实检查 (`[guardrail]`），语义缓存 (`[cache]`），冲突敏感性 (`[conflict]`）和嵌入 (`[embedding]`)。
### 按项目隔离记忆
默认情况下，每个项目共享一个全局数据库。传递一个命名的 `db_memory` 以保持项目的记忆完全隔离（单独的 SQLite 存储，索引和冲突范围）：```bash
yb --db-memory my-project remember "项目特定决策"
yb --db-memory my-project recall "决策"
```
`yb install` 自动检测项目（git 仓库文件夹）并将 `--db-memory <name>` 写入生成的 MCP 配置。有关项目令牌预算、缓存阈值、冲突敏感性和嵌入器选择的详细信息，请参阅 [docs/IDE_SETUP.md](docs/IDE_SETUP.md#per-project-settings)。
### 语义理解（可选 ONNX）
默认嵌入器是无依赖但主要基于共享词汇的匹配。为了真正的基于含义的回忆（带有无公共词的 paraphrases），使用可选的 ONNX 句子转换器后端并迁移：
```bash
cargo build --release --features onnx
yb reindex --provider onnx --model multilingual-e5-small --yes
```
完整的详细信息、支持的模型和 Windows 构建说明都在 **[docs/INSTALL.md](docs/INSTALL.md#optional-onnx-embedder)**。
## 团队协作
记忆在整个团队共享时更有价值。YourBrain 构建了一个团队收敛于**一个连贯的事实来源**，而不是许多漂移的私人笔记：
- **范围** - `yb remember "<fact>" --scope team` 将记忆标记为共享；`--scope personal`（默认）使其保持作者私有。只有团队范围的记忆才会在人员之间传递。
- **共识，而不仅仅是存储** - 任何人都可以 `yb endorse <id>` 或 `yb dispute <id>`。置信度计算为拉普拉斯平滑比率 `(endorsements + 1) / (endorsements + disputes + 2)`，因此广泛支持的事实会上升，而有争议的事实会下降（并且可以翻转为 `Disputed` 状态）- 默认情况下，任何作者的主张都不会获胜。
- **作者感知冲突解决** - 当新的记忆 **取代** 现有记忆时，由 **不同作者** 编写，YourBrain **始终要求人类决策** 而不是静默覆盖团队成员的知识。相同作者的更新可以自动解决。
- **通过 JSONL 或 git 共享** - `yb export --scope team --out team.jsonl` 然后 `yb import team.jsonl` 另一台机器；或提交项目的隔离 `--db-memory <name>` 数据库到您的仓库，以便每个人加载相同的上下文。
**为什么很重要：** 新的队友立即继承架构和决策，改变的决策被记录在时间线上而不是丢失，并且重要的声明可以在代理采取行动之前使用 `yb_validate` 进行检查。
> 实时多用户同步（git/relay）正在路线图中；基础 - `brain_meta`，JSONL 导出/导入和 `Scope` - 已经到位。
## 文档
| 文档 | 里面有什么 |
|---|---|
| [docs/INSTALL.md](docs/INSTALL.md) | 在 Windows、macOS、Linux 上构建和运行；ONNX 构建；更新。 |
| [docs/IDE_SETUP.md](docs/IDE_SETUP.md) | Cursor、Claude Code、VS Code、Trae - 配置 + 项目调整。 |
| [config.example.toml](config.example.toml) | 每个配置选项，注释。 |
| [CHANGELOG.md](CHANGELOG.md) | 发布历史。 |
## 项目状态
一个干净、完全测试的 **核心** （存储、嵌入、向量搜索、压缩、分类、混合检索 + 重新排序、动态预算、护栏、语义缓存、1 级冲突解决）加上运行 **进程内模式** 的 `yb` 二进制文件（CLI、MCP 服务器、钩子处理程序、安装程序）。可选的 ONNX 嵌入器在 `onnx` 特征后面提供。更高级别的冲突裁判（NLI/LLM）、HNSW 索引器和团队同步同步正在设计稳定的接口作为自然的下一步骤。
## 贡献
贡献欢迎。在打开 PR 之前：```bash
cargo fmt --all
cargo clippy --all-targets -D warnings
cargo test --all
```
保持代码注释为英文，并添加 [CHANGELOG.md](CHANGELOG.md) 中用户界面更改的说明。
## 许可证
[Apache-2.0](LICENSE)。
