>_ docs / getting started / Agent setup

§ 01 Getting started

Agent setup

Everything an agent needs to use Grounded, in one place: a block for its rules file, a startup hook, six slash commands, and MCP if you want it. All of it talks to the HTTP API, so it works from any harness that can run curl.

Primary path · HTTP MCP · optional Downloads · SHA-256 listed

// The shape of it

HTTP first #

Grounded Core serves one HTTP API, by default at http://127.0.0.1:7437. Every agent integration on this page is a thin layer over it: the hook calls POST /brief, the commands call /recall, /facts, /sessions, /impact, /docs/ingest and /brief, and the guidance block tells the agent to do the same itself. Nothing here needs an SDK, a plugin or an MCP client.

The API documents itself. GET /llms.txt is the agent-facing manual for the running instance: routes, shapes, limits, gotchas. It needs no token, so an agent can read it before it knows how to authenticate.
One setting: the base URL. The hooks and commands read GROUNDED_URL and fall back to http://127.0.0.1:7437. Set it when Core runs on another machine or port. If you turned on a token, set GROUNDED_TOKEN too.
MCP is optional. It exposes the same engine as tools, and only on the machine that holds the cabinet. Set it up if your harness prefers tools; skip it and you lose nothing the API doesn't have.

// Paste into the rules file

Guidance block #

Put this in the file your agent reads at startup: CLAUDE.md for Claude Code, AGENTS.md for Codex and others, a project rules file for Cursor. Replace the base URL if yours differs. It is deliberately short: it points at /llms.txt for mechanics instead of copying them, so it doesn't go stale when Core changes.

grounded-agent-guidance.md CLAUDE.md · AGENTS.md

## Grounded (shared memory)

Grounded is this workspace's memory service. Base URL: http://127.0.0.1:7437 (replace with yours). If a token is set, send `Authorization: Bearer <token>` on every call except /health and /llms.txt.

- Read `GET /llms.txt` before your first call. It is the manual for this instance: do not guess routes, fields or limits.

- Session start, when no brief was injected: `POST /brief` with `{"agent":"<you>","project":"<repo>","cwd":"<abs path>","format":"markdown","timezone":"<IANA zone>"}` and read `.text`.

- Before asserting a port, path, service, decision or status: `POST /recall` with `{"query":"<question>","limit":10}`. Cards are in `.data`, ranked by `score`; read `.meta` before concluding nothing matched. Full record: `GET /get/<typedId>`.

- Before stopping, removing, deleting or renaming anything: `POST /impact` with `{"subject":"<name, port or path>"}`.

- A durable rule the user states or confirms: `POST /facts` with `{"fact":"<one terse line>","scope":"global | project:<name> | agent:<name>","topicKey":"<stable-key>"}`. Same scope + topicKey revises in place. Check `delivery.delivered`. Never write a fact by inference.

- When the user asks to log the work, or the session is ending: `POST /sessions` with `{"summary":"<one line>","details":"<what shipped, what is open>","project":"<name>","agent":"<you>"}`.

- A record that contradicts what you observe: name it by typed id and propose the fix. Do not silently work around it.

Download: grounded-agent-guidance.md · sha256 eb0f1eb74ee1e6c99b04713a95352365f1277f05743e97be707d0d8cd3fab97e

Keep agent-specific truth out of it. Topology, credentials and house rules belong in facts or in your own config files, never in both: see one truth, one home.

// Context before the first token

Startup hooks #

A SessionStart hook hands the agent its brief before it starts: vision, facts, recent work and related docs, scoped to the agent and the project it opened in. Both scripts are the ones Core ships, and both are failure-silent: if Core is down they exit 0 and the agent starts the way it would have without Grounded.

File	For	sha256
`grounded-session-start.sh`	Claude Code SessionStart hook. Reads the hook payload's cwd, asks for the brief, returns it as additionalContext. Needs curl and jq.	`d503524e60004ffa186e136d931e5f374d43a3d4273e61b9004a442d07f35c29`
`grounded-session-start.generic.sh`	Any harness. Prints the brief as plain markdown to stdout. Needs curl; uses jq when present.	`528831cc77d19727ce6cc9acc583ca52360c612a8549774048bbacd95c43f4d7`

Claude Code. Download the hook, check it, make it executable:

install hook ~/.claude/hooks

>mkdir -p ~/.claude/hooks && cd ~/.claude/hooks

>curl -fsSLO https://getgrounded.dev/downloads/hooks/grounded-session-start.sh

>sha256sum grounded-session-start.sh

d503524e60004ffa186e136d931e5f374d43a3d4273e61b9004a442d07f35c29 grounded-session-start.sh

>chmod +x grounded-session-start.sh

Then merge this under "hooks" in ~/.claude/settings.json (or a project's .claude/settings.json):

settings.json ~/.claude

{

"hooks": {

"SessionStart": [

{

"hooks": [

{ "type": "command", "command": "$HOME/.claude/hooks/grounded-session-start.sh" }

]

}

]

}

Another machine or port: put the variable in front of the command, "GROUNDED_URL=http://10.0.0.5:7437 $HOME/.claude/hooks/grounded-session-start.sh". Same for GROUNDED_TOKEN.
Scoping: the brief is asked for as agent claude (change it with GROUNDED_AGENT) and project = the name of the folder the session opened in.
Windows: the scripts are bash; they need a bash with curl and jq on its PATH, such as Git Bash.

Other harnesses. Use grounded-session-start.generic.sh: it prints the brief as markdown, so anything that runs a command before a session can feed it in. Pass the working directory as the first argument. A harness with no startup hook at all (Cursor, for one) still gets the brief: the guidance block tells the agent to call POST /brief itself. Core also prints either script and its wiring with grounded hooks print <target>. More on push vs pull: hooks & integration depth.

// Recall, write, check, re-index

Slash commands #

Six commands in Claude Code's .claude/commands/*.md format, written against the HTTP API only. Each one reads GROUNDED_URL (default http://127.0.0.1:7437) and GROUNDED_TOKEN, builds its JSON with jq, and falls back to /llms.txt when a call fails. The bodies are plain instructions, so they port to any harness with prompt files or skills.

File	Does	sha256
`grounded-recall.md`	/grounded-recall <question>: search before asserting, cite the cards.	`689717ec6ac63be164451d5d702fb0b4aff08baac1920abd9a0aeb62b28b46e4`
`grounded-fact.md`	/grounded-fact <rule>: check for an existing fact, then write or revise one.	`1ba65e7ef64f479600aabfe6a265fa834a1a5df7d78da19325c46ab7ef22854e`
`grounded-session.md`	/grounded-session: log the working session when asked or ending.	`e2c84f1c882a6dda39e66a7e1231ea741e6bac592f15c74326aa8b3856d510a6`
`grounded-impact.md`	/grounded-impact <name>: what depends on this, before you stop, remove, delete or rename it.	`536be5cad3567c3907384689b554403025af52e0323acd48879e693a1679b078`
`grounded-ingest.md`	/grounded-ingest <folder>: re-index docs after edits, and check the engine actually saw files.	`2d4e08816667d6a3fb110c08e7420dd9834336e94ed56f81626da27267757296`
`grounded-brief.md`	/grounded-brief: pull the startup brief mid-session or where there is no hook.	`dc4a997574485bffc9a2172806e51f7344465c8367d9448873ffb4f4b8829973`

install commands ~/.claude/commands

>mkdir -p ~/.claude/commands && cd ~/.claude/commands

>curl -fsSLO https://getgrounded.dev/downloads/commands/grounded-recall.md

>curl -fsSLO https://getgrounded.dev/downloads/commands/grounded-fact.md

>curl -fsSLO https://getgrounded.dev/downloads/commands/grounded-session.md

>curl -fsSLO https://getgrounded.dev/downloads/commands/grounded-impact.md

>curl -fsSLO https://getgrounded.dev/downloads/commands/grounded-ingest.md

>curl -fsSLO https://getgrounded.dev/downloads/commands/grounded-brief.md

>sha256sum grounded-*.md

# compare with the table above, or with https://getgrounded.dev/downloads/SHA256SUMS

Install them in a project's .claude/commands/ instead to scope them to that repo. Writing is deliberate: a fact only when the user states or confirms it, a session only when asked or when the session is ending. /grounded-impact is the one to make a habit of: run it before stopping, removing, deleting or renaming anything.

// If your harness wants tools

Optional: MCP #

The MCP server exposes the same engine as ground_* tools over stdio. It opens the cabinet directly rather than calling the API, so it runs on the machine where Core is installed. An agent on another machine uses the HTTP API (over LAN sharing or your own network).

Core newer than 0.2.0 launches it with grounded mcp serve. grounded mcp install <target> prints the snippet for you; it changes no files.

Harness	Paste into
Claude Code	`~/.claude.json`, or `.mcp.json` in a project
Cursor	`~/.cursor/mcp.json`, or `.cursor/mcp.json` in a project
Codex	`~/.codex/config.toml`

mcpServers Claude Code · Cursor

{

"mcpServers": {

"grounded": { "command": "grounded", "args": ["mcp", "serve"] }

}

config.toml ~/.codex

[mcp_servers.grounded]

command = "grounded"

args = ["mcp", "serve"]

Add --http-port <port> to the args (or set GROUNDED_MCP_HTTP_PORT) to serve streamable HTTP on 127.0.0.1 instead of stdio.

Core 0.2.0 has no mcp serve, and the grounded-mcp command its mcp install prints is not on the PATH of a release install. Point the harness at the bundled server with Node instead:

Linux (install.sh) ~/.grounded

{

"mcpServers": {

"grounded": {

"command": "node",

"args": ["/home/<you>/.grounded/lib/current/lib/mcp.mjs"]

}

Linux: install.sh puts the runtime in ~/.grounded/lib/current/. Use your absolute home path: MCP clients don't expand ~. Installed with a custom GROUNDED_HOME? Use $GROUNDED_HOME/lib/current/lib/mcp.mjs and also set "env": {"GROUNDED_HOME": "<that path>"} in the server entry: only the grounded launcher sets it for you.
Windows (Companion): the runtime is in %USERPROFILE%\.grounded\lib\current\ (older installs: %USERPROFILE%\Grounded\.core\lib\current\). Call Node directly on 0.2.0 — its grounded.cmd launcher is broken, fixed in the next release. If where node finds nothing, use the Node that Companion installed: %USERPROFILE%\.grounded\runtime\node-<version>-win-x64\node.exe.

Windows (Companion) %USERPROFILE%.grounded

{

"mcpServers": {

"grounded": {

"command": "node",

"args": ["C:\\Users\\<you>\\.grounded\\lib\\current\\lib\\mcp.mjs"]

}

// Keep Core updated

Stay current #

Hooks, commands and the guidance block lean on what Core serves, and Core keeps improving what it serves: recall ranking, brief budgets, /llms.txt itself. Compare the version you run with the latest release:

version check :7437

>curl -s localhost:7437/health | jq -r .version

0.2.0

>curl -s https://getgrounded.dev/llms.txt | grep -i 'latest core'

If /health reports an older version than "Latest Core", update: Companion does it from its Settings page on Windows and macOS; on Linux, re-run install.sh and restart the service. Data is never touched by an update. See updating. An agent can run the same check itself, and should mention it when it finds Core behind.