PersonalBrain
一个供 Codex 和支持 HTTP MCP 的 AI 客户端使用的个人知识库。每个人独立部署，知识以 Markdown 文件保存，SQLite FTS5 提供可重建的检索索引。服务端不调用大模型，不依赖 embedding 服务。
客户端决定何时检索、阅读和提炼知识；服务端负责执行工具、校验输入和可靠保存。适合记录个人偏好、生活经验、项目整体架构、核心业务逻辑和关键决策。
本地启动
需要 Python 3.10+，推荐 Python 3.12。进入项目目录后执行：
python bootstrap.py --serve
脚本创建项目内 .venv、安装依赖、初始化空知识库、生成访问令牌和私有客户端接入包，然后前台启动服务。首次安装需要联网；按 Ctrl+C 停止。重复执行不会重置已有令牌或知识。只有下载或解压项目这一步需要提前完成。
服务地址：http://127.0.0.1:18080/mcp。所有请求都需要 .env 中的 PERSONALBRAIN_TOKEN。令牌不在终端输出。默认只监听本机。
日常启动：
# Windows PowerShell
.\.venv\Scripts\personalbrain.exe serve
# Linux / macOS
.venv/bin/personalbrain serve
连接 Codex
启动脚本生成 .local-client/：
| 文件 | 用途 |
|---|---|
codex.toml |
Codex HTTP MCP 配置片段，通过环境变量引用令牌 |
plugin/.codex-plugin/plugin.json |
插件清单 |
plugin/.mcp.json |
当前实例的 MCP 地址及访问令牌 |
plugin/skills/personalbrain/SKILL.md |
知识检索与维护规则 |
可以立即使用 Codex 的直接 MCP 接入方式。 在新终端中进入项目目录，读取令牌到进程环境并注册服务：
# Windows PowerShell：不在聊天或终端打印令牌
$brainTokenLine = Get-Content -LiteralPath .env | Where-Object { $_ -match '^PERSONALBRAIN_TOKEN=' } | Select-Object -First 1
$env:PERSONALBRAIN_TOKEN = ($brainTokenLine -split '=', 2)[1]
codex mcp add personalbrain --url http://127.0.0.1:18080/mcp --bearer-token-env-var PERSONALBRAIN_TOKEN
codex
# Linux / macOS；.env 应为本项目生成的可信文件
set -a
. ./.env
set +a
codex mcp add personalbrain --url http://127.0.0.1:18080/mcp --bearer-token-env-var PERSONALBRAIN_TOKEN
codex
桌面应用需要从含有该环境变量的进程启动，或在其 MCP 设置中填写同一地址和认证信息。已经运行的桌面进程不会自动获得新终端的环境变量。先查看现有的 personalbrain 配置，避免覆盖其他同名实例；可将配置片段中的名称改为独立名称。
客户端如支持导入本地插件，可导入生成的 plugin/ 文件夹。插件承载相同的 MCP 连接及 skill。若客户端没有本地插件导入入口，使用上面的直接 MCP 接入，并将生成的 skills/personalbrain 文件夹安装到客户端的 skills 目录。不要同时配置两个指向同一实例的连接。
生成其他实例的接入包：
personalbrain client-config --url https://brain.example.com/mcp --output .local-client/remote
命令读取当前进程或 .env 中的访问令牌；目标目录必须不存在。.local-client 包含实例访问令牌，属于个人配置，不应发布到 GitHub。开源发布项目源码，由每个部署者生成自己的接入包。
ChatGPT 网页端的插件发布、导入和认证入口取决于账号及产品能力。 此项目提供标准 MCP 服务和本地插件文件，不会自动在 ChatGPT 账号中创建、安装或发布插件。网页端连接自建服务还需要它能够访问的 HTTPS 地址；本机 127.0.0.1 不能供远程平台访问。目前实现 Bearer 访问令牌，未实现 OAuth；若接入入口要求 OAuth，需要进一步适配。
参考：官方 MCP 接入文档、官方插件构建说明。
使用示例
连接后可向 Codex 说：
- “记住：我偏好周末短途旅行，每次不超过两天，保存到生活/旅行。”
- “查一下我的旅行偏好。”
- “更新旅行偏好，每次可以安排三天，其他内容保持有效。”
- “列出待确认的记忆。”
- “先查 demo-project 的项目概览和架构，再结合当前源码分析这次需求。”
四个 MCP 工具：
| 工具 | 功能 |
|---|---|
list_categories |
分层浏览分类和状态数量，支持分页 |
search_memories |
关键词检索摘要，支持分类、状态和分页 |
read_memory |
读取完整正文、来源和 revision |
save_memory |
新建、更新、移动分类、确认或归档 |
默认只搜索 active。推断保存为 pending，用户确认后可更新为 active。失效主题可设为 archived。状态是客户端依据用户授权填写的标签，服务端不能自行判断现实事实是否正确。
检索使用中文单字与双字组合、英文词和项目名拆分，多关键词按 AND 匹配。应从问题中提炼关键词，必要时尝试别名或扩大分类；不承诺语义相近的不同措辞自动召回。命中先返回摘要、来源和 ID，需要正文再读。
知识保存结构
data/
memories/
个人/
偏好与习惯.md
生活/
旅行/
旅行偏好.md
工作/
项目/
demo-project/
项目概览.md
整体架构.md
核心业务逻辑.md
关键决策.md
.history/ # 更新前的原文，按 ID / revision 保存
index.sqlite3 # 检索索引，可由 Markdown 重建
.write.lock # 同一台机器上的写入与重建互斥
目录按需生成，初始化不会写入示例个人事实。分类最多六层，每个文件一个主题。分类由文件所在目录决定，稳定 ID 保留在 YAML frontmatter 中。
Markdown 示例：
---
id: 0f27e938-6310-40b9-a130-f2e2e2e0bc57
title: 旅行偏好
summary: 周末短途旅行的时间偏好
tags:
- 旅行
status: active
source: 用户明确说明
updated_at: '2026-10-29T08:00:00+00:00'
---
# 旅行偏好
偏好周末短途旅行，每次不超过两天。
id、title、summary、status、source、updated_at 为必填元信息；tags 可省略。不要复制文件时沿用同一个 ID。正文限 24,000 字符，摘要限 400 字符，整个文件限 100 KB。主题过大时按核心内容拆分，避免保存聊天流水和无关细节。
revision 是文件内容哈希，读取工具返回它，正文不需要手工维护。更新必须带 memory_id 和读到的 expected_revision。遇到冲突先重新读取并合并；相同路径、相同内容的重试返回已有记录。
直接编辑或移动 Markdown 后，执行 personalbrain reindex 或重启服务。直接编辑时请停止并发 MCP 写入；外部编辑器不参与服务文件锁。MCP 保存成功后立即更新索引。服务没有自动扫描文件的后台任务。
重建时，格式错误或重复 ID 的文件不进入检索，原文件保留，报告返回错误路径。错误应先修复，再重新重建，避免把漏检误认为知识不存在。
备份与恢复
personalbrain backup backups/brain-2026-10-29.zip
备份包括 memories/ 和 .history/，不包含访问令牌与可重建索引。目标备份文件必须不存在。通过 MCP 的写入与备份使用同一文件锁；备份期间不要用外部编辑器改文件。
恢复时停止服务，把自己创建的可信备份解压到一个空数据目录，将 PERSONALBRAIN_DATA_DIR 指向它，运行 personalbrain reindex 后启动。历史恢复可取 .history/<id>/<revision>.md 中的正文，通过读取当前记忆后调用 save_memory 写回；历史不会自动合并到当前正文。
写入采用临时文件替换、更新前原文副本和 .pending.json 恢复记录。若文件已保存而索引更新中断，下一次操作或启动将恢复索引。文件被外部同时改写导致恢复冲突时会报错，需保留恢复记录并人工核对。
自建服务部署
Docker 环境中，先生成 .env，再启动：
python bootstrap.py
docker compose up -d --build
容器知识存放在独立的 brain-data 命名卷中；与本地 Python 启动所用的 data/ 是两套独立数据目录。若已有本地知识，先备份，再按恢复流程迁入卷。不要执行 docker compose down -v 删除知识卷。
HTTP MCP 是固定交互方式。自建服务器本机监听 127.0.0.1:18080；跨网络访问建议用 HTTPS 反向代理提供同一 /mcp 端点。HTTPS 是 HTTP 的加密传输，无需客户端维护业务私钥。代理需转发 Authorization，不缓存 MCP 请求，并保留 POST、GET、DELETE。
在 .env 的 PERSONALBRAIN_ALLOWED_HOSTS 中加入对外实际域名，如 brain.example.com。Origin 校验默认仅允许本机来源；通常服务到服务的客户端不发送 Origin。如客户端确实发送其他 Origin，可用 PERSONALBRAIN_ALLOWED_ORIGINS 配置逗号分隔的可信来源。直接浏览器跨域调用还需代理层按实际来源配置 CORS；不应直接关闭全部校验。
服务使用独立访问令牌保护个人知识。不会收集公司系统 Token、密码或私钥。对常见凭据格式有基础拦截，但它不是完整的敏感信息识别系统；保存前仍应提炼和清理内容。Markdown、历史和搜索索引均以可读形式保存，请在自己控制的主机与备份位置保管。
验证与维护
python -m pip install -e ".[test]"
python -m pytest -q
python tests/benchmark.py --count 3000
测试覆盖 Markdown 持久化、中文检索、分类边界、状态过滤、重复请求、更新冲突、并发、崩溃恢复、备份恢复，以及真实 HTTP MCP 握手和四个工具的完整流程。
MCP SDK 固定为已验证的 1.30.0 维护版本；更新依赖时运行测试。当前设计为单用户、单实例、本地磁盘，不应让多台机器共享同一个 SQLite 文件。
尚需在实际部署环境验证 Docker、HTTPS 代理和目标客户端的插件导入。测试结果与性能测量见 VALIDATION.md。