Fix summarizer hot path: capture on SessionEnd, drain in background

[jamby77]

Problem

The Stop hook fires on every turn, so the plugin re-summarized the whole session on each response — burning minutes of local LLM time on a hook, blocking the turn, and discarding the work when the Ollama client timed out. The success path stored empty husks (SessionSummarySchema.parse({}) passes and yields "Session recorded — summary unavailable"). Net result over 8 days: one memory, and it was empty; after a GPU fix, near-duplicate memories appeared one-per-turn.

Change

• Capture on SessionEnd (fires once), not Stop (every turn) — with a migration that strips the stale Stop registration from existing installs.
• Queue-only capture hook — the hook parses the transcript, pushes to the existing ingest queue, spawns a detached drainer, and exits in milliseconds. No LLM ever runs on a hook.
• Reject empty summaries before they reach the store (isEmptySummary predicate); husks are dropped, not re-queued.
• Plus small fixes made while verifying: correct the stale Stop label in the install summary, fix an integration test that recalled by the wrong embed text, and gitignore .idea/.

Verification

bun run typecheck clean · bun test tests/unit green · bun test tests/integration green (against Valkey on 6390).

Stack

Bottom of a 2-PR stack. The follow-on #9 (checkpoint capture) builds directly on this branch — merge this one first.

---

Note

Medium Risk
Changes when and how session memories are captured (hook lifecycle + async drain); misconfiguration could leave transcripts queued until drain runs, but hooks no longer block on LLM calls.

Overview
Moves session memory capture off the per-turn Stop hook to SessionEnd, so summarization no longer runs on every assistant response or blocks the hook path.

The session-end hook now only parses the transcript, pushes to the Valkey ingest queue, and spawns a detached drain process (compiled binary or bun run source). AgingPipeline.processIngestQueue performs LLM summarization and storage. Install and register-hooks register SessionEnd instead of Stop, and stripLegacyBetterdbHooks removes stale Stop entries on upgrade without touching third-party hooks.

Adds isEmptySummary so default-schema “husks” are dropped from the ingest queue (not stored or re-queued). New betterdb-memory drain command and drain binary in the install set. Hook payload schema switches from StopPayload to SessionEndPayload.

^{Reviewed by Cursor Bugbot for commit 2e3e752. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 2e3e752. Configure here.}

[cursor]

Install omits dev hook markers

Medium Severity

betterdb-memory install calls stripLegacyBetterdbHooks with only the default betterdb marker, while register-hooks.ts also passes the plugin src/hooks path. A leftover Stop registration whose command path does not contain betterdb can survive install and keep firing the old per-turn hook alongside SessionEnd.

Additional Locations (1)

• scripts/register-hooks.ts#L69-L73

 

^{Reviewed by Cursor Bugbot for commit 2e3e752. Configure here.}

[KIvanow]

Approve. This fixes a real, costly bug — capture was on Stop (fires every turn), so the plugin re-summarized the whole session on every response and stored empty husks. The fix is sound: SessionEnd fires once, the hook does zero model work (queues transcript + spawns a detached unref()'d drainer), and isEmptySummary correctly distinguishes an all-defaults husk from a real summary — every SessionSummarySchema field has a .default(), so {} parses as valid and the predicate is the only thing that can tell them apart. Husks are dropped, not re-queued (no infinite loop). The stacked commits also show careful verification (Windows USERPROFILE fallback; binary-vs-source drain resolution so the dev path isn't silently skipped).

Verified locally: bun run typecheck clean · bun test tests/unit 164/164 green.

Two non-blocking nits:

• src/hooks/drain.ts + src/index.ts runDrain() — these are near-identical copies of the same pipeline wiring (client + model + store + processIngestQueue). Worth collapsing into one shared helper so the two don't drift.
• src/index.ts (formatting) — a large share of the +676 is Prettier reflow of untouched code, which makes the meaningful change harder to isolate in review. Not wrong, just flagging that bundling a formatting pass with a behavior change inflates the diff.

Pre-existing bug worth a fast-follow (not introduced here, but #9 raises its blast radius):

• src/memory/aging.ts processIngestQueue (catch → break) — popIngestQueue(20) pulls up to 20 items into memory; on the first summarizer failure only the failing item is re-queued and the loop breaks, silently dropping every already-popped item after it. Once #9's segmented capture lands, a long session enqueues many segments, so one transient Ollama hiccup mid-drain discards the rest of that session. (The re-queue also rpushes to the tail, reordering segments — cosmetic, since each becomes an independent memory.) Suggest re-queuing the remaining unpopped items on failure, or switching to pop-one-process-one.