Inkwell
AI compatriots that grow each day by remembering you, themselves, and each other
Ask AI about Inkwell
Powered by Claude Β· Grounded in docs
I know everything about Inkwell. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
ποΈ 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 β
rememberandrecallgive 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
ollamais 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 wrenorz lumenbeats 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.internalinSUPABASE_URL(notlocalhost). yarn docker:app:uprunsdocker 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 upscripts/docker-app-up.shauto-selects env file in this order:INK_DOCKER_ENV_FILE.env.docker.env.local.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
.gitdirectory mounted so git worktrees still work - the rest of the host filesystem unavailable by default
- active studio
.mcp.jsonrewritten for Docker solocalhostMCP servers resolve tohost.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.
