aionai

A shared working-state layer for your AI coding tools. Claude, Cursor, and other MCP clients read and write one small notebook, so they stay on the same page — and you stop being the copy-paste bus between them.

One-click install for Cursor (it configures uvx aionai). After it's added, set AIONAI_SOURCE=cursor in the server's env. If Cursor can't find uvx, see Troubleshooting; or set it up manually via Connect your tools.

The problem

You use more than one AI assistant on a project. They don't know what each other did: you tell Claude a decision, switch to Cursor, and Cursor has no idea. You end up re-explaining and copy-pasting context by hand.

Related MCP server: Agent Room

What aionai does

aionai is a tiny local MCP server that keeps a shared, persistent notebook every tool can read and write. It does three jobs:

• Remember — decisions, changes, questions, and notes, organized by project.

• Track — a lightweight roadmap/to-do list with progress rollup.

• Hand off — post a task to another tool's inbox (with an optional "doorbell").

It does not replace your repo, docs, or git — those stay the source of truth. aionai just holds the live working state and hands each tool the slice it needs.

Install

Most portable — works on Windows, macOS, and Linux, and puts the aionai command where GUI apps (Cursor, Claude Desktop) can find it:

pipx install aionai

Already use uv? Skip the install entirely:

uvx aionai --help

Requires Python 3.10+. If a client later reports the launcher (aionai / uvx) "not recognized", see Troubleshooting.

Connect your tools

Point each client at the aionai command. Give each client a distinct AIONAI_SOURCE (so handoffs route correctly) and set AIONAI_SEGMENT to your project name.

Claude Code

claude mcp add aionai --env AIONAI_SOURCE=claude-code --env AIONAI_SEGMENT=myproject -- aionai
# or with uv:  claude mcp add aionai --env AIONAI_SOURCE=claude-code -- uvx aionai

Cursor — .cursor/mcp.json:

{
  "mcpServers": {
    "aionai": { "command": "aionai", "env": { "AIONAI_SOURCE": "cursor", "AIONAI_SEGMENT": "myproject" } }
  }
}

Claude Desktop — Settings → Developer → Edit Config:

{
  "mcpServers": {
    "aionai": { "command": "aionai", "env": { "AIONAI_SOURCE": "claude-desktop", "AIONAI_SEGMENT": "myproject" } }
  }
}

Restart the client after editing its config — MCP servers are launched (and their env read) when the client connects.

Use it

Add this to each tool's rules (CLAUDE.md, Cursor rules) so they do it reflexively:

Before working, call context_pull(segment="myproject") and treat the result as the current truth. As you work, context_log(...) your decisions/changes/questions/tasks. When something is settled, context_resolve(id).

That's the whole loop: pull first, write back. Now open Cursor and it already knows what you and Claude decided — no paste.

Segments

State is organized by a dotted segment path whose first element is the project:

myproject                     # the whole project
myproject/backend             # a layer
myproject/backend/auth        # a workstream

Pulling a parent includes all descendants. That one mechanism keeps an always-on space from turning into an undifferentiated blob.

The tools

They also surface as slash commands (/mcp__aionai__pull, …log, …resolve, …search, …handoff) in clients that support MCP prompts.

Optional extras

• Auto-ingest commits — copy hooks/post-commit into a repo's .git/hooks/ (set AIONAI_SEGMENT) and every commit logs itself as a change.

• Doorbell — set AIONAI_DELIVERY=1 in a sender's env and a context_handoff to Cursor also summons Cursor via its deeplink (you confirm before it runs). Without it, handoffs are inbox-only. Only cursor has a verified deeplink today.

How it works

One SQLite database, one append-only table. Every decision, task, handoff, and roadmap node is a row tagged with a segment and a type. History is free because nothing is overwritten. Full-text search uses FTS5 with a LIKE fallback. The MCP tools are thin wrappers over a plain-Python storage layer (src/aionai/store.py).

Troubleshooting

A client reports 'uvx' / 'aionai' is not recognized (or the server errors on start). The client can't find the launcher on its PATH — common for GUI apps (Cursor, Claude Desktop) on Windows and macOS, which don't always inherit your shell's PATH. Fixes, best first:

1. Use pipx: pipx install aionai, then set "command": "aionai". pipx puts the command where GUI apps usually find it.

2. Point at the full path of the launcher. Find it with where uvx (Windows) or which uvx (macOS/Linux), then use it verbatim, e.g.:

   "aionai": { "command": "C:/Users/you/AppData/Roaming/Python/Python3xx/Scripts/uvx.exe",
               "args": ["aionai"], "env": { "AIONAI_SOURCE": "cursor" } }

3. Skip the launcher — run via your Python directly (after pip install aionai):

   "aionai": { "command": "python", "args": ["-m", "aionai.cli"] }

Then restart the client so it re-reads the config.

Configuration

Development

git clone https://github.com/imsm/aionai && cd aionai
pip install -e ".[dev]"
pytest
ruff check .

License

Apache-2.0 © Ismail Saleh.