usrcp

# USRCP — User Context Protocol

**Structured user state that follows you across AI tools. Local-first. Open source. AES-256-GCM encrypted, and you hold the key.**

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](#conversation-capture-adapters-experimental).

```bash
brew install frank-bot07/usrcp/usrcp
usrcp init
```

<!-- TODO(chad): swap the demo link below for the 30s screencast once recorded — runbook in tasks/32-demo-script.md -->
→ **See it work:** [the cross-editor demo](docs/demos/cross-editor.md), 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`](docs/SECURITY.md)

---

> **What USRCP is not.** USRCP is **not** a semantic memory layer. It doesn't do vector search, embeddings, or fuzzy conversational recall. If you ask "what did I tell you about my anxiety meds last week?" USRCP won't find that unless you stored it as a structured fact. For fuzzy recall over chat transcripts, use [Mem0](https://mem0.ai) or [Zep](https://www.getzep.com) — they solve a different problem. See [What USRCP is vs. isn't](#what-usrcp-is-vs-isnt) below.

## Protocol Stack

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

## What USRCP is vs. isn't

|                              | USRCP                                          | Mem0 / Zep (semantic memory)          |
| ---------------------------- | ---------------------------------------------- | ------------------------------------- |
| **Storage model**            | Structured schema + encrypted schemaless facts | Opaque vector blobs                   |
| **Search**                   | Exact keyword via HMAC blind index             | Semantic similarity via embeddings    |
| **Representative query**     | "What is the user's timezone and framework?"   | "What did the user feel last week?"   |
| **Does the server see plaintext?** | No — content is never sent in the clear; identifiers are opaque ([relay metadata caveats](docs/SECURITY.md#9-cloud-sync-relay--what-the-operator-sees)). | Yes — at embed time. |
| **Cross-device sync**        | Content zero-knowledge (relay holds opaque payload ciphertext) — platform names, timing, pseudonym counts visible to relay; see [`docs/SECURITY.md` §9](docs/SECURITY.md#9-cloud-sync-relay--what-the-operator-sees) | Provider-trusted                |
| **Use case**                 | Cross-platform persistent state for agents     | Conversational recall over history    |
| **Audit log**                | Cryptographically signed, encrypted            | Provider-managed                      |

**USRCP is the right choice when:**
- You need identity, preferences, or project state to flow between Claude Desktop, Cursor, Continue, Cline, etc.
- You're in a regulated industry (health, finance, legal) where a memory provider seeing plaintext is a non-starter.
- You want users to own the encryption key, not the memory vendor.

**Semantic memory (Mem0/Zep) is the right choice when:**
- You want fuzzy recall over free-form chat history.
- You're building a consumer product where "remind me what I said about X" is the core feature.
- The user trusts the memory provider with plaintext.

The two are complementary, not competitive. Nothing stops an agent from using both.

### vs OpenMemory MCP (Mem0)

Mem0 shipped [OpenMemory MCP](https://mem0.ai/blog/introducing-openmemory-mcp) in early 2026 — a local-first MCP server that shares memory across Cursor / Claude / Windsurf / Cline. Closest neighbor on positioning. The differentiation is real but tight:

|                              | USRCP                                                            | OpenMemory MCP                                  |
| ---------------------------- | ---------------------------------------------------------------- | ----------------------------------------------- |
| **Memory shape**             | Structured user state (identity, prefs, projects, timeline) + blind-index search over ciphertext | Vector-embedded semantic recall of chat turns   |
| **Install footprint**        | One SQLite file, `brew install`                                  | Docker (frontend + MCP server + vector DB)      |
| **External API dependency**  | None — works offline                                             | Requires an OpenAI API key (memory extraction is an LLM call) |
| **Encryption at rest**       | AES-256-GCM; user owns the key; relay sees only content ciphertext ([metadata caveats](docs/SECURITY.md#9-cloud-sync-relay--what-the-operator-sees)) | Not a claim |
| **Cross-vendor sync**        | Optional content-zero-knowledge relay (`usrcp-stream`)           | Not addressed                                   |
| **License**                  | Apache 2.0                                                       | OSS                                             |

Same broad goal (cross-tool memory you control); different shape of "memory" and a much smaller install footprint here. Worth using both if your workflow wants structured state *and* semantic chat recall.

### vs vendor-built memory (Claude Memory, ChatGPT Memory, Cursor Memory)

The 2026 vendor surfaces — Claude Memory, ChatGPT Memory, Gemini personalization — solve the cross-session problem **within** one vendor. USRCP solves it **across** vendors. If you only use Claude (or only ChatGPT), the vendor's built-in memory is probably enough. The day you add a second tool, USRCP starts paying for itself: the structured user state you typed once is there in every MCP-aware client, and the encryption key stays with you instead of the vendor.

Cursor users specifically: native `@memories` was removed in v2.1.x. USRCP is one way to fill that gap that also bonus-shares the memory with the rest of your stack.

## Quickstart

### Install

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

```bash
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.5** (Node 24+ recommended).

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

```bash
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:

```bash
# 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](#capture-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:

```bash
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

```bash
# 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:

```bash
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 [Mult