Qorven is one Go binary + Postgres. The binary embeds the Next.js web UI via
go:embed, so deployment is a single file. Everything else — Qors, memory, tools, channels — is orchestrated by that binary.The ten-thousand-foot view
The four things to understand
One binary, everything in-process
The web UI, API, WebSocket hub, agent loop, scheduler, dreamer, tool executors — all one Go process. No Node runtime at deploy time. No inter-service RPC. Single-binary build →
Postgres is the source of truth
Users, Qors, sessions, messages, memories, audit log, tenant data, queues. One database. Vectors live next to metadata (pgvector), so no separate vector DB. Database schema →
Qors are rows, not processes
A Qor is a row in
agents plus its system prompt, tools, model preference, and history. The agent loop rehydrates a Qor on demand when it needs to run — no long-lived per-Qor process. What is a Qor →Channels are surfaces, not identities
You have one Qor per role; it’s reachable from the web, TUI, Telegram, WhatsApp. Every inbound message is tagged with its channel and merged into the Qor’s single canonical chat. One Qor, one chat →
Request path, end-to-end
Take the simple case: you ask Prime “summarise my inbox” from the web UI.Web UI sends message
Browser →
POST /api/v1/chat/completions with {session_id, agent_id, message}. The /api prefix is stripped by middleware in production; in dev it routes through Next’s rewrites.Gateway authenticates + validates
AuthMiddlewareV2 checks the auth token, TenantScopeMiddleware binds the Postgres transaction to the caller’s tenant, TenantQuotaMiddleware rate-limits by tenant. Auth middleware →Agent loop picks up
The loop loads Prime’s row, recent messages (compacted if long), system prompt, and toolset. It calls the LLM with streaming enabled.
LLM streams back
Tokens flow back through the WebSocket hub to the UI. If the LLM decides to call a tool (e.g.
delegate_to_soul → “Inbox Qor”), the loop pauses, runs the tool, appends the result, re-invokes the LLM.Tool calls fan out
The inbox Qor gets spawned (or found), runs its own loop, uses
email tool to read Gmail, writes a summary, returns. Prime’s loop resumes with that summary in context.What’s not in the picture
No Redis, no Kafka, no message queue
No Redis, no Kafka, no message queue
Background work uses Postgres
LISTEN/NOTIFY + SELECT ... FOR UPDATE SKIP LOCKED. Good enough for hundreds of concurrent Qors; simpler to operate; no extra service to keep alive.No separate vector DB
No separate vector DB
pgvector lives in the same Postgres. Embedding writes + metadata writes are one transaction. Memory system →
No cloud-only components
No cloud-only components
Qorven runs fully on a $5 VPS, a Raspberry Pi 5, a Mac mini, or air-gapped. The only network calls the binary makes are to LLM providers you’ve configured. Zero telemetry. Threat model →
No custom DSL for agents
No custom DSL for agents
Qors are configured by writing a system prompt + picking tools/models from the UI. No YAML workflows, no DAGs, no graph editor. Delegation happens because the LLM decides to delegate, not because you wired a graph.
How the pieces relate
| Component | What it owns | Where it lives |
|---|---|---|
| Gateway | HTTP/WS, auth, routing, rate-limits | One Go binary |
| Agent loop | Running Qors, tool dispatch, streaming | In-process |
| Tools | 80+ built-in actions + MCP + custom | In-process, some shell out to browser/Python |
| Memory store | Sessions, messages, memories, graph edges | Postgres + pgvector |
| Scheduler | Cron jobs, heartbeats, QOROS | In-process, Postgres rows for state |
| Dreamer | Periodic memory consolidation | Background goroutine |
| Web UI | React/Next.js dashboard | Embedded in the binary via go:embed |
| TUI | Terminal UI | qorven binary, same code path |
| Channels | Inbound webhooks, outbound dispatch | In-process, per-channel goroutines |
Read the code
Qorven is open-source under FSL‑1.1‑ALv2. The hot paths:backend/internal/gateway/gateway.go— the HTTP router, middleware stack, route mount orderbackend/internal/agent/loop.go— the agent loop, tool dispatch, streamingbackend/internal/session/session.go— canonical chat, compaction, per-channel filteringbackend/internal/memory/— embedding, compression, graph, dreamerbackend/internal/tools/— every built-in tool, one file eachweb/— the Next.js app;app/(app)/has every dashboard page
Where next
One Qor, one chat
The canonical chat model and per-channel filtering.
Delegation
Prime → specialists. How and when Qors delegate.
Memory system
Compaction, pgvector, the knowledge graph, dreaming.
Security model
Tenant isolation, encryption, audit trail.