Grounded Companion

What it is #

Click the Grounded icon and a small panel opens. The header shows whether the selected cabinet is ready and how long its health check took. Below it:

• Cabinets — the memory stores you're connected to, with live health.
• Agents — which coding agents on this computer are set up to use Grounded.
• Add-ons — search by meaning and Databox, switched on from here.
• Status — Core on this computer, its storage, whether search by meaning runs on the CPU or the graphics card, and Databox.
• Open Console — the full console in your browser.

There is deliberately no search box. Finding things is your agents' job, through MCP; the console is there when you want to look yourself.

Click away or press Escape and the panel hides; Companion keeps running. Quit is in the icon's menu. Opening the app a second time brings back the one already running.

Windows and macOS #

Either way, Core answers only on http://127.0.0.1:7437, stores memory in a single SQLite file by default, and starts with keyword search. Search by meaning is an add-on.

What it installs #

With no Core on the computer, Settings shows Install Grounded Core. Clicking it:

• Reads the Grounded release channel on GitHub Releases and picks the build for your system.
• Finds a Node.js that build runs on. If there isn't one, it downloads the official build from nodejs.org, checks its SHA-256 against that release's published sums, and keeps it in ~/.grounded/runtime. Your own Node install is left alone.
• Downloads Core, verifies it, unpacks it to ~/.grounded/lib/<version> and points lib/current at it.
• Registers the service with Core's own installer, the same one grounded install uses, then waits until /health answers.

It refuses to install over a Core that's already there, or when something else already answers on port 7437. Where things end up:

Companion never puts your cabinet inside .grounded. The layout is the same one Core uses everywhere; see installation.

Cabinets #

A cabinet connection is an address, not a copy. Companion talks to each cabinet's API; nothing is synchronized or moved.

• On this computer — Core at 127.0.0.1:7437. Companion finds it even before you connect it, so Settings, Add-ons and Databox work on first run.
• On your network — a cabinet another computer shares with you. Pair once with a code; see LAN sharing.
• Cloud — a hosted cabinet, connected by its full API address and an existing cabinet token. Account sign-in stays in the browser. The option to add a new Cloud connection is hidden in the current release; one saved earlier still shows and can be edited.

Companion checks every connected cabinet every 30 seconds and whenever you open it, and shows its health and document count. Network and sign-in errors are named, not lumped together. You can select, rename, update a cabinet's credentials, or disconnect it.

Choosing a cabinet in Companion does not change your agents. They keep using whatever their own configuration points at.

Agents #

The Agents sheet reads the user-level configuration of the coding agents on this computer and tells you which ones mention Grounded:

Add-ons #

The Add-ons page lists what Core can add, with the download size first and progress while it runs:

• Search by meaning — a small local embedding model for semantic recall. The page shows the model, whether it runs on the graphics card or the CPU, and the device setting.
• Databox — folders of structured items your agents query with SQL. Once it's on, a Databox view lists each dataset's freshness, item and index counts, tables and columns. Update index runs only when you click it.

Add-ons run on the computer that hosts the cabinet. You can see a network cabinet's add-ons from any Companion, but you install them from Companion on that computer. With no Core yet, the catalog shows each one marked Needs Core. More: Add-ons.

Health and notices #

Each cabinet's /health can report issues. Companion gathers them from every connected cabinet, most severe first:

• A badge in the footer counts them, tinted by the worst one, and opens the Notifications page.
• Home shows one warning or error at a time, compactly. Information-only notices stay on the Notifications page.
• The tray or menu bar icon changes while a warning or error is undismissed, and its tooltip says how many.

The first case is search by meaning running on the CPU, which is slow and heavy next to the graphics card. The notice in the screenshot above offers Use graphics card, Turn off (keep keyword search only) and Settings. Those buttons appear only for Core on this computer; for a network cabinet, change it in Companion on the computer that hosts it.

Dismissing a notice hides it for that cabinet. If the issue clears and later comes back, it shows again.

Credentials and config #

• Tokens and passwords go to Windows Credential Manager or the macOS Keychain, tied to the connection and its exact address. They are not written to Companion's config and never shown back in the app.
• Redirects are refused, so a credential can't follow a cabinet to another address. Don't put credentials in an address.
• Everything else — connection names and addresses, the selected cabinet, dismissed notices — lives in ~/.grounded/companion.json (%USERPROFILE%\.grounded on Windows).

Updating #

• Core — Companion checks the release channel at launch and every six hours. When a newer Core is out, a green up-arrow appears in the footer; it opens the Grounded Core card in Settings, where you update. The new version is verified and unpacked beside the old one before lib/current switches over; if it doesn't start, Companion switches back.
• Companion on Windows updates itself: it downloads the new version from getgrounded.dev, checks its size and SHA-256, and swaps it in.
• Companion on macOS doesn't update itself yet. Download the new version from the download page.

Updates never touch your cabinet. Core migrates its database on startup.

Uninstall #

In Settings, the Grounded Core card has Uninstall. It removes the service and Core's program files (lib/ and runtime/). Your cabinet, config, models and logs stay.

Deleting the cabinet is a separate choice you confirm by typing DELETE. That removes your memory and ~/.grounded, except companion.json, so Companion stays connected to your other cabinets. A Core running from a source checkout is left alone: uninstall it there with grounded uninstall.

To remove Companion itself, quit it from the icon's menu and delete the app.