`compaction-bridge`

Category: context · Cloud + Local · Status: v1.0 — production

Detects when an upstream client (Claude Code, Cursor, etc.) has just triggered its own context-compaction and is sending what looks like a brand new conversation. Re-injects the most relevant pieces of the most recent eviction archive: last N turns, active files, recent decisions, and surviving directives.

When to use it

Running Claude Code or any client that auto-compacts.
Long-running agent sessions where compaction kills momentum.
Workflows with stateful directives that must survive context resets.

Dependency on `ipc`

Reads from evictions/{user_id}/* — populated by ipc in cloud mode. If no archive exists, the module is a clean no-op. Pair with patterns for the richest recovery (patterns persist across sessions; compaction-bridge restores the in-flight state).

Configuration


compaction-bridge:
  preserveLastTurns: 5         # last N archived turns to re-inject
  preserveActiveFiles: true    # extract and re-inject file paths from the archive
  preserveDirectives: true     # extract surviving "always/never/prefer/avoid" rules
  detectionThreshold: 0.6      # confidence (0-1) before injecting; 0.6 is conservative
  blobPrefix: 'evictions'

All fields are optional. Defaults shown.

Detection signals (combined into a 0-1 score)

Signal	Weight
≤ 2 messages in the request	+0.4
User content matches a continuation marker (`continuing from where we left off`, etc.)	+0.5
Short system prompt (< 200 chars) AND user references prior work (file paths, “the fix”, etc.)	+0.3

The score is capped at 1. Default detectionThreshold is 0.6 — so either a continuation marker on its own (0.5 + 0.4 from short message count = 0.9) or short-msg + prior-work references (0.4 + 0.3 = 0.7) crosses the bar.

Metrics emitted

compaction-bridge.recovered (boolean) — was a recovery block injected?
compaction-bridge.confidence (number) — the detection score.
compaction-bridge.source_blob (string) — which archive was used.
compaction-bridge.turns_restored (number)
compaction-bridge.files_restored (number)
compaction-bridge.decisions_restored (number)
compaction-bridge.directives_restored (number)

How it works

Pre hook scores the request via the heuristics above. Below threshold → no-op.
Lists archive blobs and reads the most recent one.
Extracts:
- Last N turns — verbatim from the archive’s messages[].
- Active files — regex-matches file paths (src/foo.ts, apps/web/page.tsx, etc.) from the archive content.
- Decisions — heuristic match on the fix is, the issue was, we decided, next step, to fix this in assistant turns.
- Directives — regex-matches always, never, prefer, avoid, must, should, do not, don't in any turn.
Builds a <compaction-bridge-recovery> block and prepends it to the system prompt.

Pipeline placement

Run before patterns (which can then build on the recovered state):


PRXY_PIPE=ipc,compaction-bridge,rehydrator,patterns,semantic-cache

compaction-bridge and rehydrator complement each other: compaction-bridge fires on detected continuations (broad recovery), rehydrator fires on explicit user references (targeted recovery). Both writing to the system prompt is fine — the model treats them as separate context blocks.

Source

packages/modules-core/src/compaction-bridge.ts

compaction-bridge