clementine-agent 1.18.28 → 1.18.30

package/dist/cli/dashboard.js

@@ -7044,6 +7044,64 @@ If the tool returns nothing or errors, return an empty array \`[]\`.`,
             res.status(500).json({ error: String(err) });
         }
     });
+    // Commitments — durable promises tracked across sessions.
+    app.get('/api/memory/commitments', async (req, res) => {
+        try {
+            const gateway = await getGateway();
+            const store = gateway.assistant?.memoryStore;
+            if (!store || typeof store.listCommitments !== 'function') {
+                res.status(503).json({ error: 'Commitments store not available' });
+                return;
+            }
+            const status = req.query.status ? String(req.query.status) : 'open';
+            const owner = req.query.owner ? String(req.query.owner) : undefined;
+            const overdueOnly = String(req.query.overdueOnly ?? '') === '1';
+            const limit = Math.min(parseInt(String(req.query.limit ?? '50'), 10) || 50, 500);
+            const commitments = store.listCommitments({
+                status: ['open', 'done', 'cancelled'].includes(status) ? status : 'open',
+                owner: owner === 'user' || owner === 'clementine' ? owner : undefined,
+                overdueOnly,
+                limit,
+            });
+            res.json({ ok: true, commitments });
+        }
+        catch (err) {
+            res.status(500).json({ error: String(err) });
+        }
+    });
+    app.post('/api/memory/commitments/action', async (req, res) => {
+        try {
+            const gateway = await getGateway();
+            const store = gateway.assistant?.memoryStore;
+            if (!store || typeof store.updateCommitmentStatus !== 'function') {
+                res.status(503).json({ error: 'Commitments store not available' });
+                return;
+            }
+            const id = Number(req.body?.id);
+            const action = String(req.body?.action ?? '');
+            if (!Number.isInteger(id) || id <= 0) {
+                res.status(400).json({ error: 'id required' });
+                return;
+            }
+            let updated = false;
+            if (action === 'done' || action === 'cancelled' || action === 'reopen') {
+                updated = store.updateCommitmentStatus(id, { status: action === 'reopen' ? 'open' : action });
+            }
+            else if (action === 'snooze') {
+                const hours = Number(req.body?.hours ?? 24);
+                const until = new Date(Date.now() + Math.max(1, hours) * 3600_000).toISOString();
+                updated = store.updateCommitmentStatus(id, { snoozeUntilIso: until });
+            }
+            else {
+                res.status(400).json({ error: 'invalid action' });
+                return;
+            }
+            res.json({ ok: updated });
+        }
+        catch (err) {
+            res.status(500).json({ error: String(err) });
+        }
+    });
     // Recent episodes — durable consolidated session summaries.
     app.get('/api/memory/episodes', async (req, res) => {
         try {
@@ -15027,6 +15085,22 @@ 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>Open commitments</span>
+                <div style="display:flex;align-items:center;gap:8px">
+                  <select id="commitments-filter-status" onchange="refreshCommitments()" style="font-size:12px;padding:4px 6px;border:1px solid var(--border);border-radius:4px;background:var(--bg-input);color:var(--text)">
+                    <option value="open" selected>Open</option>
+                    <option value="done">Done</option>
+                    <option value="cancelled">Cancelled</option>
+                  </select>
+                  <span style="font-size:11px;color:var(--text-muted)">Promises tracked across sessions</span>
+                </div>
+              </div>
+              <div class="card-body" id="panel-commitments" 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" 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>
@@ -18555,6 +18629,7 @@ function switchTab(group, tab) {
       refreshMemory();
       if (typeof refreshRecentWrites === 'function') refreshRecentWrites();
       if (typeof refreshRecentEpisodes === 'function') refreshRecentEpisodes();
+      if (typeof refreshCommitments === 'function') refreshCommitments();
       if (typeof refreshSupersedes === 'function') refreshSupersedes();
       if (typeof refreshCoverageStrip === 'function') refreshCoverageStrip();
     }
@@ -24913,6 +24988,7 @@ async function submitQuickAddMemory() {
       closeQuickAddMemory();
       if (typeof refreshRecentWrites === 'function') refreshRecentWrites();
       if (typeof refreshRecentEpisodes === 'function') refreshRecentEpisodes();
+      if (typeof refreshCommitments === 'function') refreshCommitments();
       if (typeof refreshMemory === 'function') refreshMemory();
     }, 600);
   } catch (err) {
@@ -25066,6 +25142,84 @@ async function refreshRecentWrites() {
   }
 }
 
+async function refreshCommitments() {
+  var el = document.getElementById('panel-commitments');
+  if (!el) return;
+  try {
+    var sel = document.getElementById('commitments-filter-status');
+    var status = sel ? sel.value : 'open';
+    var r = await apiFetch('/api/memory/commitments?limit=50&status=' + encodeURIComponent(status));
+    var d = await r.json();
+    if (!d.ok || !Array.isArray(d.commitments)) {
+      el.innerHTML = '<div class="empty-state" style="padding:14px">' + esc(d.error || 'No data') + '</div>';
+      return;
+    }
+    if (d.commitments.length === 0) {
+      el.innerHTML = '<div class="empty-state" style="padding:14px">No commitments. They land automatically when you say things like "I\\'ll fix that tomorrow" or "remind me to call them Friday".</div>';
+      return;
+    }
+    var html = '<table class="data-table" style="width:100%">';
+    html += '<thead><tr>'
+      + '<th style="width:80px">Owner</th>'
+      + '<th>Promise</th>'
+      + '<th style="width:140px">Due</th>'
+      + '<th style="width:100px">Source</th>'
+      + '<th style="width:200px">Actions</th>'
+      + '</tr></thead><tbody>';
+    var nowMs = Date.now();
+    for (var i = 0; i < d.commitments.length; i++) {
+      var c = d.commitments[i];
+      var ownerLabel = c.owner === 'clementine' ? 'I' : 'You';
+      var ownerColor = c.owner === 'clementine' ? '#a78bfa' : '#10b981';
+      var dueText = '—';
+      var dueColor = 'var(--text-muted)';
+      if (c.dueAt) {
+        try {
+          var dueMs = new Date(c.dueAt).getTime();
+          var deltaMs = dueMs - nowMs;
+          dueText = new Date(c.dueAt).toLocaleString();
+          if (deltaMs < 0) { dueText = 'OVERDUE — ' + dueText; dueColor = '#ef4444'; }
+          else if (deltaMs < 86_400_000) { dueColor = '#f59e0b'; }
+        } catch { dueText = c.dueAt; }
+      } else if (c.dueHint) {
+        dueText = c.dueHint;
+      }
+      var actions = '';
+      if (c.status === 'open') {
+        actions = '<button class="btn-sm" onclick="commitmentAction(' + c.id + ', \\'done\\')">Done</button>'
+          + ' <button class="btn-sm" onclick="commitmentAction(' + c.id + ', \\'snooze\\', 24)" title="Snooze 24h">Snooze</button>'
+          + ' <button class="btn-sm" onclick="commitmentAction(' + c.id + ', \\'cancelled\\')">Cancel</button>';
+      } else {
+        actions = '<button class="btn-sm" onclick="commitmentAction(' + c.id + ', \\'reopen\\')">Reopen</button>';
+      }
+      html += '<tr>'
+        + '<td style="font-size:11px;color:' + ownerColor + ';font-weight:600">' + ownerLabel + '</td>'
+        + '<td style="font-size:12px">' + esc(c.text) + '</td>'
+        + '<td style="font-size:11px;color:' + dueColor + '">' + esc(dueText) + '</td>'
+        + '<td style="font-size:11px;color:var(--text-muted)">' + esc(c.source) + '</td>'
+        + '<td>' + actions + '</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 commitmentAction(id, action, hours) {
+  try {
+    var body = { id: id, action: action };
+    if (hours) body.hours = hours;
+    var r = await apiJson('POST', '/api/memory/commitments/action', body);
+    if (r.error) { toast('Action failed: ' + r.error, 'error'); return; }
+    toast('Commitment ' + action, 'success');
+    refreshCommitments();
+  } catch (err) {
+    toast('Failed: ' + String(err), 'error');
+  }
+}
+
 async function refreshRecentEpisodes() {
   var el = document.getElementById('panel-recent-episodes');
   if (!el) return;

package/dist/gateway/active-context.d.ts

@@ -7,7 +7,7 @@
  * run logs into the model.
  */
 export interface ActiveContextItem {
-    source: 'notification' | 'background-task' | 'unleashed' | 'turn-ledger';
+    source: 'notification' | 'background-task' | 'unleashed' | 'turn-ledger' | 'commitment';
     label: string;
     detail: string;
     priority: number;
@@ -39,6 +39,19 @@ export interface ActiveContextOptions {
         embedded: number;
         total: number;
     };
+    /**
+     * Open commitments tied to this session (or owner-wide). Caller looks
+     * these up via store.listCommitments and threads them through so
+     * active-context.ts stays free of the store dependency.
+     */
+    openCommitments?: Array<{
+        id: number;
+        owner: 'user' | 'clementine';
+        text: string;
+        dueAt: string | null;
+        dueHint: string | null;
+        sessionKey: string | null;
+    }>;
 }
 export declare function buildActiveContextSnapshot(sessionKey: string, opts: ActiveContextOptions): ActiveContextSnapshot;
 //# sourceMappingURL=active-context.d.ts.map

package/dist/gateway/active-context.js

@@ -271,6 +271,36 @@ function turnLedgerItems(surfaceHistory) {
         greetingEligible: false,
     }));
 }
+function commitmentItems(opts) {
+    const list = opts.openCommitments ?? [];
+    if (list.length === 0)
+        return [];
+    const nowMs = opts.now ?? Date.now();
+    const dayMs = 24 * 60 * 60 * 1000;
+    return list.slice(0, 10).map((c) => {
+        const dueMs = c.dueAt ? Date.parse(c.dueAt) : NaN;
+        const overdue = Number.isFinite(dueMs) && dueMs < nowMs;
+        const dueWithin24 = Number.isFinite(dueMs) && dueMs >= nowMs && dueMs - nowMs <= dayMs;
+        let priority = 60;
+        if (overdue)
+            priority = 90;
+        else if (dueWithin24)
+            priority = 80;
+        else if (c.dueHint)
+            priority = 70;
+        const ownerLabel = c.owner === 'clementine' ? 'I committed' : 'You committed';
+        const dueLabel = overdue ? ' (overdue)' : dueWithin24 ? ' (due within 24h)' : c.dueHint ? ` (${c.dueHint})` : '';
+        return {
+            source: 'commitment',
+            label: `${ownerLabel}${dueLabel}`,
+            detail: cap(c.text),
+            priority,
+            timestamp: c.dueAt ?? undefined,
+            sourceId: `commitment:${c.id}`,
+            greetingEligible: overdue || dueWithin24,
+        };
+    });
+}
 function formatPromptBlock(items, coverage) {
     if (items.length === 0)
         return null;
@@ -312,6 +342,7 @@ export function buildActiveContextSnapshot(sessionKey, opts) {
         ...notificationItems(sessionKey, opts),
         ...unleashedItems(opts, surfaceHistory),
         ...turnLedgerItems(surfaceHistory),
+        ...commitmentItems(opts),
     ]
         .sort((a, b) => {
         const priority = b.priority - a.priority;

package/dist/gateway/commitments.d.ts

@@ -0,0 +1,38 @@
+import type { MemoryStore } from '../memory/store.js';
+export type CommitmentOwner = 'user' | 'clementine';
+export interface DetectedCommitment {
+    text: string;
+    owner: CommitmentOwner;
+    dueHint?: string;
+    dueAt?: string;
+}
+export declare function fingerprintCommitment(sessionKey: string, owner: CommitmentOwner, normalizedText: string): string;
+/**
+ * Parse a relative date phrase into an ISO datetime. Returns null when the
+ * phrase isn't recognized; callers fall back to storing the raw `dueHint`
+ * so the model still sees the deadline. Default time-of-day for date-only
+ * phrases is 17:00 local (5pm) — close enough for "by Friday" semantics
+ * without forcing the user to be precise.
+ */
+export declare function parseRelativeDue(phrase: string, now?: Date): string | null;
+/**
+ * Scan a single turn for commitment phrases. Returns at most one commitment
+ * per turn — the first strong match wins. Returning multiple per turn is
+ * possible but tends to over-fire; we'd rather miss one and let the LLM
+ * extractor catch it during consolidation.
+ */
+export declare function detectCommitmentInTurn(text: string, role: string): DetectedCommitment | null;
+/**
+ * Persist a detected commitment via the store, deduping on a stable
+ * fingerprint. Designed to be called from the chat path; failures are
+ * swallowed because commitment recording must never break a turn.
+ */
+export declare function recordDetectedCommitment(store: MemoryStore, sessionKey: string, detected: DetectedCommitment, meta: {
+    source: string;
+    transcriptId?: number;
+    episodeId?: number;
+}): {
+    id: number;
+    created: boolean;
+} | null;
+//# sourceMappingURL=commitments.d.ts.map

package/dist/gateway/commitments.js

@@ -0,0 +1,172 @@
+/**
+ * Commitments — first-class promises ("I'll fix the dashboard tomorrow",
+ * "remind me to call them Friday"). Lives alongside conversation-learning
+ * but tracks durable, actionable items that need surfacing in greetings
+ * until they're done or cancelled.
+ *
+ * Two ingest paths share a fingerprint-based dedupe so the same promise
+ * never gets recorded twice:
+ *
+ *   1. Per-turn regex detector (this file) — runs synchronously on user
+ *      and assistant turns. High-precision: matches obvious phrasings only,
+ *      to avoid spamming on every "I'll think about it" pleasantry.
+ *
+ *   2. LLM extraction during episodic consolidation — catches multi-turn
+ *      and implicit commitments the regex misses. Runs after the session
+ *      has been idle, so it sees the full context.
+ *
+ * Date parsing is intentionally tiny — we recognize common phrases
+ * ("tomorrow", "by Friday", "in 3 days", "next week") without pulling in
+ * a chrono dep. Anything we can't parse stays as `dueHint` text and is
+ * still surfaceable; it just doesn't drive overdue prioritization.
+ */
+import { createHash } from 'node:crypto';
+export function fingerprintCommitment(sessionKey, owner, normalizedText) {
+    const key = `${sessionKey}|${owner}|${normalizedText}`;
+    return createHash('sha1').update(key).digest('hex').slice(0, 16);
+}
+function normalizeText(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}]+/gu, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, 200);
+}
+const DAYS = ['sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday'];
+/**
+ * Parse a relative date phrase into an ISO datetime. Returns null when the
+ * phrase isn't recognized; callers fall back to storing the raw `dueHint`
+ * so the model still sees the deadline. Default time-of-day for date-only
+ * phrases is 17:00 local (5pm) — close enough for "by Friday" semantics
+ * without forcing the user to be precise.
+ */
+export function parseRelativeDue(phrase, now = new Date()) {
+    if (!phrase)
+        return null;
+    const text = phrase.toLowerCase().trim();
+    const today = new Date(now.getFullYear(), now.getMonth(), now.getDate(), 17, 0, 0, 0);
+    if (/^today$/.test(text) || /\bby today\b/.test(text) || /\bend of (?:the )?day\b/.test(text) || /\beod\b/.test(text)) {
+        return today.toISOString();
+    }
+    if (/^tomorrow$|by tomorrow|tomorrow morning|tomorrow night|tomorrow evening/.test(text)) {
+        const d = new Date(today);
+        d.setDate(d.getDate() + 1);
+        return d.toISOString();
+    }
+    if (/\bnext week\b/.test(text)) {
+        const d = new Date(today);
+        d.setDate(d.getDate() + 7);
+        return d.toISOString();
+    }
+    if (/\bend of (?:the )?week\b/.test(text)) {
+        const d = new Date(today);
+        const daysToFri = (5 - d.getDay() + 7) % 7;
+        d.setDate(d.getDate() + (daysToFri === 0 ? 0 : daysToFri));
+        return d.toISOString();
+    }
+    const inN = text.match(/\bin (\d+) (day|days|week|weeks|hour|hours)\b/);
+    if (inN) {
+        const n = parseInt(inN[1], 10);
+        const unit = inN[2];
+        const d = new Date(now);
+        if (unit.startsWith('hour'))
+            d.setHours(d.getHours() + n);
+        else if (unit.startsWith('week'))
+            d.setDate(d.getDate() + 7 * n);
+        else
+            d.setDate(d.getDate() + n);
+        return d.toISOString();
+    }
+    for (let i = 0; i < DAYS.length; i++) {
+        const re = new RegExp(`\\b(?:by |on )?${DAYS[i]}\\b`);
+        if (re.test(text)) {
+            const d = new Date(today);
+            const delta = (i - d.getDay() + 7) % 7;
+            d.setDate(d.getDate() + (delta === 0 ? 7 : delta));
+            return d.toISOString();
+        }
+    }
+    return null;
+}
+/**
+ * Match phrases that signal a real promise. We're deliberately strict:
+ * "I'll think about it", "I'll see what I can do", and other hedges are
+ * not commitments. We require an action verb after "I'll/I will" and a
+ * recognizable object phrase, OR an explicit "remind me to" / "by [day]".
+ */
+const STRONG_USER_PATTERNS = [
+    // "I'll fix that tomorrow", "I'll send the doc by Friday"
+    /\bi(?:'| wi)ll\s+(?!think|see|try)([a-z][a-z'-]*\s+(?:[\w'-]+\s+){0,8}[\w'-]+)/i,
+    // "I need to ship this by Friday"
+    /\bi need to\s+([\w'-]+(?:\s+[\w'-]+){1,10})/i,
+    // "remind me to email them tomorrow"
+    /\bremind me to\s+([\w'-]+(?:\s+[\w'-]+){1,10})/i,
+    // "I should follow up Friday"
+    /\bi should\s+([\w'-]+(?:\s+[\w'-]+){1,10})/i,
+];
+const STRONG_ASSISTANT_PATTERNS = [
+    // "I'll fix that tonight" — Clementine self-committing.
+    /\bi(?:'| wi)ll\s+(?!think|see|try|let)([a-z][a-z'-]*\s+(?:[\w'-]+\s+){0,8}[\w'-]+)/i,
+];
+const DUE_HINT_RE = /\b(today|tomorrow|next week|end of (?:the )?week|end of day|eod|by (?:the )?(?:end of (?:the )?(?:day|week)|monday|tuesday|wednesday|thursday|friday|saturday|sunday|tomorrow|today|next week)|on (?:monday|tuesday|wednesday|thursday|friday|saturday|sunday)|in \d+ (?:day|days|week|weeks|hour|hours))\b/i;
+/**
+ * Scan a single turn for commitment phrases. Returns at most one commitment
+ * per turn — the first strong match wins. Returning multiple per turn is
+ * possible but tends to over-fire; we'd rather miss one and let the LLM
+ * extractor catch it during consolidation.
+ */
+export function detectCommitmentInTurn(text, role) {
+    if (!text || text.length < 8)
+        return null;
+    const isAssistant = role === 'assistant';
+    const patterns = isAssistant ? STRONG_ASSISTANT_PATTERNS : STRONG_USER_PATTERNS;
+    let matchedAction = null;
+    for (const pat of patterns) {
+        const m = text.match(pat);
+        if (m && m[1]) {
+            matchedAction = m[0].trim();
+            break;
+        }
+    }
+    if (!matchedAction)
+        return null;
+    // Truncate the surrounding sentence so the commitment text stays tight.
+    // Strip punctuation noise but keep the original case for the saved text.
+    const sentence = (text.match(new RegExp(`[^.!?\\n]*${matchedAction.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[^.!?\\n]*`, 'i')) ?? [matchedAction])[0].trim();
+    const cleaned = sentence.replace(/\s+/g, ' ').slice(0, 220);
+    const hintMatch = cleaned.match(DUE_HINT_RE);
+    const dueHint = hintMatch ? hintMatch[0] : undefined;
+    const dueAt = dueHint ? parseRelativeDue(dueHint) ?? undefined : undefined;
+    return {
+        text: cleaned,
+        owner: isAssistant ? 'clementine' : 'user',
+        dueHint,
+        dueAt,
+    };
+}
+/**
+ * Persist a detected commitment via the store, deduping on a stable
+ * fingerprint. Designed to be called from the chat path; failures are
+ * swallowed because commitment recording must never break a turn.
+ */
+export function recordDetectedCommitment(store, sessionKey, detected, meta) {
+    try {
+        const fingerprint = fingerprintCommitment(sessionKey, detected.owner, normalizeText(detected.text));
+        return store.upsertCommitment({
+            fingerprint,
+            source: meta.source,
+            owner: detected.owner,
+            text: detected.text,
+            sessionKey,
+            transcriptId: meta.transcriptId ?? null,
+            episodeId: meta.episodeId ?? null,
+            dueAt: detected.dueAt ?? null,
+            dueHint: detected.dueHint ?? null,
+        });
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=commitments.js.map

package/dist/gateway/context-policy.d.ts

@@ -7,6 +7,7 @@
  * replies into status dumps.
  */
 import type { ActiveContextItem, ActiveContextSnapshot } from './active-context.js';
+import type { EntityMatch } from './entity-registry.js';
 export type ContextTurnIntent = 'greeting' | 'ack' | 'status' | 'repair_request' | 'followup' | 'memory_correction' | 'work_request' | 'general_chat';
 export type RequiredRetrieval = 'none' | 'event' | 'transcript';
 export interface ContextPolicyDecision {
@@ -17,10 +18,19 @@ export interface ContextPolicyDecision {
     requiredRetrieval: RequiredRetrieval;
     retrievalQueries: string[];
     debugReasons: string[];
+    triggeredEntities: EntityMatch[];
 }
 export interface ContextPolicyInput {
     text: string;
     activeContext?: ActiveContextSnapshot | null;
+    /**
+     * Pre-computed entity matches against the registry. Caller looks these
+     * up via entity-registry.findEntitiesInText so the policy module stays
+     * free of the store dependency. When matches arrive, the policy elevates
+     * recall to 'transcript' on non-trivial intents and seeds entity names
+     * into the retrieval queries.
+     */
+    entityMatches?: EntityMatch[];
 }
 export declare function looksLikeVagueContextReference(text: string): boolean;
 export declare function classifyContextTurn(text: string): ContextTurnIntent;

package/dist/gateway/context-policy.js

@@ -88,6 +88,7 @@ function buildRetrievalQueries(intent, text, activeContext) {
 export function decideContextPolicy(input) {
     const intent = classifyContextTurn(input.text);
     const activeContext = input.activeContext ?? null;
+    const entityMatches = input.entityMatches ?? [];
     const debugReasons = [`intent:${intent}`];
     const proactiveSurface = (activeContext?.items ?? [])
         .filter((item) => item.greetingEligible && !item.alreadySurfaced && !item.resolved)
@@ -98,8 +99,21 @@ export function decideContextPolicy(input) {
     if (intent === 'repair_request' || intent === 'followup' || intent === 'memory_correction') {
         requiredRetrieval = 'transcript';
     }
+    // Entity-driven proactive recall: a known topic in the user's turn is a
+    // strong enough signal to pre-fetch related history without waiting for
+    // a vague-repair phrase. Skip on greeting/ack so a passing entity mention
+    // ("hey, how's the dashboard?") doesn't pull a wall of context into a
+    // friendly hello.
+    const elevatedByEntity = entityMatches.length > 0 && intent !== 'greeting' && intent !== 'ack';
+    if (elevatedByEntity && requiredRetrieval !== 'transcript') {
+        requiredRetrieval = 'transcript';
+        debugReasons.push('entity:elevated-retrieval');
+    }
     if (requiredRetrieval !== 'none')
         debugReasons.push(`retrieval:${requiredRetrieval}`);
+    if (entityMatches.length > 0) {
+        debugReasons.push(`entities:${entityMatches.map(e => e.name).join(',')}`);
+    }
     const silentContextBlocks = [];
     if (activeContext?.promptBlock
         && intent !== 'greeting'
@@ -112,14 +126,24 @@ export function decideContextPolicy(input) {
             ? activeContext?.greetingLine ?? 'Hey. I am here.'
             : 'Hey. I am here.'
         : null;
+    const baseQueries = buildRetrievalQueries(intent, input.text, activeContext);
+    // Prepend entity display names so the recall search prioritizes them.
+    // Dedup against the base lexical queries so we don't pay twice for the
+    // same term.
+    const entityQueries = entityMatches.map(e => e.display);
+    const merged = [...new Set([...entityQueries, ...baseQueries])]
+        .map(q => q.trim())
+        .filter(Boolean)
+        .slice(0, 6);
     return {
         turnIntent: intent,
         silentContextBlocks,
         visibleOpening,
         proactiveSurface,
         requiredRetrieval,
-        retrievalQueries: buildRetrievalQueries(intent, input.text, activeContext),
+        retrievalQueries: merged,
         debugReasons,
+        triggeredEntities: entityMatches,
     };
 }
 //# sourceMappingURL=context-policy.js.map

package/dist/gateway/entity-registry.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Entity registry — detects when a user turn mentions a topic / entity
+ * Clementine already has context on, so recall can fire without waiting
+ * for vague-repair phrases like "what did we decide?".
+ *
+ * The registry is a flattened, mention-frequency-ranked snapshot of:
+ *   - chunks.topic (curated knowledge)
+ *   - episodes.topics + episodes.entities (consolidated session memory)
+ *
+ * Cached per store dbPath with a 5-minute TTL — the registry only changes
+ * when episodes consolidate or new chunks land, both of which are minutes-
+ * scale events. Invalidating less often keeps the chat path fast.
+ */
+import type { MemoryStore } from '../memory/store.js';
+export interface RegistryEntity {
+    name: string;
+    display: string;
+    kind: 'topic' | 'entity';
+    count: number;
+}
+export interface EntityMatch {
+    name: string;
+    display: string;
+    kind: 'topic' | 'entity';
+}
+/** Read the registry from cache, refreshing if stale or missing. Tests can
+ *  call invalidateEntityRegistry() between cases to bypass the cache. */
+export declare function getEntityRegistry(store: MemoryStore, opts?: {
+    now?: number;
+    key?: string;
+}): RegistryEntity[];
+/** Drop cached registry entries — used by tests and by code paths that
+ *  know they just mutated the registry source (e.g. after a fresh episode
+ *  consolidation pass). */
+export declare function invalidateEntityRegistry(key?: string): void;
+/**
+ * Find registry entities mentioned in the input text, with word-boundary
+ * matching so "auth" doesn't match "author". Multi-word entities are
+ * matched as contiguous word sequences. Longer matches are preferred
+ * (more specific), with mention-count as the tiebreaker.
+ *
+ * Returns at most `maxMatches` (default 5) entities, deduplicated.
+ */
+export declare function findEntitiesInText(text: string, registry: RegistryEntity[], opts?: {
+    maxMatches?: number;
+}): EntityMatch[];
+//# sourceMappingURL=entity-registry.d.ts.map

package/dist/gateway/entity-registry.js

@@ -0,0 +1,92 @@
+const REGISTRY_TTL_MS = 5 * 60 * 1000;
+const cache = new Map();
+/** Words that trigger pointless matches when allowed (too generic). Augments
+ *  the per-entity length filter — "we" or "do" would never make it past the
+ *  3-char floor anyway, but common-but-bare nouns sometimes do, and they
+ *  cause false positives across unrelated turns. */
+const ENTITY_STOPWORDS = new Set([
+    'the', 'and', 'but', 'for', 'are', 'was', 'has', 'had', 'have', 'this',
+    'that', 'with', 'from', 'they', 'them', 'their', 'these', 'those',
+    'about', 'into', 'over', 'just', 'than', 'then', 'when', 'what', 'where',
+    'while', 'will', 'would', 'could', 'should',
+]);
+/** Read the registry from cache, refreshing if stale or missing. Tests can
+ *  call invalidateEntityRegistry() between cases to bypass the cache. */
+export function getEntityRegistry(store, opts = {}) {
+    const key = opts.key ?? store.dbPath ?? 'default';
+    const now = opts.now ?? Date.now();
+    const cached = cache.get(key);
+    if (cached && now - cached.loadedAt < REGISTRY_TTL_MS) {
+        return cached.entries;
+    }
+    let entries = [];
+    try {
+        if (typeof store.getEntityRegistrySnapshot === 'function') {
+            entries = store.getEntityRegistrySnapshot({ minCount: 1, maxItems: 500 });
+        }
+    }
+    catch { /* registry probe is best-effort */ }
+    cache.set(key, { entries, loadedAt: now });
+    return entries;
+}
+/** Drop cached registry entries — used by tests and by code paths that
+ *  know they just mutated the registry source (e.g. after a fresh episode
+ *  consolidation pass). */
+export function invalidateEntityRegistry(key) {
+    if (key)
+        cache.delete(key);
+    else
+        cache.clear();
+}
+function normalizeForMatch(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}]+/gu, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/**
+ * Find registry entities mentioned in the input text, with word-boundary
+ * matching so "auth" doesn't match "author". Multi-word entities are
+ * matched as contiguous word sequences. Longer matches are preferred
+ * (more specific), with mention-count as the tiebreaker.
+ *
+ * Returns at most `maxMatches` (default 5) entities, deduplicated.
+ */
+export function findEntitiesInText(text, registry, opts = {}) {
+    const max = Math.max(1, opts.maxMatches ?? 5);
+    if (!text || registry.length === 0)
+        return [];
+    const haystack = ` ${normalizeForMatch(text)} `;
+    if (haystack.trim().length < 3)
+        return [];
+    const candidates = [];
+    for (const entry of registry) {
+        if (entry.name.length < 3)
+            continue;
+        if (entry.name.split(' ').length === 1 && ENTITY_STOPWORDS.has(entry.name))
+            continue;
+        const needle = ` ${entry.name} `;
+        if (haystack.includes(needle)) {
+            candidates.push({ entry, specificity: entry.name.length });
+        }
+    }
+    // Specificity desc, then count desc — multi-word matches win, frequency
+    // breaks ties between equally-specific candidates.
+    candidates.sort((a, b) => b.specificity - a.specificity || b.entry.count - a.entry.count);
+    // Dedup: skip a candidate if a longer already-accepted match fully
+    // contains its name (e.g. don't surface "dashboard" if "dashboard
+    // refactor" already matched).
+    const accepted = [];
+    const acceptedNames = [];
+    for (const { entry } of candidates) {
+        if (acceptedNames.some(n => n.includes(entry.name)))
+            continue;
+        accepted.push({ name: entry.name, display: entry.display, kind: entry.kind });
+        acceptedNames.push(entry.name);
+        if (accepted.length >= max)
+            break;
+    }
+    return accepted;
+}
+//# sourceMappingURL=entity-registry.js.map

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

@@ -16,6 +16,7 @@
  */
 import Anthropic from '@anthropic-ai/sdk';
 import type { MemoryStore } from '../memory/store.js';
+import { type CommitmentOwner } from './commitments.js';
 export interface EpisodicConsolidationOptions {
     /** Minutes of inactivity before a session becomes consolidation-eligible. */
     idleMinutes?: number;
@@ -32,12 +33,18 @@ export interface EpisodicConsolidationOptions {
     /** Wallclock now() — used by tests for deterministic timestamps. */
     now?: () => Date;
 }
+export interface ExtractedCommitment {
+    text: string;
+    owner: CommitmentOwner;
+    dueHint?: string;
+}
 export interface EpisodeExtraction {
     summary: string;
     topics: string[];
     entities: string[];
     outcome: string;
     openLoops: string[];
+    commitments: ExtractedCommitment[];
 }
 interface CandidateRow {
     sessionKey: string;

package/dist/gateway/episodic-consolidation.js

@@ -17,6 +17,7 @@
 import Anthropic from '@anthropic-ai/sdk';
 import pino from 'pino';
 import { MODELS } from '../config.js';
+import { fingerprintCommitment, parseRelativeDue, } from './commitments.js';
 const logger = pino({
     name: 'clementine.episodic-consolidation',
     level: process.env.CLEMENTINE_CONSOLIDATION_LOG_LEVEL || 'warn',
@@ -31,7 +32,10 @@ const SYSTEM_PROMPT = [
     '  "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)',
+    '  "openLoops": string[] (unresolved follow-ups; empty array if none, max 5),',
+    '  "commitments": Array<{ text: string, owner: "user" | "clementine", dueHint?: string }>',
+    '      (explicit promises only — "I\'ll do X", "remind me to Y", "by Friday".',
+    '       owner = whoever committed: user vs the assistant. Empty array if none, max 5.)',
     '}',
 ].join('\n');
 function buildUserPrompt(turns) {
@@ -71,12 +75,28 @@ export function parseEpisodeJson(raw) {
     const summary = typeof obj.summary === 'string' ? obj.summary.trim() : '';
     if (!summary)
         return null;
+    const rawCommitments = Array.isArray(obj.commitments) ? obj.commitments : [];
+    const commitments = [];
+    for (const raw of rawCommitments) {
+        if (!raw || typeof raw !== 'object')
+            continue;
+        const c = raw;
+        const text = typeof c.text === 'string' ? c.text.trim() : '';
+        const owner = c.owner === 'clementine' || c.owner === 'user' ? c.owner : null;
+        if (!text || !owner)
+            continue;
+        const dueHint = typeof c.dueHint === 'string' && c.dueHint.trim() ? c.dueHint.trim() : undefined;
+        commitments.push({ text: text.slice(0, 220), owner, dueHint });
+        if (commitments.length >= 5)
+            break;
+    }
     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),
+        commitments,
     };
 }
 function getAnthropicClient(opts) {
@@ -149,6 +169,34 @@ export async function consolidateOneSession(store, candidate, opts = {}) {
         transcriptIds,
         chunkId,
     });
+    // Lift extracted commitments into first-class rows. Fingerprint dedupe
+    // keeps these from colliding with regex-detected commitments captured
+    // in real time on the same turns.
+    let commitmentsCreated = 0;
+    for (const c of extraction.commitments) {
+        try {
+            const normalized = c.text.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ' ').replace(/\s+/g, ' ').trim().slice(0, 200);
+            if (!normalized)
+                continue;
+            const fp = fingerprintCommitment(candidate.sessionKey, c.owner, normalized);
+            const dueAt = c.dueHint ? parseRelativeDue(c.dueHint) ?? null : null;
+            const result = store.upsertCommitment({
+                fingerprint: fp,
+                source: 'episode-extractor',
+                owner: c.owner,
+                text: c.text,
+                sessionKey: candidate.sessionKey,
+                episodeId: insert.episodeId,
+                dueAt,
+                dueHint: c.dueHint ?? null,
+            });
+            if (result.created)
+                commitmentsCreated++;
+        }
+        catch (err) {
+            logger.debug({ err }, 'Failed to persist extracted commitment');
+        }
+    }
     store.updateConsolidationCursor(candidate.sessionKey, {
         lastTranscriptId: candidate.endTranscriptId,
         success: true,
@@ -158,6 +206,7 @@ export async function consolidateOneSession(store, candidate, opts = {}) {
         episodeId: insert.episodeId,
         chunkId,
         turns: turns.length,
+        commitmentsCreated,
     }, 'Consolidated episode');
     return { episodeId: insert.episodeId, chunkId };
 }

package/dist/gateway/router.js

@@ -28,6 +28,8 @@ import { recordProactiveNotificationEvent, } from './notification-context.js';
 import { isInternalSyntheticPrompt, resolveRecentOperationalContext } from './recent-context.js';
 import { decideContextPolicy } from './context-policy.js';
 import { persistConversationLearning } from './conversation-learning.js';
+import { detectCommitmentInTurn, recordDetectedCommitment } from './commitments.js';
+import { findEntitiesInText, getEntityRegistry } from './entity-registry.js';
 import { getBackgroundCreditBlock, isCreditBalanceError, markBackgroundCreditBlocked } from './credit-guard.js';
 import { appendTurnLedger, estimateTokensApprox, formatLastTurnLedger, readRecentTurnLedger } from './turn-ledger.js';
 import { assessGatewayContextHygiene, formatGatewayHygieneAnnotation } from './context-hygiene.js';
@@ -1521,6 +1523,7 @@ export class Gateway {
         // another turn is active.
         const localTurnStarted = Date.now();
         let transcriptCoverage;
+        let openCommitments;
         if (this.isTrustedPersonalSession(sessionKey)) {
             try {
                 const store = this.assistant.getMemoryStore?.();
@@ -1528,13 +1531,41 @@ export class Gateway {
                     const cov = store.getTranscriptDenseCoverage();
                     transcriptCoverage = { embedded: cov.embedded, total: cov.total };
                 }
+                if (store && typeof store.listCommitments === 'function') {
+                    // Pull session-scoped open commitments first, then pad with the
+                    // wider open list so commitments captured in other sessions still
+                    // surface in greetings (e.g. user said "remind me Friday" via
+                    // Slack, then opens a Discord DM Saturday).
+                    const list = store.listCommitments;
+                    const scoped = list({ status: 'open', sessionKey, limit: 10 });
+                    const wider = scoped.length < 6 ? list({ status: 'open', limit: 10 }) : [];
+                    const seen = new Set();
+                    const merged = [...scoped, ...wider].filter(c => !seen.has(c.id) && (seen.add(c.id), true));
+                    openCommitments = merged.slice(0, 10);
+                }
             }
-            catch { /* coverage probe is best-effort */ }
+            catch { /* probes are best-effort */ }
         }
         const activeContext = this.isTrustedPersonalSession(sessionKey)
-            ? buildActiveContextSnapshot(sessionKey, { baseDir: BASE_DIR, transcriptCoverage })
+            ? buildActiveContextSnapshot(sessionKey, { baseDir: BASE_DIR, transcriptCoverage, openCommitments })
             : null;
-        const contextDecision = decideContextPolicy({ text, activeContext });
+        // Entity recall: if the user mentions something we already have context
+        // on (a chunk topic or an episode entity), elevate retrieval so the
+        // model gets the relevant history without waiting for a repair phrase.
+        let entityMatches = [];
+        if (this.isTrustedPersonalSession(sessionKey)) {
+            try {
+                const store = this.assistant.getMemoryStore?.();
+                if (store) {
+                    const registry = getEntityRegistry(store);
+                    if (registry.length > 0) {
+                        entityMatches = findEntitiesInText(text, registry);
+                    }
+                }
+            }
+            catch { /* entity registry probe is best-effort */ }
+        }
+        const contextDecision = decideContextPolicy({ text, activeContext, entityMatches });
         if (this.isTrustedPersonalSession(sessionKey)) {
             const learning = persistConversationLearning(sessionKey, text, this.assistant.getMemoryStore?.());
             if (learning?.corrections.length || learning?.preferences.length) {
@@ -1544,6 +1575,26 @@ export class Gateway {
                     preferences: learning.preferences.length,
                 }, 'Captured deterministic conversation learning signal');
             }
+            // Best-effort: scan this user turn for an explicit commitment phrase
+            // ("I'll fix that tomorrow"). Detection runs synchronously and
+            // dedupes by fingerprint so re-running on the same text is a no-op.
+            try {
+                const detected = detectCommitmentInTurn(text, 'user');
+                if (detected) {
+                    const store = this.assistant.getMemoryStore?.();
+                    if (store) {
+                        const recorded = recordDetectedCommitment(store, sessionKey, detected, { source: 'turn-detector' });
+                        if (recorded?.created) {
+                            logger.info({
+                                sessionKey, owner: detected.owner, dueHint: detected.dueHint, hasDueAt: !!detected.dueAt,
+                            }, 'Captured explicit user commitment');
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                logger.debug({ err }, 'Commitment detection failed (non-fatal)');
+            }
         }
         const localResponse = await this.handleLocalTurn(sessionKey, text, onText, contextDecision);
         if (localResponse !== null) {

package/dist/memory/store.d.ts

@@ -703,6 +703,82 @@ export declare class MemoryStore {
         chunkId: number | null;
         createdAt: string;
     }>;
+    /**
+     * Pull a flattened, deduplicated snapshot of named topics + entities the
+     * agent already knows about, ranked by mention frequency. Sources:
+     *   - chunks.topic         (curated knowledge — the strongest signal)
+     *   - episodes.topics      (LLM-extracted topic phrases per session)
+     *   - episodes.entities    (LLM-extracted named things)
+     *
+     * Used by the entity-registry module to detect when a user turn mentions
+     * something we have prior context on, so recall can fire proactively.
+     */
+    getEntityRegistrySnapshot(opts?: {
+        minCount?: number;
+        maxItems?: number;
+    }): Array<{
+        name: string;
+        display: string;
+        kind: 'topic' | 'entity';
+        count: number;
+    }>;
+    /**
+     * Insert a commitment, deduping on the fingerprint. If a row with the
+     * same fingerprint already exists, the existing id is returned and no
+     * write occurs — keeps the regex detector + LLM extractor from creating
+     * duplicates of the same promise.
+     */
+    upsertCommitment(entry: {
+        fingerprint: string;
+        source: string;
+        owner: 'user' | 'clementine';
+        text: string;
+        sessionKey?: string | null;
+        transcriptId?: number | null;
+        episodeId?: number | null;
+        dueAt?: string | null;
+        dueHint?: string | null;
+    }): {
+        id: number;
+        created: boolean;
+    };
+    /**
+     * List commitments with optional filters. Sorted by due_at ASC NULLS LAST
+     * so overdue + soon-due float to the top.
+     */
+    listCommitments(opts?: {
+        status?: 'open' | 'done' | 'cancelled';
+        sessionKey?: string;
+        owner?: 'user' | 'clementine';
+        overdueOnly?: boolean;
+        dueBeforeIso?: string;
+        limit?: number;
+    }): Array<{
+        id: number;
+        fingerprint: string;
+        source: string;
+        owner: 'user' | 'clementine';
+        text: string;
+        sessionKey: string | null;
+        transcriptId: number | null;
+        episodeId: number | null;
+        dueAt: string | null;
+        dueHint: string | null;
+        status: 'open' | 'done' | 'cancelled';
+        createdAt: string;
+        completedAt: string | null;
+        snoozedUntil: string | null;
+    }>;
+    /**
+     * Update commitment status. 'done' / 'cancelled' set completed_at; 'snooze'
+     * (with snoozeIso) bumps snoozed_until without changing status so the row
+     * stays open but suppressed from greeting until the snooze expires.
+     */
+    updateCommitmentStatus(id: number, update: {
+        status?: 'open' | 'done' | 'cancelled';
+        snoozeUntilIso?: string;
+        notes?: string;
+    }): boolean;
     /**
      * Fetch a slice of transcripts by id range for consolidation. Used by
      * the consolidation module to materialize the conversation it's about

package/dist/memory/store.js

@@ -984,6 +984,33 @@ export class MemoryStore {
         last_success_at TEXT,
         fail_count INTEGER NOT NULL DEFAULT 0
       );
+    `);
+        // Commitments — first-class promises in either direction. owner = 'user'
+        // for "I'll fix that tomorrow" turns, 'clementine' for things she
+        // committed to do. fingerprint = sha1(session_key|owner|normalized_text)
+        // makes the explicit detector and the LLM episode extractor share an
+        // idempotent insert path so one promise doesn't get double-recorded.
+        this.conn.exec(`
+      CREATE TABLE IF NOT EXISTS commitments (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        fingerprint TEXT NOT NULL UNIQUE,
+        source TEXT NOT NULL,
+        owner TEXT NOT NULL,
+        text TEXT NOT NULL,
+        session_key TEXT,
+        transcript_id INTEGER,
+        episode_id INTEGER,
+        due_at TEXT,
+        due_hint TEXT,
+        status TEXT NOT NULL DEFAULT 'open',
+        created_at TEXT DEFAULT (datetime('now')),
+        completed_at TEXT,
+        snoozed_until TEXT,
+        notes TEXT
+      );
+      CREATE INDEX IF NOT EXISTS idx_commitments_status ON commitments(status, due_at);
+      CREATE INDEX IF NOT EXISTS idx_commitments_session ON commitments(session_key, status);
+      CREATE INDEX IF NOT EXISTS idx_commitments_owner ON commitments(owner, status);
     `);
         // 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
@@ -3155,6 +3182,199 @@ export class MemoryStore {
             createdAt: row.created_at,
         }));
     }
+    // ── Entity registry ───────────────────────────────────────────────
+    /**
+     * Pull a flattened, deduplicated snapshot of named topics + entities the
+     * agent already knows about, ranked by mention frequency. Sources:
+     *   - chunks.topic         (curated knowledge — the strongest signal)
+     *   - episodes.topics      (LLM-extracted topic phrases per session)
+     *   - episodes.entities    (LLM-extracted named things)
+     *
+     * Used by the entity-registry module to detect when a user turn mentions
+     * something we have prior context on, so recall can fire proactively.
+     */
+    getEntityRegistrySnapshot(opts = {}) {
+        const minCount = Math.max(1, opts.minCount ?? 1);
+        const maxItems = Math.max(1, Math.min(opts.maxItems ?? 500, 5000));
+        const counts = new Map();
+        const accept = (raw, kind) => {
+            if (!raw)
+                return;
+            const display = raw.trim();
+            if (display.length < 3 || display.length > 80)
+                return;
+            const name = display.toLowerCase();
+            const existing = counts.get(name);
+            if (existing) {
+                existing.count++;
+                // Topics from chunks outrank LLM-derived ones for kind classification.
+                if (kind === 'topic')
+                    existing.kind = 'topic';
+            }
+            else {
+                counts.set(name, { display, kind, count: 1 });
+            }
+        };
+        try {
+            const topicRows = this.conn
+                .prepare(`SELECT topic, COUNT(*) as cnt FROM chunks
+           WHERE topic IS NOT NULL AND length(trim(topic)) > 0
+           GROUP BY topic`)
+                .all();
+            for (const r of topicRows) {
+                const existing = counts.get(r.topic.trim().toLowerCase());
+                if (existing)
+                    existing.count += r.cnt - 1; // already added 1 above
+                accept(r.topic, 'topic');
+                if (existing) {
+                    // Increment with the SQL-derived count (offset by the 1 accept added).
+                    const e = counts.get(r.topic.trim().toLowerCase());
+                    if (e)
+                        e.count = Math.max(e.count, r.cnt);
+                }
+            }
+        }
+        catch { /* chunks.topic column missing or query fails */ }
+        try {
+            const epRows = this.conn
+                .prepare(`SELECT topics, entities FROM episodes`)
+                .all();
+            for (const row of epRows) {
+                if (row.topics) {
+                    try {
+                        const arr = JSON.parse(row.topics);
+                        if (Array.isArray(arr))
+                            for (const t of arr)
+                                if (typeof t === 'string')
+                                    accept(t, 'topic');
+                    }
+                    catch { /* skip malformed JSON */ }
+                }
+                if (row.entities) {
+                    try {
+                        const arr = JSON.parse(row.entities);
+                        if (Array.isArray(arr))
+                            for (const e of arr)
+                                if (typeof e === 'string')
+                                    accept(e, 'entity');
+                    }
+                    catch { /* skip malformed JSON */ }
+                }
+            }
+        }
+        catch { /* episodes table missing */ }
+        const all = [...counts.entries()]
+            .map(([name, v]) => ({ name, display: v.display, kind: v.kind, count: v.count }))
+            .filter(e => e.count >= minCount);
+        all.sort((a, b) => b.count - a.count || a.name.length - b.name.length);
+        return all.slice(0, maxItems);
+    }
+    // ── Commitments ───────────────────────────────────────────────────
+    /**
+     * Insert a commitment, deduping on the fingerprint. If a row with the
+     * same fingerprint already exists, the existing id is returned and no
+     * write occurs — keeps the regex detector + LLM extractor from creating
+     * duplicates of the same promise.
+     */
+    upsertCommitment(entry) {
+        const existing = this.conn
+            .prepare('SELECT id FROM commitments WHERE fingerprint = ?')
+            .get(entry.fingerprint);
+        if (existing) {
+            return { id: existing.id, created: false };
+        }
+        const result = this.conn
+            .prepare(`INSERT INTO commitments
+         (fingerprint, source, owner, text, session_key, transcript_id, episode_id, due_at, due_hint)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(entry.fingerprint, entry.source, entry.owner, entry.text, entry.sessionKey ?? null, entry.transcriptId ?? null, entry.episodeId ?? null, entry.dueAt ?? null, entry.dueHint ?? null);
+        return { id: result.lastInsertRowid, created: true };
+    }
+    /**
+     * List commitments with optional filters. Sorted by due_at ASC NULLS LAST
+     * so overdue + soon-due float to the top.
+     */
+    listCommitments(opts = {}) {
+        const params = [];
+        const where = [];
+        if (opts.status) {
+            where.push('status = ?');
+            params.push(opts.status);
+        }
+        if (opts.sessionKey) {
+            where.push('session_key = ?');
+            params.push(opts.sessionKey);
+        }
+        if (opts.owner) {
+            where.push('owner = ?');
+            params.push(opts.owner);
+        }
+        if (opts.overdueOnly) {
+            where.push("due_at IS NOT NULL AND due_at < datetime('now') AND status = 'open'");
+        }
+        else if (opts.dueBeforeIso) {
+            where.push('due_at IS NOT NULL AND due_at <= ?');
+            params.push(opts.dueBeforeIso);
+        }
+        // Suppress snoozed rows from "open" view unless caller asked for status explicitly.
+        // Wrapping both sides in datetime() so ISO-8601 strings (with T/Z/millis) and
+        // SQLite's space-separated `datetime('now')` format compare correctly.
+        if (opts.status === 'open' || (!opts.status && !opts.overdueOnly)) {
+            where.push("(snoozed_until IS NULL OR datetime(snoozed_until) <= datetime('now'))");
+        }
+        const limit = Math.max(1, Math.min(opts.limit ?? 50, 500));
+        const sql = `SELECT * FROM commitments
+                 ${where.length ? 'WHERE ' + where.join(' AND ') : ''}
+                 ORDER BY (due_at IS NULL) ASC, due_at ASC, created_at DESC
+                 LIMIT ?`;
+        params.push(limit);
+        const rows = this.conn.prepare(sql).all(...params);
+        return rows.map(r => ({
+            id: r.id,
+            fingerprint: r.fingerprint,
+            source: r.source,
+            owner: r.owner,
+            text: r.text,
+            sessionKey: r.session_key,
+            transcriptId: r.transcript_id,
+            episodeId: r.episode_id,
+            dueAt: r.due_at,
+            dueHint: r.due_hint,
+            status: r.status,
+            createdAt: r.created_at,
+            completedAt: r.completed_at,
+            snoozedUntil: r.snoozed_until,
+        }));
+    }
+    /**
+     * Update commitment status. 'done' / 'cancelled' set completed_at; 'snooze'
+     * (with snoozeIso) bumps snoozed_until without changing status so the row
+     * stays open but suppressed from greeting until the snooze expires.
+     */
+    updateCommitmentStatus(id, update) {
+        const sets = [];
+        const vals = [];
+        if (update.status) {
+            sets.push('status = ?');
+            vals.push(update.status);
+            if (update.status === 'done' || update.status === 'cancelled') {
+                sets.push("completed_at = datetime('now')");
+            }
+        }
+        if (update.snoozeUntilIso !== undefined) {
+            sets.push('snoozed_until = ?');
+            vals.push(update.snoozeUntilIso);
+        }
+        if (update.notes !== undefined) {
+            sets.push('notes = ?');
+            vals.push(update.notes);
+        }
+        if (sets.length === 0)
+            return false;
+        vals.push(id);
+        const result = this.conn.prepare(`UPDATE commitments SET ${sets.join(', ')} WHERE id = ?`).run(...vals);
+        return result.changes > 0;
+    }
     /**
      * Fetch a slice of transcripts by id range for consolidation. Used by
      * the consolidation module to materialize the conversation it's about

package/package.json

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