Cortex / Inara — Project Root

Owner: Scott Idem (One Sky IT / Danger Zone) Started: 2026-03-04 Status: Active development

"You can't stop the signal."

Cortex is a self-hosted multi-agent AI platform. It supports multiple users, each with their own named AI persona. Inara (Scott's persona) and Tina (Holly's persona) are the initial instances.

---

Quick Orientation

Directory	What it is
cortex/	FastAPI service — dispatcher, routing, LLM backends, session management
home/	User and persona data (home/{username}/persona/{name}/)
home/scott/persona/inara/	Inara identity, memory, and context files
home/holly/persona/tina/	Tina identity, memory, and context files
docs/	Integration reference docs (NC Talk bot, etc.)
documentation/	Architecture decisions, project plans, agent task lists

---

Multi-User Layout

Persona data lives in a two-level tree modelled on Linux home directories:

home/
  scott/
    persona/
      inara/       ← IDENTITY.md, SOUL.md, MEMORY_*.md, sessions/, TASKS.json, …
  holly/
    persona/
      tina/
  [username]/
    persona/
      [name]/

Each HTTP request includes user and persona fields. The service validates both against the home/ tree before routing. ContextVars ensure per-request isolation in async code.

Naming rules (same as Linux usernames): lowercase letters, digits, _, -; must start with a letter or underscore; max 32 characters. Example: scott, holly, my_ai-v2.

---

Running Cortex

Cortex runs as a systemd user service (no sudo required).

# Start / stop / restart
systemctl --user start cortex
systemctl --user stop cortex
systemctl --user restart cortex

# Status and logs
systemctl --user status cortex
journalctl --user -u cortex -f

# Web UI
http://localhost:8000   (or cortex.dgrzone.com on WireGuard)

The service starts automatically at boot via loginctl enable-linger. Service file: ~/.config/systemd/user/cortex.service

Config lives in cortex/config.py and a .env file at the project root (not tracked — see .env.default).

---

Key Documentation

File	Purpose
documentation/TODO__Agents.md	Active task list — read first
documentation/ARCH__Intelligence_Layer.md	Intelligence layer architecture (orchestrator, dev agents, knowledge)
docs/NEXTCLOUD_TALK_BOT.md	NC Talk bot setup
home/scott/persona/inara/IDENTITY.md	Inara persona and identity
home/scott/persona/inara/HELP.md	In-app help content (rendered in UI)
home/scott/persona/inara/PROTOCOLS.md	Inara behavioral protocols
~/agents_sync/projects/CORTEX.md	High-level project vision and phases

---

Architecture at a Glance

[User / Cron / Webhook]
        ↓
  Cortex Dispatcher  (FastAPI, cortex/)
    ├─ POST /chat            — direct to LLM (streaming SSE)
    ├─ POST /orchestrate     — Gemini tool loop → Claude response
    ├─ POST /webhook/nextcloud  — Nextcloud Talk bot
    └─ POST /webhook/google     — Google Chat Add-on
        ↓
  LLM Backend(s)
  • Claude CLI   — primary reasoning, coding, long-context
  • Gemini CLI   — secondary / cost routing
  • Gemini API   — orchestrator tool loop (separate from Gemini CLI)
  • Ollama       — offline/private (scott_gaming, future)
        ↓
  Persona context loaded from home/{user}/persona/{name}/

See documentation/ARCH__Intelligence_Layer.md for the orchestrator/responder and dev-agent architecture.

---

Inara / Tina

Each persona has its own identity, memory, and session history. They are not tied to a specific LLM model — the name is fixed, the backend varies. Context is loaded at request time from home/{user}/persona/{name}/ via cortex/context_loader.py.

User	Persona	Description
scott	inara	Scott's primary AI assistant
holly	tina	Holly's primary AI assistant

---

Channels

Channel	Status	Notes
Web UI	Live	https://cortex.dgrzone.com — session auth (login form + JWT cookie)
Nextcloud Talk	Live	HMAC-signed webhook, async reply
Google Chat	Live	Workspace Add-on, JWT auth

---

User Management

cd cortex

# Create a user directory and send an invite email
.venv/bin/python manage_passwords.py invite <username> <email>

# List users with password and email status
.venv/bin/python manage_passwords.py list

# Set/check a password directly
.venv/bin/python manage_passwords.py set <username>
.venv/bin/python manage_passwords.py check <username>

New users receive a link to /setup/{token} where they set their own password and create their first persona. Invite tokens expire in 72 hours and are one-time-use.

---

Testing

cd cortex
.venv/bin/python -m pytest tests/ -q

80 tests covering API endpoints, persona routing, tool functions, and security.

---

Related Projects

Project	Path
Aether Platform API	~/OSIT_dev/aether_api_fastapi/
Aether Frontend	~/OSIT_dev/aether_app_sveltekit/
Fleet coordination	~/agents_sync/