USRCP — User Context Protocol

A private context brief for the human behind every AI tool. Continue your work across interfaces without repeating the briefing.

You told Claude Desktop your stack on Tuesday. On Wednesday, Cursor doesn't know. Thursday, Codex asks again. Every AI tool you use has its own memory, or none.

USRCP is a local, encrypted SQLite ledger that any MCP-aware tool can read and write. One install, one passphrase, and every tool shares the same structured user state — your timezone, your stack, your projects, your preferences.

Registers with Claude Desktop, Cursor, Continue, Cline, and terminal agents (Claude Code, Codex CLI, Copilot CLI, Aider, OpenCode, Antigravity). Captures structured activity from GitHub, Linear, Obsidian, Claude Code sessions, and Google Calendar — plus an experimental conversation-capture set.

brew install frank-bot07/usrcp/usrcp
usrcp init

→ See it work: the cross-editor demo, or prove the claim on your own machine in one command — node scripts/cross-client-proof.mjs (writes state as one editor, reads it as another, then scans the raw DB to show it's all ciphertext). → Apache 2.0 · 600+ tests · threat model in docs/SECURITY.md

Core and optional features: the structured core uses exact-keyword lookup. Optional usrcp-stream adds semantic recall with a different storage/privacy boundary; see the capability matrix below.

Protocol Stack

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

One human, many AI interfaces

USRCP is the human user's context layer. The launch workflow is live retrieval of a compact brief from one shared ledger. Your next assistant should know the relevant ongoing work, decisions, constraints and next steps.

usrcp handoff --domain=coding --output=HANDOFF.md

Connected MCP clients call usrcp_handoff to get current context and save meaningful updates immediately. The file command above is an optional manual fallback. The local MCP server provides startup instructions, but clients must honor them; verify actual behavior with the two-client acceptance test. A shared ledger alone does not prove automatic retrieval.

Capability and privacy boundaries

The initial supported workflow is developers switching Claude Code, Codex and Cursor, with Markdown export available for other interfaces. The broader goal remains continuity for the human user across tools. Read context ownership for inspection, correction, provenance, expiry and deletion alternatives.

Alternatives

OpenMemory also targets cross-tool coding context and automatic capture. Zep provides temporal knowledge graphs. These products overlap with parts of USRCP's workflow. USRCP's proposed advantage is a small, inspectable human-context brief backed by a local encrypted ledger, explicit sharing and no required cloud account for the core workflow. Compare current editions and test against your existing project notes; do not assume other products are merely vector storage or always require a particular provider.

Quickstart

Install

npm (recommended) — the usrcp CLI + encrypted ledger:

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

No native build, no compiler, no postinstall — usrcp uses Node's built-in SQLite (node:sqlite), so npm install just works on any npm (including npm 12+, whose allowScripts default blocks native build scripts). Requires Node ≥ 22.13 (Node 24+ recommended).

Homebrew (macOS / Linux) — alternative for the core CLI:

brew install frank-bot07/usrcp/usrcp

The CLI ships with the inline adapters (terminal, mcp-agent, openclaw). Capture adapters install as their own packages, then you configure each with the setup wizard:

# 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

See the Adapters table for the full list (the Chrome extension and VS Code viewer ship separately — see their package READMEs).

From source — for contributing or running unreleased changes:

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

First run

# 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

In passphrase mode, init offers to store the passphrase in the OS keychain (macOS Keychain / Linux Secret Service); pass --keychain / --no-keychain to decide non-interactively. With a keychain entry present, MCP clients auto-start the server with no plaintext passphrase in any config file. Manage the entry anytime:

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 creates ~/.usrcp/users/<slug>/ with an encrypted SQLite ledger and writes the MCP server entry to Claude Desktop's config:

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

Single-user is the default and what every shared-machine consideration in the rest of this README assumes. If two people use the same OS account (or you run multiple identities side by side), see Multiple users on one machine below — each user gets an independent ledger and passphrase under a --user=<name> slug.

Adding capture adapters

Adapters watch a source (a GitHub org, an Obsidian vault, a Linear workspace, etc.) and append the activity you authored into the same ledger your local MCP server reads from. Install the adapter's package, then run the setup wizard to configure it:

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

See the Adapters tables below for the full list.

Multiple users on one machine

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

Each user gets an independent ledger, passphrase, and MCP server entry.

Passphrase mode and terminal agents

If you initialized USRCP in passphrase mode (usrcp init with the default), the MCP server needs the passphrase to decrypt the ledger. The terminal-adapter register() writes only command + args to each agent's config — it never bakes the passphrase in.

Recommended: the OS keychain. One command covers every agent — shell-launched and GUI alike — with nothing in plaintext on disk:

usrcp keychain store

The server checks USRCP_PASSPHRASE, then --passphrase, then the keychain, so existing setups keep working unchanged. (Windows: keychain support isn't wired up yet — use the env-var paths below.)

Env-var alternatives, if you'd rather not use the keychain:

• Shell-launched agents (claude-code, codex, copilot-cli, aider, opencode) — add to ~/.zshrc / ~/.bashrc and restart your shell:

  server.ts

  Copy

  export USRCP_PASSPHRASE="your secret phrase"
  

• GUI/IDE-launched agents (cursor, cline, continue, antigravity) do not inherit shell environment. Either add an env block under the usrcp server entry in the agent's config file (JSON for Cursor/Cline/Continue, TOML for Codex), or set a system-wide GUI env on macOS with launchctl setenv USRCP_PASSPHRASE "..." (persists until reboot; use a ~/Library/LaunchAgents/ plist for permanence).