Brain Memory

brain-connector

Brain Memory Claude 连接器——一个远程 MCP 服务，可向 Claude（网页端／桌面端／iOS／Cowork）提供大脑的评分召回能力。根据 Anthropic 的 build-mcp-server 指南，使用官方 @modelcontextprotocol/sdk 构建。设计原理见 brain-cloud/docs/connector-architecture.md。

它位于此仓库中（不属于 npm 包——与 website/ 一样，已从 package.json 的 files 中排除），因此可以直接复用 ../src 中的真实召回引擎。一个大脑，一个引擎，两种入口。

状态：🟢 已在生产环境上线——阶段 1 + 2（读 + 写）

已部署在 https://mcp.brainmemory.ai/mcp（VPS 上与 brain-cloud 并列运行的 Node 服务；使用 systemd + nginx + certbot——见 deploy/）。已添加到 claude.ai，并在 Claude 网页端 + iPhone 上完成验证。工具：brain_recall、brain_status（读取）+ brain_memorize、brain_pin、brain_unpin、brain_forget、brain_verify（写入——写入内容会同步回 brain-cloud；宿主会要求确认）+ brain_use（在账户的大脑之间切换）。

生产环境中有两点需要了解：

• 一个大脑 ↔ 一个 Google 账户——连接器会提供使用 Firebase（Google） 身份登录的账户所对应的大脑，因此必须将大脑推送到该 brain-cloud 账户。有关连接器现在如何显示错误／空／多大脑账户，而不是静默地提供一个虚幻大脑，请参阅下文的身份与账户。
• 会话可静默续期约一个月——访问令牌有效期为 1 h，但令牌端点会签发轮换刷新令牌（OAuth 2.1：单次使用，重用时撤销整个令牌族），并采用滑动 30 天窗口（CONNECTOR_REFRESH_TTL_MS），因此活跃用户不会看到登录页面。每次刷新也会在服务端续期 Firebase 凭据（通过 securetoken API，使用登录时捕获的刷新令牌），因此即使远超旧版约 1 h 的 Firebase ID 令牌有效期，同步回传和 TTL 重新拉取仍可正常工作。授权信息和 DCR 客户端注册表会持久化到 CONNECTOR_STATE_DIR（systemd StateDirectory；Firebase 刷新令牌通过 CONNECTOR_STATE_KEY 静态加密，本站令牌以哈希形式存储），因此部署／重启不再会让用户退出登录。本地 CLI 记忆（brain cloud push）会通过 TTL 重新拉取（CONNECTOR_REPULL_TTL_MS，默认 120s）自动送达活跃会话——仅在云端校验和发生变化时重新拉取，且绝不会覆盖尚未同步的本地写入。

npm test 会进行类型检查，并在单个服务中端到端验证完整流程——从 OAuth 2.1 握手到真实的评分召回（令牌请求采用 form-urlencoded 格式，与真实客户端一致）：

① unauthenticated MCP call → 401 + WWW-Authenticate (RFC 9728)
② discovery → AS metadata (RFC 8414), PKCE S256
③ Dynamic Client Registration (RFC 7591)
④ authorize → code (iss + state validated, RFC 9207)
⑤ token → audience-bound Bearer (PKCE verified, RFC 8707)
⑥ MCP initialize + tools/list → [brain_recall, brain_status, brain_use, brain_memorize, brain_pin, brain_unpin, brain_forget, brain_verify]  (official SDK)
⑦ brain_recall(query) → the brain's REAL scored results (relevance + decayed
   strength + spreading activation), identical to the CLI

召回如何与 CLI 保持一致

引擎桥接程序（src/engine.ts）会运行仓库的 bin/recall.js，并将 BRAIN_DIR 指向已通过身份验证的用户的大脑工作副本——因此连接器的评分与 CLI 逐字节一致，无需重新实现。（BRAIN_DIR 与 CLI 自带的覆盖项相同。）

运行／测试

npm install
npm test          # end-to-end Phase 1 proof
npm start         # serve MCP on http://localhost:8788

工具

工具	类型	描述
brain_recall	读取（readOnlyHint）	根据查询进行排名检索，由 brain 引擎评分。
brain_status	读取（readOnlyHint）	用户的 brain 记忆数量和最后更新时间，以及账户中的所有 brain，并用 active 标记正在使用的 brain。
brain_use	写入（idempotentHint）	按名称或 ID 切换连接器提供服务的账户 brain。此选择会跨会话保留；不会在 brain 之间复制任何内容。
brain_memorize	写入（destructiveHint）	存储提供的明确内容（绝不存储对话）；可立即检索。
brain_pin / brain_unpin	写入（destructiveHint、idempotentHint）	将记忆移入或移出常驻层。
brain_forget	写入（destructiveHint）	归档记忆（可恢复 — 移至 _archived/，而非永久删除）。
brain_verify	写入（destructiveHint）	列出待验证的记忆；批准它们，或将其拒绝并移入归档。

写入操作会复用确定性 CLI（memorize.js / pin.js / unpin.js / forget.js），然后 执行 syncBack() 同步回 brain-cloud。

身份与账户

一个 brain ↔ 一个 Google 账户。 连接器不知道你使用的是哪台笔记本电脑 — 它会提供 Firebase（Google）身份完成登录后所属 brain 的服务。经过验证的 uid 会确定性地映射到 一个 brain 用户（resolveBrainUserId），并从 brain-cloud 拉取该用户的规范 brain： 即用户通过 brain_use 选择的 brain；若未选择，则使用账户中最早创建的 brain。因此 规则很简单：使用 CLI 的 brain cloud 同步到的同一个 Google 账户连接，并使用 同一个 brain（brain cloud brains 会显示 CLI 关联的是哪个 brain）。

为避免该规则失效时毫无提示，ensureUserBrain 会返回一个 identity 信号，供工具 显示给你：

情况	identity.status	你会看到什么
账户在 Brain Cloud 中没有 brain	no-cloud-brain	一条提示（显示在 brain_status 中；如果 brain_recall 没找到任何内容，也会显示），说明此账户为空 — 最可能是你使用了错误的 Google 账户登录，或者你是新用户。
账户恰好有一个 brain	ok	无提示 — 这是常见且明确的情况。
账户有多个 brain	multiple-brains	一条提示，指出当前使用的 brain。brain_status 会列出所有 brain；brain_use 可切换 brain，选择会随 OAuth 状态按用户保存，并在之后的会话中沿用。之后如果所选 brain 被删除，则会回退到最早创建的 brain。

这是指引，而非强制措施 — 真正的新用户即使还没有 brain，仍会获得一个可用的空 brain。账户关联（让一个 Google 身份同时关联多个 brain）已特意延后处理；一次选择一个 brain 的操作是 brain_use。

身份验证

现在有两层 — 都已实际启用：

1. Claude 与连接器之间的 OAuth 2.1（src/oauth.ts）：authorize / token / register / metadata、PKCE S256、RFC 8707 受众绑定、RFC 9207 iss。令牌会签发到 src/auth.ts 的存储中；/mcp 守卫会验证令牌（包括受众）。
2. 用户身份（src/firebase.ts）：/authorize 会将用户重定向至 Firebase 登录（与 brain-cloud 使用同一项目）。连接器会在服务端验证 ID 令牌，且无需 密钥 — 使用 Google 公共证书验证 RS256，并检查 aud / iss / exp — 因此只需要公开的项目配置，无需服务账户密钥。经过验证的 uid 会映射到 brain 用户，然后签发 OAuth code。

如果未设置 FIREBASE_* 环境变量，/authorize 会回退到固定的开发用户 （STUB:FIREBASE），让无头测试无需浏览器即可运行。

查看 Firebase 登录流程（演示）

cp .env.example .env      # fill in FIREBASE_API_KEY / AUTH_DOMAIN / PROJECT_ID
npm start                 # http://localhost:8788
# then connect an MCP client (e.g. Claude) to http://localhost:8788/mcp —
# the OAuth flow opens the branded Google sign-in page from /authorize

通过 /authorize 登录会显示带品牌标识的授权／登录页面；登录成功后，会解析已验证的 firebase_uid → brain_user_id → brain_dir，连接器据此确定要提供哪个用户的脑库。（默认情况下，localhost 是 Firebase 授权域名，因此可以在本地使用弹出式登录。）

按用户划分的存储（src/store.ts）

ensureUserBrain({ userId, brainDir, idToken }) 会通过可插拔的提供方填充用户的脑库工作副本，然后引擎会在其中进行回忆。提供方（通过 CONNECTOR_STORE 指定，否则自动推断）：

• brain-cloud（生产环境）——使用用户的 Firebase ID token（brain-cloud 的中间件可直接接受该令牌）从 BRAIN_CLOUD_API_URL（默认为 https://api.brainmemory.ai）拉取用户的 {brainID}.tar.gz，然后解压到 brainDir。每次登录时都会刷新。
• local（开发环境）——将 brainDir 符号链接到 $DEV_LOCAL_BRAIN（你当前使用的 ~/.brain），让你的机器通过连接器提供真实的脑库。
• none——假定已预先配置（用于测试）。

始终优雅处理：如果脑库仍不存在，就初始化一个有效的空脑库（可安全进行回忆）。

brain-cloud 提供方遵循存储契约，因此适用于任何实现该契约的存储，包括可自托管的 brain-store。回写同步采用条件请求（If-Match）：如果另一台设备先推送，连接器会丢弃自己的工作副本，从存储中的脑库重新开始、重新应用写入并再次推送，避免覆盖任何人的记忆。

身份提供方（src/identity.ts）

谁在登录，以及连接器代表其向存储提供什么凭据，都由同一接口管理。使用 CONNECTOR_IDP 选择：

• firebase（设置了 FIREBASE_* 时的默认值）——Google 登录。存储凭据为 Firebase ID token，并通过 Firebase refresh token 更新。

• static——用于自托管存储。登录页面会要求输入存储运营者签发的令牌（brain-store user add）；用户身份由存储决定。必须显式设置 BRAIN_CLOUD_API_URL，确保令牌绝不会意外发送到托管服务的默认地址。在存储端轮换或移除用户后，其会话会在下次静默续期时终止。

• oidc——用于接受组织 OpenID Connect 发行方的自托管存储（Entra、Google Workspace、Keycloak、Okta）。/authorize 会将浏览器转到发行方（使用授权码 + PKCE + nonce），发行方再将浏览器返回到 /oidc/callback。ID token 是存储凭据，并通过发行方的 refresh token 更新。需要设置 OIDC_ISSUER、OIDC_CLIENT_ID 和显式指定的 BRAIN_CLOUD_API_URL。令牌验证由存储自身负责（store/lib/oidc.js），因此双方对有效令牌的判断不会出现分歧。发行方故障时会返回 503 并保留登录状态；撤销令牌则会终止会话。

未配置任何提供方时，连接器在生产环境中会拒绝启动。当反向代理不在回环地址上时（例如位于另一个容器中），请使用 CONNECTOR_TRUST_PROXY 为其命名，例如 uniquelocal；不接受 true。

后续计划

• 账号关联——允许一个用户同时关联多个脑库（跨脑库回忆），而不是一次只提供一个选定的脑库。请参阅身份与账号。
• 提交至目录——剩余的手动步骤（测试账号、MCPB 打包、发布帖子）；请参阅 brain-cloud/docs/connector-architecture.md 第 7 节中的提交检查清单。