Cortex-Inara/README.md

# 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).

```bash
# 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

```bash
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

```bash
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/` |