658c508925
agent_manager.py (new): - AgentRecord dataclass: agent_id, level (1/2/3), role, task, status, started, parent_id (lineage), finished, result, notify, _task_ref - register() / finish() / cancel_agent() / list_agents() / get() / set_task_ref() - Calls notification.notify() on completion when notify=True (same channel as reminders and cron completions) - 24-hour pruning of completed records on each new registration spawn_agent (tools/agents.py): - background=True: fires asyncio.create_task(), registers in agent_manager, returns agent_id string immediately — sync path unchanged (no regression) - notify=True: push/Talk notification when the background task completes - Level enforcement: _agent_level param tracks hierarchy depth; when spawning from Level 2, child automatically gets spawn_agent + aider_run denied so Level 3 agents cannot delegate further New lifecycle tools (tools/agents.py + __init__.py): - agent_status(agent_id) — status, role, level, elapsed, task, result preview; user-level - agent_list(status, limit) — all agents for current user, newest first; user-level - agent_cancel(agent_id) — kills background task; admin-only, confirm-required tests/test_agent_manager.py (new, 41 tests): - agent_manager CRUD, pruning, notification hook - spawn_agent background: returns immediately, completes async, timeout, failure - Level enforcement: L1→L2 permits spawn, L2→L3 auto-denies; explicit tool_list path - agent_status / agent_list / agent_cancel output formatting - aider_run background: returns agent_id, completes async, sync path unchanged - All tests run without browser or Cortex service (~2.5s total) Run: cd cortex && .venv/bin/python -m pytest tests/test_agent_manager.py -v Docs: ARCH__FUTURE.md §13 (full design), ROADMAP.md, TODO__Agents.md, MASTER.md, HELP.md (orchestrator description corrected, tool schema line updated to reflect keyword routing), CLAUDE.md tool count 66→69. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
7.4 KiB
Cortex — Master Index
Start here. This document is a map, not a manual. Last updated: 2026-06-03
Documentation philosophy: Cortex is a no-black-box system. Docs must match reality. Update docs before implementing significant changes. Verify they still match after.
What It Is
Cortex is a self-hosted personal AI platform. It routes messages from any input channel to AI backends, manages per-user AI personas with persistent memory, and coordinates across a fleet of machines. It is infrastructure, not a product.
Running at: https://cortex.dgrzone.com | systemctl --user restart cortex
Current State
| Component | Status | Notes |
|---|---|---|
| Web UI | ✅ Live | SPA, dark theme, mobile-responsive, PWA-installable |
| Nextcloud Talk bot | ✅ Live | HMAC-signed, per-user routing |
| Google Chat Add-on | ✅ Live | JWT-verified, per-user routing |
| Claude backend | ✅ Live | Primary — via Claude Code CLI |
| Gemini backend | ✅ Live | Fallback — via Gemini CLI |
| Local backend | ✅ Live | Open WebUI/Ollama on scott_gaming; per-user multi-model config |
| Gemini orchestrator | ✅ Live | Tool loop → Claude response, ⚡ toggle in UI (66 tools) |
| Local orchestrator | ✅ Live | OpenAI-compatible ReAct loop; used when orchestrator role → local model |
| Model registry V2 | ✅ Live | Providers (Anthropic/Google/Local), multi-account Gemini, role assignments |
| Memory distillation | ✅ Live | Short (daily) / Mid (weekly) / Long (monthly) |
| Multi-user | ✅ Live | Scott, Holly, Brian — each with own personas |
| Session search | ✅ Live | Full-text search across past session logs |
| Proactive cron | ✅ Live | 5 job types: remind, note, message, brief, task (full orchestrator loop) → NC Talk / web push |
| Schedules web UI | ✅ Live | /settings/crons — view, add, edit, pause/resume, delete jobs without going through the AI |
| Tool audit log | ✅ Live | Every orchestrator tool call logged to home/{user}/tool_audit/ |
| Token usage tracking | ✅ Live | Per-user daily buckets in home/{user}/usage.json; visible in Settings |
| Web push notifications | ✅ Live | VAPID push; web_push orchestrator tool; subscribe via ☰ menu |
| Proactive notifications | ✅ Live | Daily reminder check (09:00); distill/cron completion alerts; dedicated /settings/notifications page |
| Sub-agent spawning | ✅ Live | spawn_agent tool — sync or background; agent_status/agent_list/agent_cancel; 3-level hierarchy (L2→L3 enforcement built in) |
| Aider coding agent | ✅ Live | aider_run tool — Aider subprocess; model-agnostic (DeepSeek, Ollama, OpenRouter, etc.) |
| Agent private notes | ✅ Live | AGENT_NOTES.md — orchestrator-only notepad; 3 rolling backups; user-visible as read-only |
| Distill safety | ✅ Live | Per-persona asyncio lock, per-endpoint cooldowns, Rebuild option |
| Guided onboarding | ✅ Live | Setup Step 3 for OpenRouter; existing-user banner; settings quick-link |
69 orchestrator tools across 17 domain modules — added 2026-06-03: agent_status/agent_list (user-level)/agent_cancel (admin, confirm-required); background mode for spawn_agent (background=True returns agent_id immediately; notify=True sends push on completion); agent_manager.py registry with lineage tracking and 24h pruning; L2→L3 level enforcement auto-denies spawn_agent/aider_run in Level 3 children. Added 2026-05-23: aider_run (Aider coding agent subprocess; project aliases for cortex/aether_api/aether_frontend/aether_container; model-agnostic via .aider.conf.yml or env vars; admin-only, confirm-required). .aider.conf.yml added to project root (read-only context, Python lint-cmd, auto-commits). Added 2026-05-12: file_diff, git_status / git_log / git_diff (read-only git inspection), ae_db_query / ae_db_describe / ae_db_show_view (SELECT-only Aether MariaDB access, admin, per-user credentials). /settings/integrations page added (admin-only). File attachments in chat (images for vision-capable local models; text/code files for all backends). Settings pages unified under pg.css. Added 2026-05-13: task cron type (full orchestrator loop on a schedule); monthly/yearly schedule formats (monthly, monthly:DD:HH:MM, yearly:MM:DD:HH:MM); Schedules web UI at /settings/crons (list, add, edit, pause, delete); HA inbound webhook tools toggle (orchestrator vs. direct LLM); Anthropic API key backend (anthropic_api model type via Anthropic SDK — alternative to CLI OAuth); Cloud APIs catalog in Model Registry — named provider picker (OpenRouter, OpenAI, Groq, X.ai/Grok, Together.ai, Fireworks.ai, Custom) with auto-filled URLs; hosts split into Cloud APIs / Local Hosts sections. Added 2026-05-15: Per-user custom roles — three required roles (chat, orchestrator, distill) are always present; users can add/remove custom roles (e.g. coder, research) via the Model Registry UI; existing .env-defined roles auto-migrated. Settings pages (local_llm.html + all settings pages) migrated to Tailwind CSS CDN (no build step); preflight: false preserves pg.css base styles; input[type=checkbox/radio] global width fix in pg.css; btn-submit now responsive (w-full md:w-96).
Active users / personas: scott/inara, holly/tina, brian/wintermute
Document Map
Project-Level
| Doc | What it covers |
|---|---|
| This file | Index and current state |
CORTEX.md |
Vision, philosophy, "what it is and isn't" |
ROADMAP.md |
Phases — what's done, what's next, what's deferred |
TODO__Agents.md |
Active task list — read before starting work |
Architecture
| Doc | What it covers |
|---|---|
ARCH__SYSTEM.md |
Overall architecture, component map, key design decisions |
ARCH__BACKENDS.md |
LLM backends, routing, fallback, per-user config |
ARCH__PERSONA.md |
Persona system, context tiers, memory distillation |
ARCH__CHANNELS.md |
Input channels — web, NC Talk, Google Chat, cron |
ARCH__FUTURE.md |
Planned: local orchestrator, dev agents, knowledge layer |
Setup & Reference
| Doc | What it covers |
|---|---|
docs/NEXTCLOUD_TALK_BOT.md |
NC Talk bot setup and troubleshooting |
docs/GOOGLE_CHAT_BOT.md |
Google Chat Add-on setup |
docs/OPEN_WEBUI_API.md |
Open WebUI/Ollama API reference for local model work |
Code-Level
| Doc | What it covers |
|---|---|
CLAUDE.md |
Project instructions for Claude Code — directory map, run commands, design decisions |
README.md |
Project root orientation, quick-start, user management |
cortex/static/HELP.md |
In-app help (rendered in UI for all users) |
SELF_UPDATE.md |
Bootstrap for agents doing self-maintenance — git, Syncthing, scripts, doc checklist |
Quick Reference
Start the service / check logs
systemctl --user restart cortex
journalctl --user -u cortex -f
Syntax check before restart
python3 -m py_compile cortex/<file>.py
Add a user
cd cortex && .venv/bin/python manage_passwords.py invite <username> <email>
Run tests
cd cortex && .venv/bin/python -m pytest tests/ -q