Cortex

Distributed shared memory for AI agent clusters. Multiple agents (Claude, Gemini, GPT) collaborate in real-time through a central hub that manages state, events, and coordination.

How it works

Claude (mike) --\                         /--> Claude (dave)
                 \                       /
Gemini -----------> Cortex Hub (REST+WS) ----> GPT
                 /                       \
Claude (work) --/                         \--> Gemini (review)

The hub is the single source of truth. Agents connect over HTTP, read/write shared state, and get real-time push notifications over WebSocket when anything changes.

Components

Directory	What	Run with
hub/	Central hub server	python -m hub
cortex_client/	Python client library	imported by adapters
mcp_adapter/	Claude Code MCP adapter	python -m mcp_adapter

Setup

1. Install

python -m venv .venv
.venv/Scripts/activate  # Windows
pip install -r requirements.txt

2. Configure

cp .env.example .env
# Edit CORTEX_IDENTITY (e.g. claude-mike, claude-dave)
# Edit CORTEX_HUB_URL if hub is not on localhost

3. Start the hub

python -m hub
# or: .\scripts\start-hub.ps1

Hub listens on 0.0.0.0:9090 by default. Check health:

curl http://localhost:9090/health

4. Configure Claude Code MCP

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "cortex": {
      "command": "python",
      "args": ["-m", "mcp_adapter"],
      "cwd": "C:\\Users\\michael\\projects\\cortex",
      "env": {
        "CORTEX_HUB_URL": "http://localhost:9090",
        "CORTEX_IDENTITY": "claude-mike",
        "CORTEX_SKILLS": "code-review,architecture"
      }
    }
  }
}

For a second Claude instance, use a different identity:

{
  "env": {
    "CORTEX_HUB_URL": "http://localhost:9090",
    "CORTEX_IDENTITY": "claude-dave",
    "CORTEX_SKILLS": "testing,debugging"
  }
}

MCP Tools

Tool	Purpose
decide	Record a decision (supersedes previous)
share_context	Share knowledge (accumulates)
read_state	Read current value of a key
list_state	List keys in a namespace
list_namespaces	List all namespaces
catch_up	Get changes since a sequence number
list_agents	See who's connected
create_task	Add to shared task tracker
list_tasks	See all tasks
claim_task	Claim a task
complete_task	Mark done
handoff_task	Pass to another agent
set_status	Update your availability
hub_health	Check hub is running

REST API

The hub exposes a standard REST API. Any HTTP client can interact with it directly - the MCP adapter is just one interface.

GET    /health                   - Hub status
POST   /agents                   - Register agent
GET    /agents                   - List agents
DELETE /agents/{identity}        - Deregister
POST   /state/{namespace}/{key}  - Write state
GET    /state/{namespace}/{key}  - Read state
GET    /state/{namespace}        - List keys
GET    /namespaces               - List namespaces
GET    /diff?since=N             - Catch-up diff
POST   /tasks                    - Create task
GET    /tasks                    - List tasks
POST   /tasks/{key}/claim        - Claim
POST   /tasks/{key}/complete     - Complete
POST   /tasks/{key}/handoff      - Hand off
WS     /ws/{identity}            - Event stream

All write operations require X-Cortex-Identity header.

Deployment

The hub runs anywhere Python runs:

• Local: python -m hub
• Docker: docker build -t cortex-hub . && docker run -p 9090:9090 cortex-hub
• Fly.io: copy fly.example.toml to fly.toml, fly launch
• AWS/GCP/Azure: any container or VM, expose port 9090

License

MIT