Grounded Docs
v0.2.0 · alpha Download Changelog GitHub
>_ docs / add-ons / Add-ons
§ 05 Add-ons

Add-ons

Core is about 2 MB and works on its own. Add-ons are the heavier, optional parts: you turn them on when you want them, and their downloads happen only then.

// Off until you ask

What an add-on is #

An add-on is a feature whose native runtime doesn't ship with Core. When you turn one on, Core downloads that runtime into its own folder (~/.grounded/addons/<id>) and loads it live. Nothing else changes: turning an add-on off leaves your memory as it was.

Add-onGives youDownload
embeddingsSearch by meaning, run on your own computer.~75 MB runtime + a ~274 MB model, once
databoxFolders of structured items your agents query with SQL.~40 MB runtime (DuckDB)
// Search by meaning

Embeddings #

Without embeddings, recall matches words: it's keyword search, and it works fine. With the Embeddings add-on, recall also matches meaning, so "how do we ship builds" can find a note titled "release procedure".

  • Runs on your machine. A small model (nomic-embed-text-v1.5) runs in-process with onnxruntime. No Ollama, no account, nothing sent anywhere.
  • Uses your graphics card on Windows through DirectML, which works with any DirectX 12 GPU. Elsewhere, or with --device cpu, it runs on the CPU: slower, but it works.
  • Catches up in the background. Turning it on embeds everything already in your cabinet while Grounded keeps working.

Already run Ollama? Grounded can use it instead — see the [embeddings] section in self-hosting.

// Structured data

Databox #

Databox is for numbers and records: catalogues, inventories, exports. Point it at a folder of JSON items and agents answer questions with one line of SQL instead of re-reading raw files. Rows never enter recall or the brief. It has its own page: Databox.

// Two ways

Turning them on #

  • Companion (Windows) — open the Add-ons page and switch one on. It shows the download size first and progress while it runs.
  • CLI — grounded addon add embeddings or grounded addon add databox. grounded addon status shows what's on. See the CLI page for options.
embeddings ~
>grounded addon add embeddings
search by meaning off (keyword search only)
? Turn it on? › yes
search by meaning is on (graphics card).
// For scripts

API #

MethodPathPurpose
GET/addonsThe catalog: each add-on's name, whether this platform supports it, its state (available, installing, on, off, error) and download size.
POST/addons/:id/installInstall and turn on. Returns 202 and runs as a job you can poll with GET /addons. For embeddings, {"device": "auto" | "cpu" | "gpu"}; on an add-on that's already on, this switches the device without a new download.
POST/addons/:id/disableTurn it off. Your data stays.

Installing and disabling are host administration: they work from the computer running Core and are refused over LAN sharing.