Session Bridge

Session Bridge

Keep context coherent across surfaces (Telegram / WhatsApp / TUI) and agents (Eddie ↔ Jon ↔ Cipher ↔ Sage ↔ Picasso) using lightweight topic capsules — without syncing full transcripts or adding load to the memory system.

Core Concept

Each active work thread gets a capsule — a small JSON file keyed by topic:

tasks/bridges/
  looking-glass.json        ← Meta Ray-Ban project
  session-bridge-design.json ← This skill's design thread
  clawhub-skill-build.json  ← Active publishing task

Capsules hold only what matters: goal, status, decisions, open questions, next action. They are transient working state, not long-term memory. They do not replace MEMORY.md, daily logs, or the ontology graph — they sit on top as a coordination layer.

Script

SCRIPT=~/.openclaw/workspace/skills/session-bridge/scripts/bridge.py
python3 $SCRIPT <command> [options]

Commands

Create a capsule

python3 $SCRIPT create \
  --topic "looking-glass" \
  --goal "Wire Meta Ray-Bans as Eddie's physical presence" \
  --source "agent:main:telegram:direct:7550791652" \
  --agent main

Update a capsule (after decisions, handoffs, progress)

python3 $SCRIPT refresh \
  --topic "looking-glass" \
  --status "active" \
  --next-action "Mike to share Ray-Ban SDK access" \
  --add-decision "Use Bluetooth audio bridge, not USB" \
  --add-question "Does Ray-Ban SDK expose camera feed?" \
  --add-fact "Mike's Ray-Bans model: Meta Ray-Ban v2"

Get a briefing for session start (hydrate)

python3 $SCRIPT hydrate --topic "looking-glass"

Output (~150–350 tokens):

[Session Bridge] Topic: looking-glass
Status: active
Goal: Wire Meta Ray-Bans as Eddie's physical presence
Decisions: Use Bluetooth audio bridge, not USB
Open: Does Ray-Ban SDK expose camera feed?
Next: Mike to share Ray-Ban SDK access
Sources: agent:main:telegram:direct:7550791652
Updated: 2026-03-20T06:45Z

Cross-agent handoff

python3 $SCRIPT handoff \
  --topic "session-bridge-design" \
  --to "agent:main:telegram:direct:7550791652"

Then pass the output to sessions_send so Eddie wakes up informed.

See all active capsules

python3 $SCRIPT list
python3 $SCRIPT status --topic "looking-glass"

Clean up stale capsules

python3 $SCRIPT expire --max-age-hours 48

Bridging Surfaces (Telegram ↔ WhatsApp ↔ TUI)

Option A — Config routing (recommended first step)

Add identityLinks to openclaw.json to collapse the same human across surfaces into one canonical session per agent:

{
  "session": {
    "dmScope": "per-channel-peer",
    "identityLinks": [
      {
        "canonical": "mike",
        "peers": [
          "telegram:7550791652",
          "whatsapp:+15555550123"
        ]
      }
    ]
  }
}

This makes Telegram-Eddie and WhatsApp-Eddie share the same session — no bridging needed. TUI uses a different mechanism (main session key).

Option B — Capsule hydration on surface switch

When the same canonical session is not possible (TUI ↔ Telegram, or different agent entirely):

1. On the outgoing surface, refresh the relevant capsule:

   python3 $SCRIPT refresh --topic <topic> --next-action "..."
   

2. On the incoming surface, hydrate at session start:

   python3 $SCRIPT hydrate --topic <topic>
   

3. Inject the briefing as context before responding.

Bridging Agents (Jon → Eddie, Cipher → Eddie)

When finishing a delegation task, the completing agent should:

1. Refresh the capsule with results:

   python3 $SCRIPT refresh \
     --topic "<task-topic>" \
     --status "done" \
     --add-decision "Research complete: X is the right approach" \
     --next-action "Eddie to implement"
   

2. Generate a handoff and deliver via sessions_send:

   python3 $SCRIPT handoff --topic "<task-topic>" --to "agent:main:telegram:direct:7550791652"
   # Copy output → sessions_send(sessionKey="agent:main:...", message=<output>)
   

Eddie reads the brief and continues — no re-explaining needed.

What Goes Where

Capsules are not a replacement for memory — they are short-lived working state that gets discarded when a topic concludes.

Token Cost

Hydration adds <0.2% of a 200k context window per session. Stale capsules add zero cost (they're just files).

Agent Protocol (Team Rules)

• On delegation: create or refresh capsule before sessions_send-ing a task
• On completion: refresh capsule with outcome + next action, then handoff
• On surface switch: hydrate the relevant capsule at session start
• On topic close: set --status done, let expire cleanup handle it
• Never: dump full session transcripts into capsules (defeats the point)

Example: Full Cross-Agent Flow

Mike asks Eddie about the Looking Glass project.
Eddie doesn't remember details from last session.

1. Eddie runs: bridge.py hydrate --topic looking-glass
   → Gets: "Status: active | Next: Mike to share SDK access"
   → Continues conversation without re-explaining from scratch

Mike tells Eddie: "Let Jon research the Ray-Ban SDK."
Eddie creates a task capsule and delegates to Jon via sessions_send.

Jon finishes research.
2. Jon runs: bridge.py refresh --topic looking-glass \
     --add-decision "SDK exposes camera feed via BLE" \
     --next-action "Eddie to prototype BLE bridge"
3. Jon runs: bridge.py handoff --topic looking-glass \
     --to agent:main:telegram:direct:7550791652
4. Jon sends handoff output to Eddie via sessions_send.

Eddie receives handoff.
5. Eddie reads capsule brief, continues work without Jon re-explaining.

Setup

No dependencies beyond Python 3.8+. Works immediately after install:

openclaw skills install session-bridge
python3 ~/.openclaw/workspace/skills/session-bridge/scripts/bridge.py list