Architecture Overview

Cremind is an open personal assistant you run yourself: a server, a desktop app, and a CLI bundled into one package. This page is the map. It walks through every layer — from the surfaces you talk to, down through the agent runtime and tool plane, to the storage that backs it all — and links out to the deeper concept pages.

The big picture

Cremind is built around a single agent runtime that many surfaces share. You reach the assistant through whichever surface fits the moment — a browser tab, the desktop app, a terminal, or a chat channel — and every one of them talks to the same backend, the same profiles, and the same conversations.

        Surfaces                 Backend (Starlette ASGI :1112)
  ┌──────────────────┐     ┌───────────────────────────────────────┐
  │  Vue 3 SPA :1515 │     │  Reasoning loop (asyncio)               │
  │  Cremind App     │◄───►│    ├─ high model  → planning/reasoning  │
  │  cremind CLI     │ SSE │    └─ low model   → per-tool calls      │
  │  Chat channels   │     │                                         │
  └──────────────────┘     │  Unified tool registry                  │
                           │    intrinsic · builtin · A2A            │
                           │    MCP · skill tools                    │
                           │                                         │
                           │  Event-driven layer (events/)           │
                           │    EventManager · FileWatcher · runner  │
                           └───────────────────┬─────────────────────┘
                                               │
                              ┌────────────────┴────────────────┐
                              │  Storage                          │
                              │  SQLite + Alembic (default)       │
                              │  Postgres · Qdrant · ChromaDB     │
                              └───────────────────────────────────┘

Surfaces

You can talk to Cremind from four places, and they are interchangeable — the agent state lives in the backend, not the client.

• Web UI — a Vue 3 + Vite single-page app served on port 1515.
• Cremind App — an Electron desktop client for Windows, macOS, and Linux. It bundles the agent, so there is no separate server install.
• cremind CLI — a terminal client for chat, conversations, tools, and admin. cremind chat gives you a streamed REPL against a profile.
• Chat channels — adapters such as Telegram, with a channel API for adding more.

Streamed responses reach every surface over Server-Sent Events (SSE), so output appears token by token as the agent works.

The backend

The backend is a Python 3.13+ Starlette ASGI application, exposing its API on port 1112 and running on asyncio throughout. At its heart is the reasoning loop: the agent plans, decides which tools to call, calls them, observes the results, and continues until the task is done.

A defining choice in Cremind is that the loop does not use one model for everything. The expensive high model handles reasoning and planning, while individual tool calls are dispatched to a cheaper low model. The result is lower token cost without giving up planning quality. This split is managed by the ModelGroupManager — see LLM Model Groups for the full story.

The unified tool plane

Everything the agent can do is a tool, and all tools live in one registry regardless of where they come from. Cremind's registry spans five kinds:

Because they share one registry, the reasoning loop treats a built-in file read, a remote MCP call, and another agent the same way. See The Tool Plane and A2A and MCP.

Profiles: isolation by default

A single install can host several assistants side by side — a work assistant, a coding assistant, a home assistant — without leaking context between them. Each profile isolates its own skills directory, embeddings, tool visibility, and conversation history. See Profiles.

The event-driven layer

Cremind doesn't just react to your messages — it can react to the world. A skill's listener holds a long-lived WebSocket to the Cremind Connect relay; when something changes externally, the agent runs immediately with the change as a synthetic user message, and the output streams back to your clients with sub-second latency. This replaces polling, cron, and heartbeat loops. See Event-Driven Architecture.

Storage

By default Cremind stores everything in SQLite, with schema migrations managed by Alembic — no external services to stand up. As your needs grow, you can switch individual services to Postgres, Qdrant, or ChromaDB from the Setup Wizard, running them as Docker sidecars or pointing at external endpoints. See Storage.

Where to go next