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:

text

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#

bash

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

---

Commands#

Create a capsule#

bash

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)#

bash

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)#

bash

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

Output (~150–350 tokens):

text

[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#

bash

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#

bash

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

Clean up stale capsules#

bash

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:

json

{
  "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: bash

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

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

   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: bash

   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: bash

   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#

Information typeWhere it livesCurrent topic, status, next actionCapsule (transient, expires)Decisions worth keeping long-termMEMORY.md (promote manually)Structured facts (people, devices, projects)Ontology graphNarrative context / observationsDaily memory logTeam operating rulesSHARED_CONTEXT.md

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

---

Token Cost#

OperationApprox. tokensWhenCreate/refresh capsule150On handoff or decisionHydrate (session start briefing)200–350Once per sessionHandoff message300Cross-agent delegationStatus/list100On demand

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#

text

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:

bash

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