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)

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

1. Pre hook scores the request via the heuristics above. Below threshold → no-op.
2. Lists archive blobs and reads the most recent one.
3. 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.
4. 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

src/modules/compaction-bridge.ts