​

Session History Hygiene — Clean Replay and Turn Provenance

​

What changes

​

Clean message column (SC1)

​

Turn provenance columns (SC3)

​

Automated turns filtered from recall and analytics (SC2)

• 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.

​

Raw entry preserved (SC4)

​

SQLite and Postgres parity (SC5)

​

Replay mode (SC6)

{
  agents: {
    defaults: {
      ctx: {
        replayMode: "clean", // default; set "framed" to restore legacy behavior
      },
    },
  },
}

​

Example queries

​

Filter to user-only turns

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

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

-- 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.
• The message column for legacy rows may contain framing if it was written before the strip logic existed. 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.