# Brainbox hooks pack

Deterministic memory choreography for AI coding harnesses. The instruction
block on the dashboard's Setup tab asks your agent to recall and to close
sessions — but instructed calls fire unreliably. These hooks make the two
load-bearing moves **deterministic**:

1. **Recall inject** — every user prompt is answered against your brain
   (`POST /ask`) and the top matches are injected into the turn as background
   context. The model no longer decides whether to look; it always sees.
2. **Digest send** — when a session ends, a mechanical digest of the
   conversation is fired at `POST /dream/end`. The brain distils lessons from
   digests while it dreams; without one, a session closes dark.

The instruction block stays in place as the **floor** (it also covers writes,
which hooks can't decide for the model). This pack is the ceiling.

## Install

From the dashboard **Setup** tab (your key is injected via env, never baked
into these files):

```bash
BRAINBOX_KEY=bbk_... bash -c "$(curl -fsSL https://brainbox.thexi.dev/hooks-pack/install.sh)"
```

Or from a local copy of this folder: `BRAINBOX_KEY=bbk_... ./install.sh`

The installer detects which harnesses exist and wires only those:

| Harness | Config touched | Recall inject | Digest send |
|---|---|---|---|
| Claude Code | `~/.claude/settings.json` | `UserPromptSubmit` | `SessionEnd` (immediate) |
| OpenAI Codex | `~/.codex/hooks.json` | `UserPromptSubmit` (stdout → developer context) | `Stop` (debounced) |
| Google Antigravity (CLI) | `~/.gemini/config/hooks.json` | — (instructions floor only) | `Stop` (debounced) |

Existing configs are merged, never clobbered; a one-time `.bak-brainbox`
backup is written next to each file the first time it's modified. Re-running
the installer is a no-op.

**Post-install, per harness:**

- **Codex** trust-reviews hooks by hash — open `codex`, run `/hooks`, and
  approve the two brainbox entries once (again after any script update).
  The installer also sets `[features] hooks = true` in `~/.codex/config.toml`
  — without it Codex silently ignores `hooks.json` (verified on 0.144.0).
- **Antigravity**: hooks run in the CLI (`agy`) only, not the IDE. Verify with
  `/hooks` inside a session. Its hook API can capture transcripts but has no
  confirmed way to inject context into a turn, so recall stays on the
  instruction floor there — digest choreography still works.
- **Claude Code**: nothing else needed.

## Your API key

Never shipped in this pack. Runtime resolution order:

1. `BRAINBOX_KEY` environment variable
2. `~/.brainbox/key` (written by the installer, `chmod 600`)
3. macOS Keychain item `brainbox-bbk-key`
   (`security add-generic-password -s brainbox-bbk-key -a brainbox -w 'bbk_...'`)

No key found → hooks silently do nothing. Rotate the key on the dashboard's
Connect tab and re-run the installer (or update the file) to swap it.

## Design guarantees

- **Bounded turn cost.** Recall adds ~5s (worker-side pipeline latency) to at
  most one prompt per 120s — follow-ups reuse the already-injected context.
  The HTTP timeout is 8s (`BRAINBOX_RECALL_TIMEOUT`) and every failure path
  is silent — worst case you're back to instructions-only.
- **Compact.** Injected recall is capped at ~2000 chars (~500 tokens).
- **Digest is fire-and-forget.** `/dream/end` answers 202 immediately; the
  dream runs server-side.
- **Why "debounced"?** Codex and Antigravity fire `Stop` after *every* turn,
  not at session end. Sending a digest per turn would run a dream per turn.
  Instead each turn rewrites a per-session state file and arms a detached
  10-minute timer; only the last turn's timer actually sends. Sessions killed
  before that are closed digest-less by the server's TTL sweep — nothing is
  ever stuck open.
- **Zero dependencies.** Plain `python3` stdlib + `bash` + `curl`.

Tunables (env vars, set where your harness launches): `BRAINBOX_MCP_URL`
(worker override), `BRAINBOX_RECALL_THROTTLE` (seconds, default 120),
`BRAINBOX_DIGEST_IDLE` (debounce seconds, default 600).

## Uninstall

1. Remove the entries whose commands mention `bb_recall_inject` /
   `bb_digest_send` from the three config files above (or restore the
   `.bak-brainbox` backups if you'd made no other changes since).
2. `rm -rf ~/.brainbox`