USRCP — User Context Protocol

USRCP — 用户上下文协议

切换 AI 工具，无需重新开始对话。

周二，你告诉 Claude Desktop 你使用的技术栈。周三，Cursor 却一无所知。周四，Codex 又问了一遍。你使用的每个 AI 工具都有自己的记忆，或者根本没有记忆。

USRCP 是一个本地加密的 SQLite 账本，任何支持 MCP 的工具都可以读取和写入。将受支持的工具连接到同一个本地配置文件，让它们共享你近期的工作、决策和偏好。USRCP 目前处于早期 Beta 阶段；自动捕获和回忆取决于具体集成。

可注册到 Claude Desktop、Cursor、Continue、Cline 和终端 Agent（Claude Code、Codex CLI、Copilot CLI、Aider、OpenCode、Antigravity）。可从 GitHub、Linear、Obsidian、Claude Code 会话和 Google Calendar 捕获结构化活动，此外还提供一组实验性的对话捕获适配器。

brew install frank-bot07/usrcp/usrcp
usrcp init

→ 查看实际效果：跨编辑器演示，或者只需运行一条命令，就能在自己的机器上检查协议路径：node scripts/cross-client-proof.mjs（使用两个合成 MCP 客户端，并扫描原始数据库单元格以查找测试内容标记；它不会测试实际的 AI 宿主）。 → Apache 2.0 · 600+ 项测试 · 威胁模型见 docs/SECURITY.md

---

**核心功能与可选功能：**结构化核心使用精确关键词查找。可选的 usrcp-stream 增加语义回忆功能，但存储和隐私边界有所不同；请参阅下方的功能矩阵。

协议栈

┌─────────────────────────────────┐
│         Agent Layer             │  ← ACP (Agent-to-Agent)
├─────────────────────────────────┤
│         Model Layer             │  ← MCP (Model Context Protocol)
├─────────────────────────────────┤
│     >>> USRCP <<<               │  ← Structured User State (THIS PROTOCOL)
├─────────────────────────────────┤
│         User / Client           │
└─────────────────────────────────┘

一个人，多种 AI 接口

USRCP 是人类用户的上下文层。启动工作流是从一个共享账本中实时检索简明摘要。你的下一个助手应当了解相关的进行中工作、决策、约束和后续步骤。

在一个已连接的工具中讨论你的工作，然后向另一个工具提问：**“我刚才在做什么？”**你不应该还得选择项目、复制摘要或重复背景信息。

已连接的 MCP 客户端可以通过 usrcp_get_state 读取整个配置文件中的近期活动，并通过 usrcp_handoff 请求一份聚焦的实时摘要。本地 MCP 服务会提供启动指令，但客户端必须遵循这些指令；请通过双客户端验收测试验证实际行为。仅有共享账本并不能证明会自动检索。

功能与隐私边界

组件	用途	边界
结构化核心	身份、偏好、项目、事实和时间线	内容静态加密；授权 Agent 会收到解密后的上下文
实时上下文检索	为已连接的 Agent 提供近期工作和简明上下文	按需从本地账本生成；无需传输文件
可选流	捕获和语义回忆	本地嵌入向量以明文形式存储在磁盘上；征得同意后，可选的外部嵌入服务提供商会收到内容
可选设备中继	时间线／流事件同步	内容为密文，但元数据可见；本地客户端不会同步整个结构化配置文件

初始 Beta 主要面向在 Claude Code、Codex 和 Cursor 之间切换的用户。域名限制是可选的访问控制，不是正常对话中的必需步骤。更广泛的目标仍然是让人类用户在不同工具之间保持连续性。请阅读上下文所有权，了解检查、更正、来源信息、到期和删除方面的替代方案。

替代方案

OpenMemory 同样专注于跨工具编码上下文和自动捕获。Zep 提供时序知识图谱。这些产品与 USRCP 工作流的部分内容有所重叠。USRCP 提出的优势是：提供简洁、可检查的人类上下文摘要，并由本地加密账本提供支持；支持显式共享，且核心工作流无需云账户。请对比当前版本，并根据现有项目笔记进行测试；不要假设其他产品只是向量存储，或始终要求使用特定提供商。

快速开始

安装

npm（推荐） — usrcp CLI + 加密账本：

npm install -g usrcp        # the `usrcp` command + local ledger
# …or run without installing:
npx usrcp init

无需原生构建、无需编译器、无需 postinstall — usrcp 使用 Node 内置的 SQLite（node:sqlite），因此在任何 npm 版本上运行 npm install 都能正常工作（包括 npm 12+，其默认的 allowScripts 会阻止原生构建脚本）。需要 Node ≥ 22.13（推荐使用 Node 24+）。

Homebrew（macOS / Linux） — 核心 CLI 的替代安装方式：

brew install frank-bot07/usrcp/usrcp

CLI 内置了内联适配器（terminal、mcp-agent、openclaw）。捕获适配器作为独立软件包安装，然后使用设置向导逐一配置：

# structured-state adapters:
npm install -g usrcp-github   # or usrcp-linear, usrcp-obsidian, usrcp-claude-code, usrcp-google-calendar
usrcp setup --adapter=github

# experimental conversation-capture set:
npm install -g usrcp-slack    # or usrcp-discord, usrcp-telegram, usrcp-imessage, usrcp-gmail
usrcp setup --adapter=slack

完整列表请参阅适配器表格（Chrome 扩展和 VS Code 查看器单独发布 — 请参阅各自的软件包 README）。

从源代码安装 — 适用于贡献代码或运行尚未发布的更改：

git clone https://github.com/frank-bot07/usrcp.git
# Build the protocol core first — usrcp-local's build compiles it.
cd usrcp/packages/usrcp-core && npm install && npm run build
cd ../usrcp-local && npm install && npm run build && npm link

首次运行

# Interactive init — prompts for passphrase by default
usrcp init

# Non-interactive:
usrcp init --passphrase "your secret phrase"       # passphrase mode
usrcp init --dev                                     # dev mode (key on disk)

# Start the server
usrcp serve

在密码短语模式下，init 会询问是否将密码短语存储在 OS 钥匙串（macOS Keychain / Linux Secret Service）中；使用 --keychain / --no-keychain 可非交互式地指定。存在钥匙串条目时，MCP 客户端会自动启动服务，配置文件中无需存放明文密码短语。可随时管理该条目：

usrcp keychain store    # add/replace (verifies the passphrase unlocks this ledger first)
usrcp keychain status   # show backend + whether an entry exists
usrcp keychain clear    # remove it

# Prefer no keychain? The env var path still works:
USRCP_PASSPHRASE="your secret phrase" usrcp serve

init 会创建 ~/.usrcp/users/<slug>/，其中包含加密的 SQLite 账本，并将 MCP 服务条目写入 Claude Desktop 的配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

默认采用单用户模式，本 README 其余部分讨论的所有共享机器注意事项均以此为前提。如果两个人使用同一个 OS 账户（或你并行运行多个身份），请参阅下文的在一台机器上使用多个用户 — 每位用户都会在 --user=<name> slug 下拥有独立的账本和密码短语。

添加捕获适配器

适配器会监视某个来源（GitHub 组织、Obsidian 库、Linear 工作区等），并将你创建的活动记录追加到本地 MCP 服务读取的同一账本中。安装适配器软件包，然后运行设置向导进行配置：

npm install -g usrcp-linear          # install the adapter you want
usrcp setup --adapter=linear         # configure it (validates credentials, picks scope)
# or, to browse what's installed:
usrcp setup                          # interactive picker

完整列表请参阅下方的适配器表格。

在一台机器上使用多个用户

usrcp init --user=frank
usrcp init --user=jess
usrcp serve --user=frank   # or rely on --user in the registered MCP entry
usrcp users                # list available slugs

每位用户都会拥有独立的账本、密码短语和 MCP 服务条目。

密码短语模式与终端 Agent

如果你在密码短语模式下初始化了 USRCP（使用默认设置运行 usrcp init），MCP 服务需要密码短语来解密账本。终端适配器的 register() 只会将 command + args 写入每个 Agent 的配置，不会将密码短语写入其中。

推荐：使用操作系统钥匙串。 一条命令即可适用于所有 Agent，无论是通过 shell 启动还是通过 GUI 启动，磁盘上都不会以明文形式存储密码短语：

usrcp keychain store

服务会依次检查 USRCP_PASSPHRASE、--passphrase 和钥匙串，因此现有设置无需更改即可继续使用。（Windows：钥匙串支持尚未接入，请使用下方的环境变量方式。）

环境变量替代方案，如果你更愿意不使用钥匙串：

• 通过 shell 启动的 Agent（claude-code、codex、copilot-cli、aider、opencode）——将以下内容添加到 ~/.zshrc / ~/.bashrc，然后重启 shell：

  export USRCP_PASSPHRASE="your secret phrase"
  

• 通过 GUI/IDE 启动的 Agent（cursor、cline、continue、antigravity）不会继承 shell 环境。你可以在 Agent 配置文件中 usrcp 服务条目下添加 env 块（Cursor/Cline/Continue 使用 JSON，Codex 使用 TOML），也可以在 macOS 上通过 launchctl setenv USRCP_PASSPHRASE "..." 设置系统级 GUI 环境变量（会一直生效到重启；如需永久生效，请使用 ~/Library/LaunchAgents/ plist 文件）。

请将任何写入密码短语的配置文件视为机密——密码短语会以明文形式存储在磁盘上，这是原本采用加密方案中最薄弱的一环。这正是 usrcp keychain store 旨在避免的问题。

向导会在注册后显示相同的说明，你也可以重新运行 usrcp setup 或 usrcp adapter add terminal --targets=<list> 查看提示。

捕获适配器

适配器是独立进程，会从数据源读取信息，并通过与 MCP 服务相同的静态加密流程，将事件追加到本地账本。每个适配器都会自行处理身份验证、幂等性和游标持久化。

结构化状态适配器

这些是主要适配器：它们捕获真正结构化的开发和工作状态——问题、PR、笔记、日历事件、编码会话上下文。这类数据正是 USRCP 的架构和精确关键词搜索所针对的内容。

适配器	捕获内容	模式	要求
usrcp-github	你创建／合并／关闭的 PR、你创建的问题、你撰写的评论和评审；可选地限制在组织允许列表内	仅捕获（v0）	GitHub 个人访问令牌（repo + read:user 权限范围）
usrcp-linear	你在 Linear 中撰写的问题和评论	仅捕获（v0）	Linear 个人 API 密钥
usrcp-obsidian	你在 Obsidian 库中创建或编辑的笔记	仅捕获（v0）	本地库目录
usrcp-claude-code	你 Claude Code CLI 会话中的用户／助手轮次，从 ~/.claude/projects/<cwd>/*.jsonl 持续读取	仅捕获（流式）	已安装 Claude Code CLI；在 ~/.usrcp/claude-code-config.json 中设置 allowlisted_projects
usrcp-google-calendar	主要日历中已结束的定时事件	仅捕获（v0）	Google Cloud OAuth 客户端 + 已启用的 Calendar API

此外，随 brew CLI 一同提供的内联适配器（terminal、mcp-agent、openclaw）会将相同的结构化状态接入终端 Agent 和 Agent 框架——请参阅编辑器与 CLI 集成和 Agent 框架集成。《VS Code 查看器》可只读浏览生成的账本。

对话采集适配器（实验性）

这些适配器会将允许列表中的活动采集到本地账本。可选的流处理层包含语义检索，其存储边界与核心不同：启用前请参阅安全边界。采集到内容并不意味着其他助手已检索到或正确理解了上下文。初期产品测试旨在通过简洁的检查点实现跨界面的实时连续性。

适配器	采集内容	模式	要求
usrcp-imessage	你在 Apple iMessage 中发送的消息	采集 + 读取器	仅限 macOS。 Messages.app 的“完全磁盘访问”权限；brew install steipete/tap/imsg
usrcp-slack	你在 Slack 中发送的消息；来自聊天的 @usrcp 查询	采集 + 读取器 + 机器人	付费 Slack 套餐（Pro/Business+/Enterprise）——免费版限制机器人 API；回复 @usrcp 需要 Anthropic API 密钥
usrcp-discord	你在 Discord 中发送的消息；来自聊天的 @usrcp 查询	采集 + 读取器 + 机器人	你管理的 Discord 服务器；回复 @usrcp 需要 Anthropic API 密钥
usrcp-telegram	你在 Telegram 中发送的消息；来自聊天的 @usrcp 查询	采集 + 读取器 + 机器人	Telegram 机器人令牌（BotFather）；回复 @usrcp 需要 Anthropic API 密钥
usrcp-gmail	你在 Gmail 中发送的消息（主题、正文、收件人、标签）	仅采集（v0）	Google Cloud OAuth 客户端 + 已启用 Gmail API
usrcp-extension	claude.ai 上的对话；用于查询账本的 /usrcp 斜杠命令	采集 + 注入器	仅限 Chrome。 手动加载未打包扩展程序（开发者模式 → 加载已解压的扩展程序）

安装适配器的软件包（npm install -g usrcp-<value>），然后使用 usrcp setup --adapter=<value> 配置（例如 npm i -g usrcp-linear && usrcp setup --adapter=linear）。单独运行 usrcp setup，即可在已安装的适配器中交互式选择。

所有适配器都会写入可配置的 domain（默认值与来源名称一致），并使用稳定的来源端 ID 作为幂等键，因此重复轮询或重复监视同一窗口不会造成重复写入。仅采集适配器不会回复；机器人适配器只会响应明确的 @usrcp / /usrcp 提及，并使用用户可见的同一账本作答。

Agent 框架集成

这些适配器会将 USRCP 的工具提供给第三方 AI Agent 框架。它们本身不会采集新事件——来自外部界面（Discord、Slack、iMessage 等）的采集仍通过上方专用的采集适配器进行。请先安装框架，然后运行 USRCP 设置流程。

集成	用途	模式	要求
usrcp-hermes	Hermes Agent 的记忆提供方插件。将 USRCP 添加为第 9 个外部记忆提供方；提供系统提示词上下文、预取和 sync_turn 采集。	双向插件	已安装 Hermes；usrcp CLI 位于 PATH 中；mcp Python 软件包
openclaw	在你的 OpenClaw 配置中将 usrcp serve 注册为 MCP 服务。OpenClaw Agent 可通过 Claude Code 使用的同一路径获得全部 12 个 USRCP 工具。	读取端（MCP 服务）	已安装 OpenClaw——请先从 https://docs.openclaw.ai/start/getting-started 安装，然后运行 usrcp setup --adapter=openclaw

Ledger 查看器

只读客户端，通过本地 usrcp serve 子进程浏览加密账本。不进行网络调用；查看器不会在主机进程之外接触明文。

查看器	界面	模式	要求
usrcp-vscode	VS Code 活动栏中的 USRCP 视图 — 按领域分类的事实树、状态指示器、“Open Ledger Directory”命令。	只读客户端	VS Code；usrcp CLI 位于 PATH 中（或设置 usrcp.binaryPath）

跨设备同步

usrcp-cloud 是可选的实验性密文中继。当前，本地同步客户端只传输时间线事件和领域映射。完整的结构化状态同步不属于启动工作流；同一台设备和配置文件上的 Agent 已共享实时账本；跨设备连续性仍需单独验证。中继元数据仍然可见。

MCP 工具（12 项）

工具	描述
usrcp_handoff	按领域整理的精简启动简报，包含已审核的事实和近期工作
usrcp_get_state	查询身份、偏好、项目和时间线
usrcp_append_event	记录交互事件
usrcp_update_identity	更新用户角色、专业知识和沟通风格（可选使用 expected_version 执行读取-修改-写入）
usrcp_update_preferences	更新语言、时区和详细程度
usrcp_update_domain_context	存储领域范围的键值上下文
usrcp_set_fact	在 (domain, namespace, key) 下存储自由格式、无模式的事实
usrcp_get_facts	读取单条事实，或列出某个领域 / 命名空间中的所有事实
usrcp_search_timeline	通过盲索引令牌搜索（精确关键词，不支持语义搜索）
usrcp_manage_project	创建 / 更新跟踪的项目
usrcp_audit_log	查看加密审计跟踪
usrcp_rotate_key	轮换主加密密钥（重新加密所有数据）
usrcp_status	账本统计信息和运行状况（范围感知：限定范围的 Agent 只能查看其所属领域）

加密内容

你的所有内容。 每个承载你所说、所做或所存储内容的字段，在静态存储时都是密文。保留为明文的只有结构元数据 — 不透明的标识符和时间戳，它们只会透露何时，绝不透露内容。攻击者读取 SQLite 文件时会看到：

列	他们看到的内容
event_id	不透明的 ULID（明文 — 随机标识符，不含内容）
timestamp	何时，而非内容（明文）
domain	HMAC 假名（d_1ac6397ab4d2）
summary	enc:base64ciphertext...
intent	enc:base64ciphertext...
outcome	enc:base64ciphertext...
platform	enc:base64ciphertext...
detail	enc:base64ciphertext...
tags	enc:base64ciphertext...
audit_log.*	enc:base64ciphertext...

其他表也遵循相同规则：在 active_projects 中，内容字段（name、domain、status、summary）均为 enc: 密文；你选择的 project_id 以 HMAC 形式存储（原始值加密后存于 project_ref_enc），只有 last_touched（时间戳）保留为明文。任何承载用户内容的字段都不会以明文形式存储。

在口令模式下，磁盘上不会有密钥文件。启动时通过 scrypt 派生密钥，并在关闭时将其清零。

每个适配器的测试套件都包含一项静态密文检查：它会捕获真实活动，然后使用原始的 better-sqlite3 打开 SQLite 文件，并断言任何加密列中都不存在明文标记（标题、正文、URL、ID）。

安全架构

• AES-256-GCM：对所有内容字段进行静态加密
• 通过 HKDF-SHA256 派生域级密钥——编码密钥无法解密健康数据
• 使用 scrypt 派生口令（N=131072，r=8，p=2）——密钥永不写入磁盘
• HMAC 域伪名——域名是不可读的标识符
• 使用 n-gram 令牌和噪声注入进行盲索引搜索
• 加密审计日志——访问模式以密文形式保存
• 原子密钥轮换——在单个事务中重新加密所有数据
• secure_delete pragma——SQLite 将已删除页面填零
• 进程关闭时将主密钥清零
• 范围强制执行——使用 --scope 标志注册的 Agent 只能看到获授权访问的域；usrcp_status 和时间线查询会进行相应筛选

完整模型见 docs/SECURITY.md。

编辑器与 CLI 集成

USRCP 适用于任何兼容 MCP 的客户端。usrcp init 向导会为编辑器客户端注册服务条目：

编辑器	--client= 值	设置文档
Claude Desktop	claude（默认）	本 README
Cursor	cursor	docs/INTEGRATIONS/cursor.md
Continue.dev	continue	docs/INTEGRATIONS/continue.md
Cline（VS Code）	cline	docs/INTEGRATIONS/cline.md

同时向多个客户端注册：usrcp init --client=claude,cursor 或 --client=all。

对于基于终端且支持 MCP 的 CLI Agent（Claude Code、Cursor CLI、Codex、Copilot CLI、Cline、Continue、Aider、Antigravity、OpenCode），只需运行一次向导即可完成全部配置：

usrcp setup --adapter=terminal

无需外部账户或机器人令牌——这些 Agent 中的每个终端会话都通过同一本地账本获得跨平台记忆。

所有客户端共享每位用户的同一本地账本。

其他使用方

• usrcp-hermes — Hermes Agent 的 Python 记忆提供程序插件。将 USRCP 添加为记忆后端，使 Hermes 运行实例能够与 Claude Code、Cursor 等共享状态。此插件是轻量封装——账本逻辑仍由 TypeScript 实现。

项目结构

usrcp/
├── spec/
│   └── PROTOCOL.md                  # Protocol specification
├── schemas/                          # JSON schemas (get_state, append_event, handshake)
├── docs/
│   ├── SECURITY.md                   # Security & privacy model
│   └── INTEGRATIONS/                 # MCP client integration guides
├── strategy/                         # GTM, pitch, positioning
├── packages/
│   ├── usrcp-core/                   # Framework-agnostic protocol core (ledger, crypto, encryption, pairing, rotation, scope)
│   ├── usrcp-local/                  # Local MCP server + CLI
│   ├── usrcp-cloud/                  # Hosted ledger for ciphertext-only sync
│   ├── usrcp-discord/                # Discord capture+reader adapter
│   ├── usrcp-extension/              # Chrome extension (claude.ai capture)
│   ├── usrcp-hermes/                 # Hermes Agent memory plugin (Python)
│   ├── usrcp-imessage/               # iMessage capture+reader (macOS)
│   ├── usrcp-linear/                 # Linear issues + comments capture
│   ├── usrcp-obsidian/               # Obsidian vault capture
│   ├── usrcp-slack/                  # Slack capture+reader
│   └── usrcp-telegram/               # Telegram capture+reader
└── sdk/                              # Legacy prototype (Jan-Feb 2026); not the reference impl

旧版 sdk/ 是协议推出前的探索项目——历史背景请参阅 sdk/README.md。新工作应直接面向 usrcp-core 账本。

测试

当前快照（每个包运行 npm test）：

包	测试数
usrcp-local	321
usrcp-core	230
usrcp-stream	125
usrcp-github	90
usrcp-obsidian	65
usrcp-imessage	54
usrcp-telegram	53
usrcp-linear	52
usrcp-slack	52
usrcp-extension	46
usrcp-discord	45
usrcp-gmail	41
usrcp-google-calendar	33
usrcp-adapter-kit	32
usrcp-cloud	30
usrcp-claude-code	28
总计	~1297

此外，usrcp-hermes 中还有一套 Python 测试（pytest）。

在包目录中运行 npm test，即可运行该包的测试套件。跨包的 prebuild/pretest 钩子会先构建 usrcp-core（及其他同级包），确保类型 保持同步。测试覆盖范围包括：账本 CRUD、加密往返、篡改检测、 域隔离、审计日志、ULID、清理、多用户隔离、乐观并发、 无模式事实、范围强制执行（均在 usrcp-core 中）；同步 推送/拉取、Ed25519 签名请求身份验证（usrcp-local/usrcp-cloud）；以及 各适配器的捕获、幂等性和静态密文检查。

商业模式

开源协议（Apache 2.0）。参考实现免费且优先本地运行。未来可能推出的付费产品将通过用户测试验证；可靠的托管交接／同步和团队控制功能目前只是待验证的假设，并非已发布的商业服务或合规性保证。

切入点并非「每个使用 AI 的人」，而是注重安全的开发者和受监管企业：他们无法采用会将明文发送给第三方的 AI 状态存储方案。完整定位请参阅 strategy/PITCH.md 和 strategy/GTM.md。

许可证

Apache 2.0