Introduction
Grounded is self-hosted continuity for multi-agent workspaces. It captures your facts, sessions, docs, and vision, ranks them with source-cited recall, and hands every agent a compact startup brief — so the work survives across models, machines, and projects.
How it fits together #
Grounded runs as a small service over a local cabinet — a folder on your
machine (~/Grounded/Cabinet) holding a single database, with its config file
kept apart in ~/.grounded. You never call a library or hand-edit rows;
you talk to the running service three ways: the web console
for humans, MCP tools for agents, and the
HTTP API for scripts. The grounded
command stands the service up and manages it, and on Windows the Companion
tray app does that job for you.
The default cabinet is a single SQLite database with vector and full-text search built in — no external services, no cloud, no account. Point it at Postgres + pgvector only when you outgrow one file. Nothing leaves your infrastructure.
The four lanes #
Grounded separates memory by responsibility instead of inferring too much. Each lane has an explicit source of truth; recall searches across them and brief assembles the right slice at startup.
- Facts — durable rules and operator truths. Explicit, scoped, pinnable, written by your agents and edited in place — never inferred.
- Sessions — the chronological work log: what happened, recently, per project.
- Docs — markdown and notes you ingest, chunked and indexed for retrieval.
- Vision — what the work is for. One active narrative per scope, injected into every brief, never ranked by recall.
Read the concepts for the data model, typed IDs, and how the cabinet stays inspectable.
Surfaces #
Everything below talks to the same engine and the same cabinet. Pick whichever fits the caller.
curl can use. Start with
GET /llms.txt — a machine-readable manual an agent can fetch
on demand, unauthenticated. For operators CLI Install, inspect, and manage the service and its add-ons with grounded. Useful without an LLM #
Facts, sessions, docs, briefs, and lexical recall all work with zero model calls. Embeddings turn
recall into hybrid vector + lexical search, but they are an enhancement, never a requirement —
set the embedding provider to none and Grounded runs full-text-only, no error.
When you want search by meaning, the Embeddings add-on runs a
small model on your own machine.
Nothing here depends on opaque agentic inference.