77e770cdb2
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>
155 lines
4.5 KiB
Markdown
155 lines
4.5 KiB
Markdown
# 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` (basic auth) |
|
|
| Nextcloud Talk | Live | HMAC-signed webhook, async reply |
|
|
| Google Chat | Live | Workspace Add-on, JWT auth |
|
|
|
|
---
|
|
|
|
## 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/` |
|