🐝 Waggle OS — the mental model
One picture: the thin layer you see, and the deep system that
actually runs beneath it. Read top → down.
Grounded in CLAUDE.md + source
Frontstage = UX · Backstage = system
👁️
What the user sees
Frontstage · the Desktop OS
A workspace-native desktop OS. A React 19 web app running inside a Tauri shell — chat, files, memory, all in one window.
🏠 Home / Cockpit
🗂️ Workspaces · 15 templates
💬 Chat (artifact-first)
🧠 Memory Center
👤 Persona Switcher · 22
🛒 Marketplace
🚀 Launcher
📎 Files & Artifacts
✅ Tasks board
⚙️ Settings · Onboarding
⌘K command bar
apps/web · Tauri 2.0 · base-ui
▲ what you touch · ▼ invisible, but does all the work
🔌
The bridge
API · Sidecar
The UI never touches the brain directly — it calls routes. A Fastify Node server bundled inside the desktop binary.
/api/* Fastify routes
🔑 device-token auth
📡 SSE live streams
🔀 LiteLLM model router
🗂️ workspace context API
🤖
The brain that acts
Agent Runtime · packages/agent
Turns one request into action: picks a persona, assembles the prompt, recalls memory, runs tools, then checks its own work.
loop
agent-loop
orchestrator · buildSystemPrompt / recallMemory
👤 22 personas
guard
🛡️ injection-scanner
🔒 capability & trust
🧹 quality · contradiction · correction
scale
🧬 evolution loop
🐝 subagents · WaggleDance
🧠
What makes it remember
Memory Substrate · "Hive-Mind" — the moat
Persistent, per-workspace memory. Free forever (the lock-in moat). Open-sourced as marolinik/hive-mind.
mind/
FrameStore
HybridSearch · vector+keyword+rerank
KnowledgeGraph
IdentityLayer
AwarenessLayer
harvest/
ChatGPT · Claude · Gemini · PDF · URL
Cognify · extraction
🗄️
Where it all lives
Storage · Foundations
Local-first. One isolated SQLite mind per workspace — memory never crosses between projects.
SQLite · better-sqlite3 + sqlite-vec
🔐 Vault · secrets
📁 file-store
🧱 per-workspace isolation
🧩
Cuts across every layer
Cross-cutting concerns
Not a layer — these touch UX, bridge, brain and storage all at once.
🔐 Security · vault-only · injection · IPC allowlist · param SQL
💳 Stripe billing
🪜 Tiers · Trial→Free→Pro→Teams→Enterprise
🏰 KVARK funnel · gated Teams/Ent
What happens when you send one message
02
Sidecar route receives it
Bridge
→
03
Brain picks persona + recalls relevant memory
Agent Runtime
→
04
Runs tools · calls the model via LiteLLM
Agent + Bridge
→
05
Saves new facts to the workspace mind
Memory
→
06
Streams the answer + artifacts back
UX
↺ Next session starts smarter — the memory persisted in step 05 is recalled in step 03.