[FEATURE] Session Bridge - Structured Context Preservation for Long-Running Agent Sessions

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

I run daily multi-hour Claude Code sessions (4+ hours) across multiple projects over weeks and months. Compaction keeps individual sessions alive, but it's lossy for cross-session continuity:

• Decisions and their reasoning get flattened into summaries that lose the "why"
• Artifacts created during a session aren't tracked with full paths and context
• Knowledge discovered gets dumped into a flat MEMORY.md with no organization
• Cross-session continuity relies on --resume (only the immediate next session) or manual dev-docs patterns

Co-work has this more acutely: context resets between tasks by design, so scheduled routines start cold every time.

The longer you use Claude Code, the more this matters. A single afternoon session is fine. Daily 4-hour sessions over months? Compaction loses the thread.

The core issue: Compaction is compression. What's needed is preservation.

Compaction asks "what can I forget?" But long-lived agents need to ask "where does this knowledge live permanently?"

Proposed Solution

Session Bridge — a two-layer pattern that preserves and routes context before a session resets:

Layer 1: Handoff (Lossless Preservation)

Before a session resets, the agent captures a structured snapshot of what happened, what was decided, what was created, and what's in progress. Written to durable storage (daily log files). Nothing is lost.

Layer 2: Structured Routing (Handoff++)

Session Bridge extends Handoff by categorizing and routing context to appropriate permanent locations:

| Category | Destination | Why |
|----------|-------------|-----|
| Decisions + reasoning | Project docs / decision logs | Retrievable by project, not buried in a dump |
| Artifacts created | Referenced with full paths | Future sessions can load specific files |
| Knowledge / insights | Topic-specific memory files | Organized by domain, not chronology |
| Active work-in-progress | Handoff summary for next session | "What does the next session need in the first 30 seconds?" |

Integration Points

• PreCompact hook — Run Session Bridge before compaction fires. Bridged context persists; compressed context still works intra-session.
• SessionEnd hook — On manual end or timeout, bridge fires.
• PostTask hook (Co-work) — After task completion, extract learnings before context resets.
• TaskStart injection (Co-work) — On scheduled task start, load relevant bridges from previous runs.

Trigger Timing

• 80-85% context usage — enough tokens remaining to perform extraction well
• Never mid-tool-loop — wait for a clean conversational boundary
• On topic switch or end-of-work signals — natural session boundaries

Why Both Layers Matter

• Handoff without routing = lossless but unorganized (a journal with no index)
• Routing without handoff = organized but lossy (an index to a book you threw away)
• Session Bridge (both) = lossless AND organized. Nothing lost, everything findable.

Enables Downstream Memory Systems

Session Bridge (preserves) → Daily Logs (accumulate) → Memory Consolidation (synthesizes)

Without Session Bridge, Dreaming can only work with what's in MEMORY.md. With Session Bridge, it has access to the full history and can extract insights across weeks of context.

Alternative Solutions

I've tried and compared these approaches:

| Approach | Weakness |
|----------|----------|
| MEMORY.md auto-memory | Unstructured; grows into a dump over weeks |
| --resume / --continue | Only works for the immediately next session |
| CLAUDE.md system prompt | Static instructions, not dynamic knowledge |
| Dev docs pattern (plan.md, context.md) | Manual; user must remember to update |

Session Bridge is the automated, structured alternative — preservation with routing, not compression without structure.

Priority

High - Significant impact on productivity

Feature Category

Other

Use Case Example

Example scenario:

1. I'm building an agent harness with memory, tools, and multi-channel support (terminal, web, mobile)
2. I work 4-hour sessions daily. By hour 3, context is at 80%+
3. Without Session Bridge: compaction fires, I lose the reasoning behind decisions made in hour 1. Next day I rediscover the same dead ends.
4. With Session Bridge: at 80%, the system automatically extracts decisions → project docs, knowledge → memory files, artifacts → tracked with paths, active work → handoff summary
5. Next session loads only the relevant handoff + memory. I'm productive in 30 seconds, not 10 minutes of re-orientation.
6. Over weeks, the accumulated daily logs become the corpus for memory consolidation (Dreaming) — enabling insights ACROSS sessions that no single compaction could produce.

Additional Context

Validation: Built and running in production since April 2026 in a personal AI agent harness using Claude Code. Daily multi-hour sessions across terminal, web, and mobile channels.

Key findings from 7+ weeks of production use:

• Categorization quality matters more than completeness
• The handoff summary should be opinionated ("what does the next session need in 30 seconds?")
• Trigger at 80-85%, not 90%+ (needs token budget to extract well)
• Safe-point awareness prevents tool-loop corruption
• Routed daily logs become the foundation for memory consolidation

Timeline:

• April 9, 2026 — First implementation committed
• April 15 — Mid-tool-loop handoff added (edge case handling)
• May 1 — Hardened for production
• May 5 — Public release: github.com/monbishnoi/cal (v1.0.0)

Reference implementation: https://github.com/monbishnoi/cal