内容
# 开放大脑
[](https://github.com/sussdorff/open-brain/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.python.org/)
[](https://modelcontextprotocol.io/)
一个可插件的MCP内存服务器，为AI助手提供长期、可搜索的跨会话和项目内存。
**问题：** AI助手在会话之间会忘记所有内容。它们无法保留学习成果、回忆过去的决定或在之前的工作基础上继续。当运行多个代理跨多个项目时，上下文会不断丢失。
**开放大脑解决了这个问题**，通过提供一个共享的内存层，任何MCP兼容的助手都可以读写，具有混合搜索（向量+全文搜索）、人工干预的分诊和内存生命周期，促进有价值的学习成果转化为持久的工件，如编码标准、技能或项目文档。
## 工作原理
```
AI助手（Claude Code、IDE等）
│
│ MCP协议
▼
┌─────────────────────────┐
│ 开放大脑服务器 │
│ │
│ 保存 ──► 嵌入 ──► 搜索
│ ▲
│ 精炼（自动） │
│ 分诊（人工） ───┘
│ 物化 ──► 文件、问题、标准
└──────────┬──────────────┘
│
▼
Postgres + pgvector + Voyage-4
```
1. **保存**：观察、学习和会话摘要存储在嵌入中
2. **搜索**：混合搜索结合关键词匹配（全文搜索）和语义相似性（pgvector）通过互惠排名融合
3. **精炼**：自动整合 - 查找重复项、合并相似的记忆、调整优先级
4. **分诊**：人工干预审查 - 将记忆分类为保留、合并、推广或存档
5. **物化**：将批准的学习成果写入目标 - 项目文档、编码标准、工作项
详见 [docs/architecture.md](docs/architecture.md) 获取详细图表和技术深入解析。
## 安装
开放大脑有两个可安装的组件：
- **服务器**：长期运行的FastAPI/MCP服务，支持Postgres + pgvector。在运行开放大脑的机器或容器宿主机上安装。
- **CLI**：`ob`命令，供人类和操作脚本使用。在工作站、笔记本电脑、跳板机或服务器本身安装。
服务器和CLI不必在同一台机器上。 Docker Compose是推荐的服务器安装方式。`uv tool install`是推荐的CLI安装方式。
### 1. 启动服务器
您需要一个带有pgvector扩展的Postgres实例和一个[Voyage AI](https://www.voyageai.com/) API密钥。
**独立（包括Postgres）：**
```bash
# 下载docker-compose文件和示例配置
curl -O https://raw.githubusercontent.com/sussdorff/open-brain/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/sussdorff/open-brain/main/.env.example
cp .env.example .env
```
编辑`.env` - 所需字段为：
| 变量 | 描述 |
|---|---|
| `MCP_SERVER_URL` | 此服务器的公共HTTPS URL（例如`https://brain.example.com`） |
| `DATABASE_URL` | Postgres连接字符串 |
| `AUTH_USER` | OAuth登录表单的用户名 |
| `AUTH_PASSWORD` | 密码（最小8个字符） |
| `JWT_SECRET` | 用于签名JWT的随机密钥 - `openssl rand -hex 32` |
| `VOYAGE_API_KEY` | [Voyage AI](https://www.voyageai.com/) API密钥 |
| `ANTHROPIC_API_KEY` | Anthropic API密钥（用于内存精炼） |
```bash
# 拉取镜像并启动
docker compose pull
docker compose up -d
# 验证
curl http://localhost:8091/health
# {"status":"ok","service":"open-brain","runtime":"python"}
```
**仅服务（自带Postgres）：**
```bash
curl -O https://raw.githubusercontent.com/sussdorff/open-brain/main/docker-compose.service.yml
curl -O https://raw.githubusercontent.com/sussdorff/open-brain/main/.env.example
cp .env.example .env
# 编辑.env，然后：
docker compose -f docker-compose.service.yml pull
docker compose -f docker-compose.service.yml up -d
```
**Python包服务器（本地/裸金属）：**
在您已经运行Postgres + pgvector并希望安装相同`ob`命令来启动服务器时使用。
```bash
uv tool install --python 3.14 "git+https://github.com/sussdorff/open-brain.git#subdirectory=python"
# 设置与.env.example中相同的变量，然后：
ob server
# 可选绑定覆盖
ob server --host 127.0.0.1 --port 8091
```
对于本地checkout，从Python包目录安装：
```bash
uv tool install --python 3.14 ./python
```
### 2. 获取访问令牌
使用您的API密钥（来自`.env`中的`API_KEYS`）为每个客户端颁发一个URL令牌：
```bash
curl -X POST https://your-server.example.com/token/url \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "my-client", "scopes": ["memory", "evolution"], "expires_in_days": 365}'
# {"token": "abc123...", "name": "my-client", "scopes": [...], "expires_at": "..."}
```
保存原始令牌 - 它只显示一次。
### 3. 安装和配置CLI
在您要使用CLI的每台机器上运行此命令。如果您没有为Python包服务器路径安装`ob`：
```bash
uv tool install --python 3.14 "git+https://github.com/sussdorff/open-brain.git#subdirectory=python"
```
将CLI指向您的MCP端点并提供步骤2中的URL令牌：
```bash
mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/open-brain"
cat > "${XDG_CONFIG_HOME:-$HOME/.config}/open-brain/config.json" <<'JSON'
{
"server_url": "https://your-server.example.com",
"url_token": "TOKEN_FROM_STEP_2"
}
JSON
chmod 600 "${XDG_CONFIG_HOME:-$HOME/.config}/open-brain/config.json"
ob --json doctor
ob search "我对X有什么决定？"
```
CLI遵循XDG配置约定。主要的配置文件是：
- `$XDG_CONFIG_HOME/open-brain/config.json`
- `~/.config/open-brain/config.json`当`XDG_CONFIG_HOME`未设置时
使用`server_url`表示公共基准URL（自动追加`/mcp`）或`mcp_url`表示显式MCP端点。
如果您之前使用钩子设置脚本，您的现有配置可能包含一个`api_key`而不是URL令牌。CLI也支持这一点：
```json
{
"server_url": "https://your-server.example.com",
"api_key": "YOUR_API_KEY"
}
```
环境变量覆盖配置：
```bash
export OB_URL="https://your-server.example.com/mcp"
export OB_URL_TOKEN="TOKEN_FROM_STEP_2"
# 或：
export OB_API_KEY="YOUR_API_KEY"
```
还支持通过`OB_TOKEN`或配置文件中的`"token"`使用OAuth承载令牌。 URL令牌使用`OB_URL_TOKEN`，配置文件中的`"url_token"`或`OB_URL`中的显式`?token=...`。 API密钥使用`OB_API_KEY`或配置文件中的`"api_key"`。 旧版`~/.open-brain/config.json`，`~/.open-brain/token`和`~/.open-brain/url-token`文件仍然作为回退。
### 4. 使用OAuth连接编码工具
```bash
claude mcp add open-brain \
--transport http \
"https://your-server.example.com/mcp"
claude mcp login open-brain
```
或手动在`~/.claude.json`中：
```json
{
"mcpServers": {
"open-brain": {
"type": "http",
"url": "https://your-server.example.com/mcp"
}
}
}
```
Codex使用相同的OAuth保护的HTTP端点：
```bash
codex mcp add open-brain --url "https://your-server.example.com/mcp"
codex mcp login open-brain --scopes memory
```
工具配置中不包含访问令牌。 Claude Code和Codex拥有自己的OAuth会话状态和刷新流程。 不要在这些MCP注册中添加URL查询令牌、静态授权头或承载令牌环境变量。
URL令牌可用于无法完成OAuth的客户端。 通过客户端名称撤销旧令牌：
```bash
curl -X DELETE https://your-server.example.com/token/url/my-client \
-H "x-api-key: YOUR_API_KEY"
```
## 配置
所有配置均通过环境变量（`.env`文件或由您的编排器注入）。
| 变量 | 必需 | 默认值 | 描述 |
|---|---|---|---|
| `MCP_SERVER_URL` | 是 | - | 此服务器的公共HTTPS URL |
| `DATABASE_URL` | 是 | - | Postgres连接字符串（需要pgvector） |
| `AUTH_USER` | 是 | - | OAuth登录的用户名 |
| `AUTH_PASSWORD` | 是 | - | 密码（最小8个字符） |
| `JWT_SECRET` | 是 | - | JWT签名密钥（最小32个字符） |
| `VOYAGE_API_KEY` | 是 | - | [Voyage AI](https://www.voyageai.com/) API密钥 |
| `VOYAGE_MODEL` | 否 | `voyage-4` | 嵌入模型 |
| `LLM_PROVIDER` | 否 | `anthropic` | `anthropic`或`openrouter` |
| `LLM_MODEL` | 否 | `claude-haiku-4-5-20251001` | 默认模型用于小调用（实体/分类/工具使用/摘要） |
| `LLM_MODEL_CAPTURE` | 否 | - | `/api/session-capture`的可选覆盖（回退到`LLM_MODEL`） |
| `ANTHROPIC_API_KEY` | 条件 | - | 当`LLM_PROVIDER=anthropic`时需要 |
| `OPENROUTER_API_KEY` | 条件 | - | 当`LLM_PROVIDER=openrouter`时需要 |
| `API_KEYS` | 否 | - | 用于钩子/CLI/脚本访问的逗号分隔API密钥 |
| `PORT` | 否 | `8091` | 服务器端口 |
| `CLIENTS_FILE` | 否 | `/app/clients.json` | OAuth客户端注册路径 |
| `MAX_MEMORIES_PER_DAY` | 否 | `500` | 每日摄入限制（0 = 禁用） |
在`.env.example`中查看完整的模板和注释。
## MCP工具
AI助手通过MCP工具与内存交互。推荐的工作流程是**3步漏斗**，以最小化令牌使用：
```
search(query) → 紧凑索引和ID（~50-100令牌/结果）
timeline(anchor=ID) → 结果周围的上下文
get_observations([IDs]) → 仅需获取详细资料
```
### 内存访问
| 工具 | 描述 |
|---|---|
| `search` | 混合搜索（向量+全文搜索）。按`project`、`type`、日期范围、`file_path`过滤。省略查询以进入浏览模式。 |
| `timeline` | 结果周围的上下文（按ID的锚点模式）或日期窗口。 |
| `get_observations` | 获取指定ID列表的完整详细信息。 |
| `search_by_concept` | 纯向量搜索 - 适用于“关于X我学到了什么？” |
| `get_context` | 最近的会话摘要 - 在对话开始时很有用。 |
| `daily_review` | 有限日期的回顾：条目、源引用、未解决的Inbox捕获和按类型计数。基于内存范围 - 无进化门控。 |
| `stats` | 数据库统计：内存计数、类型分类、DB大小、嵌入令牌使用、估计的API成本。 |
### 内存写入
| 工具 | 描述 |
|---|---|
| `save_memory` | 存储观察结果。`text` + `project`必填。异步自动嵌入。 **捕获路由器**应用领域模板并并发提取结构化字段。 |
| `update_memory` | 更新现有内存的字段。如果内容更改，则重新嵌入。 |
| `set_capture_status` | 转换捕获的收件箱状态（`inbox` / `processed` / `dismissed`）。知识生命周期`metadata.status`除非显式传递`lifecycle_status`，否则保持不变。 |
| `refine_memories` | 自动整合：重复、合并、优先级调整。 |
| `triage_memories` | 人工干预分类为生命周期动作。 |
| `materialize_memories` | 执行分诊动作（推广到文档、创建问题、存档）。 |
### 自我改进循环
| 工具 | 描述 |
|---|---|
| `analyze_briefing_engagement` | 按简报类型计算过去N天的响应率。显示哪些简报类型用户参与度最高。 |
| `generate_evolution_suggestion` | 提出一个行为改变建议：删除低参与度简报类型或扩展高参与度简报类型。限速并尊重30天拒绝抑制。 |
| `log_evolution_approval` | 记录用户批准或拒绝建议。记录的拒绝在30天内抑制重新提案。 |
| `query_evolution_history` | 检索过去的进化建议和批准 - 跟踪哪些简报类型随时间调整。 |
详见 [docs/features/self-improvement-loop.md](docs/features/self-improvement-loop.md) 获取完整的工作流程和示例。
### 内存类型
`discovery`, `change`, `feature`, `decision`, `bugfix`, `refactor`, `session_summary`, `learning`, `briefing`, `evolution`
如果没有合适的类型，可以添加新类型。检查`stats()`以查看现有词汇。
## 结构化内存：捕获路由器
**捕获路由器**自动将传入的内存分类为领域特定的模板。当您调用`save_memory`时，LLM同时：
1. 分类文本（决策、会议、人员上下文等）
2. 提取结构化字段（与会者、行动项、所有者、理由等）
3. 将字段合并到内存元数据中
无需更改您的代码 - 它透明地工作：
```python
# 调用者：只需保存原始文本
await save_memory(
text="决定使用async以获得更好的可扩展性",
type="decision"
)
# 数据库中的结果：
# metadata = {
# "capture_template": "decision",
# "what": "使用async",
# "context": "可扩展性要求",
# "owner": "...",
# "alternatives": ["...", "..."],
# "rationale": "更好的I/O吞吐量"
# }
```
这使得：
- **自动结构** 无需调用者努力
- **下游处理** - 分诊、精炼和物化可以依赖于结构化数据
- **更好的检索** - 操作项、决策和学习成果是可查询的
- **代理工作流** - 一个代理捕获；另一个检索并基于结构化字段采取行动
详见 [docs/features/capture-router.md](docs/features/capture-router.md) 获取模板引用和示例。
## 多用户
open-brain目前支持**单个用户**实例（一个`AUTH_USER` / `AUTH_PASSWORD`对）。多个MCP客户端可以通过OAuth或API密钥同时连接，但所有共享相同的内存池。
内存按`project`分段，而不是按用户。这适用于单个使用或小团队，其中共享上下文是目标。
**计划**: 共享内存与用户归属 - 内存由作者标记，对所有认证用户可见，可按贡献者过滤。
## 库市场
open-brain注册为 [`the-library`](https://github.com/disler/the-library) (`cognovis/library`分叉）。存储库顶级`skills/`和`hooks/`目录是硬件中立的源基元；元库安装它们进入任何工具（Claude Code、Codex，...）通过 `/library use`.
### 交互式迁移
对于Obsidian/Markdown库的大规模迁移（历史第二大脑笔记），请使用独立导入器：`python -m open_brain.second_brain_import <vault_path> [--apply]`。详见 [docs/features/second-brain-import.md](docs/features/second-brain-import.md) 获取完整参考。对于交互式单笔记捕获，`ob-migrate`是合适的工具。
内存CLI路由规则和`save_memory`约定位于标准`open-brain/cli-routing`、`open-brain/memory-write-patterns`和`open-brain/memory-status-conventions`中（通过`requires_standards`自动加载）。
代码智能工具（`smart_search` / `smart_outline` / `smart_unfold`）已迁移到 `cognovis-core` 市场作为 `/library use code-navigator` - 脚本与open-brain内存无功能关系。
`open-brain-hooks` 守护程序安装了来自 `hooks/` 的特定于工具的清单：Claude Code 使用 `hooks/hooks.json`，而 Codex 使用 `hooks/hooks.codex.json`。源路径解析为库缓存，因此无需在 `plugin/` 中建立符号链接，无需 `claude plugin add`，也无需 `marketplace.json` 清单。
安装钩子后，请配置服务器连接：
```bash
python3 ~/.local/share/library/guardrails/open-brain-hooks/checkout/hooks/scripts/setup.py
```
这将提示服务器URL和API密钥，并写入 `~/.open-brain/config.json`。
## 嵌入到现有堆栈中
open-brain 可以通过 `include:` 嵌入到更大的 Docker Compose 堆栈中：
```yaml
include:
- path: ../open-brain/docker-compose.service.yml
services:
your-app:
depends_on:
- open-brain
```
`docker-compose.service.yml` 仅包含 open-brain 服务（无 Postgres）- 使用您自己的数据库。
## 开发
```bash
cd python
uv sync --dev
# 单元测试（无外部服务）
uv run pytest -m "not integration"
# 所有测试（需要 VOYAGE_API_KEY）
uv run pytest
# 本地运行
uv run ob server
```
## 部署
Docker镜像在CI中构建，并在每次推送到`main`时发布到`ghcr.io/sussdorff/open-brain:latest`。无需服务器上的构建步骤。
```bash
# 拉取最新镜像并重启
docker compose pull && docker compose up -d
# 或仅服务
docker compose -f docker-compose.service.yml pull
docker compose -f docker-compose.service.yml up -d
```
机密从 `.env` 由docker compose加载。生成 `JWT_SECRET` 和 `AUTH_PASSWORD` 的强值：
```bash
openssl rand -hex 32 # JWT_SECRET
openssl rand -base64 16 | tr -d '=' # AUTH_PASSWORD
```
### OAuth客户端注册
客户端通过 `/register` （RFC 7591）或静态通过 `clients.json` 动态注册：
```yaml
volumes:
- ./clients.json:/app/clients.json:ro
```
行界面使用
`ob` 命令是主要的面向用户的命令行界面。它故意涵盖了正常的服务器和内存工作流程；一次性迁移、开发检查和 Claude Code 钩子内部仍然保留在 `scripts/`、`python/scripts/` 和 `hooks/scripts/` 中。
```bash
ob server
ob --json doctor
ob search "我对 X 做出了什么决定？"
ob save "决定使用 asyncpg 以降低开销" --type decision \
--source-ref agent-session:codex:<session-id>
ob provenance report
ob ingest transcript --source-ref meeting-2026-04-29 --file transcript.txt
ob ingest macwhisper list --limit 5
ob ingest macwhisper entry <entry-id>
ob people list --collisions
```
当前 `ob` 命令：
| 命令 | 用途 |
|---|---|
| `ob server` | 从已安装的 Python 包启动 FastAPI/MCP 服务器 |
| `ob doctor` | 通过 MCP `doctor` 工具运行服务器诊断 |
| `ob stats` | 显示内存/数据库统计信息 |
| `ob search` | 混合向量 + 全文搜索 |
| `ob concept` | 仅语义的向量搜索 |
| `ob timeline` | 显示围绕锚点内存或查询的上下文 |
| `ob get` | 按 ID 获取完整的观察结果 |
| `ob context` | 获取最近的会话上下文 |
| `ob save` | 保存内存 |
| `ob provenance report` | 检查源-出处覆盖率，而不修改内存 |
| `ob update` | 更新现有的内存 |
| `ob ingest email` | 通过 MCP 服务器提取 IMAP 收件箱 |
| `ob ingest transcript` | 提取转录文件或标准输入 |
| `ob ingest macwhisper` | 从本地 MacWhisper 历史记录中列出和提取转录记录 |
| `ob people list` | 通过 MCP 服务器列出人员内存和合并候选项 |
| `ob people merge` | 在服务器端合并重复的人员内存 |
| `ob export <bundle>` | 将所有内存、关系和元数据导出到可移植的 JSONL 包中 |
| `ob restore <bundle>` | 将可移植的包恢复到空存储中（幂等重运行） |
| `ob verify <bundle>` | 验证包的往返完整性（内容哈希、关系、实体 ID） |
| `ob inbox` | 列出 `capture_status=inbox` 的捕获结果 |
| `ob capture set-status` | 转换捕获的 inbox 状态（`inbox` / `processed` / `dismissed`） |
| `ob daily [DATE]` | 每日内存审查：日期范围的条目、源链接、未解决的 inbox 捕获和计数。默认为今天。 |
### `ob people`
人员重复识别在服务器上运行，因为远程 CLI 安装不应需要 `DATABASE_URL`。
```bash
ob people list --collisions
ob people merge --source 17692 --target 17700 --dry-run
ob people merge --source 17692 --target 17700
```
当源内容应作为出处附加到目标时，请使用 `--absorb-text`。合并重新指向提及/交互引用，重新指向键入的关系，更新目标别名，并使用 `metadata.merged_into` 标记源。
### `ob ingest transcript`
将转录或标准输入开放脑内存。
# 通过 MCP 服务器（默认 — 适用于代理用户设置）
ob --source-ref meeting-2026-04-29 --file transcript.txt
# 直接 绕过 MCP PostgresDataLayer 进程
ob ingest transcript --source-ref meeting-2026-04-29 --file transcript.txt
```
**何时direct`：**
- 具有直接数据库访问权限运算符脚本（`DATABASE_URL` 可用）
- MCP 传输延迟累积的批量提取管道
- 没有正在运行的开放脑服务器的开发/测试环境
**何时不使用 `--direct`：**
- 多用户设置（绕过所有 MCP 层身份验证和速率限制）
- 不应数据库访问权限的沙盒代理
- 当您不控制 `DATABASE_URL` 时（而是依赖 MCP 身份验证）
direct` 需要设置 `DATABASE_URL`（环境变量或 `.env` 文件中的_URL=...` 行VOYAGE_API_KEY` 也必须设置为嵌入调用。
您还可以将 `OB_DIRECT= 设置为环境变量，而不是在每次调用时传递 `--direct`。
### `ob ingest mac`
从本地 MacWhisper 历史记录目录中列出和提取转录会话。 对于现代isper SQLite 历史记录，`list` 默认显示转录会话/会议，包括源应用程序、持续时间和检测到的参与者，来自 MacWhisper 扬声器数据。 字典仍然可以通过 ID 读取，但不属于默认会议/会话列表。 此命令故意在 CLI 机器上读取 MacWhisper 文件，然后将转录文本提交到配置的开放脑服务器。 这意味着它在服务器运行在其他地方时仍然有效。
```bash
# 显示最近的本地 MacWhisper 转录会话/会议
ob ingest macwhisper list --limit 10
# 检查配置的开放脑服务器并显示提取状态
ob ingest macwhisper list --limit 10 --status
# 仅显示没有匹配的 macwhisper:<entry-id> 源引用的会话
ob ingest macwhisper list --not-ingested
# 机器可读输出
ob ingest macwhisper list --limit 10 --json
# 提取一个条目，默认为源引用 macwhisper:<entry-id>
ob ingest macwhisper entry <entry-id>
# 使用非标准历史目录
ob ingest macwhisper list --history-path ~/Exports/MacWhisper
ob ingest macwhisper entry <entry-id> --history-path ~/Exports/MacWhisper
```
历史路径从 `MACWHISPER_HISTORY_PATH` 自动发现，标准 MacWhisper 沙盒/应用程序支持目录，或 `mw` CLI 的路径提示。`macwhisper entry` 默认将媒体提示设置为 `macwhisper`，除非 MacWhisper 条目 `--medium-hint` 提供更具体的值。`isper ingest` 被接受为兼容性别名。
`--status` 和 `--not-ingested` 调用配置的开放脑服务器，以比较每个本地条目与通过 `metadata.source_ref` 提取的会议内存。 默认源引用为 `macwhisper:<entry-id>`。 `--not-ingested` 默认扫描比显示更多的本地条目（`max(limit*5, 50)` `--scan-limit N` 调整该窗口。
## 文档
- [架构和图表](docs/architecture.md) — 系统设计、混合搜索、内存生命周期、身份验证流程
- [代理知识工作流程](/agent-knowledge-workflows.md) — 捕获、收件箱审查、每日审查和每周审查工作流程，用于替换 Obsidian 的代理
- [操作员脚本提升策略](docs/operator-scripts.md) — 哪些脚本成为稳定的 `ob` 命令，哪些保留为脚本
- [贡献](CONTRIBUTING.md) — 开发设置、PR 流程、编码指南
- [安全](SECURITY.md) — 漏洞报告、安全考虑
- [变更日志](CHANGELOG.md) — 版本历史
## 许可证
[MIT](LICENSE)
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器