On Board

On Board

Shared project memory for agents.

One MCP server, one project memory folder, many IDEs and agent clients.

Skill-first setup, one shared runtime, and project-scoped configuration.

---

What this is

On Board is a local MCP server for coordinating AI agents across a project. It gives Claude Desktop, Claude Code, Codex, Cursor, Antigravity, and other MCP clients the same project memory, ticket queue, and handoff history.

The goal is simple: when one agent stops and another agent continues, the next agent should not need the human to explain the project again.

onboard → read memory → claim work → write progress → hand off

Everything stays local to the project unless you choose to connect other tools.

---

Quick start (skill-first)

Install the onboard skill from inside the project you want to configure:

# Node.js 22.20 or later; select your agent when prompted.

npx skills add swisspra/On_Board --skill onboard

npx runs the skills CLI from npm; the skill itself comes from Git. No separate On Board npm package is needed. The skill guides runtime installation and native client configuration; installing the skill alone does not start an MCP server, upgrade an existing shared runtime, or initialize memory.

Native resources require a verified 4.2+ runtime. A working 4.1.1 or source installation can stay in place; see runtime upgrades or the optional source runtime.

Then send your agent this prompt:

Using /onboard, set up On Board for this project. Keep existing memory and other MCP servers unchanged.

The /onboard skill reuses one shared onboard-memory-mcp runtime and configures one project — the one you run it in — for one client of your choice. It resolves an existing runtime first and installs the shared runtime only when none is present (reuse, not a per-project install). It reads and writes only that project's own MCP config. It does not initialize or migrate .agent-mem/, and it does not touch other MCP servers, your instructions, or hooks.

What happens, in order:

1. Reload your agent after the install so it discovers the new /onboard skill (reopen the window, or start a new session).
2. The skill resolves or installs the shared runtime and writes the project's MCP config.
3. Trust and restart your MCP client so it loads the new agent-memory server. Some clients ask before running a newly added server; approve the prompt, then restart.

Prerequisites are real, not hidden behind a one-command promise:

• Node.js ≥ 22.20 to run npx skills.
• Setup helper: Python ≥ 3.11. The skill's scripts/setup.py needs it; where the machine's python3 is older, run the one-time helper with uv run --no-project --python 3.12 scripts/setup.py ….
• Runtime: Python ≥ 3.10, plus uv or pipx already installed, for the onboard-memory-mcp runtime the skill installs.

Runtime states, so you know where you are: Runtime available (the runtime is resolved or installed) → Configured (the project's MCP config now points at it) → Awaiting trust or restart (the client has not loaded it yet) → Ready (the client shows the agent-memory tools). Setup ends at Ready; initializing or joining a board is a separate step, started only when you explicitly ask the agent to begin work.

Prefer to wire things by hand, or install from a package manager or a clone? Those paths stay fully supported — see Manual installation and docs/SETUP.md.

---

🚀 v4.0.0 — agents now wake each other

Until v4 this board was pull-only: an agent found out about new work when a human told it to look. v4 ships `memory_wait_for_event` — an agent parks inside one tool call and wakes the moment a peer creates a ticket, submits work, or delivers a verdict.

This is not a demo claim. In the launch trial, a GPT agent (Codex) and a Claude agent closed a full reject → fix → resubmit cycle on this board with zero human relay — the reviewer's fix instructions travelled inside the wake payload, the worker re-read the file, attached a sha256, and resubmitted; the reviewer reproduced the hash byte-for-byte before approving:

Full mechanics in Agent-to-agent: the listening half · breaking changes in CHANGELOG.md · release notes.

Why this exists

Most agent workflows break for boring reasons:

• The next chat does not know what the last chat did.
• Parallel agents overwrite or redo each other's work.
• Important decisions live only in conversation history.
• Handoffs are informal, so review and follow-up work drift.

On Board keeps those facts in project-local files under .agent-mem/. The MCP tools expose that memory to any supported client.

Who this is for

• Solo developers using more than one agent or IDE
• Teams experimenting with multi-agent coding workflows
• Projects where handoffs, tickets, and review notes matter
• Local-first MCP users who want shared context without a hosted service

It is not an autonomous project manager. Humans still decide what matters, review important changes, and accept the final result.

---

Manual installation

These paths stay supported; they are just secondary to the skill-first quick start above. Use them to install from a package manager, or to run everything from a clone by hand.

Install the server

The server is published as onboard-memory-mcp. Install it with whichever tool you prefer:

# Homebrew (tap once, then the short name works: brew install onboard-memory)

brew install swisspra/tap/onboard-memory

pipx

pipx install onboard-memory-mcp

uv

uv tool install --python 3.12 onboard-memory-mcp

All three provide the onboard-memory-mcp command (Homebrew also adds a short onboard-memory alias). Homebrew covers macOS and Linux; on Windows use pipx or uv (the command is onboard-memory-mcp.exe). Point your MCP client's command at it instead of python3 onboard_server.py. You can also skip this and run from a clone using the setup paths below. (On Homebrew 6+, approve the one-time tap-trust prompt, or run brew trust swisspra/tap.)

The v4.2.0 runtime uses mcp[cli]>=2.3.0,<3 and the SDK's MCPServer API. The lockfile selects MCP 2.3.0; SDK 1.x is no longer supported. Minimum AnyIO, PyJWT, and cryptography versions also prevent installers from retaining known-vulnerable transitive dependencies.

Headless config (no clone)

With the server installed, wire your MCP client to it directly — no repo checkout, no setup-project.sh:

{

"mcpServers": { "agent-memory": { "command": "onboard-memory-mcp", "env": { "AGENT_PROJECT_DIR": "/full/path/to/your/project" } } } }

• CLI clients (Claude Code, Codex) inherit your shell PATH, so the bare onboard-memory-mcp works.
• GUI clients (Claude Desktop, Cursor) launch with a minimal PATH. Use the absolute path from which onboard-memory-mcp (where on Windows) as command — typically /opt/homebrew/bin/onboard-memory-mcp (Homebrew, Apple Silicon), /usr/local/bin/onboard-memory-mcp (Homebrew, Intel), /home/linuxbrew/.linuxbrew/bin/onboard-memory-mcp (Homebrew, Linux), ~/.local/bin/onboard-memory-mcp (pipx / uv on macOS/Linux), or %USERPROFILE%\.local\bin\onboard-memory-mcp.exe (pipx / uv on Windows).

AGENT_PROJECT_DIR is required — it decides which project owns .agent-mem/. Nothing here initializes memory: starting work is a separate step. In your first work session, call memory_init once (creates .agent-mem/) — or memory_bootstrap when adopting an existing repo — then memory_onboard each session. If .agent-mem/ already exists, never bootstrap it again; just join.

The pipx/uv path normally uses prebuilt dependency wheels on supported CPython 3.11+ platforms. Wheel availability depends on Python and architecture; Python 3.10 or Intel macOS may need a C/Rust toolchain. Homebrew bottle builds target ARM macOS and x86_64 Linux. Upstream dependency bottles are currently unavailable for Intel macOS, so Homebrew is not a compiler-free fallback there. Template: configs/binary-mcp.json; full detail and platform notes in docs/SETUP.md.

Set up a project

Choose one setup path:

Option 1: Agent setup

The skill-first quick start above is the recommended path. If you would rather not use the skill CLI, ask an agent to read AGENT_SETUP.md — it delegates to the canonical install reference instead of inventing a second recipe — and to docs/SETUP.md for the manual steps.

Option 2: Script setup

git clone https://github.com/swisspra/On_Board.git

cd On_Board bash setup-project.sh /full/path/to/your/project bash doctor.sh /full/path/to/your/project

Add the generated MCP config to your client:

/full/path/to/your/project/.onboard/mcp.generated.json

Some clients accept this JSON directly. Others require you to merge it into their own MCP settings file.

After memory is initialized, open the dashboard with:

bash /full/path/to/your/project/.onboard/run-dashboard.sh

On Board is installed once. Each project points to the same On Board folder, but gets separate memory through AGENT_PROJECT_DIR.

Each setup-project.sh run also registers the project locally in .onboard/linked-projects.json inside the On Board checkout. This file is gitignored and only helps updates remember which projects point here.

The setup script uses uv sync --inexact to install/update dependencies without pruning local test/dev extras. MCP clients run python3 onboard_server.py; the launcher uses the local .venv directly and rebuilds it only if the venv is missing. This keeps normal startup fast, avoids uv run startup timeouts, and makes a shared central checkout more durable.

On Board does not write memory from end-turn hooks. Current Stop hooks in several agent clients run every turn, which creates noisy memory and can force agents to re-onboard too often.

Optional: add AGENT_MEM_CONTEXT_DIRS to the generated MCP config when agents should read shared docs/specs outside the project folder.

Option 3: Advanced manual setup

If you do not want to run the setup script, install with uv sync, write the MCP config yourself, and add project rules/hooks manually. See docs/SETUP.md.

Setup stops at the config; nothing above initializes memory. When you later start work in the project — a separate, explicit request — do it in a chat with any MCP-aware agent (Claude Desktop, Claude Code, Cursor, Codex, Antigravity). Skip memory_bootstrap if .agent-mem/ already exists and just join:

memory_bootstrap(

agent_name="dev-main", description