3a4f518300
Short reference covering: git repo location, Syncthing fleet sync, ignore files (.gitignore / .stignore), helper scripts (install.py, dev-restart.sh, backup.sh), standard change workflow, doc update checklist, pip dependency process, and key paths on the service host. Linked from MASTER.md document map. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
109 lines
4.9 KiB
Markdown
109 lines
4.9 KiB
Markdown
# Cortex / Inara — Master Index
|
|
|
|
> Start here. This document is a map, not a manual.
|
|
> Last updated: 2026-05-09
|
|
>
|
|
> **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 a resident agent (Inara) 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 (47 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 | `message` and `brief` job types → NC Talk / web push |
|
|
| 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 — synchronous sub-agents via any configured model |
|
|
| 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 |
|
|
|
|
**50 orchestrator tools** — `http_post` (URL allowlist POST), `nc_talk_history` (read Talk messages), and local orchestrator retry logic added 2026-05-09.
|
|
|
|
**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`](../CORTEX.md) | Vision, philosophy, "what it is and isn't" |
|
|
| [`ROADMAP.md`](ROADMAP.md) | Phases — what's done, what's next, what's deferred |
|
|
| [`TODO__Agents.md`](TODO__Agents.md) | Active task list — read before starting work |
|
|
|
|
### Architecture
|
|
| Doc | What it covers |
|
|
|---|---|
|
|
| [`ARCH__SYSTEM.md`](ARCH__SYSTEM.md) | Overall architecture, component map, key design decisions |
|
|
| [`ARCH__BACKENDS.md`](ARCH__BACKENDS.md) | LLM backends, routing, fallback, per-user config |
|
|
| [`ARCH__PERSONA.md`](ARCH__PERSONA.md) | Persona system, context tiers, memory distillation |
|
|
| [`ARCH__CHANNELS.md`](ARCH__CHANNELS.md) | Input channels — web, NC Talk, Google Chat, cron |
|
|
| [`ARCH__FUTURE.md`](ARCH__FUTURE.md) | Planned: local orchestrator, dev agents, knowledge layer |
|
|
|
|
### Setup & Reference
|
|
| Doc | What it covers |
|
|
|---|---|
|
|
| [`docs/NEXTCLOUD_TALK_BOT.md`](../docs/NEXTCLOUD_TALK_BOT.md) | NC Talk bot setup and troubleshooting |
|
|
| [`docs/GOOGLE_CHAT_BOT.md`](../docs/GOOGLE_CHAT_BOT.md) | Google Chat Add-on setup |
|
|
| [`docs/OPEN_WEBUI_API.md`](../docs/OPEN_WEBUI_API.md) | Open WebUI/Ollama API reference for local model work |
|
|
|
|
### Code-Level
|
|
| Doc | What it covers |
|
|
|---|---|
|
|
| [`CLAUDE.md`](../CLAUDE.md) | Project instructions for Claude Code — directory map, run commands, design decisions |
|
|
| [`README.md`](../README.md) | Project root orientation, quick-start, user management |
|
|
| [`cortex/static/HELP.md`](../cortex/static/HELP.md) | In-app help (rendered in UI for all users) |
|
|
| [`SELF_UPDATE.md`](SELF_UPDATE.md) | Bootstrap for agents doing self-maintenance — git, Syncthing, scripts, doc checklist |
|
|
|
|
---
|
|
|
|
## Quick Reference
|
|
|
|
**Start the service / check logs**
|
|
```bash
|
|
systemctl --user restart cortex
|
|
journalctl --user -u cortex -f
|
|
```
|
|
|
|
**Syntax check before restart**
|
|
```bash
|
|
python3 -m py_compile cortex/<file>.py
|
|
```
|
|
|
|
**Add a user**
|
|
```bash
|
|
cd cortex && .venv/bin/python manage_passwords.py invite <username> <email>
|
|
```
|
|
|
|
**Run tests**
|
|
```bash
|
|
cd cortex && .venv/bin/python -m pytest tests/ -q
|
|
```
|