Summary

Add companion-friendly SQLite transcript/session seams on top of the new database-first runtime so advanced consumers can build on canonical runtime state without scraping opaque blobs or reimplementing internal branch/session logic.

Problem to solve

openclaw/openclaw#78595 is the right long-term direction for runtime state, but the current public read seam is still too narrow for serious downstream and internal consumers.

Today, advanced consumers can reach canonical SQLite transcript rows, but they still have to:

• parse opaque event/session blobs to recover useful read models
• scan session rows to resolve sessionId -> current logical session
• reimplement active-branch traversal and transcript frontier logic

That creates duplicated correctness risk exactly where OpenClaw is trying to get more reliable: transcript history, reset/rotation semantics, multi-entity session routing, and future database-backed tooling.

This is not hypothetical. The current runtime already contains private implementations of the logic advanced consumers need:

• transcript stats, append, replacement, and ordered load in transcript-store.sqlite.ts
• session family persistence via usageFamilyKey and usageFamilySessionIds in session.ts and agent-runner-session-reset.ts
• sessionId -> sessionKey ambiguity handling in session-id-resolution.ts and session-transcript-key.ts
• active-branch reconstruction in session-transcript-readers.ts

The gap is that these capabilities are mostly private implementation detail instead of a stable public companion seam.

Proposed solution

Add a small set of public, companion-safe seams on top of the database-first runtime:

1. A cursored SQLite transcript read API keyed by {agentId, sessionId} with frontier metadata.
2. Durable session lineage and sessionId discovery helpers across rotations/families.
3. Typed transcript projections/helpers for high-value read paths such as message_role, tool_call_id, and active-branch traversal, plus a documented rebuild contract for companion consumers.

Important boundary:

• keep OpenClaw as the canonical operational store
• keep companion-specific semantic stores outside core
• do not pull summary DAGs, recall indexes, or plugin-specific compaction bookkeeping into OpenClaw core

Concretely, this means:

• keep session_entries, transcript_events, transcript_event_identities, and transcript_snapshots as the canonical runtime data model
• expose just enough public read-side structure that advanced consumers do not need to import gateway internals or parse entry_json blindly
• document the supported rebuild path from populated SQLite state so runtime no longer implies JSONL compatibility

Alternatives considered

1. Leave companions to parse internal tables directly

This keeps core smaller in the short term, but every advanced consumer ends up duplicating fragile logic around branch walking, session lineage, and typed event extraction.

2. Add compatibility shims back to JSONL/session-file runtime

This would reduce short-term migration pressure for some consumers, but it would cut against the whole database-first goal and keep file-era identities alive in runtime paths.

3. Reshape OpenClaw core around one companion's schema

This would overfit the runtime store to a single downstream model and blur the boundary between canonical operational state and specialized semantic/read-side state.

Impact

Affected:

• future first-party memory/search/export/audit features
• advanced plugins and internal tools that need transcript/session reads
• operators on multi-entity or reset-heavy deployments

Severity:

• medium to high for maintainability and correctness

Frequency:

• always for any serious consumer that needs more than "load all events and figure it out yourself"

Consequence:

• duplicated parsing and lineage logic across consumers
• higher chance of correctness drift around session rotation and active-branch reads
• slower adoption of the new runtime as the only source of truth

Maintainer/platform value beyond LCM:

• future first-party memory, search, export, audit, and analytics features can reuse one public read seam
• multi-entity and reset-heavy deployments keep one canonical continuity policy
• companion and plugin authors stay on the supported SDK boundary instead of importing gateway internals
• operational tools can resume from a durable frontier without bespoke table archaeology

Evidence/examples

Relevant current surfaces in #78595:

• runtime contract is explicitly database-first and file-era identities are migration-only
• transcript rows are canonical, but the stable public read seam is still mostly full-load/full-replace
• active-branch traversal and sessionId -> sessionKey resolution already exist internally, which suggests a reusable public seam is possible

Representative code anchors:

• runtime contract: database-first.md
• session row schema: openclaw-agent-schema.sql
• transcript schema: openclaw-agent-schema.sql
• narrow public SDK exports today: session-store-runtime.ts

Initial follow-up slices that would address this cleanly:

• #79904 — [Feature]: Add cursored SQLite transcript read API for companion consumers
• #79903 — [Feature]: Expose durable session lineage and sessionId discovery across rotations
• #79905 — [Feature]: Add typed transcript projections and a documented companion rebuild contract

Acceptance criteria

• a consumer can resume transcript ingest by {agentId, sessionId} without full transcript reloads
• a consumer can resolve sessionId -> canonical session ownership and family continuity without scanning session-row blobs
• a consumer can obtain active-branch or branch-safe message traversal without copying gateway-private parent-walk logic
• a populated SQLite install has a documented, idempotent companion rebuild path that does not depend on legacy runtime JSONL files

Non-goals

• moving companion summary DAGs or recall indexes into OpenClaw core
• preserving JSONL as an equal runtime storage mode
• redesigning the canonical transcript schema around one companion's internal tables

Example consumer flows

1. Memory or audit companion:

• read new transcript rows after a known frontier
• resolve the active logical session family for a rotated sessionId
• persist its own normalized projections without reading raw session-row blobs

2. Export or search tool:

• request canonical branch-bounded transcript rows
• use typed helper data like tool_call_id or message_role
• resume from a durable frontier on the next run

Additional information

This request is deliberately not asking OpenClaw to absorb companion-specific memory models.

The goal is a cleaner public database-first boundary that benefits any future companion or internal consumer. Lossless Claw is one demanding consumer and a useful proof case, but these seams are broadly valuable even without that plugin.