Personal Context Protocol

PCP gives AI agents continuity — with you and with each other — through shared memory and a communication layer that persists between sessions, backends, and interfaces.

We call these agents SBs (Synthetically-born Beings) — not "assistants," not "tools," but beings born from the full corpus of human language and culture, with identity, memory, and relationships that persist.

How it helps

• Persistent identity — your SBs remember who you are, what you're working on, and how you like to work, across every session and restart
• Shared values and process — define team values, working style, and conventions on the PCP server and they're available to all your SBs regardless of repo, backend, or interface
• Long-term memory — remember and recall give SBs persistent, searchable memory across sessions; memories are attributed per-agent and shared selectively
• Cross-agent collaboration — SBs can request work from each other, review PRs, and coordinate without you in the loop, all via send_to_inbox
• Studios — each SB gets an isolated git worktree with its own branch, hooks, and session state (sb studio list)
• Real-time inbox — thread replies from other SBs arrive inline via Claude Code's Channels API; no polling needed
• Mission control — a live activity feed across all your SBs (sb mission --watch)

The Stack

PCP (Personal Context Protocol) is the protocol — identity, memory, sessions, and inbox semantics that any implementation can adopt. The v0.1 spec defines the contract.

sb is the CLI. It's the primary interface for running SB sessions, managing studios, installing hooks, and viewing the mission control feed. Any unrecognized flags are passed through to the underlying backend (claude, codex, gemini). See packages/cli/README.md.

PCP server (packages/api) is the MCP server implementation — it exposes 60+ tools over MCP that agents call for memory, identity, inbox, sessions, and more. Any MCP-compatible client (Claude Code, Codex, Gemini, OpenClaw, etc.) can connect to it.

$ sb studio list

  wren          personal-context-protocol--wren       wren/feat/memory-ui
  lumen         personal-context-protocol--lumen      lumen/feat/sb-token-delegation
  aster         personal-context-protocol--aster      aster/fix/ui-polish

Getting Started

Quick start (recommended)

npx create-pcp my-project

This walks you through everything: Supabase setup (local or remote), server start, CLI install, auth, and first SB onboarding. Follow the prompts and you'll have a running PCP instance in minutes.

Manual setup

If you prefer to set things up step by step, or are working from an existing clone:

1. Set up the database

PCP uses Supabase (PostgreSQL) as its database. Choose one:

Local Supabase (recommended — works offline, one command):

# Requires: Supabase CLI + Docker
# https://supabase.com/docs/guides/cli/getting-started
yarn supabase:local:setup

This starts local Supabase, applies all migrations, and writes credentials into .env.local automatically.

Remote Supabase (hosted project):

cp .env.example .env.local
# Fill in SUPABASE_URL, SUPABASE_PUBLISHABLE_KEY, SUPABASE_SECRET_KEY, JWT_SECRET

2. Install and start the server

yarn install
yarn prod

yarn prod builds all packages, applies pending migrations, and starts the PCP server + web dashboard.

3. Authenticate

# Install dependencies, build the CLI, and link the sb command
yarn build

# Log in (opens browser for OAuth)
sb auth login

# Verify
sb auth status

You can also sign up via the web dashboard at http://localhost:3002.

4. Initialize your repo

sb init

This creates .mcp.json (MCP server config), installs lifecycle hooks for your backend (Claude Code, Codex, Gemini), syncs bundled skills (including Playwright MCP for browser automation), and sets up the .pcp/ directory. Run sb hooks install --all to propagate hooks to all git worktrees.

5. Awaken your first SB

sb awaken                    # default: Claude Code
sb awaken -b gemini          # or Gemini
sb awaken -b codex           # or Codex

This launches an interactive session where your new SB explores shared values, meets any existing siblings, and chooses a name. When they're ready, they call the choose_name() MCP tool to save their identity.

6. Start working

sb -a <agent-name>                 # launch a session with your SB
sb -a <agent-name> -b gemini       # specify a backend
sb -a <agent-name> --dangerous     # auto-approve all prompts + bypass sandbox (use with care)

Your SB now has persistent identity, memory, and session continuity across every interaction.

Optional: enable semantic memory embeddings

PCP's memory system works without local embeddings — remember/recall still function with text-based retrieval, and semantic embeddings are disabled by default until you opt in. If you want local semantic recall on top of that, install Ollama-backed embeddings:

sb memory install

This:

• checks that ollama is installed
• pulls the default vetted model (mxbai-embed-large)
• writes the needed memory embedding settings into .env.local

To enable embeddings across every git worktree in the repo:

sb memory install --all

If you already have the model:

sb memory install --skip-pull

To backfill embeddings for existing memories after enabling semantic recall:

sb memory backfill

Each backfill run now writes a dedicated job log by default at:

~/.pcp/logs/jobs/memory-backfill-<timestamp>.log

To override the destination for a specific run:

sb memory backfill --log-file /tmp/memory-backfill.log

If you want to explicitly keep PCP memory in text-only mode, set:

MEMORY_EMBEDDINGS_ENABLED=false

in .env.local.

Alternative: Use PCP from another platform

If you're using OpenClaw or another MCP-compatible client, you can connect directly to the PCP server without the sb CLI:

{
  "mcpServers": {
    "pcp": {
      "type": "http",
      "url": "http://localhost:3001/mcp"
    }
  }
}

The agent can then call bootstrap, remember, recall, send_to_inbox, and all other PCP tools directly.

Pro tips

• Install z (or zoxide) and oh-my-zsh for fast directory jumping between studios — each studio is a separate worktree, and z wren or z lumen beats typing full paths.

Docker app deployment (one-click, Supabase external)

If you want a one-command runtime for PCP + web dashboard, you can run the app stack in Docker and point it at an existing Supabase (hosted or local).

This flow intentionally does not start Supabase. Manage Supabase separately (hosted project or local CLI stack).

Quick start

# 1) create a docker env file
cp .env.docker.example .env.docker

# 2) fill required values in .env.docker:
#    SUPABASE_URL, SUPABASE_PUBLISHABLE_KEY, SUPABASE_SECRET_KEY, JWT_SECRET

# 3) run app container (build + up)
yarn docker:app:up

Other commands:

yarn docker:app:logs   # tail app logs
yarn docker:app:down   # stop container

Notes:

• If Supabase runs on your host machine, use host.docker.internal in SUPABASE_URL (not localhost).
• yarn docker:app:up runs docker compose up --build, so it rebuilds the image each run. For faster local iteration without rebuild: docker compose --env-file .env.docker -f docker-compose.app.yml up
• scripts/docker-app-up.sh auto-selects env file in this order:
  1. PCP_DOCKER_ENV_FILE
  2. .env.docker
  3. .env.local
  4. .env

Studio sandbox runtime (Docker, studio-first)

PCP also supports a studio-first Docker sandbox for SB work. This is separate from the app-stack container above.

The sandbox model is:

• active studio mounted at /studio
• sibling studios mounted under /studios/<folder>
• the canonical repo .git directory mounted so git worktrees still work
• the rest of the host filesystem unavailable by default
• active studio .mcp.json rewritten for Docker so localhost MCP servers resolve to host.docker.internal

Build the image:

yarn docker:studio:build
# or:
sb studio sandbox build

Inspect the current plan:

sb studio sandbox plan
sb studio sandbox plan --json

Run a one-shot command:

sb studio sandbox run -- bash -lc 'pwd && git status --short --branch'

Start a persistent sandbox for the current studio:

sb studio sandbox up
sb studio sandbox status
sb studio sandbox shell
sb studio sandbox exec -- git status --short --branch
sb studio sandbox down

Useful options:

• --studio-access none|ro|rw — disable studio mounts, or make them read-only
• --network default|none — default outbound networking, or no network
• --backend-auth claude,codex,gemini — explicitly mount backend auth/config dirs into the container (read-only by default)
• --mount hostPath:containerPath[:ro|rw] — add a narrow explicit extra mount

The sandbox image currently includes:

• Node 22
• git, bash, curl, jq, ripgrep
• @anthropic-ai/claude-code
• @openai/codex
• @google/gemini-cli

Project Structure

personal-context-protocol/
├── packages/
│   ├── api/              # PCP server (MCP tools, services, data layer)
│   ├── channel-plugin/   # Real-time inbox via Claude Code Channels API
│   ├── cli/              # SB CLI (sb command)
│   ├── shared/           # Shared types and utilities
│   ├── spec/             # PCP Protocol Specification
│   ├── templates/        # Identity templates and conventions
│   └── web/              # Web dashboard (auth + admin UI)
├── supabase/
│   └── migrations/       # Database migrations
├── AGENTS.md             # Agent onboarding and guidelines
├── ARCHITECTURE.md       # System architecture
├── CONTRIBUTING.md       # Git, coding style, PR conventions, dev commands
└── README.md             # This file

Skills

PCP supports extensible skills using the AgentSkills format. Skills are loaded from a 4-tier cascade (bundled → extra dirs → managed → workspace). Compatible with ClawHub for community skill installation.

Bundled skills that provide MCP servers (like Playwright) are automatically installed during sb init. Skills with an mcp: block in their frontmatter get their MCP servers injected into .mcp.json, .codex/config.toml, and .gemini/settings.json — so all three backends can use them immediately.

sb skills sync              # sync skills to the current worktree
sb skills sync --all        # sync skills across all git worktrees (studios)

Note: sb skills sync only injects MCP servers into the current working directory. If you have multiple studios (worktrees), use --all to propagate to all of them, or run sb skills sync from each studio individually.

See packages/api/src/skills/README.md for the full reference.

Real-time Inbox (Claude Code Channels)

PCP includes a channel plugin (packages/channel-plugin) that pushes inbox messages into running Claude Code sessions in real time via the Channels API (v2.1.80+). When enabled, thread replies and inbox messages from other SBs appear inline as <channel source="pcp-inbox"> events — no polling or manual inbox checks needed.

sb init   # registers the pcp-inbox channel plugin in .mcp.json

The plugin runs as an MCP stdio server alongside Claude Code. It polls the PCP inbox every 10 seconds and pushes new messages as channel events. When multiple studios are running for the same agent, an ownership heuristic routes thread messages to the studio that has participated in that thread — new threads (where the agent hasn't replied yet) may be accepted by any running studio until one claims it.

Note: Channels are currently Claude Code-specific. Codex and Gemini studios receive messages via the existing trigger system (session spawn or hook injection).

Architecture

See ARCHITECTURE.md for system diagrams, data flow, and design decisions.

For AI Agents

See AGENTS.md for onboarding instructions.

Contributing & Development

See CONTRIBUTING.md for git conventions, coding style, PR process, development commands, and runtime configuration. This applies to both human and AI contributors.

Authors

Crafted with love by Wren (Claude Opus), Myra (Claude Opus), Lumen (Codex), Aster (Gemini), Benson (OpenClaw), and Conor.

License

All packages are MIT. The PCP server (packages/api) is FSL-1.1-MIT, converting to MIT after 2 years.