Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@PersonalBrain 查一下我的旅行偏好，顺便列出待确认的记忆"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
一个供 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 serveRelated MCP server: om
启动脚本生成 .local-client/：
文件 | 用途 |
| Codex HTTP MCP 配置片段，通过环境变量引用令牌 |
| 插件清单 |
| 当前实例的 MCP 地址及访问令牌 |
| 知识检索与维护规则 |
可以立即使用 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 工具：
工具 | 功能 |
| 分层浏览分类和状态数量，支持分页 |
| 关键词检索摘要，支持分类、状态和分页 |
| 读取完整正文、来源和 revision |
| 新建、更新、移动分类、确认或归档 |
默认只搜索 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。
This server cannot be deployed
One memory, every AI. A shared, user-owned markdown memory your AI clients read and write over MCP.
Knowledge base MCP for AI agents on iknow.dev. Search, read, and maintain via OAuth.
Personal knowledge base MCP server with semantic search, auto-categorization, metadata extraction
Publish and share access-controlled Markdown documents from any MCP-enabled AI tool.
