Files

Scott Idem 77e770cdb2 feat: multi-user/multi-persona support with two-level home directory layout

Restructures persona storage from a flat personas/{name}/ layout to
home/{username}/persona/{name}/, mirroring Linux home directories.

Changes:
- persona.py: two ContextVars (user + persona), Linux-style name validation,
  set_context(), get_user(), get_persona(), validate(), list_users(),
  list_user_personas(); persona_path() takes (username, name)
- config.py: replaces personas_dir with home_dir + home_root()
- git mv personas/inara → home/scott/persona/inara (history preserved)
- home/holly/persona/tina/: Holly's persona stub added
- cron_runner.py: all storage functions take (username, persona) params
- tools/cron.py: stamps user + persona on jobs; APScheduler IDs are
  {user}:{persona}:{job_id} to prevent collisions across users
- memory_distiller.py: distill_short/mid/long take (username, persona);
  added missing Path + settings imports
- scheduler.py: _load_user_crons() iterates home/*/persona/* (two-level)
- routers/chat.py, orchestrator.py: user field added; set_context() called
- tests/conftest.py: home_root fixture with two-level structure;
  patches home_dir instead of personas_dir
- tests/test_persona.py: fully rewritten for two-level API
- tests/test_api_files.py: updated fixture name and path
- .env.default: documents HOME_DIR setting; scrubs stale API key
- CLAUDE.md, README.md: directory maps updated for new layout

All 80 tests pass.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-03-20 22:35:40 -04:00

4.5 KiB

Raw Blame History

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` (basic auth)
Nextcloud Talk	Live	HMAC-signed webhook, async reply
Google Chat	Live	Workspace Add-on, JWT auth

Testing

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

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

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

4.5 KiB Raw Blame History