✦ Extended Mind

<p align="center"> <img src="assets/banner.webp" alt="Extended Mind"> </p>

<p align="center"> <a href="LICENSE"><img src="https://img.shields.io/github/license/SnowLightPath/extended-mind" alt="License"></a> <a href="https://github.com/SnowLightPath/extended-mind"><img src="https://img.shields.io/badge/platform-Cloudflare%20Workers-F38020?logo=cloudflare&logoColor=white" alt="Cloudflare Workers"></a> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/protocol-MCP-5A67D8" alt="MCP"></a> </p>

Your context, shared across every AI platform.

Extended Mind is a Personal Context Protocol — a single MCP server that gives Claude, ChatGPT, Codex, and any MCP-compatible AI access to the same personal context.

Two tools. That's it.

context_get()  → returns who you are, what you're working on, what happened recently
context_log(m) → stores a message verbatim — the next AI on a different platform reads it

💡 Why

You switch between Claude Chat, Claude Code, ChatGPT, Codex. Each session starts from zero. Extended Mind fixes this: one server, one context, every platform.

☀️  Morning — Claude Code:  "Refactored the executor to use async"
               └→ context_log(summary)

🌤️ Afternoon — ChatGPT:   context_get()
               └→ "This morning you refactored the executor..."

🌙 Evening — Claude Chat:  context_get()
               └→ knows everything from today

🏗️ Architecture

+---------------+  +---------------+  +---------------+
|  Claude Chat  |  |    ChatGPT    |  |     Codex     |
|  Claude Code  |  |  (OAuth MCP)  |  |               |
+-------+-------+  +-------+-------+  +-------+-------+
        |                   |                  |
        +-------------------+------------------+
                            |
                POST /mcp (Streamable HTTP)
                            |
                  +---------+---------+
                  |    Cloudflare     |
                  |      Worker       |
                  |                   |
                  |  context_get ---->| cached response (~30ms)
                  |  context_log ---->| async write (~30ms response)
                  |                   |   +-> LLM classify (async)
                  |                   |   +-> GitHub backup (async)
                  +-------------------+

• ⚡ KV — hot storage for all reads/writes
• 📦 GitHub — async version history backup (your private data repo)
• 🔍 LLM API — classifies logged messages, extracts priorities, detects contradictions (configurable: OpenAI / Anthropic)
• 🔑 WebAuthn — passkey authentication (Touch ID / Face ID) on OAuth authorize
• 🔗 OAuth 2.0 — authorization code flow for ChatGPT / Claude Chat, with /oauth/revoke (RFC 7009)

🚀 Quick Start

1. Deploy

git clone https://github.com/SnowLightPath/extended-mind.git
cd extended-mind
npm install

# Create KV namespace
npx wrangler kv namespace create PCP
# → Copy the ID into wrangler.toml

# Set secrets
npx wrangler secret put PCP_TOKEN         # your bearer token (generate any 64-char hex)
npx wrangler secret put GITHUB_TOKEN      # GitHub PAT with repo scope
npx wrangler secret put OPENAI_API_KEY    # or ANTHROPIC_API_KEY depending on CLASSIFY_PROVIDER
npx wrangler secret put WEBHOOK_SECRET    # GitHub webhook HMAC-SHA256 secret

# Configure wrangler.toml
# - Set KV namespace ID
# - Set GITHUB_REPO to your private data repo (e.g., "yourname/my-mind")
# - Set CLASSIFY_PROVIDER to "openai" or "anthropic" (default: openai)
# - Optionally set CLASSIFY_MODEL to override (openai: gpt-5.4-mini, anthropic: claude-sonnet-4-6)
# - Optionally set CLASSIFY_REASONING_EFFORT for OpenAI reasoning models (none/low/medium/high/xhigh)
# - Optionally set CLASSIFY_MAX_TOKENS (default: 4096)

npx wrangler deploy

2. Create your data repo

Create a private GitHub repository for your personal context data (e.g., yourname/my-mind). This is where the Worker backs up core.yaml, active.json, and session logs.

Add a webhook in the data repo (Settings → Webhooks):

Field	Value
Payload URL	https://your-worker.workers.dev/webhook
Content type	application/json
Secret	Same value as WEBHOOK_SECRET (required — webhook is rejected without it)
Events	Just the push event

This enables automatic core sync: when you push changes to seed/core.yaml, the webhook notifies the Worker, which updates KV. A cron trigger also runs as a fallback every 5 minutes.

3. Seed your context

Edit seed/core.yaml with your identity. Copy seed/active.template.json to seed/active.json and edit with your work context. Place these in your private data repo (not this repo), then:

node seed/seed-kv.js

This writes 2 initial KV keys (core, active). Additional keys (sessions, pending_classify, OAuth tokens, auth sessions, WebAuthn credentials) are created at runtime. Initial setup only — re-running resets everything and wipes the active context that AI clients have built up.

4. Update core

Core is the human-owned layer — identity, ontology, interaction rules. AI clients cannot write to it.

# Edit seed/core.yaml, then:
git add seed/core.yaml
git commit -m "your change description"
git push

The webhook fires → Worker fetches → KV updated. No wrangler commands needed.

5. Connect your AI clients

🟠 Claude Code — add to ~/.claude/settings.json:

{
  "mcpServers": {
    "extended-mind": {
      "url": "https://your-worker.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_PCP_TOKEN"
      }
    }
  }
}

Global setting — all projects get access. Add "mcp__extended-mind" to permissions.allow to auto-approve.

🟠 Claude Chat — Settings → Connectors → Add custom connector:

Field	Value
Remote MCP Server URL	https://your-worker.workers.dev/mcp
OAuth Client ID	Your registered client ID
OAuth Client Secret	Your registered client secret

⚪ ChatGPT — Settings → Apps → Create app (native MCP, not Custom GPT):

Field	Value
MCP Server URL	https://your-worker.workers.dev/mcp
Authentication	OAuth
Auth URL	https://your-worker.workers.dev/oauth/authorize
Token URL	https://your-worker.workers.dev/oauth/token

⚪ Codex — two steps:

1. Settings → MCP servers → Connect a custom MCP:

Field	Value
URL	https://your-worker.workers.dev/mcp
Bearer token env var	MCP_BEARER_TOKEN

2. Add to ~/.zshrc or ~/.bashrc:

export MCP_BEARER_TOKEN="YOUR_PCP_TOKEN"

Codex reads the env var from the shell, not from the MCP settings UI. Restart shell and start a new thread.

6. Verify

# Get context
curl -s -X POST https://your-worker.workers.dev/mcp \
  -H "Authorization: Bearer $PCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"context_get","arguments":{}}}' \
  | jq -r '.result.content[0].text'

# Log a message
curl -s -X POST https://your-worker.workers.dev/mcp \
  -H "Authorization: Bearer $PCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"context_log","arguments":{"message":"Testing Extended Mind setup"}}}'

📐 How It Works

Your context has two layers:

Layer	What	Who edits	How
🔒 Core	Identity, ontology, interaction rules	You only	Edit seed/core.yaml → git push → webhook → KV
📝 Active	Team, projects, priorities, recent sessions	AI clients	context_log() → KV + GitHub + classification

When an AI calls context_log:

1. Message stored verbatim in KV (async via waitUntil, ~30ms response)
2. LLM API classifies in the background — updates priorities, flags contradictions
3. GitHub gets an async backup commit

When an AI calls context_get:

• Returns everything as a single YAML document (~2500-3000 tokens)
• The AI now knows who you are, what you're working on, and what happened across all platforms

🔐 Security

• WebAuthn Passkeys — Touch ID / Face ID / security key authentication on the OAuth authorize page. Register at /passkey, then use Conditional UI (browser auto-suggests passkey on the token input field)
• XSS Protection — all dynamic values in OAuth HTML are entity-encoded
• CSRF Protection — one-time tokens on the authorize form
• Token TTL — OAuth tokens expire after 90 days (re-auth required)
• Token Revocation — POST /oauth/revoke (RFC 7009) to invalidate compromised tokens
• Webhook Signature — HMAC-SHA256 verification required (WEBHOOK_SECRET)
• Constant-time Comparison — client secret verification resistant to timing attacks

🔄 Development: Design-Doc Loop

This project uses Design-Doc Loop (DDL) — a human-LLM collaborative development methodology where a living design document (design.md) serves as shared cognition between sessions.

The name "Extended Mind" comes from the Extended Mind thesis (Clark & Chalmers, 1998), which argues that cognitive processes extend beyond the brain into the environment. In DDL, design.md functions as Otto's notebook — an external artifact that is constitutive of the design process, not merely a record of it.

The loop: Draft (experience first) → Realize (design → code) → Reflect (code → design)

Command	What it does
/draft	Design the experience before writing code
/realize	Implement what design.md describes
/reflect	Detect drift between code and design, reconcile
/refactoring	Audit code quality against detection targets
/docs	Audit and fix documentation
/commit	Verify, commit, push, deploy

Each command runs through phases with +++DETECT targets that catch violations automatically and +++STOP gates that require human approval before proceeding.

design.md is gitignored — it's working notes, not a deliverable. Code is the source of truth.

References

• Clark, A. & Chalmers, D. (1998). "The Extended Mind." Analysis, 58(1), 7–19. doi:10.1093/analys/58.1.7
• Design-Doc Loop (DDL) — Human-LLM collaborative development methodology

🔀 Data Separation

Extended Mind uses two repositories:

Repo	Visibility	Purpose
extended-mind	Public	Source code (this repo)
Your data repo	Private	Context data synced by the Worker (core.yaml, active.json, sessions)

Your personal context never touches the code repository.

⚖️ License

MIT