Hooks & integration depth

An agent gets context from Grounded in one of two ways: it is pushed without asking, or it pulls when it decides to. How deep you can go is set by your harness, not by Grounded — so the surfaces are documented by capability tier rather than assuming one runtime.

// The split

Push vs pull #

A pulled answer is only as good as the agent's decision to ask — and a cold agent does not know there is anything to ask about. Push closes that gap; pull covers everything push cannot anticipate. Most setups want both.

	Push	Pull
Trigger	A harness event — session start, a tool call.	The agent or the human asks.
Needs	A hook system in the harness.	Nothing but an HTTP request.
Surface	`POST /brief`, `POST /recall` from a hook script.	Console, MCP tools, HTTP API.
Fails	Silently — never blocks a session.	Visibly — the caller sees the error.
Costs	Context on every session, asked for or not.	A round-trip, and the judgement to make it.

// Context you didn't ask for

Push: hooks #

SessionStart brief. The shipped push surface. grounded hooks print emits a wrapper that curls POST /brief, extracts the text, and hands it to the agent before its first token. The agent opens already knowing the pinned facts, what shipped recently, the loose ends, and the vision for the project it is sitting in.

hooks print ~

>grounded hooks print claude-code

# SessionStart → curl POST /brief → stdout

# failure-silent: a down service never blocks a session

Scope the brief with agent, project, machine and cwd so five agents on three boxes each get the context that is theirs. Every hook script exits 0 on any failure path — failure-silent means the worst case is an agent that starts the way it would have without Grounded.

PreToolUse injection — a prototype, not a shipped feature. A hook on the edit tools takes the path about to be written, turns it into query words, and runs a facts-only POST /recall against it: the guardrail for the file you are touching, delivered at the moment you touch it. It is advisory — it never denies a tool call — and it needs no server-side support, since sources: ["fact"] is already a recall option. It exists to measure whether trigger-time facts earn dedicated trigger machinery later.

// Context on request

Pull: ask on demand #

MCP tools — the agent surface. ground_recall for cited cards, ground_get for a full record, ground_brief to fetch a brief mid-session, plus the write tools. stdio locally, streamable HTTP for remote or multi-agent setups.
HTTP API — the lowest common denominator. Anything that can make a request can use Grounded: curl -X POST :7437/recall from a script, a Makefile, another tool.
Console — the human surface. Read the cabinet, edit facts, browse the sessions timeline, preview the brief your agent will get.
Lexical search, no hooks at all. Set embeddings.provider = "none" and recall runs full-text only. No model, no hook system, no MCP client — the cabinet is still searchable and every result is still cited.

// Meet the harness where it is

By harness capability #

This is why the split is documented at all. Hook systems are not a given: some harnesses run MCP servers but expose no session lifecycle to hang a brief on. An integration guide that assumes one runtime silently fails on every other one, so Grounded describes three tiers and each is a complete, working setup:

Harness has	You get	Wire it with
Hooks + MCP	Full depth — brief pushed at startup, tools pulled during work.	`grounded hooks print` + `grounded mcp install`
MCP only, no session hook — Cursor, for one	Pull only. Have the agent call `ground_brief` as its first action; a project rules file is the usual place to tell it to.	`grounded mcp install`
Neither	The HTTP API and the console. Shell out to `curl`, or read the cabinet yourself.	`curl :7437/brief`

Tier two is not a downgrade you have to accept quietly — a rules file that says “call ground_brief first” buys most of what the SessionStart hook buys, at the cost of depending on the model to follow it. Prefer the hook whenever the harness has one.