>_ docs / getting started / Quickstart

§ 01 Getting started

Quickstart

This takes a fresh cabinet to recallable, agent-ready memory. Everything below is shown with curl against the running service — the console does all of it with no terminal, and agents do it through MCP tools.

First, install

These calls assume the service is up at 127.0.0.1:7437. If it isn't, install it first: on Windows with Grounded Companion, on macOS and Linux with the install script. See installation.

// Explicit memory

Record what matters #

Add a durable fact and log a session. Facts are the rules an agent must follow; sessions are what happened recently.

terminal :7437

>curl -sX POST localhost:7437/facts \

-H 'content-type: application/json' \

-d '{"fact":"Never push without permission","scope":"global"}'

{ "id": 1, "typedId": "fact:1", "status": "active", … }

>curl -sX POST localhost:7437/sessions \

-H 'content-type: application/json' \

-d '{"summary":"Shipped recall UI","project":"grounded"}'

{ "id": 1, "typedId": "session:1", … }

// Index your writing

Ingest your docs #

Point Grounded at folders of markdown. It walks them, honours .groundignore, strips <private> blocks, chunks, and embeds — re-ingest is cheap because unchanged chunks are skipped by hash.

terminal :7437

>curl -sX POST localhost:7437/docs/ingest \

-H 'content-type: application/json' \

-d '{"paths":["./docs","./notes"]}'

{ "scanned": 42, "added": 118, "updated": 0, "skipped": 0, "removed": 0 }

// Find prior context

Recall #

Ask a question. Recall embeds it once, searches lexical + vector lanes in parallel, fuses with reciprocal rank fusion, and returns small, ranked, source-cited cards — grouped facts, then sessions, then docs.

>_ POST /recall "what did we decide about sqlite?"3 results

fact

SQLite + sqlite-vec is the default cabinet
fact:12 · matched both

0.94

session

Chose SQLite as the laptop wedge
session:274 · matched vector

0.88

doc

Storage adapters — decisions locked
doc:1091 · STATE.md

0.81

Every card carries a typed ID, a source, and how it matched. Pass an ID to GET /get/fact:12 for the full, cited record — compact by default, complete on demand. How ranking works.

// Load the right context

Get a brief #

A brief is the scoped startup summary an agent reads before it works: your vision, the most recent work, the facts that apply to this agent and project, and related docs.

brief :7437

>curl -sX POST localhost:7437/brief \

-H 'content-type: application/json' \

-d '{"agent":"codex","project":"grounded","format":"markdown"}'

=== STARTUP CONTEXT ===

=== VISION (global · project:grounded) ===

=== MOST RECENT WORK (newest first) ===

=== DYNAMIC FACTS (curated · scope: global + agent:codex + project:grounded) ===

// Hand it to your agent

Wire an agent #

Print the MCP config snippet for your agent and paste it in. From then on the agent recalls, fetches by ID, writes sessions, and pulls briefs itself — no framework required.

mcp install ~

>grounded mcp install claude-code

# prints the config snippet for ~/.claude.json

# targets: claude-code · codex · cursor · generic

Prefer startup briefs to be injected automatically? grounded hooks print emits a SessionStart hook that curls POST /brief for you. See MCP & wiring.