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