@cleocode/core 2026.4.58 → 2026.4.59

package/dist/memory/memory-bridge.js

@@ -0,0 +1,382 @@
+/**
+ * Memory Bridge Generator
+ *
+ * Generates .cleo/memory-bridge.md from brain.db content. This file is
+ * @-referenced by CLEO-INJECTION.md so that any provider (Claude Code,
+ * OpenCode, Cursor, etc.) automatically loads project memory context.
+ *
+ * Content assembly:
+ *   - Last session handoff summary
+ *   - High-confidence learnings
+ *   - Active patterns (follow + avoid)
+ *   - Recent decisions
+ *   - Recent observations
+ *
+ * Regeneration triggers:
+ *   - session.end
+ *   - tasks.complete
+ *   - memory.observe (high-confidence observations only)
+ *   - Manual: cleo refresh-memory
+ *
+ * @task T5240
+ * @epic T5149
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getLastHandoff } from '../sessions/handoff.js';
+/** Default configuration. */
+const DEFAULT_CONFIG = {
+    maxObservations: 10,
+    maxLearnings: 8,
+    maxPatterns: 8,
+    maxDecisions: 5,
+    includeHandoff: true,
+    includeAntiPatterns: true,
+};
+// ============================================================================
+// Memory Decay Configuration (T028)
+// ============================================================================
+/**
+ * Confidence decay for old memories.
+ *
+ * effectiveConfidence = confidence * decayRate ^ (ageDays / halfLifeDays)
+ *
+ * With defaults: confidence halves every 90 days.
+ * A 0.9-confidence learning that is 180 days old has effective confidence:
+ *   0.9 * 0.5^(180/90) = 0.9 * 0.25 = 0.225 → would be filtered out (< 0.6 threshold).
+ *
+ * Memories with an `updated_at` timestamp use that instead of `created_at`,
+ * so referenced/updated memories decay more slowly.
+ */
+const DECAY_RATE = 0.5;
+const DECAY_HALF_LIFE_DAYS = 90;
+const DECAY_MIN_CONFIDENCE_THRESHOLD = 0.6;
+/** Type-safe wrapper for StatementSync.all(). */
+function typedAll(db, sql, ...params) {
+    return db.prepare(sql).all(...params);
+}
+/**
+ * Generate memory bridge content from brain.db.
+ * Returns the markdown string (does not write to disk).
+ */
+export async function generateMemoryBridgeContent(projectRoot, config) {
+    const cfg = { ...DEFAULT_CONFIG, ...config };
+    // Ensure brain.db is initialized
+    const { getBrainDb, getBrainNativeDb } = await import('../store/brain-sqlite.js');
+    await getBrainDb(projectRoot);
+    const nativeDb = getBrainNativeDb();
+    if (!nativeDb) {
+        return buildEmptyBridge();
+    }
+    const lines = [
+        '# CLEO Memory Bridge',
+        '',
+        `> Auto-generated at ${new Date().toISOString().slice(0, 19)}`,
+        '> Do not edit manually. Regenerate with `cleo refresh-memory`.',
+        '',
+    ];
+    // --- Last session handoff ---
+    if (cfg.includeHandoff) {
+        const handoffData = await getLastHandoffSafe(projectRoot);
+        if (handoffData) {
+            const h = handoffData.handoff;
+            lines.push('## Last Session');
+            lines.push('');
+            lines.push(`- **Session**: ${handoffData.sessionId}`);
+            if (h.lastTask) {
+                lines.push(`- **Last focused task**: ${h.lastTask}`);
+            }
+            if (h.tasksCompleted.length > 0) {
+                lines.push(`- **Completed**: ${h.tasksCompleted.join(', ')}`);
+            }
+            if (h.nextSuggested.length > 0) {
+                lines.push(`- **Next suggested**: ${h.nextSuggested.join(', ')}`);
+            }
+            if (h.openBlockers.length > 0) {
+                lines.push(`- **Open blockers**: ${h.openBlockers.join(', ')}`);
+            }
+            if (h.note) {
+                lines.push(`- **Note**: ${h.note}`);
+            }
+            lines.push('');
+        }
+    }
+    // --- Decisions ---
+    const decisions = queryRecentDecisions(nativeDb, cfg.maxDecisions);
+    if (decisions.length > 0) {
+        lines.push('## Recent Decisions');
+        lines.push('');
+        for (const d of decisions) {
+            const date = (d.created_at ?? '').slice(0, 10);
+            lines.push(`- [${d.id}] ${d.decision.slice(0, 300)} (${date})`);
+        }
+        lines.push('');
+    }
+    // --- Learnings ---
+    const learnings = queryHighConfidenceLearnings(nativeDb, cfg.maxLearnings);
+    if (learnings.length > 0) {
+        lines.push('## Key Learnings');
+        lines.push('');
+        for (const l of learnings) {
+            lines.push(`- [${l.id}] ${l.insight.slice(0, 400)} (confidence: ${l.confidence})`);
+        }
+        lines.push('');
+    }
+    // --- Patterns to Follow (success, workflow, optimization) ---
+    const followPatterns = queryUsefulPatterns(nativeDb, 'follow', cfg.maxPatterns);
+    if (followPatterns.length > 0) {
+        lines.push('## Patterns to Follow');
+        lines.push('');
+        for (const p of followPatterns) {
+            lines.push(`- [${p.id}] ${p.pattern.slice(0, 300)} (${p.type})`);
+        }
+        lines.push('');
+    }
+    // --- Anti-Patterns to Avoid (failure, blocker) ---
+    if (cfg.includeAntiPatterns) {
+        const avoidPatterns = queryUsefulPatterns(nativeDb, 'avoid', cfg.maxPatterns);
+        if (avoidPatterns.length > 0) {
+            lines.push('## Anti-Patterns to Avoid');
+            lines.push('');
+            for (const p of avoidPatterns) {
+                lines.push(`- [${p.id}] AVOID: ${p.pattern.slice(0, 300)}`);
+            }
+            lines.push('');
+        }
+    }
+    // --- Recent observations ---
+    const observations = queryRecentObservations(nativeDb, cfg.maxObservations);
+    if (observations.length > 0) {
+        lines.push('## Recent Observations');
+        lines.push('');
+        for (const o of observations) {
+            const date = (o.created_at ?? '').slice(0, 10);
+            lines.push(`- [${o.id}] ${date}: ${o.title.slice(0, 200)}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+/**
+ * Write memory bridge content to .cleo/memory-bridge.md.
+ */
+export async function writeMemoryBridge(projectRoot, config) {
+    const cleoDir = join(projectRoot, '.cleo');
+    const bridgePath = join(cleoDir, 'memory-bridge.md');
+    try {
+        const content = await generateMemoryBridgeContent(projectRoot, config);
+        if (!existsSync(cleoDir)) {
+            mkdirSync(cleoDir, { recursive: true });
+        }
+        // Only write if content changed (avoid unnecessary git noise)
+        if (existsSync(bridgePath)) {
+            const existing = readFileSync(bridgePath, 'utf-8');
+            // Compare without the timestamp line
+            const stripTimestamp = (s) => s.replace(/^> Auto-generated at .*/m, '');
+            if (stripTimestamp(existing) === stripTimestamp(content)) {
+                return { path: bridgePath, written: false };
+            }
+        }
+        writeFileSync(bridgePath, content, 'utf-8');
+        return { path: bridgePath, written: true };
+    }
+    catch (err) {
+        console.error('[CLEO] Failed to write memory bridge:', err instanceof Error ? err.message : String(err));
+        return { path: bridgePath, written: false };
+    }
+}
+/**
+ * Best-effort refresh: call from session.end, tasks.complete, or memory.observe.
+ * Never throws.
+ *
+ * @param projectRoot - Absolute path to the project root.
+ * @param scope - Optional session scope for context-aware generation (T139).
+ * @param currentTaskId - Optional current task ID for scoped context (T139).
+ */
+export async function refreshMemoryBridge(projectRoot, scope, currentTaskId) {
+    try {
+        const { loadConfig } = await import('../config.js');
+        const config = await loadConfig(projectRoot);
+        if (config.brain?.memoryBridge?.contextAware && scope) {
+            await generateContextAwareContent(projectRoot, scope, currentTaskId);
+        }
+        else {
+            await writeMemoryBridge(projectRoot);
+        }
+    }
+    catch (err) {
+        console.error('[CLEO] Memory bridge refresh failed:', err instanceof Error ? err.message : String(err));
+    }
+}
+/**
+ * Generate context-aware memory bridge content and write to disk.
+ *
+ * When `brain.memoryBridge.contextAware` is true and a scope is available,
+ * uses hybridSearch() to surface memories relevant to the current scope,
+ * then enforces the `brain.memoryBridge.maxTokens` budget.
+ *
+ * Falls back to standard generation if hybrid search is unavailable.
+ * Never throws.
+ *
+ * @param projectRoot - Absolute path to the project root.
+ * @param scope - Session scope string (e.g. 'global', 'epic:T###').
+ * @param currentTaskId - Optional current task ID for narrower scoping.
+ * @task T139 @epic T134
+ */
+export async function generateContextAwareContent(projectRoot, scope, currentTaskId) {
+    try {
+        const { loadConfig } = await import('../config.js');
+        const config = await loadConfig(projectRoot);
+        const maxTokens = config.brain?.memoryBridge?.maxTokens ?? 2000;
+        // Build a search query from scope + currentTaskId
+        const query = currentTaskId ? `${scope} ${currentTaskId}` : scope;
+        let contextSections = [];
+        try {
+            const { hybridSearch } = await import('./brain-search.js');
+            const hits = await hybridSearch(query, projectRoot, { limit: 10 });
+            if (hits && hits.length > 0) {
+                contextSections = hits
+                    .slice(0, 5)
+                    .map((h) => `- [${h.id}] ${h.title ?? h.text?.slice(0, 120) ?? ''}`);
+            }
+        }
+        catch {
+            // Hybrid search unavailable — fall back to standard generation
+            await writeMemoryBridge(projectRoot);
+            return;
+        }
+        // Build content with token budget enforcement (rough estimate: 4 chars/token)
+        const charsPerToken = 4;
+        const budgetChars = maxTokens * charsPerToken;
+        const cleoDir = join(projectRoot, '.cleo');
+        const bridgePath = join(cleoDir, 'memory-bridge.md');
+        const headerLines = [
+            '# CLEO Memory Bridge',
+            '',
+            `> Auto-generated at ${new Date().toISOString().slice(0, 19)} (context-aware: ${scope})`,
+            '> Do not edit manually. Regenerate with `cleo refresh-memory`.',
+            '',
+        ];
+        const contextBlock = contextSections.length > 0 ? ['## Relevant Context', '', ...contextSections, ''] : [];
+        // Append standard content but enforce token budget
+        const standardContent = await generateMemoryBridgeContent(projectRoot);
+        const combined = [...headerLines, ...contextBlock].join('\n');
+        const remainingChars = budgetChars - combined.length;
+        const finalContent = remainingChars > 200 ? combined + '\n' + standardContent.slice(0, remainingChars) : combined;
+        if (!existsSync(cleoDir)) {
+            mkdirSync(cleoDir, { recursive: true });
+        }
+        writeFileSync(bridgePath, finalContent, 'utf-8');
+    }
+    catch {
+        // Best-effort — fall through to standard generation
+        try {
+            await writeMemoryBridge(projectRoot);
+        }
+        catch {
+            // Ignore
+        }
+    }
+}
+// ============================================================================
+// Query helpers
+// ============================================================================
+/** Wrapper around getLastHandoff that never throws. */
+async function getLastHandoffSafe(projectRoot) {
+    try {
+        return await getLastHandoff(projectRoot);
+    }
+    catch {
+        return null;
+    }
+}
+function queryRecentDecisions(db, limit) {
+    try {
+        return typedAll(db, 'SELECT id, decision, created_at FROM brain_decisions ORDER BY created_at DESC LIMIT ?', limit);
+    }
+    catch {
+        return [];
+    }
+}
+function queryHighConfidenceLearnings(db, limit) {
+    try {
+        // Fetch more than needed so we can apply decay filtering client-side.
+        // We fetch 3x the limit to account for entries that will be filtered out.
+        const candidates = typedAll(db, `SELECT id, insight, confidence, created_at, updated_at FROM brain_learnings
+         WHERE CAST(confidence AS REAL) >= 0.3
+           AND insight NOT LIKE 'Completed:%'
+         ORDER BY confidence DESC, created_at DESC
+         LIMIT ?`, limit * 3);
+        // Apply confidence decay based on age (T028).
+        // Uses updated_at if available (referenced memories decay slower),
+        // otherwise falls back to created_at.
+        const now = Date.now();
+        const MS_PER_DAY = 86_400_000;
+        return candidates
+            .map((row) => {
+            const referenceDate = row.updated_at || row.created_at;
+            const ageDays = Math.max(0, (now - new Date(referenceDate).getTime()) / MS_PER_DAY);
+            const rawConfidence = parseFloat(row.confidence) || 0;
+            const effectiveConfidence = rawConfidence * DECAY_RATE ** (ageDays / DECAY_HALF_LIFE_DAYS);
+            return { ...row, effectiveConfidence };
+        })
+            .filter((row) => row.effectiveConfidence >= DECAY_MIN_CONFIDENCE_THRESHOLD)
+            .sort((a, b) => b.effectiveConfidence - a.effectiveConfidence)
+            .slice(0, limit)
+            .map(({ effectiveConfidence, ...row }) => ({
+            ...row,
+            // Override displayed confidence with effective value for transparency
+            confidence: effectiveConfidence.toFixed(2),
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+function queryUsefulPatterns(db, mode, limit) {
+    try {
+        const typeFilter = mode === 'follow'
+            ? "type IN ('success', 'workflow', 'optimization')"
+            : "type IN ('failure', 'blocker')";
+        return typedAll(db, `SELECT id, pattern, type, impact, extracted_at FROM brain_patterns
+         WHERE ${typeFilter}
+           AND pattern NOT LIKE 'Recurring label%'
+           AND pattern NOT LIKE 'Test pattern%'
+           AND pattern NOT LIKE 'test'
+           AND pattern NOT LIKE 'Audit probe:%'
+           AND LENGTH(pattern) > 20
+         ORDER BY extracted_at DESC
+         LIMIT ?`, limit);
+    }
+    catch {
+        return [];
+    }
+}
+function queryRecentObservations(db, limit) {
+    try {
+        return typedAll(db, `SELECT id, title, type, created_at FROM brain_observations
+         WHERE type != 'change'
+           AND title NOT LIKE 'File changed:%'
+           AND title NOT LIKE 'Task start:%'
+           AND title NOT LIKE 'Task complete:%'
+           AND title NOT LIKE '[hook]%'
+         ORDER BY created_at DESC LIMIT ?`, limit);
+    }
+    catch {
+        return [];
+    }
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+function buildEmptyBridge() {
+    return [
+        '# CLEO Memory Bridge',
+        '',
+        `> Auto-generated at ${new Date().toISOString().slice(0, 19)}`,
+        '',
+        'No brain.db data available yet. Observations will appear here as you work.',
+        '',
+    ].join('\n');
+}
+//# sourceMappingURL=memory-bridge.js.map

package/dist/memory/memory-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-bridge.js","sourceRoot":"","sources":["../../src/memory/memory-bridge.ts"],"names":[],"mappings":"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"}

package/dist/memory/mental-model-injection.js

@@ -0,0 +1,61 @@
+/**
+ * Pure helpers for validate-on-load mental-model injection.
+ *
+ * These helpers are used by:
+ *   - The Pi CANT bridge (cleo-cant-bridge.ts) to build the system-prompt block
+ *   - T421 empirical tests to assert on preamble content without a real Pi runtime
+ *
+ * No I/O. Safe to call in tests without a real DB or Pi extension context.
+ *
+ * @task T420
+ * @epic T377
+ * @wave W8
+ */
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * Preamble text injected into the Pi system prompt when an agent has a
+ * `mental_model:` CANT block. The agent MUST re-evaluate each observation
+ * against the current project state before acting.
+ *
+ * Exported so empirical tests (T421) can assert on its presence.
+ */
+export const VALIDATE_ON_LOAD_PREAMBLE = '===== MENTAL MODEL (validate-on-load) =====\n' +
+    'These are your prior observations, patterns, and learnings for this project.\n' +
+    'Before acting, you MUST re-evaluate each entry against current project state.\n' +
+    'If an entry is stale, note it and proceed with fresh understanding.';
+// ============================================================================
+// Pure helpers
+// ============================================================================
+/**
+ * Build the validate-on-load mental-model injection string.
+ *
+ * Pure function — no I/O, safe to call in tests without a real DB.
+ *
+ * @param agentName - Name of the spawned agent (used in the header line).
+ * @param observations - Prior mental-model observations to list.
+ * @returns System-prompt block containing the preamble and numbered observations,
+ *          or an empty string when `observations` is empty.
+ *
+ * @example
+ * ```ts
+ * const block = buildMentalModelInjection('my-agent', [
+ *   { id: 'O-abc1', type: 'discovery', title: 'Auth uses JWT', date: '2026-04-08' },
+ * ]);
+ * // block contains VALIDATE_ON_LOAD_PREAMBLE + numbered list
+ * ```
+ */
+export function buildMentalModelInjection(agentName, observations) {
+    if (observations.length === 0)
+        return '';
+    const lines = ['', `// Agent: ${agentName}`, VALIDATE_ON_LOAD_PREAMBLE, ''];
+    for (let i = 0; i < observations.length; i++) {
+        const obs = observations[i];
+        const datePart = obs.date ? ` [${obs.date}]` : '';
+        lines.push(`${i + 1}. [${obs.id}] (${obs.type})${datePart}: ${obs.title}`);
+    }
+    lines.push('===== END MENTAL MODEL =====');
+    return lines.join('\n');
+}
+//# sourceMappingURL=mental-model-injection.js.map

package/dist/memory/mental-model-injection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mental-model-injection.js","sourceRoot":"","sources":["../../src/memory/mental-model-injection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAkBH,+EAA+E;AAC/E,YAAY;AACZ,+EAA+E;AAE/E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GACpC,+CAA+C;IAC/C,gFAAgF;IAChF,iFAAiF;IACjF,qEAAqE,CAAC;AAExE,+EAA+E;AAC/E,eAAe;AACf,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,yBAAyB,CACvC,SAAiB,EACjB,YAAsC;IAEtC,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEzC,MAAM,KAAK,GAAa,CAAC,EAAE,EAAE,aAAa,SAAS,EAAE,EAAE,yBAAyB,EAAE,EAAE,CAAC,CAAC;IAEtF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,YAAY,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7C,MAAM,GAAG,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;QAC5B,MAAM,QAAQ,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QAClD,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,MAAM,GAAG,CAAC,IAAI,IAAI,QAAQ,KAAK,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC;IAC7E,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC;IAE3C,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/memory/mental-model-queue.js

@@ -0,0 +1,211 @@
+/**
+ * Async reinforcement queue for non-blocking mental-model writes.
+ *
+ * ULTRAPLAN L5 compliance: observations tagged with an `agent` provenance and a
+ * mental-model-relevant type ('discovery', 'change', 'feature', 'decision') are
+ * routed through this queue instead of writing synchronously to brain.db. This
+ * decouples the hot path (agent execution) from I/O latency.
+ *
+ * The queue is drained to brain.db either:
+ *   1. Periodically — every {@link FLUSH_INTERVAL_MS} milliseconds via a timer.
+ *   2. On high watermark — when the queue exceeds {@link FLUSH_WATERMARK} entries.
+ *   3. On process exit — SIGINT, SIGTERM, and 'exit' hooks perform a best-effort
+ *      synchronous flush so no observations are lost.
+ *
+ * Observations without an `agent` field continue to use the existing synchronous
+ * path in observeBrain() and are never routed here.
+ *
+ * @task T383/T419
+ * @epic T377
+ */
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Drain interval in milliseconds. */
+const FLUSH_INTERVAL_MS = 5_000;
+/** Drain when queue exceeds this many entries, regardless of timer. */
+const FLUSH_WATERMARK = 50;
+// ---------------------------------------------------------------------------
+// Observation types that route through the mental-model queue.
+// ---------------------------------------------------------------------------
+/**
+ * Observation types that are considered mental-model relevant and therefore
+ * eligible for async queuing when produced by a named agent.
+ */
+const MENTAL_MODEL_TYPES = new Set([
+    'discovery',
+    'change',
+    'feature',
+    'decision',
+    'bugfix',
+    'refactor',
+]);
+// ---------------------------------------------------------------------------
+// Queue implementation
+// ---------------------------------------------------------------------------
+/** In-memory queue of pending mental-model observations. */
+const _queue = [];
+/** Whether a flush is currently in progress (prevents re-entrant flushes). */
+let _flushing = false;
+/** Whether process-exit hooks have been registered. */
+let _hooksRegistered = false;
+/** Handle for the periodic flush timer (undefined = no active timer). */
+let _timer;
+/**
+ * Drain the queue synchronously where possible, or fall back to async writes.
+ * Returns when all observations in the current batch have been persisted.
+ */
+async function drainQueue() {
+    if (_queue.length === 0)
+        return 0;
+    // Snapshot current batch and clear the queue
+    const batch = _queue.splice(0, _queue.length);
+    let count = 0;
+    // Import observeBrain lazily to avoid circular dependencies at module load
+    const { observeBrain } = await import('./brain-retrieval.js');
+    for (const entry of batch) {
+        try {
+            const result = await observeBrain(entry.projectRoot, entry.params);
+            entry.resolve(result);
+            count++;
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            entry.reject(error);
+        }
+    }
+    return count;
+}
+/**
+ * Best-effort synchronous exit flush.
+ * Used in 'exit' event handler where async I/O is not guaranteed.
+ * Falls back to fire-and-forget if the environment does not support
+ * synchronous-style promises (i.e., in environments where the event
+ * loop may already be draining).
+ */
+function exitFlush() {
+    if (_queue.length === 0)
+        return;
+    // We can't reliably await in a synchronous exit handler. The best we
+    // can do is trigger the drain and hope the pending writes complete.
+    drainQueue().catch(() => {
+        // Silently swallow — process is terminating anyway
+    });
+}
+/**
+ * Register process-exit hooks once.
+ * Ensures that no observations are silently dropped on graceful shutdown.
+ */
+function registerExitHooks() {
+    if (_hooksRegistered)
+        return;
+    _hooksRegistered = true;
+    process.on('exit', exitFlush);
+    process.once('SIGINT', () => {
+        drainQueue()
+            .catch(() => {
+            /* best-effort */
+        })
+            .finally(() => {
+            process.exit(130); // 128 + SIGINT
+        });
+    });
+    process.once('SIGTERM', () => {
+        drainQueue()
+            .catch(() => {
+            /* best-effort */
+        })
+            .finally(() => {
+            process.exit(143); // 128 + SIGTERM
+        });
+    });
+}
+/**
+ * Start the periodic flush timer if it isn't already running.
+ */
+function ensureTimer() {
+    if (_timer !== undefined)
+        return;
+    _timer = setInterval(() => {
+        if (_queue.length === 0)
+            return;
+        if (_flushing)
+            return;
+        _flushing = true;
+        drainQueue()
+            .catch(() => {
+            /* best-effort */
+        })
+            .finally(() => {
+            _flushing = false;
+        });
+    }, FLUSH_INTERVAL_MS);
+    // Unref so the timer doesn't prevent process exit when queue is idle
+    if (typeof _timer.unref === 'function') {
+        _timer.unref();
+    }
+}
+// ---------------------------------------------------------------------------
+// Public singleton
+// ---------------------------------------------------------------------------
+/**
+ * Mental-model queue singleton.
+ *
+ * Use this instead of calling observeBrain() directly when writing agent-tagged
+ * observations that should be queued for async persistence (ULTRAPLAN L5).
+ */
+export const mentalModelQueue = {
+    enqueue(projectRoot, params) {
+        registerExitHooks();
+        ensureTimer();
+        return new Promise((resolve, reject) => {
+            _queue.push({ projectRoot, params, resolve, reject });
+            // High-watermark flush
+            if (_queue.length >= FLUSH_WATERMARK && !_flushing) {
+                _flushing = true;
+                drainQueue()
+                    .catch(() => {
+                    /* best-effort */
+                })
+                    .finally(() => {
+                    _flushing = false;
+                });
+            }
+        });
+    },
+    async flush() {
+        if (_flushing) {
+            // Wait for the current flush to settle then flush again
+            await new Promise((r) => setTimeout(r, 50));
+        }
+        _flushing = true;
+        try {
+            return await drainQueue();
+        }
+        finally {
+            _flushing = false;
+        }
+    },
+    size() {
+        return _queue.length;
+    },
+};
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Determine whether an observation should be routed through the mental-model
+ * queue rather than written synchronously.
+ *
+ * Returns `true` when the observation has a non-empty `agent` field AND a
+ * mental-model-relevant type.
+ *
+ * @param params - Observation parameters to evaluate.
+ */
+export function isMentalModelObservation(params) {
+    if (!params.agent)
+        return false;
+    const type = params.type ?? 'discovery';
+    return MENTAL_MODEL_TYPES.has(type);
+}
+//# sourceMappingURL=mental-model-queue.js.map