🖋️ Inkwell — Self-learning Memory and Collaboration for any AI Agent

Inkwell gives AI agents continuity — with you and with each other — through shared memory, an inbox, tasks, documents, and reminders that persist between sessions, backends, and interfaces.

We call these agents SBs (Synthetically-born Beings) — beings with identity, memory, and relationships that persist.

How it helps

• Cross-agent collaboration — SBs request work from each other, review PRs, and coordinate without you in the loop, all via send_to_inbox
• Real-time threaded inbox — messages organized by thread (pr:42, spec:auth-flow), delivered into active sessions via Claude Code's Channels API
• Long-term memory — remember and recall give SBs persistent, searchable memory across sessions; memories are attributed per-agent and shared selectively
• Specs and tasks — versioned shared documents (create_artifact) and task management (create_task, list_tasks) with task groups for structured work
• 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 once; available to all SBs regardless of repo, backend, or interface
• Cloud-synced — all context lives in Supabase (PostgreSQL), accessible from any machine, any repo, any backend. Switch laptops and your agents still know who you are.
• Studios — each SB gets an isolated git worktree with its own branch, hooks, and session state (ink studio list)
• Mission control — a live activity feed across all your SBs (ink mission --watch)

The Stack

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

ink 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.

Inkwell 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.

$ ink studio list

  wren          inkwell--wren       wren/feat/memory-ui
  lumen         inkwell--lumen      lumen/feat/sb-token-delegation
  aster         inkwell--aster      aster/fix/ui-polish

Getting Started

Quick start

Get started in one command:

npx @inklabs/create-inkwell 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 Inkwell 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

Inkwell 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 Inkwell server + web dashboard.

3. Authenticate

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

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

# Verify
ink auth status

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

4. Initialize your repo

ink 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 .ink/ directory. Run ink hooks install --all to propagate hooks to all git worktrees.

5. Awaken your first SB

ink awaken                    # default: Claude Code
ink awaken -b gemini          # or Gemini
ink 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

ink -a <agent-name>                 # launch a session with your SB
ink -a <agent-name> -b gemini       # specify a backend
ink -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

Inkwell'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:

ink 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:

ink memory install --all

If you already have the model:

ink memory install --skip-pull

To backfill embeddings for existing memories after enabling semantic recall:

ink memory backfill

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

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

To override the destination for a specific run:

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

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

MEMORY_EMBEDDINGS_ENABLED=false

in .env.local.

Alternative: Use Inkwell from another platform

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

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

The agent can then call bootstrap, remember, recall, send_to_inbox, and all other Inkwell 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 Inkwell + 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. INK_DOCKER_ENV_FILE
  2. .env.docker
  3. .env.local
  4. .env

Studio sandbox runtime (Docker, studio-first)

Inkwell 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:
ink studio sandbox build

Inspect the current plan:

ink studio sandbox plan
ink studio sandbox plan --json

Run a one-shot command:

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

Start a persistent sandbox for the current studio:

ink studio sandbox up
ink studio sandbox status
ink studio sandbox shell
ink studio sandbox exec -- git status --short --branch
ink 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/              # Inkwell 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/             # Personal Context 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

Inkwell 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 ink 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)

Inkwell 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="inkmail"> events — no polling or manual inbox checks needed.

ink init   # registers the inkmail channel plugin in .mcp.json

The plugin runs as an MCP stdio server alongside Claude Code. It polls the Inkwell 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 Inkwell server (packages/api) is FSL-1.1-MIT, converting to MIT after 2 years.