gbrain/docs/guides/push-context.md

Push-based context (#2095, v0.42.43.0)

Retrieval used to be pull-only: the agent had to know to ask before the brain contributed anything. Push-based context inverts that — the brain volunteers relevant pages from the recent conversation, confidence-gated so push noise never becomes worse than pull silence.

The push channels share one zero-LLM core (src/core/context/volunteer.ts):

Channel	Surface	When to use
reflex	automatic, inside the context engine	default-on for plugin hosts; nothing to call
op	gbrain volunteer-context / MCP volunteer_context	agents without the plugin; one call per turn
watch	gbrain watch	stream a transcript in, volunteered pages stream out
claude-code / codex	gbrain hook user-prompt (registered by gbrain bootstrap)	per-prompt injection inside a harness; see "Harness hooks" below

How it decides

1. Extract entities across the last N turns (capitalized runs, @handles), merged with recency / frequency / user-role salience. Assistant-introduced entities and "what did she invest in?" follow-ups whose antecedent was named in the window now resolve.
2. Resolve through the alias table, exact titles, and slug suffixes — each arm carries an honest confidence: alias 0.9, exact title 0.8, slug-suffix 0.6, +0.05 when mentioned in ≥2 turns or the newest turn.
3. Gate at min_confidence (default 0.7 — slug-suffix matches need an explicit lower gate), suppress pages already surfaced (slug-presence only), cap at 3 pages (hard cap 5).

CLI

# one-shot: pipe recent turns (oldest → newest)
printf 'user: ask alice-example about the deal\nassistant: noted\nuser: what did she say?\n' \
  | gbrain volunteer-context

# streaming: volunteered pages print as the transcript flows
some-transcript-feed | gbrain watch --json

# the feedback loop: how often were volunteered pages actually opened?
gbrain volunteer-context --stats

Stats are approximate by design: "used" means pages.last_retrieved_at > volunteered_at — the 5-minute last-retrieved throttle causes false negatives and unrelated reads of the same page cause false positives. Use the per-arm precision to tune min_confidence, not as an exact metric.

PGLite + gbrain watch: PGLite is single-connection, and watch holds its connection for the whole session — a concurrent gbrain serve or any write path blocks until watch exits. On a PGLite brain, run watch in bursts (piped input exits at EOF) or use the ambient reflex channel instead, which routes through a running serve's resolve socket rather than taking the lock. Routing watch through that same socket is a filed follow-up (TODOS.md). Postgres brains are unaffected.

Harness hooks (the prompt-time channel)

gbrain bootstrap registers gbrain hook user-prompt as a Claude Code UserPromptSubmit hook: every prompt is assembled into a per-turn context block (reflex pointers + volunteered pages + hot facts) through a running serve's IPC socket and injected as additionalContext. Two properties make this channel production-grade rather than spammy-and-invisible:

• Cross-turn dedupe. The hook reads its OWN previous injections back out of the session transcript (Claude Code records them as structured hook_additional_context attachments; only gbrain-marked blocks count) and passes them as prior context — so a page is volunteered once per session, not once per mention. The dedupe horizon is bounded (the recent transcript window, byte-capped), so a marathon session can eventually re-volunteer its oldest injections. The extraction is structural, never substring matching over raw turn text, so a short slug appearing in a tool payload can't over-suppress.
• The feedback loop. The serve logs each DELIVERED block's volunteered pages and pointers to context_volunteer_events under the hook's channel (claude-code by default; a codex hook registration passes --harness codex). gbrain volunteer-context --stats then shows per-harness precision, and gbrain doctor's volunteer_channels check shows which channels actually fire, with guidance for the two quiet cases: "hook installed but never registered (restart the session)" and "registered but quiet". Logging happens at the delivery point only — a block abandoned before the serve responded is never counted — and because a delivered response still isn't proof of injection (the hook can trim or drop it client-side), the doctor check reconciles the counts against the hook's own heartbeat and cautions when they diverge.

The hook lane rides the PGLite serve's IPC socket: on a Postgres brain or a thin-client install the hook stays quiet by design (pull-mode retrieval covers those; extending the lane is a filed follow-up in TODOS.md).

Kill switch: GBRAIN_HOOKS=0. Install/uninstall: docs/guides/bootstrap.md.

Config

Key	Default	What it does
retrieval_reflex_window_turns	4	turns the ambient reflex extracts from; 1 = legacy current-turn-only (file/env plane: GBRAIN_RETRIEVAL_REFLEX_WINDOW_TURNS)
retrieval_reflex	true	the ambient channel's master switch
retrieval_reflex_max_pointers	3	pointer cap per turn

Per-call knobs: max_pages + min_confidence on both the op and gbrain watch (--max-pages / --min-confidence, plus --window-turns / --source on watch); on the op only: prior_context (text whose already-surfaced slugs are suppressed), session_id / turn attribution params (watch stamps its own per-session id and turn numbers in the feedback log), and days to size the --stats window.

Storage + privacy

Volunteered pages log to context_volunteer_events (migration v117): slug, arm, confidence, channel, optional session/turn — the rationale is a deterministic template string, never raw conversation text. Event writes are best-effort (fire-and-forget, drained at CLI exit) — the log is a tuning signal, not an audit trail. Rows are pruned after 90 days by the dream cycle's purge phase. Synopses always strip the takes/facts fences — the same strip get_page applies to untrusted callers, applied unconditionally here so private fence rows never reach a prompt regardless of caller trust.