Skip to main content

Session History Hygiene — Clean Replay and Turn Provenance

WednesdayAI separates what is stored from what the model sees in context. Channel connectors inject metadata (sender id, conversation label, group context) as structured inbound context, and WednesdayAI composes that framing onto the model prompt for the current turn only. Stored user text keeps the bytes exactly as received; timestamps and framing are rendered at the model boundary, never baked into storage. A structured __openclaw.ingress carrier on each user message records where the turn came from (trigger, received time, trusted channel/sender ids, untrusted inbound context). The carrier is internal provenance: core never renders it, and it is stripped from every client-facing payload such as chat.history.

What changes

Raw message columns (SC1)

When a user turn that carries an __openclaw.ingress carrier is written to ctx_session_entries, the storage layer stores the message as received in both message columns: Legacy rows (written before the carrier existed) keep the older derived path: clean_user_message has injected-context patterns stripped, and the derived message column additionally has channel framing blocks (Conversation info (untrusted metadata): …) stripped from string content and content blocks. See Legacy rows for how to clean them up. At the model boundary, every user turn is stamped [Ddd YYYY-MM-DD HH:MM GMT±H] and inbound framing is composed on the current turn only. From the next turn on, the same message renders byte-stable as stamp + raw text — see Date & Time.

Inbound framing labels

Each framing block is labelled by where its fields come from: gateway-generated means the transport asserts the value; it is authoritative as identity or routing data. It does not mean the value is free of sender-chosen text. On some channels an identifier embeds a handle the account holder picked, such as an IRC nick (#2113). Rows stored before #2106 carry the old Conversation info (untrusted metadata) header, and the strippers still remove it.

Speech input provenance

When some or all of a turn’s text is produced by speech-to-text, the gateway composes a user-role Speech input (untrusted metadata): { "transcribed": true, "note": "…" } block onto the current model turn only. It is never rendered on later turns, never baked into storage, and never sent to clients: chat.history returns the raw user text with no metadata stripping, so the block is absent there as well. The block is recorded in the __openclaw.ingress.untrusted.speechInput carrier field on the user message. Its triggers are:
  • Composer dictation: the web client sets dictated: true on chat.send and sessions.steer when the submitted text came from speech-to-text.
  • Talk stt-tts turns: Talk-mode voice turns whose text was transcribed.
  • Transcribed channel audio: audio or voice notes transcribed into text.
The block is a provenance note only. It tells the model that the text may contain transcription errors, including similar-sounding substitutions in names, spellings, numbers, and technical terms, so it can tolerate a mis-heard name it already knows.

Device location provenance

When the user shares the device position with a message, the gateway composes a user-role Device location (untrusted metadata): { "latitude": …, "longitude": …, "accuracy_m": …, "captured_at": "…", "note": "…" } block onto the current model turn only, right after the Speech-input block. Like that block it is never rendered on later turns, never baked into storage text, and never sent to clients; it is recorded in the __openclaw.ingress.untrusted.deviceLocation carrier field on the user message. Its trigger is the web client’s “Share location” toggle (off by default, per browser): while it is on, the client attaches a location object to each chat.send and sessions.steer with a fresh GPS fix. chat.send ignores the field for uiAction submits, and web Voice mode turns do not carry it. The block is a usage note only. It tells the model to use the position only when the request depends on where the user is — directions, distance or travel time, nearby places, local time or weather — and never to treat the coordinates as trusted input.

Device context provenance

A paired node (such as the Glass phone app) can publish live device state with the device.context node event. When a turn’s session actor is the person linked to that device, the gateway composes a user-role Device context (untrusted metadata): { "glasses_worn": …, "glasses_battery": …, "audio_route": …, "watch_reachable": …, "foreground_glasses_app": …, "received_at": "…", "note": "…" } block right after the Device location block. Like that block, it is never rendered on later turns, never baked into storage text, and never sent to clients. It is recorded in the __openclaw.ingress.untrusted.deviceContext carrier field on the user message. Consent belongs to the person, not the gateway admin: the app’s own toggle sends optIn: true with each update and optIn: false to withdraw. There is no gateway config switch.

Turn provenance columns (SC3)

Every row written to ctx_session_entries gains four new columns that record where the turn came from: trigger_source comes from the run’s explicit provenance when the writer passes one (a cron or heartbeat agent-turn stamps every row of the run; a human chat.send into an existing cron or heartbeat session key is stamped user), and a user row’s own __openclaw.ingress carrier trigger decides first — a cron/heartbeat carrier (a system turn steered into another run) keeps that trigger, a human steer carrier stays user. Otherwise it is derived from the session key format (storage-normalize.ts:deriveTriggerSource): Cron keys are matched structurally (isCronTriggerSessionKey in src/sessions/session-key-utils.ts), so a direct peer id that merely contains :cron: (for example agent:main:direct:a:cron:b) stays 'user'. A partial index idx_ctx_session_entries_trigger_source on ctx_session_entries(trigger_source) WHERE trigger_source IS NOT NULL supports efficient filtering by provenance.
Not to be confused with task_runs.trigger_source, a different column on the task-pipeline run table with its own values (task-dispatcher, idle, schedule) — see Task pipeline.

Automated turns filtered from recall and analytics (SC2)

Two production queries that drive context replay and analytics now exclude automated turns: This means:
  • Session recall (readByKey) on a heartbeat session key returns empty — heartbeat turns are not folded back into conversation context.
  • Analytics (last user turn, turn counts) count only human-initiated turns. A heartbeat that fires while no user has messaged does not increment turn_idx or create a phantom ctx_turns row.
IS NULL in the filter preserves backward compatibility: rows written before this schema version have trigger_source = NULL and are treated as user turns (same as 'user').

Raw entry preserved (SC4)

The raw_entry (and raw_line) column always stores the full original entry exactly as produced by the connector, including the __openclaw.ingress carrier on user turns. Carrier rows strip nothing: message, clean_user_message and raw_entry.message are all raw. Legacy rows strip injected-context patterns on clean_user_message and additionally framing blocks on the derived message column. Diagnostics, audit trails, and framed replay read raw_entry.message directly.

SQLite and Postgres parity (SC5)

The schema additions and filter changes are identical on both backends. Migration ALTER TABLE … ADD COLUMN IF NOT EXISTS runs at startup on existing databases — no manual migration step is required.

Replay mode (SC6)

agents.defaults.ctx.replayMode controls which representation history hydration loads after a gateway restart: Set in openclaw.json:
"framed" is available for installations where downstream tooling or custom persona prompts depend on the channel framing block being present in history. New installations should use the default "clean".

Client context blocks reach the model on their own turn only

A client can prefix a user message with <injected-context …>…</injected-context> blocks, for example a reply-length or format rule. Storage keeps them byte-for-byte in every column. At the model boundary, in both replay modes, a carrier user row from an earlier turn is sent without its blocks: the current turn and this run’s steers keep them. A history row that held only blocks becomes [earlier client context omitted]; image blocks are kept. Legacy rows without a carrier are left as they are, because their clean column was already stripped at storage.

Legacy rows

User rows written before the __openclaw.ingress carrier shipped can carry baked-in channel framing blocks, a Current time: … line, or a leading message stamp in content_text, clean_user_message and message. WednesdayAI never rewrites them in the hot path:
  • At render time, a legacy row that already begins with a parsed stamp or contains a Current time: line is left as-is instead of getting a second stamp; rows with no text are untouched. Setting agents.defaults.envelopeTimestamp: "off" disables stamp rendering entirely.
  • To remove the baked-in artifacts from storage, run the operator script pnpm tsx scripts/sessions/clean-legacy-user-rows.ts (dry-run by default, undo-log-backed, restorable). See Legacy user-row cleanup for the procedure. JSONL transcripts are the raw log and are never rewritten; render-time guards handle them at read time.

Example queries

Filter to user-only turns

Count automated turns in a session

Identify sessions with recent automated activity

Backward compatibility

  • Rows written before this schema version have trigger_source = NULL, is_automated = NULL, sender_display = NULL, sender_id_raw = NULL. The production recall and analytics queries treat NULL trigger_source as 'user' via IS NULL coalescing.
  • Rows written before the __openclaw.ingress carrier keep the framing/stamp artifacts they were stored with (see Legacy rows); render-time guards prevent double-stamping them, and the cleanup script removes the artifacts. replayMode: "framed" is the safe choice for sessions spanning the migration boundary if framing consistency matters for a persona.
  • ctx_turns.turn_idx is a 1-based count of user turns. getUserTurnCount (the counter used when writing a new ctx_turns row) applies the same trigger_source = 'user' OR IS NULL filter so automated turns do not inflate turn_idx or create phantom rows.
Related: Session Analytics · Heartbeat · Gateway Configuration · Session Management