> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Session History Hygiene — Clean Replay and Turn Provenance

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

| Column / field | Contains |
| - | - |
| `message` | The raw message, exactly as received — no framing blocks, no timestamp stamp, no injected-context stripping |
| `clean_user_message` | The same raw message (pristine by contract) |
| `raw_entry.message` | The original entry exactly as produced, including the `__openclaw.ingress` carrier |

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](#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](https://docs.wednesdayai.dev/next/users/date-time.md).

### Inbound framing labels

Each framing block is labelled by where its fields come from:

| Block | Label | Fields |
| - | - | - |
| `## Inbound Context` (system prompt, byte-stable per session) | `gateway-generated` | `chat_id`, `account_id`, `channel`, `provider`, `surface`, `chat_type` |
| `Conversation info` (current user turn) | `gateway-generated` | `message_id`, `reply_to_id`, `sender_id`, `timestamp`, `topic_id`, and flags such as `is_group_chat`, `was_mentioned`, `has_reply_context` and `history_count` |
| `Conversation context` (current user turn) | `untrusted metadata` | `conversation_label`, `sender`, `group_subject`, `group_channel`, `group_space`, `thread_label` |
| `Sender`, `Replied message`, `Forwarded message context`, `Chat history since last reply`, `Thread starter` | `untrusted` | sender-chosen names, quoted bodies and history |

`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](https://github.com/ExpansionX/WednesdayAI-core/issues/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:

| Column | Type | Meaning |
| - | - | - |
| `trigger_source` | TEXT | Who triggered this turn: `'user'`, `'heartbeat'`, `'cron'`, `'subagent'`, `'acp'` |
| `is_automated` | BOOLEAN | `1` when the turn was not initiated by a human (`trigger_source != 'user'`) |
| `sender_display` | TEXT | Human-readable sender name — from the `__openclaw.ingress` carrier when present, else best-effort from message text |
| `sender_id_raw` | TEXT | Raw provider-level sender id (e.g. Telegram user id, Discord snowflake) — from the carrier when present, else best-effort |

`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`):

| Pattern | Example key | `trigger_source` |
| - | - | - |
| Explicit system run (cron/nudge/work/announce agent-turns stamp `heartbeat`/`cron`) | `agent:main:main` | `'heartbeat'` or `'cron'` |
| Key suffix `:heartbeat` | `telegram:direct:abc:heartbeat` | `'heartbeat'` |
| Isolated cron key (`cron:` prefix or `agent:<id>:cron:<uuid>`, incl. `:run:` variants) | `agent:main:cron:1c70aabc` | `'cron'` |
| Key segment `:subagent:` (UUID-suffixed) | `agent:main:subagent:f47ac10b-…` | `'subagent'` |
| Key segment `:acp:` (UUID-suffixed) | `agent:main:acp:f47ac10b-…` | `'acp'` |
| All other keys | `telegram:direct:abc123` | `'user'` |

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](https://docs.wednesdayai.dev/next/developers/concepts/tasks).

### Automated turns filtered from recall and analytics (SC2)

Two production queries that drive context replay and analytics now exclude automated turns:

| Query / operation | Filter applied |
| - | - |
| `SELECT_CTX_LAST_USER_ENTRY_SQL` (last user turn for analytics) | `AND (trigger_source = 'user' OR trigger_source IS NULL)` |
| `SELECT_CTX_BY_KEY_SQL` (`readByKey`, session recall) | `AND (trigger_source = 'user' OR trigger_source IS NULL)` |

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:

| Value | Default | Behavior |
| - | - | - |
| `"clean"` | ✓ | Model history replays the stored `message` column — raw text for carrier rows, framing-stripped text for legacy rows |
| `"framed"` | | Model history replays `raw_entry.message` verbatim — framing blocks and carrier included (backward compatibility, diagnostics) |

Set in `openclaw.json`:

```json5 theme={"dark"}
{
  agents: {
    defaults: {
      ctx: {
        replayMode: "clean", // default; set "framed" to restore legacy behavior
      },
    },
  },
}
```

`"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](https://docs.wednesdayai.dev/next/admin/gateway/session-storage-recovery#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

```sql theme={"dark"}
-- SQLite: last real user message in a session (heartbeat rows excluded)
SELECT *
FROM ctx_session_entries
WHERE session_id = ?
  AND role = 'user'
  AND entry_type = 'message'
  AND (trigger_source = 'user' OR trigger_source IS NULL)
ORDER BY seq DESC
LIMIT 1;

-- Postgres
SELECT *
FROM ctx_session_entries
WHERE session_id = $1
  AND role = 'user'
  AND entry_type = 'message'
  AND (trigger_source = 'user' OR trigger_source IS NULL)
ORDER BY seq DESC
LIMIT 1;
```

### Count automated turns in a session

```sql theme={"dark"}
-- SQLite: how many heartbeat turns has this session accumulated?
SELECT COUNT(*) AS heartbeat_count
FROM ctx_session_entries
WHERE session_id = ?
  AND trigger_source = 'heartbeat';
```

### Identify sessions with recent automated activity

```sql theme={"dark"}
-- SQLite: sessions with heartbeat or cron turns in the last 24 hours
SELECT DISTINCT session_id, trigger_source, MAX(created_at) AS last_automated
FROM ctx_session_entries
WHERE is_automated = 1
  AND created_at >= datetime('now', '-1 day')
GROUP BY session_id, trigger_source;
```

## 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](#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](https://docs.wednesdayai.dev/next/developers/concepts/session-analytics.md) · [Heartbeat](https://docs.wednesdayai.dev/next/admin/gateway/heartbeat.md) · [Gateway Configuration](https://docs.wednesdayai.dev/next/admin/gateway/configuration.md) · [Session Management](https://docs.wednesdayai.dev/next/developers/concepts/session.md)*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.