clementine-agent 1.18.27 → 1.18.28

package/dist/cli/dashboard.js

@@ -7044,6 +7044,35 @@ If the tool returns nothing or errors, return an empty array \`[]\`.`,
             res.status(500).json({ error: String(err) });
         }
     });
+    // Recent episodes — durable consolidated session summaries.
+    app.get('/api/memory/episodes', async (req, res) => {
+        try {
+            const gateway = await getGateway();
+            const store = gateway.assistant?.memoryStore;
+            if (!store || typeof store.listRecentEpisodes !== 'function') {
+                res.status(503).json({ error: 'Episodes store not available' });
+                return;
+            }
+            const limit = Math.min(parseInt(String(req.query.limit ?? '30'), 10) || 30, 200);
+            const sessionKey = req.query.session ? String(req.query.session) : undefined;
+            const sinceParam = req.query.since ? String(req.query.since) : '';
+            // since: '24h' | '7d' | '30d' | '' (all) | ISO string
+            let sinceIso;
+            if (sinceParam === '24h')
+                sinceIso = new Date(Date.now() - 24 * 3600_000).toISOString();
+            else if (sinceParam === '7d')
+                sinceIso = new Date(Date.now() - 7 * 24 * 3600_000).toISOString();
+            else if (sinceParam === '30d')
+                sinceIso = new Date(Date.now() - 30 * 24 * 3600_000).toISOString();
+            else if (sinceParam)
+                sinceIso = sinceParam;
+            const episodes = store.listRecentEpisodes({ limit, sessionKey, sinceIso });
+            res.json({ ok: true, episodes });
+        }
+        catch (err) {
+            res.status(500).json({ error: String(err) });
+        }
+    });
     // Coverage + recall telemetry for both chunks and transcripts. Powers the
     // Memory Coverage card showing whether dense recall is actually earning its
     // keep on the current corpus.
@@ -14998,6 +15027,23 @@ if('serviceWorker' in navigator){navigator.serviceWorker.getRegistrations().then
                 <div class="skel-block" style="padding:14px"><div class="skel-row med"></div><div class="skel-row short"></div></div>
               </div>
             </div>
+            <div class="card" style="margin-bottom:14px">
+              <div class="card-header" style="display:flex;align-items:center;justify-content:space-between;gap:8px;flex-wrap:wrap">
+                <span>Recent episodes</span>
+                <div style="display:flex;align-items:center;gap:8px">
+                  <select id="episodes-filter-since" onchange="refreshRecentEpisodes()" style="font-size:12px;padding:4px 6px;border:1px solid var(--border);border-radius:4px;background:var(--bg-input);color:var(--text)">
+                    <option value="24h">Last 24h</option>
+                    <option value="7d" selected>Last 7d</option>
+                    <option value="30d">Last 30d</option>
+                    <option value="">All</option>
+                  </select>
+                  <span style="font-size:11px;color:var(--text-muted)">Consolidated session summaries</span>
+                </div>
+              </div>
+              <div class="card-body" id="panel-recent-episodes" style="padding:0">
+                <div class="skel-block" style="padding:14px"><div class="skel-row med"></div><div class="skel-row short"></div></div>
+              </div>
+            </div>
             <div class="card">
               <div class="card-header" style="display:flex;align-items:center;justify-content:space-between">
                 <span>Self-correction (supersedes)</span>
@@ -18508,6 +18554,7 @@ function switchTab(group, tab) {
       // Consolidated Memory tab: search results + stats + MEMORY.md + recent writes + supersedes + coverage strip.
       refreshMemory();
       if (typeof refreshRecentWrites === 'function') refreshRecentWrites();
+      if (typeof refreshRecentEpisodes === 'function') refreshRecentEpisodes();
       if (typeof refreshSupersedes === 'function') refreshSupersedes();
       if (typeof refreshCoverageStrip === 'function') refreshCoverageStrip();
     }
@@ -24865,6 +24912,7 @@ async function submitQuickAddMemory() {
     setTimeout(function() {
       closeQuickAddMemory();
       if (typeof refreshRecentWrites === 'function') refreshRecentWrites();
+      if (typeof refreshRecentEpisodes === 'function') refreshRecentEpisodes();
       if (typeof refreshMemory === 'function') refreshMemory();
     }, 600);
   } catch (err) {
@@ -25018,6 +25066,55 @@ async function refreshRecentWrites() {
   }
 }
 
+async function refreshRecentEpisodes() {
+  var el = document.getElementById('panel-recent-episodes');
+  if (!el) return;
+  try {
+    var sel = document.getElementById('episodes-filter-since');
+    var since = sel ? sel.value : '7d';
+    var url = '/api/memory/episodes?limit=30' + (since ? '&since=' + encodeURIComponent(since) : '');
+    var r = await apiFetch(url);
+    var d = await r.json();
+    if (!d.ok || !Array.isArray(d.episodes)) {
+      el.innerHTML = '<div class="empty-state" style="padding:14px">' + esc(d.error || 'No data') + '</div>';
+      return;
+    }
+    if (d.episodes.length === 0) {
+      el.innerHTML = '<div class="empty-state" style="padding:14px">No episodes yet. They land automatically when a session has been idle for ~20 min with at least 3 exchanges.</div>';
+      return;
+    }
+    var html = '<table class="data-table" style="width:100%">';
+    html += '<thead><tr>'
+      + '<th style="width:120px">When</th>'
+      + '<th style="width:160px">Session</th>'
+      + '<th>Summary</th>'
+      + '<th style="width:140px">Topics</th>'
+      + '<th style="width:120px">Outcome</th>'
+      + '<th style="width:50px;text-align:right">Open</th>'
+      + '</tr></thead><tbody>';
+    for (var i = 0; i < d.episodes.length; i++) {
+      var ep = d.episodes[i];
+      var when = '';
+      try { when = new Date(ep.createdAt + 'Z').toLocaleString(); } catch { when = ep.createdAt; }
+      var topics = (ep.topics || []).slice(0, 3).map(esc).join(', ');
+      var openCount = (ep.openLoops || []).length;
+      var openColor = openCount > 0 ? '#f59e0b' : 'var(--text-muted)';
+      html += '<tr>'
+        + '<td style="font-size:11px;color:var(--text-muted)">' + esc(when) + '</td>'
+        + '<td style="font-size:11px">' + esc(ep.sessionKey) + '</td>'
+        + '<td style="font-size:12px">' + esc(ep.summary) + '</td>'
+        + '<td style="font-size:11px;color:var(--text-muted)">' + (topics || '—') + '</td>'
+        + '<td style="font-size:11px">' + esc(ep.outcome || '—') + '</td>'
+        + '<td style="text-align:right;font-weight:600;color:' + openColor + '">' + openCount + '</td>'
+        + '</tr>';
+    }
+    html += '</tbody></table>';
+    el.innerHTML = html;
+  } catch (err) {
+    el.innerHTML = '<div class="empty-state" style="padding:14px">Failed to load: ' + esc(String(err)) + '</div>';
+  }
+}
+
 async function memoryHealthAction(action, extra) {
   var labels = { 'janitor': 'cleanup', 'rebuild-fts': 'FTS rebuild', 'fix-orphans': 'orphan fix', 'install-dense-model': 'local embedding model install/verify', 'reembed-dense': 'dense embedding backfill' };
   if (!confirm('Run ' + (labels[action] || action) + ' now?')) return;

package/dist/gateway/episodic-consolidation.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Episodic consolidation — turn raw transcript ranges into durable, indexed
+ * episodes that hybrid recall can surface across sessions.
+ *
+ * Why not just keep transcripts? Transcripts are noisy and minute-grained.
+ * "What did we decide about auth?" should match a clean summary of the
+ * decision, not the eight messages where we worked toward it. Episodes
+ * compress a session range into {summary, topics, entities, outcome,
+ * openLoops}, persist that to the episodes table, and also write the
+ * summary into chunks so PR-1's hybrid recall picks them up automatically.
+ *
+ * The pass is driven by the heartbeat: every few minutes we look for
+ * sessions that have been idle for ≥20 min with ≥3 new exchanges and
+ * consolidate up to a small bounded number per pass to keep LLM cost
+ * predictable.
+ */
+import Anthropic from '@anthropic-ai/sdk';
+import type { MemoryStore } from '../memory/store.js';
+export interface EpisodicConsolidationOptions {
+    /** Minutes of inactivity before a session becomes consolidation-eligible. */
+    idleMinutes?: number;
+    /** Minimum turns since last cursor for a session to qualify. */
+    minExchanges?: number;
+    /** Cap LLM calls per pass to bound cost. */
+    maxSessionsPerPass?: number;
+    /** How long to back off after a consolidation failure for a session. */
+    failBackoffMinutes?: number;
+    /** Override Anthropic client (used by tests). */
+    anthropicClient?: Pick<Anthropic, 'messages'>;
+    /** Override the model id (used by tests). */
+    model?: string;
+    /** Wallclock now() — used by tests for deterministic timestamps. */
+    now?: () => Date;
+}
+export interface EpisodeExtraction {
+    summary: string;
+    topics: string[];
+    entities: string[];
+    outcome: string;
+    openLoops: string[];
+}
+interface CandidateRow {
+    sessionKey: string;
+    startTranscriptId: number;
+    endTranscriptId: number;
+    startedAt: string;
+    endedAt: string;
+    exchanges: number;
+}
+export interface ConsolidationPassResult {
+    consolidated: number;
+    failed: number;
+    skipped: number;
+    candidates: number;
+}
+/** Parse the model's output as JSON, tolerating leading/trailing whitespace and
+ *  occasional code fences. Returns null on any structural problem. */
+export declare function parseEpisodeJson(raw: string): EpisodeExtraction | null;
+/**
+ * Consolidate a single candidate session range. Returns the new episode id
+ * + chunk id on success, or null on failure (the caller bumps the failure
+ * cursor so we don't retry every tick).
+ */
+export declare function consolidateOneSession(store: MemoryStore, candidate: CandidateRow, opts?: EpisodicConsolidationOptions): Promise<{
+    episodeId: number;
+    chunkId: number | null;
+} | null>;
+/**
+ * Run one bounded consolidation pass. Designed to be called from the
+ * heartbeat tick — quick to no-op when nothing's eligible, capped at
+ * `maxSessionsPerPass` LLM calls when work exists.
+ */
+export declare function runEpisodicConsolidationPass(store: MemoryStore, opts?: EpisodicConsolidationOptions): Promise<ConsolidationPassResult>;
+export {};
+//# sourceMappingURL=episodic-consolidation.d.ts.map

package/dist/gateway/episodic-consolidation.js

@@ -0,0 +1,205 @@
+/**
+ * Episodic consolidation — turn raw transcript ranges into durable, indexed
+ * episodes that hybrid recall can surface across sessions.
+ *
+ * Why not just keep transcripts? Transcripts are noisy and minute-grained.
+ * "What did we decide about auth?" should match a clean summary of the
+ * decision, not the eight messages where we worked toward it. Episodes
+ * compress a session range into {summary, topics, entities, outcome,
+ * openLoops}, persist that to the episodes table, and also write the
+ * summary into chunks so PR-1's hybrid recall picks them up automatically.
+ *
+ * The pass is driven by the heartbeat: every few minutes we look for
+ * sessions that have been idle for ≥20 min with ≥3 new exchanges and
+ * consolidate up to a small bounded number per pass to keep LLM cost
+ * predictable.
+ */
+import Anthropic from '@anthropic-ai/sdk';
+import pino from 'pino';
+import { MODELS } from '../config.js';
+const logger = pino({
+    name: 'clementine.episodic-consolidation',
+    level: process.env.CLEMENTINE_CONSOLIDATION_LOG_LEVEL || 'warn',
+});
+const SYSTEM_PROMPT = [
+    'You are a memory consolidator for a personal AI assistant.',
+    'You read a transcript range and produce a compact, durable record of what happened.',
+    'Output STRICT JSON matching the schema, with no prose, no markdown, no code fences.',
+    'Schema:',
+    '{',
+    '  "summary": string (2-4 sentences, neutral, factual),',
+    '  "topics": string[] (lowercase noun phrases, max 6),',
+    '  "entities": string[] (named things: files, services, people; max 8),',
+    '  "outcome": string (one short clause: decided / implemented / discussed / blocked / none),',
+    '  "openLoops": string[] (unresolved follow-ups; empty array if none, max 5)',
+    '}',
+].join('\n');
+function buildUserPrompt(turns) {
+    const formatted = turns
+        .map(t => `[${t.createdAt}] ${t.role}: ${t.content.replace(/\s+/g, ' ').slice(0, 1200)}`)
+        .join('\n');
+    return [
+        'Consolidate the following conversation range into the JSON schema described.',
+        'Only include facts present in the conversation. Use empty arrays for unknown fields.',
+        '',
+        formatted,
+    ].join('\n');
+}
+/** Parse the model's output as JSON, tolerating leading/trailing whitespace and
+ *  occasional code fences. Returns null on any structural problem. */
+export function parseEpisodeJson(raw) {
+    if (!raw)
+        return null;
+    let text = raw.trim();
+    if (text.startsWith('```')) {
+        // Strip fence; keep everything between first and last triple-backtick.
+        const m = text.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
+        if (m)
+            text = m[1];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    const obj = parsed;
+    const arr = (v) => Array.isArray(v) ? v.filter(x => typeof x === 'string').map(s => s.trim()).filter(Boolean) : [];
+    const summary = typeof obj.summary === 'string' ? obj.summary.trim() : '';
+    if (!summary)
+        return null;
+    return {
+        summary,
+        topics: arr(obj.topics).slice(0, 6),
+        entities: arr(obj.entities).slice(0, 8),
+        outcome: typeof obj.outcome === 'string' ? obj.outcome.trim().slice(0, 200) : '',
+        openLoops: arr(obj.openLoops).slice(0, 5),
+    };
+}
+function getAnthropicClient(opts) {
+    if (opts.anthropicClient)
+        return opts.anthropicClient;
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey)
+        return null;
+    return new Anthropic({ apiKey });
+}
+/**
+ * Consolidate a single candidate session range. Returns the new episode id
+ * + chunk id on success, or null on failure (the caller bumps the failure
+ * cursor so we don't retry every tick).
+ */
+export async function consolidateOneSession(store, candidate, opts = {}) {
+    const turns = store.getTranscriptsByIdRange(candidate.sessionKey, candidate.startTranscriptId, candidate.endTranscriptId);
+    if (turns.length === 0)
+        return null;
+    const client = getAnthropicClient(opts);
+    if (!client) {
+        logger.debug({ sessionKey: candidate.sessionKey }, 'No Anthropic client available — skipping consolidation');
+        return null;
+    }
+    let extraction = null;
+    try {
+        const response = await client.messages.create({
+            model: opts.model ?? MODELS.haiku,
+            max_tokens: 1024,
+            system: SYSTEM_PROMPT,
+            messages: [{ role: 'user', content: buildUserPrompt(turns.map(t => ({ role: t.role, content: t.content, createdAt: t.createdAt }))) }],
+        });
+        const text = (response.content ?? []).map((b) => b.type === 'text' ? (b.text ?? '') : '').join('');
+        extraction = parseEpisodeJson(text);
+    }
+    catch (err) {
+        logger.warn({ err, sessionKey: candidate.sessionKey }, 'Episode LLM call failed');
+        return null;
+    }
+    if (!extraction) {
+        logger.warn({ sessionKey: candidate.sessionKey }, 'Episode JSON parse failed — skipping');
+        return null;
+    }
+    // Index the summary into chunks so hybrid recall surfaces it. The
+    // source_file shape mirrors how internal-derived chunks are stored
+    // elsewhere; section is the session key for traceability.
+    let chunkId = null;
+    try {
+        chunkId = store.insertSummaryChunk(`episodes/${candidate.sessionKey}.md`, `Episode ${candidate.startedAt}`, [
+            extraction.summary,
+            extraction.topics.length ? `Topics: ${extraction.topics.join(', ')}` : '',
+            extraction.entities.length ? `Entities: ${extraction.entities.join(', ')}` : '',
+            extraction.outcome ? `Outcome: ${extraction.outcome}` : '',
+            extraction.openLoops.length ? `Open: ${extraction.openLoops.join('; ')}` : '',
+        ].filter(Boolean).join('\n'));
+    }
+    catch (err) {
+        logger.debug({ err }, 'insertSummaryChunk failed — episode still persisted');
+    }
+    const transcriptIds = turns.map(t => t.id ?? 0).filter(n => n > 0);
+    const insert = store.insertEpisode({
+        sessionKey: candidate.sessionKey,
+        startedAt: candidate.startedAt,
+        endedAt: candidate.endedAt,
+        summary: extraction.summary,
+        topics: extraction.topics,
+        entities: extraction.entities,
+        outcome: extraction.outcome,
+        openLoops: extraction.openLoops,
+        transcriptIds,
+        chunkId,
+    });
+    store.updateConsolidationCursor(candidate.sessionKey, {
+        lastTranscriptId: candidate.endTranscriptId,
+        success: true,
+    });
+    logger.info({
+        sessionKey: candidate.sessionKey,
+        episodeId: insert.episodeId,
+        chunkId,
+        turns: turns.length,
+    }, 'Consolidated episode');
+    return { episodeId: insert.episodeId, chunkId };
+}
+/**
+ * Run one bounded consolidation pass. Designed to be called from the
+ * heartbeat tick — quick to no-op when nothing's eligible, capped at
+ * `maxSessionsPerPass` LLM calls when work exists.
+ */
+export async function runEpisodicConsolidationPass(store, opts = {}) {
+    const idleMinutes = opts.idleMinutes ?? 20;
+    const minExchanges = opts.minExchanges ?? 3;
+    const maxSessions = Math.max(1, opts.maxSessionsPerPass ?? 3);
+    const failBackoffMinutes = opts.failBackoffMinutes ?? 60;
+    const candidates = store.getIdleSessionsForEpisodicConsolidation({
+        idleMinutes,
+        minExchanges,
+        maxResults: maxSessions,
+        failBackoffMinutes,
+    });
+    let consolidated = 0;
+    let failed = 0;
+    let skipped = 0;
+    for (const candidate of candidates) {
+        try {
+            const result = await consolidateOneSession(store, candidate, opts);
+            if (result) {
+                consolidated++;
+            }
+            else {
+                store.updateConsolidationCursor(candidate.sessionKey, { success: false });
+                failed++;
+            }
+        }
+        catch (err) {
+            logger.warn({ err, sessionKey: candidate.sessionKey }, 'Consolidation pass error');
+            try {
+                store.updateConsolidationCursor(candidate.sessionKey, { success: false });
+            }
+            catch { /* ignore */ }
+            failed++;
+        }
+    }
+    return { consolidated, failed, skipped, candidates: candidates.length };
+}
+//# sourceMappingURL=episodic-consolidation.js.map

package/dist/gateway/heartbeat-scheduler.d.ts

@@ -44,6 +44,8 @@ export declare class HeartbeatScheduler {
     private denseBackfillInFlight;
     private lastSalienceDecayDate;
     private lastMemoryPulseDate;
+    private lastEpisodicConsolidationAt;
+    private episodicConsolidationInFlight;
     /** Wire up the cron scheduler so daily plan suggestions can be applied. */
     setCronScheduler(cs: CronScheduler): void;
     private getLastAgentSiRun;
@@ -68,6 +70,14 @@ export declare class HeartbeatScheduler {
      * Coverage climbs over hours/days without user action.
      */
     private maybeIdleDenseBackfill;
+    /**
+     * Episodic consolidation pass. Turns idle session transcript ranges into
+     * durable episodes via a small Haiku call per session. Same shape as
+     * maybeIdleDenseBackfill: in-flight guard, cooldown, chat-lane busy check,
+     * bounded work per pass. Skipped silently when there's nothing eligible
+     * (which is the common case).
+     */
+    private maybeRunEpisodicConsolidation;
     /**
      * Daily salience decay. Multiplies salience by 0.95 on chunks unaccessed
      * for >30 days. Date-gated (one pass per calendar day), persisted in

package/dist/gateway/heartbeat-scheduler.js

@@ -54,6 +54,8 @@ export class HeartbeatScheduler {
     denseBackfillInFlight = false;
     lastSalienceDecayDate = '';
     lastMemoryPulseDate = '';
+    lastEpisodicConsolidationAt = 0;
+    episodicConsolidationInFlight = false;
     /** Wire up the cron scheduler so daily plan suggestions can be applied. */
     setCronScheduler(cs) { this.cronScheduler = cs; }
     getLastAgentSiRun(slug) {
@@ -158,6 +160,12 @@ export class HeartbeatScheduler {
         // Pinned + soft-deleted + superseded chunks are exempt. One UPDATE per
         // day, gated by a date stamp on HeartbeatState.
         this.maybeRunSalienceDecay();
+        // Episodic consolidation — turn idle sessions' raw transcripts into
+        // durable, indexed episodes. ~5 min cooldown, capped at 3 sessions per
+        // pass to bound LLM cost. Best-effort; never blocks the tick.
+        this.maybeRunEpisodicConsolidation().catch(err => {
+            logger.debug({ err }, 'Episodic consolidation pass failed (non-fatal)');
+        });
         // Claim verification sweep — auto-verify pending claims whose due
         // times have passed (e.g. "I scheduled X for 8am" → check at 9am).
         import('./claim-tracker.js').then(async ({ verifyDueClaims, drainLLMFallback }) => {
@@ -810,6 +818,43 @@ export class HeartbeatScheduler {
             this.denseBackfillInFlight = false;
         }
     }
+    /**
+     * Episodic consolidation pass. Turns idle session transcript ranges into
+     * durable episodes via a small Haiku call per session. Same shape as
+     * maybeIdleDenseBackfill: in-flight guard, cooldown, chat-lane busy check,
+     * bounded work per pass. Skipped silently when there's nothing eligible
+     * (which is the common case).
+     */
+    async maybeRunEpisodicConsolidation() {
+        if (this.episodicConsolidationInFlight)
+            return;
+        const sinceLastMs = Date.now() - this.lastEpisodicConsolidationAt;
+        if (sinceLastMs < 5 * 60 * 1000)
+            return;
+        const { lanes } = await import('./lanes.js');
+        if (lanes.status().chat.active > 0)
+            return;
+        const store = this.gateway.getMemoryStore();
+        if (!store)
+            return;
+        this.episodicConsolidationInFlight = true;
+        this.lastEpisodicConsolidationAt = Date.now();
+        try {
+            const { runEpisodicConsolidationPass } = await import('./episodic-consolidation.js');
+            const result = await runEpisodicConsolidationPass(store, {
+                idleMinutes: 20,
+                minExchanges: 3,
+                maxSessionsPerPass: 3,
+                failBackoffMinutes: 60,
+            });
+            if (result.consolidated > 0 || result.failed > 0) {
+                logger.info(result, 'Episodic consolidation pass complete');
+            }
+        }
+        finally {
+            this.episodicConsolidationInFlight = false;
+        }
+    }
     /**
      * Daily salience decay. Multiplies salience by 0.95 on chunks unaccessed
      * for >30 days. Date-gated (one pass per calendar day), persisted in

package/dist/memory/store.d.ts

@@ -622,6 +622,93 @@ export declare class MemoryStore {
         bothModes: number;
         avgTopScore: number;
     };
+    /**
+     * Find sessions whose latest turn is older than `idleMinutes` minutes,
+     * have at least `minExchanges` user/assistant turns combined since the
+     * last consolidation cursor, and aren't already up-to-date. Returns one
+     * row per session ranked oldest-idle first so we consolidate the
+     * least-fresh first when bounded by maxResults.
+     */
+    getIdleSessionsForEpisodicConsolidation(opts: {
+        idleMinutes: number;
+        minExchanges: number;
+        maxResults: number;
+        failBackoffMinutes?: number;
+    }): Array<{
+        sessionKey: string;
+        startTranscriptId: number;
+        endTranscriptId: number;
+        startedAt: string;
+        endedAt: string;
+        exchanges: number;
+    }>;
+    /**
+     * Persist a consolidated episode and bump the per-session cursor so the
+     * same range isn't re-consolidated on the next pass. The summary text is
+     * also indexed into chunks (returned as chunkId) so hybrid recall surfaces
+     * episodes alongside raw transcripts.
+     */
+    insertEpisode(entry: {
+        sessionKey: string;
+        startedAt: string;
+        endedAt: string;
+        summary: string;
+        topics: string[];
+        entities: string[];
+        outcome: string;
+        openLoops: string[];
+        transcriptIds: number[];
+        chunkId?: number | null;
+    }): {
+        episodeId: number;
+        chunkId: number | null;
+    };
+    /**
+     * Mark a consolidation pass result on the per-session cursor. On success
+     * we advance last_transcript_id and reset fail_count; on failure we bump
+     * fail_count + last_attempted_at so the backoff-aware idle scan skips
+     * this session for a while.
+     */
+    updateConsolidationCursor(sessionKey: string, update: {
+        lastTranscriptId?: number;
+        success: boolean;
+    }): void;
+    /** Read the consolidation cursor for a session — used in tests and for diagnostics. */
+    getConsolidationCursor(sessionKey: string): {
+        sessionKey: string;
+        lastTranscriptId: number;
+        lastAttemptedAt: string | null;
+        lastSuccessAt: string | null;
+        failCount: number;
+    } | null;
+    /**
+     * List recent episodes for the dashboard. JSON columns are parsed back
+     * into arrays so callers don't have to.
+     */
+    listRecentEpisodes(opts?: {
+        limit?: number;
+        sessionKey?: string;
+        sinceIso?: string;
+    }): Array<{
+        id: number;
+        sessionKey: string;
+        startedAt: string;
+        endedAt: string;
+        summary: string;
+        topics: string[];
+        entities: string[];
+        outcome: string;
+        openLoops: string[];
+        transcriptIds: number[];
+        chunkId: number | null;
+        createdAt: string;
+    }>;
+    /**
+     * Fetch a slice of transcripts by id range for consolidation. Used by
+     * the consolidation module to materialize the conversation it's about
+     * to summarize.
+     */
+    getTranscriptsByIdRange(sessionKey: string, startId: number, endId: number): TranscriptTurn[];
     /**
      * Save a session summary for cross-session context.
      */
@@ -1542,7 +1629,7 @@ export declare class MemoryStore {
      * Stored as JSON in `chunks.derived_from` so the dashboard can show
      * "view source memories" — abstractions become auditable.
      */
-    insertSummaryChunk(sourceFile: string, section: string, content: string, derivedFromIds?: number[]): void;
+    insertSummaryChunk(sourceFile: string, section: string, content: string, derivedFromIds?: number[]): number;
     upsertLead(lead: {
         agentSlug: string;
         email: string;

package/dist/memory/store.js

@@ -948,6 +948,42 @@ export class MemoryStore {
         created_at TEXT DEFAULT (datetime('now'))
       );
       CREATE INDEX IF NOT EXISTS idx_recall_telemetry_created ON recall_telemetry(created_at DESC);
+    `);
+        // Episodes — durable, retrievable summaries of past sessions. Each
+        // episode is one chunked range of transcripts; the LLM extracts
+        // {summary, topics, entities, outcome, openLoops}. The summary text is
+        // also written into chunks so hybrid recall picks it up. transcript_ids
+        // is a JSON array; we don't normalize because the lineage is read-only.
+        this.conn.exec(`
+      CREATE TABLE IF NOT EXISTS episodes (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        session_key TEXT NOT NULL,
+        started_at TEXT NOT NULL,
+        ended_at TEXT NOT NULL,
+        summary TEXT NOT NULL,
+        topics TEXT,
+        entities TEXT,
+        outcome TEXT,
+        open_loops TEXT,
+        transcript_ids TEXT,
+        chunk_id INTEGER,
+        created_at TEXT DEFAULT (datetime('now'))
+      );
+      CREATE INDEX IF NOT EXISTS idx_episodes_session ON episodes(session_key, started_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_episodes_created ON episodes(created_at DESC);
+    `);
+        // Per-session consolidation cursor — tracks how far the LLM has
+        // summarized so we don't re-consolidate the same turns. Failure tracking
+        // (fail_count + last_attempted_at) lets us back off cleanly when the
+        // model rejects a session repeatedly without spamming retries.
+        this.conn.exec(`
+      CREATE TABLE IF NOT EXISTS consolidation_cursors (
+        session_key TEXT PRIMARY KEY,
+        last_transcript_id INTEGER NOT NULL DEFAULT 0,
+        last_attempted_at TEXT,
+        last_success_at TEXT,
+        fail_count INTEGER NOT NULL DEFAULT 0
+      );
     `);
         // Soft-delete via a separate table — keeps the chunks_au trigger
         // out of the path so we don't have to fight with the FTS5 contentless
@@ -2940,6 +2976,206 @@ export class MemoryStore {
             return { total: 0, semanticOnly: 0, lexicalOnly: 0, bothModes: 0, avgTopScore: 0 };
         }
     }
+    // ── Episodes (durable session summaries) ──────────────────────────
+    /**
+     * Find sessions whose latest turn is older than `idleMinutes` minutes,
+     * have at least `minExchanges` user/assistant turns combined since the
+     * last consolidation cursor, and aren't already up-to-date. Returns one
+     * row per session ranked oldest-idle first so we consolidate the
+     * least-fresh first when bounded by maxResults.
+     */
+    getIdleSessionsForEpisodicConsolidation(opts) {
+        const idleMin = Math.max(1, opts.idleMinutes);
+        const minEx = Math.max(1, opts.minExchanges);
+        const max = Math.max(1, opts.maxResults);
+        const backoff = Math.max(0, opts.failBackoffMinutes ?? 60);
+        try {
+            // Per-session: last cursor (or 0), count of new turns, MIN/MAX(id)
+            // bounding the new range, and the timestamps. The fail-backoff
+            // suppresses sessions whose last_attempted_at is recent enough that
+            // the cursor's fail_count > 0 indicates we should wait.
+            const rows = this.conn.prepare(`
+        SELECT
+          t.session_key AS session_key,
+          MIN(t.id) AS start_id,
+          MAX(t.id) AS end_id,
+          MIN(t.created_at) AS started_at,
+          MAX(t.created_at) AS ended_at,
+          COUNT(*) AS exchanges
+        FROM transcripts t
+        LEFT JOIN consolidation_cursors c ON c.session_key = t.session_key
+        WHERE t.id > COALESCE(c.last_transcript_id, 0)
+          AND (
+            c.fail_count IS NULL
+            OR c.fail_count = 0
+            OR c.last_attempted_at IS NULL
+            OR c.last_attempted_at < datetime('now', ?)
+          )
+        GROUP BY t.session_key
+        HAVING COUNT(*) >= ?
+           AND MAX(t.created_at) < datetime('now', ?)
+        ORDER BY MAX(t.created_at) ASC
+        LIMIT ?
+      `).all(`-${backoff} minutes`, minEx, `-${idleMin} minutes`, max);
+            return rows.map(r => ({
+                sessionKey: r.session_key,
+                startTranscriptId: r.start_id,
+                endTranscriptId: r.end_id,
+                startedAt: r.started_at,
+                endedAt: r.ended_at,
+                exchanges: r.exchanges,
+            }));
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Persist a consolidated episode and bump the per-session cursor so the
+     * same range isn't re-consolidated on the next pass. The summary text is
+     * also indexed into chunks (returned as chunkId) so hybrid recall surfaces
+     * episodes alongside raw transcripts.
+     */
+    insertEpisode(entry) {
+        const result = this.conn
+            .prepare(`INSERT INTO episodes
+         (session_key, started_at, ended_at, summary, topics, entities, outcome, open_loops, transcript_ids, chunk_id)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(entry.sessionKey, entry.startedAt, entry.endedAt, entry.summary, JSON.stringify(entry.topics ?? []), JSON.stringify(entry.entities ?? []), entry.outcome ?? '', JSON.stringify(entry.openLoops ?? []), JSON.stringify(entry.transcriptIds ?? []), entry.chunkId ?? null);
+        return {
+            episodeId: result.lastInsertRowid,
+            chunkId: entry.chunkId ?? null,
+        };
+    }
+    /**
+     * Mark a consolidation pass result on the per-session cursor. On success
+     * we advance last_transcript_id and reset fail_count; on failure we bump
+     * fail_count + last_attempted_at so the backoff-aware idle scan skips
+     * this session for a while.
+     */
+    updateConsolidationCursor(sessionKey, update) {
+        const existing = this.conn
+            .prepare('SELECT session_key FROM consolidation_cursors WHERE session_key = ?')
+            .get(sessionKey);
+        if (!existing) {
+            this.conn
+                .prepare(`INSERT INTO consolidation_cursors
+           (session_key, last_transcript_id, last_attempted_at, last_success_at, fail_count)
+           VALUES (?, ?, datetime('now'), ?, ?)`)
+                .run(sessionKey, update.success ? (update.lastTranscriptId ?? 0) : 0, update.success ? new Date().toISOString() : null, update.success ? 0 : 1);
+            return;
+        }
+        if (update.success) {
+            this.conn
+                .prepare(`UPDATE consolidation_cursors
+           SET last_transcript_id = ?, last_attempted_at = datetime('now'),
+               last_success_at = datetime('now'), fail_count = 0
+           WHERE session_key = ?`)
+                .run(update.lastTranscriptId ?? 0, sessionKey);
+        }
+        else {
+            this.conn
+                .prepare(`UPDATE consolidation_cursors
+           SET last_attempted_at = datetime('now'), fail_count = fail_count + 1
+           WHERE session_key = ?`)
+                .run(sessionKey);
+        }
+    }
+    /** Read the consolidation cursor for a session — used in tests and for diagnostics. */
+    getConsolidationCursor(sessionKey) {
+        const row = this.conn
+            .prepare('SELECT * FROM consolidation_cursors WHERE session_key = ?')
+            .get(sessionKey);
+        if (!row)
+            return null;
+        return {
+            sessionKey: row.session_key,
+            lastTranscriptId: row.last_transcript_id,
+            lastAttemptedAt: row.last_attempted_at,
+            lastSuccessAt: row.last_success_at,
+            failCount: row.fail_count,
+        };
+    }
+    /**
+     * List recent episodes for the dashboard. JSON columns are parsed back
+     * into arrays so callers don't have to.
+     */
+    listRecentEpisodes(opts = {}) {
+        const limit = Math.max(1, Math.min(opts.limit ?? 30, 200));
+        const params = [];
+        let where = '';
+        if (opts.sessionKey) {
+            where += where ? ' AND' : ' WHERE';
+            where += ' session_key = ?';
+            params.push(opts.sessionKey);
+        }
+        if (opts.sinceIso) {
+            where += where ? ' AND' : ' WHERE';
+            where += ' created_at >= ?';
+            params.push(opts.sinceIso);
+        }
+        params.push(limit);
+        const rows = this.conn
+            .prepare(`SELECT * FROM episodes${where} ORDER BY created_at DESC LIMIT ?`)
+            .all(...params);
+        const parseArray = (v) => {
+            if (!v)
+                return [];
+            try {
+                const x = JSON.parse(v);
+                return Array.isArray(x) ? x.map(String) : [];
+            }
+            catch {
+                return [];
+            }
+        };
+        const parseNumArray = (v) => {
+            if (!v)
+                return [];
+            try {
+                const x = JSON.parse(v);
+                return Array.isArray(x) ? x.filter(n => Number.isFinite(n)).map(Number) : [];
+            }
+            catch {
+                return [];
+            }
+        };
+        return rows.map(row => ({
+            id: row.id,
+            sessionKey: row.session_key,
+            startedAt: row.started_at,
+            endedAt: row.ended_at,
+            summary: row.summary,
+            topics: parseArray(row.topics),
+            entities: parseArray(row.entities),
+            outcome: row.outcome ?? '',
+            openLoops: parseArray(row.open_loops),
+            transcriptIds: parseNumArray(row.transcript_ids),
+            chunkId: row.chunk_id,
+            createdAt: row.created_at,
+        }));
+    }
+    /**
+     * Fetch a slice of transcripts by id range for consolidation. Used by
+     * the consolidation module to materialize the conversation it's about
+     * to summarize.
+     */
+    getTranscriptsByIdRange(sessionKey, startId, endId) {
+        const rows = this.conn
+            .prepare(`SELECT id, session_key, role, content, model, created_at
+         FROM transcripts
+         WHERE session_key = ? AND id >= ? AND id <= ?
+         ORDER BY id ASC`)
+            .all(sessionKey, startId, endId);
+        return rows.map(r => ({
+            id: r.id,
+            sessionKey: r.session_key,
+            role: r.role,
+            content: r.content,
+            model: r.model,
+            createdAt: r.created_at,
+        }));
+    }
     // ── Session Summaries ─────────────────────────────────────────────
     /**
      * Save a session summary for cross-session context.
@@ -5318,14 +5554,16 @@ export class MemoryStore {
             .prepare(`INSERT INTO chunks (source_file, section, content, chunk_type, content_hash, salience, consolidated, derived_from)
          VALUES (?, ?, ?, 'summary', ?, 0.8, 0, ?)`)
             .run(sourceFile, section, content, hash, derivedJson);
+        const chunkId = result.lastInsertRowid;
         // Immediately compute embedding so the summary is vector-searchable right away
         if (embeddingsModule.isReady()) {
             const vec = embeddingsModule.embed(content);
             if (vec) {
                 this.conn.prepare('UPDATE chunks SET embedding = ? WHERE id = ?')
-                    .run(embeddingsModule.serializeEmbedding(vec), result.lastInsertRowid);
+                    .run(embeddingsModule.serializeEmbedding(vec), chunkId);
             }
         }
+        return chunkId;
     }
     // ── SDR Operational Data ─────────────────────────────────────────
     // -- Leads --

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clementine-agent",
-  "version": "1.18.27",
+  "version": "1.18.28",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",