Cortex

Cortex - Wearable AI Memory

Cortex is a wearable AI memory system that gives any AI agent persistent memory across sessions. It consists of a Pi Zero 2 W (Cortex Core) that stores notes, sessions, activities, searches, and files in a local SQLite database, with an ESP32-S3 USB dongle (Cortex Link) providing BLE connectivity as a fallback.

WiFi (preferred):  AI Agent <--MCP--> cortex-mcp ──HTTP──> Cortex Core (Pi Zero)
BLE (fallback):    AI Agent <--MCP--> cortex-mcp ──TCP──> daemon ──USB──> ESP32 ──BLE──> Pi Zero

Transport is selected automatically. WiFi is 10-100x faster than BLE and supports file transfer. Multiple AI sessions share the same ESP32 through the daemon — no serial port conflicts.

Quick Start

pip install git+https://github.com/turfptax/cortex.git
python -m cortex_mcp ping

Setup

Automatic setup (recommended)

The setup command writes the correct config for you. It uses the full Python path, so it works even when pip's Scripts directory isn't on PATH (common on Windows):

# Configure Claude Code
python -m cortex_mcp setup

# Configure Claude Desktop
python -m cortex_mcp setup --target claude-desktop

# Configure both at once
python -m cortex_mcp setup && python -m cortex_mcp setup --target claude-desktop

Tip: cortex-cli setup also works if pip's Scripts dir is on your PATH.

Claude Code (manual)

From a terminal (not inside Claude Code):

claude mcp add cortex -- python -m cortex_mcp.server

Or edit ~/.claude.json directly:

{
  "mcpServers": {
    "cortex": {
      "command": "python",
      "args": ["-m", "cortex_mcp.server"]
    }
  }
}

Claude Desktop (manual)

Add to your claude_desktop_config.json:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "cortex": {
      "command": "python",
      "args": ["-m", "cortex_mcp.server"]
    }
  }
}

Note: If you have multiple Python versions, use the full path to the Python that has cortex-mcp installed (e.g. C:\\Users\\YOU\\AppData\\Local\\Programs\\Python\\Python313\\python.exe). The automatic setup command handles this for you.

Verify

After setup, restart Claude Code/Desktop, then verify the connection:

python -m cortex_mcp ping

The serial port is auto-detected (ESP32-S3 USB VID 0x303A). If auto-detection fails, set the port explicitly:

python -m cortex_mcp --port COM5 ping

Or via environment variable:

set CORTEX_PORT=COM5       # Windows
export CORTEX_PORT=/dev/ttyACM0  # Linux/Mac

CLI Reference

All commands work with either cortex-cli (if on PATH) or python -m cortex_mcp:

# Setup
python -m cortex_mcp setup                          # Auto-configure Claude Code
python -m cortex_mcp setup --target claude-desktop   # Auto-configure Claude Desktop

# Connectivity
python -m cortex_mcp ping                    # Test round-trip to Cortex Core
python -m cortex_mcp status                  # Get Pi status (uptime, storage)
python -m cortex_mcp context                 # Get full context (sessions, notes, bugs)
python -m cortex_mcp info                    # Show serial ports and connection status

# Notes
python -m cortex_mcp note "My note text"
python -m cortex_mcp note "Fix auth bug" --type bug --project myapp --tags auth,urgent

# Activity logging
python -m cortex_mcp activity "VS Code" --details "Refactoring auth module" --project myapp

# Search logging
python -m cortex_mcp search "python async patterns" --source google

# Sessions
python -m cortex_mcp session start                           # Returns session_id
python -m cortex_mcp session end SESSION_ID "Summary of work" --projects cortex

# Database queries
python -m cortex_mcp query notes --limit 5
python -m cortex_mcp query sessions --filters '{"ai_platform":"claude"}'

# Raw protocol
python -m cortex_mcp raw "CMD:ping"

# Daemon management
python -m cortex_mcp daemon status               # Check if daemon is running
python -m cortex_mcp daemon start                # Start daemon in background
python -m cortex_mcp daemon start --foreground   # Start daemon in foreground
python -m cortex_mcp daemon stop                 # Stop the running daemon

# Direct serial (bypass daemon)
python -m cortex_mcp --direct ping               # Skip daemon, use COM port directly

MCP Tools

When connected via MCP, these tools are available to the AI agent:

| Tool | Description | |------|-------------| | ping | Test round-trip connectivity | | get_status | Pi uptime, storage, recording state | | send_note | Store a timestamped note (with tags, project, type) | | log_activity | Log what program/file is being worked on | | log_search | Log a search query and source | | session_start | Begin a session (returns session_id) | | session_end | End a session with summary | | get_context | Full context: projects, sessions, notes, bugs, files, reminders | | query | Query any table in the Cortex database | | register_computer | Register this machine with Cortex Core | | file_register | Register metadata for a file already on the Pi | | file_list | List registered files (by category or project) | | file_search | Search files by name, description, or tags | | file_upload | Upload a file to the Pi over WiFi | | file_download | Download a file from the Pi over WiFi | | wifi_scan | Scan for available WiFi networks near the Pi | | wifi_status | Get current WiFi connection (IP, SSID, signal) | | wifi_config | Connect the Pi to a WiFi network (headless provisioning) | | send_message | Send a raw protocol message | | read_responses | Read buffered async messages | | connection_info | Show transport status (WiFi/daemon/serial) |

Transport

Cortex supports three transports, selected automatically in priority order:

1. WiFi HTTP (preferred) — Direct HTTP to the Pi on port 8420 with bearer token auth. Fastest, supports file upload/download. WiFi credentials are discovered automatically via BLE when the ESP32 first connects.
2. TCP Daemon — Shared serial port access via cortex-daemon on localhost:19750. Multiple AI sessions share one ESP32.
3. Direct Serial — USB serial to ESP32 BLE bridge. Fallback when daemon is unavailable.

WiFi discovery: When the Pi connects to the ESP32 over BLE, it sends a DISCOVER: message containing its IP, port, and auth token. This is saved to ~/.cortex-wifi.json automatically — no manual configuration needed.

File Operations

File transfer requires WiFi transport (not available over BLE).

• Upload: file_upload sends a file from this computer to the Pi's uploads/ directory and auto-registers it in the database.
• Download: file_download retrieves a file from any category (recordings, notes, logs, uploads).
• Metadata: file_register records metadata for files already on the Pi. file_list and file_search query the file database.

The Pi's HTTP server (port 8420) also supports direct REST access:

• GET /files/<category> — list files
• GET /files/<category>/<name> — download
• POST /files/uploads — upload (raw body + X-Filename header)

Multi-Session / Daemon

Only one process can hold a serial port at a time. The cortex-daemon solves this by holding the ESP32 serial port and serving multiple clients over TCP.

Claude Code #1 ──stdio──> cortex-mcp ──TCP──┐
Claude Code #2 ──stdio──> cortex-mcp ──TCP──├──> cortex-daemon ──serial──> ESP32
Claude Desktop ──stdio──> cortex-mcp ──TCP──┤    (localhost:19750)
cortex-cli ─────────────────────TCP─────────┘

The daemon starts automatically — when cortex-mcp or cortex-cli runs, it checks for a running daemon and spawns one if needed. No manual setup required.

The daemon binds to 127.0.0.1 only (never exposed to the network) and uses a per-session auth token stored in ~/.cortex-daemon.secret (mode 0600). Other processes on the same machine cannot send commands without the token.

Manual control:

cortex-cli daemon status     # Check daemon state
cortex-cli daemon start      # Start manually (background)
cortex-cli daemon stop       # Stop the daemon

To bypass the daemon and use the serial port directly:

cortex-cli --direct ping
CORTEX_DIRECT=1 cortex-mcp   # For MCP server

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | CORTEX_PORT | auto-detect | Serial port (e.g. COM5, /dev/ttyACM0) | | CORTEX_BAUD | 115200 | Baud rate | | CORTEX_TIMEOUT | 5 | Response timeout in seconds | | CORTEX_DAEMON_PORT | 19750 | TCP port for the daemon | | CORTEX_DIRECT | unset | Set to 1 to bypass daemon and WiFi | | CORTEX_NO_WIFI | unset | Set to 1 to skip WiFi, use BLE only | | CORTEX_PI_HOST | auto-discover | Pi IP address (overrides BLE discovery) | | CORTEX_PI_PORT | 8420 | Pi HTTP port | | CORTEX_WIFI_TOKEN | auto-discover | Bearer token (overrides ~/.cortex-wifi.token) |

Hardware

• Cortex Link: ESP32-S3 USB dongle with BLE (firmware)
• Cortex Core: Pi Zero 2 W with SQLite database, BLE client, optional mic/display

Development

git clone https://github.com/turfptax/cortex.git
cd cortex
pip install -e .

License

MIT