docs: update README for current state
- .env location: cortex/.env + cortex/.env.example (not project root)
- Webhook endpoints: per-user /webhook/nextcloud/{username} and /channels/google-chat/{username}
- Personas table: added brian/wintermute and scott/developer
- Docs table: added GOOGLE_CHAT_BOT.md, cortex/static/HELP.md
- Channels section: per-user webhook note + links to setup docs
- User management: added google-add command and channels.json note
- Removed stale Inara/Tina-only framing
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
45
README.md
45
README.md
@@ -6,7 +6,7 @@
|
||||
|
||||
> *"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.
|
||||
Cortex is a self-hosted multi-agent AI platform. It supports multiple users, each with their own named AI persona.
|
||||
|
||||
---
|
||||
|
||||
@@ -16,9 +16,7 @@ Cortex is a self-hosted multi-agent AI platform. It supports multiple users, eac
|
||||
|---|---|
|
||||
| `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.) |
|
||||
| `docs/` | Integration reference docs (NC Talk bot, Google Chat bot) |
|
||||
| `documentation/` | Architecture decisions, project plans, agent task lists |
|
||||
|
||||
---
|
||||
@@ -69,7 +67,7 @@ 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`).
|
||||
Config lives in `cortex/config.py` and `cortex/.env` (not tracked — see `cortex/.env.example`).
|
||||
|
||||
---
|
||||
|
||||
@@ -79,10 +77,10 @@ Config lives in `cortex/config.py` and a `.env` file at the project root (not tr
|
||||
|---|---|
|
||||
| `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 |
|
||||
| `docs/NEXTCLOUD_TALK_BOT.md` | NC Talk bot setup and troubleshooting |
|
||||
| `docs/GOOGLE_CHAT_BOT.md` | Google Chat Add-on setup and troubleshooting |
|
||||
| `cortex/static/HELP.md` | Shared in-app help content (rendered in UI for all users) |
|
||||
| `home/scott/persona/inara/PROTOCOLS.md` | Inara behavioral protocols (template for all personas) |
|
||||
| `~/agents_sync/projects/CORTEX.md` | High-level project vision and phases |
|
||||
|
||||
---
|
||||
@@ -93,10 +91,10 @@ Config lives in `cortex/config.py` and a `.env` file at the project root (not tr
|
||||
[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
|
||||
├─ POST /chat — direct to LLM (streaming SSE)
|
||||
├─ POST /orchestrate — Gemini tool loop → Claude response
|
||||
├─ POST /webhook/nextcloud/{username} — Nextcloud Talk bot (per-user)
|
||||
└─ POST /channels/google-chat/{username} — Google Chat Add-on (per-user)
|
||||
↓
|
||||
LLM Backend(s)
|
||||
• Claude CLI — primary reasoning, coding, long-context
|
||||
@@ -111,7 +109,7 @@ See `documentation/ARCH__Intelligence_Layer.md` for the orchestrator/responder a
|
||||
|
||||
---
|
||||
|
||||
## Inara / Tina
|
||||
## Personas
|
||||
|
||||
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.
|
||||
@@ -120,17 +118,23 @@ Context is loaded at request time from `home/{user}/persona/{name}/` via `cortex
|
||||
| User | Persona | Description |
|
||||
|---|---|---|
|
||||
| scott | inara | Scott's primary AI assistant |
|
||||
| scott | developer | Scott's dev-focused persona |
|
||||
| holly | tina | Holly's primary AI assistant |
|
||||
| brian | wintermute | Brian's primary AI assistant |
|
||||
|
||||
---
|
||||
|
||||
## Channels
|
||||
|
||||
| Channel | Status | Notes |
|
||||
Webhook endpoints are per-user — each user configures their own secrets in `home/{username}/channels.json`.
|
||||
|
||||
| Channel | Status | Endpoint |
|
||||
|---|---|---|
|
||||
| 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 |
|
||||
| Nextcloud Talk | Live | `POST /webhook/nextcloud/{username}` — HMAC-signed, async reply |
|
||||
| Google Chat | Live | `POST /channels/google-chat/{username}` — Workspace Add-on, JWT auth |
|
||||
|
||||
See `docs/NEXTCLOUD_TALK_BOT.md` and `docs/GOOGLE_CHAT_BOT.md` for setup instructions.
|
||||
|
||||
---
|
||||
|
||||
@@ -142,7 +146,10 @@ 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
|
||||
# Register a Google account for sign-in (run after user completes onboarding)
|
||||
.venv/bin/python manage_passwords.py google-add <username> <email>
|
||||
|
||||
# List users with password, Google, and email status
|
||||
.venv/bin/python manage_passwords.py list
|
||||
|
||||
# Set/check a password directly
|
||||
@@ -152,6 +159,8 @@ cd cortex
|
||||
|
||||
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.
|
||||
|
||||
To enable a channel for a user, create `home/{username}/channels.json` — see the relevant doc in `docs/`.
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
Reference in New Issue
Block a user