@kognai/orchestrator-core 0.1.0

package/dist/lib/anthropic-direct.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * anthropic-direct.ts — Minimal Anthropic Messages API client.
+ *
+ * Bypasses OpenClaw gateway entirely. OpenClaw is an agentic gateway that
+ * wraps requests with its workspace agent's IDENTITY.md (e.g. "Nova"),
+ * overriding caller-supplied system prompts. For senior-coder we need a
+ * clean, identity-less Sonnet call.
+ *
+ * Zero npm deps (uses node `https`). Reads ANTHROPIC_API_KEY from env.
+ *
+ * Created: 2026-04-28 after senior-coder responses came back as "Nova".
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.callAnthropic = callAnthropic;
+const https = __importStar(require("https"));
+const ANTHROPIC_KEY = process.env.ANTHROPIC_API_KEY || '';
+const ANTHROPIC_VERSION = '2023-06-01';
+const DEFAULT_TIMEOUT_MS = 60_000;
+async function callAnthropic(opts) {
+    if (!ANTHROPIC_KEY)
+        throw new Error('ANTHROPIC_API_KEY not set');
+    const body = JSON.stringify({
+        model: opts.model,
+        max_tokens: opts.max_tokens ?? 800,
+        temperature: opts.temperature ?? 0.4,
+        system: opts.system,
+        messages: [{ role: 'user', content: opts.user }],
+    });
+    return new Promise((resolve, reject) => {
+        const req = https.request({
+            hostname: 'api.anthropic.com',
+            path: '/v1/messages',
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': ANTHROPIC_KEY,
+                'anthropic-version': ANTHROPIC_VERSION,
+                'Content-Length': Buffer.byteLength(body),
+            },
+            timeout: opts.timeout_ms ?? DEFAULT_TIMEOUT_MS,
+        }, (res) => {
+            let chunks = '';
+            res.on('data', (c) => (chunks += c));
+            res.on('end', () => {
+                try {
+                    const parsed = JSON.parse(chunks);
+                    if (parsed.error) {
+                        reject(new Error(`Anthropic ${parsed.error.type}: ${parsed.error.message}`));
+                        return;
+                    }
+                    const text = parsed.content
+                        .filter((c) => c.type === 'text')
+                        .map((c) => c.text || '')
+                        .join('');
+                    resolve({
+                        content: text,
+                        input_tokens: parsed.usage?.input_tokens ?? 0,
+                        output_tokens: parsed.usage?.output_tokens ?? 0,
+                        stop_reason: parsed.stop_reason ?? 'unknown',
+                    });
+                }
+                catch (e) {
+                    reject(new Error(`Anthropic parse failed (HTTP ${res.statusCode}): ${chunks.slice(0, 300)}`));
+                }
+            });
+        });
+        req.on('error', reject);
+        req.on('timeout', () => {
+            req.destroy();
+            reject(new Error(`Anthropic timeout after ${opts.timeout_ms ?? DEFAULT_TIMEOUT_MS}ms`));
+        });
+        req.write(body);
+        req.end();
+    });
+}

package/dist/lib/asmr-extractor.d.ts

@@ -0,0 +1,40 @@
+/**
+ * asmr-extractor.ts — AMD-21 ASMR Six-Vector Extraction Engine (Sprint 1511)
+ *
+ * Extracts six semantic vectors from AARReceipt entries for episodic memory.
+ * Vectors: topic, emotion, stance, entities, temporality, intent
+ *
+ * Routing: T1 LOCAL (qwen3:4b) — cost-efficient, zero data egress
+ * Fail-open: LLM error → minimal fallback vectors derived from actionSummary
+ * Storage: logs/asmr/YYYY-MM-DD.jsonl
+ *
+ * FP-007: < 200 lines
+ */
+import { AARReceipt } from './aar-types';
+export interface ASMRVectors {
+    topic: string;
+    emotion: string;
+    stance: string;
+    entities: string[];
+    temporality: string;
+    intent: string;
+}
+export interface ASMREntry {
+    id: string;
+    agentId: string;
+    taskId: string;
+    sprintId: string;
+    timestamp: string;
+    actionSummary: string;
+    vectors: ASMRVectors;
+}
+/**
+ * Extract six semantic vectors from an AAR receipt entry.
+ * Fail-open: on LLM error returns minimal fallback vectors.
+ */
+export declare function extractSixVectors(entry: AARReceipt): Promise<ASMRVectors>;
+/**
+ * Extract six vectors and persist the ASMR entry to daily JSONL log.
+ * Log write failure is non-fatal — entry is always returned.
+ */
+export declare function extractAndStore(entry: AARReceipt): Promise<ASMREntry>;

package/dist/lib/asmr-extractor.js

@@ -0,0 +1,151 @@
+"use strict";
+/**
+ * asmr-extractor.ts — AMD-21 ASMR Six-Vector Extraction Engine (Sprint 1511)
+ *
+ * Extracts six semantic vectors from AARReceipt entries for episodic memory.
+ * Vectors: topic, emotion, stance, entities, temporality, intent
+ *
+ * Routing: T1 LOCAL (qwen3:4b) — cost-efficient, zero data egress
+ * Fail-open: LLM error → minimal fallback vectors derived from actionSummary
+ * Storage: logs/asmr/YYYY-MM-DD.jsonl
+ *
+ * FP-007: < 200 lines
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractSixVectors = extractSixVectors;
+exports.extractAndStore = extractAndStore;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const engine_paths_1 = require("./engine-paths");
+const model_router_registry_1 = require("./model-router-registry");
+// ── Config ────────────────────────────────────────────────────────────────────
+const LOG_DIR = path.join((0, engine_paths_1.resolveEnginePaths)().root, 'logs', 'asmr');
+const EXTRACT_SYSTEM = `You are a structured episodic memory extraction engine.
+Extract exactly six semantic vectors from the agent action entry provided.
+Respond ONLY with valid JSON — no markdown fences, no commentary, no prose.
+Required JSON shape:
+{
+  "topic": "one sentence: primary task domain",
+  "emotion": "one word from: success|failure|blocked|uncertain|neutral",
+  "stance": "one sentence: agent posture (e.g. cautious refactoring, aggressive build)",
+  "entities": ["array", "of", "key", "nouns", "files", "agents", "concepts"],
+  "temporality": "one phrase: timing relative to sprint (e.g. mid-sprint, post-gate)",
+  "intent": "one sentence: the goal the agent was trying to achieve"
+}`;
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function stripThink(text) {
+    return text.replace(/<think>[\s\S]*?<\/think>/gi, '').trim();
+}
+function fallbackVectors(entry) {
+    return {
+        topic: entry.actionSummary.slice(0, 120),
+        emotion: entry.status === 'success' ? 'success'
+            : entry.status === 'failed' ? 'failure'
+                : 'neutral',
+        stance: 'autonomous execution',
+        entities: [entry.agentId, entry.taskId, entry.sprintId].filter(Boolean),
+        temporality: 'sprint-time',
+        intent: `${entry.agentId} executed task ${entry.taskId}`,
+    };
+}
+function getLogPath(timestamp) {
+    const date = new Date(timestamp).toISOString().slice(0, 10);
+    return path.join(LOG_DIR, `${date}.jsonl`);
+}
+// ── Core extractor ────────────────────────────────────────────────────────────
+/**
+ * Extract six semantic vectors from an AAR receipt entry.
+ * Fail-open: on LLM error returns minimal fallback vectors.
+ */
+async function extractSixVectors(entry) {
+    try {
+        const prompt = [
+            `Agent: ${entry.agentId} | Sprint: ${entry.sprintId} | Task: ${entry.taskId}`,
+            `Status: ${entry.status} | Score: ${entry.outcomeScore}`,
+            `Summary: ${entry.actionSummary}`,
+            `\nExtract six semantic vectors as JSON.`,
+        ].join('\n');
+        const response = await (0, model_router_registry_1.getModelRouter)().routeCall({
+            task_type: 'asmr_extraction',
+            tier_class: 'text',
+            complexity: 'local', // T1 qwen3:4b
+            context_tokens: Math.ceil((prompt.length + EXTRACT_SYSTEM.length) / 4),
+            constitutional_flag: false,
+            agent_id: 'asmr-extractor',
+            payload: { system: EXTRACT_SYSTEM, prompt },
+        });
+        const cleaned = stripThink(response.content);
+        const jsonMatch = cleaned.match(/\{[\s\S]*\}/);
+        if (!jsonMatch)
+            throw new Error('No JSON found in LLM response');
+        const p = JSON.parse(jsonMatch[0]);
+        return {
+            topic: typeof p.topic === 'string' ? p.topic : entry.actionSummary.slice(0, 120),
+            emotion: typeof p.emotion === 'string' ? p.emotion : 'neutral',
+            stance: typeof p.stance === 'string' ? p.stance : 'autonomous execution',
+            entities: Array.isArray(p.entities) ? p.entities : [entry.agentId],
+            temporality: typeof p.temporality === 'string' ? p.temporality : 'sprint-time',
+            intent: typeof p.intent === 'string' ? p.intent : entry.actionSummary.slice(0, 120),
+        };
+    }
+    catch {
+        return fallbackVectors(entry);
+    }
+}
+/**
+ * Extract six vectors and persist the ASMR entry to daily JSONL log.
+ * Log write failure is non-fatal — entry is always returned.
+ */
+async function extractAndStore(entry) {
+    const vectors = await extractSixVectors(entry);
+    const asmrEntry = {
+        id: entry.receiptId,
+        agentId: entry.agentId,
+        taskId: entry.taskId,
+        sprintId: entry.sprintId,
+        timestamp: entry.timestamp,
+        actionSummary: entry.actionSummary,
+        vectors,
+    };
+    try {
+        fs.mkdirSync(LOG_DIR, { recursive: true });
+        fs.appendFileSync(getLogPath(entry.timestamp), JSON.stringify(asmrEntry) + '\n', 'utf8');
+    }
+    catch {
+        // Log write failure is non-fatal — do not block caller
+    }
+    return asmrEntry;
+}

package/dist/lib/asmr-retrieval.d.ts

@@ -0,0 +1,76 @@
+/**
+ * asmr-retrieval.ts — AMD-21 ASMR Active Memory Retrieval (Sprint 1511)
+ *
+ * Query-driven episodic memory retrieval over the ASMR six-vector store.
+ * Replaces the pattern of loading full MEMORY.md on every agent invocation.
+ *
+ * Strategy: embed query → embed each ASMR entry (sequential) → cosine rank → top-N
+ * Embeddings: nomic-embed-text local (768-dim, no OpenAI dependency)
+ * Cap: MAX_ENTRIES = 500 (newest first across all daily JSONL files)
+ *
+ * FP-007: < 200 lines
+ */
+import { ASMREntry } from './asmr-extractor';
+export interface RankedASMREntry extends ASMREntry {
+    similarity: number;
+}
+/**
+ * Retrieve the most relevant episodic memory entries for a given query.
+ *
+ * Uses cosine similarity over nomic-embed-text embeddings of the six-vector text.
+ * Sequential embedding (not parallel) to avoid Ollama overload.
+ *
+ * @param query   Natural-language retrieval query
+ * @param limit   Maximum number of results to return (default: 5)
+ * @returns       Array of ASMREntry sorted by descending similarity
+ */
+export declare function retrieveRelevantMemories(query: string, limit?: number): Promise<ASMREntry[]>;
+import { BrainXMemory } from './brainx-client';
+export interface MemoryHit {
+    source: 'hot' | 'warm' | 'cold';
+    content: string;
+    score: number;
+    ts: string;
+    provenance: string;
+}
+export interface RetrievalResult {
+    hot: MemoryHit[];
+    warm: MemoryHit[];
+    cold: MemoryHit[];
+    merged: MemoryHit[];
+    latency_ms: {
+        hot: number;
+        warm: number;
+        cold: number;
+        total: number;
+    };
+}
+export interface ThreeTierOpts {
+    hotTurns?: number;
+    warmDays?: number;
+    maxResults?: number;
+    coldThresholdDays?: number;
+    /** Inject a BrainXClient — primarily for testing. Default: real client. */
+    brainx?: {
+        retrieve(query: string, opts?: any): Promise<BrainXMemory[]>;
+    };
+    /** Override cold-scan root directory (testing). Default: workspace/asmr. */
+    coldRoot?: string;
+    /** Disable cold scan entirely (testing or perf). Default: false. */
+    skipCold?: boolean;
+}
+/** Append a turn to the hot buffer. Caller-driven population. */
+export declare function appendHotTurn(agentId: string, content: string, score?: number, capacity?: number): void;
+/** Test helper — clear the buffer (single agent or all). */
+export declare function _clearHotBufferForTesting(agentId?: string): void;
+/**
+ * Three-tier retrieval over hot in-memory turns + warm BrainX vectors +
+ * cold archive scan. Returns ranked, deduped results with provenance tags
+ * and a per-tier latency breakdown.
+ *
+ * Cold tier only fires when hot+warm don't hit `maxResults` — keeps the
+ * common path fast.
+ *
+ * Never throws. All three tiers fail-open to empty hits on error.
+ */
+export declare function retrieveThreeTier(query: string, agentId: string, opts?: ThreeTierOpts): Promise<RetrievalResult>;

package/dist/lib/asmr-retrieval.js

@@ -0,0 +1,311 @@
+"use strict";
+/**
+ * asmr-retrieval.ts — AMD-21 ASMR Active Memory Retrieval (Sprint 1511)
+ *
+ * Query-driven episodic memory retrieval over the ASMR six-vector store.
+ * Replaces the pattern of loading full MEMORY.md on every agent invocation.
+ *
+ * Strategy: embed query → embed each ASMR entry (sequential) → cosine rank → top-N
+ * Embeddings: nomic-embed-text local (768-dim, no OpenAI dependency)
+ * Cap: MAX_ENTRIES = 500 (newest first across all daily JSONL files)
+ *
+ * FP-007: < 200 lines
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.retrieveRelevantMemories = retrieveRelevantMemories;
+exports.appendHotTurn = appendHotTurn;
+exports._clearHotBufferForTesting = _clearHotBufferForTesting;
+exports.retrieveThreeTier = retrieveThreeTier;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const engine_paths_1 = require("./engine-paths");
+const brainx_embed_1 = require("./brainx-embed");
+// ── Config ────────────────────────────────────────────────────────────────────
+const ASMR_LOG_DIR = path.join((0, engine_paths_1.resolveEnginePaths)().root, 'logs', 'asmr');
+const MAX_ENTRIES = 500;
+// ── Helpers ───────────────────────────────────────────────────────────────────
+/**
+ * Combine all six ASMR vectors + supporting fields into a single text string
+ * for embedding. This text represents the semantic fingerprint of the entry.
+ */
+function vectorText(e) {
+    const { topic, emotion, stance, entities, temporality, intent } = e.vectors;
+    return [
+        topic,
+        emotion,
+        stance,
+        entities.join(' '),
+        temporality,
+        intent,
+        e.actionSummary,
+        e.agentId,
+        e.sprintId,
+    ]
+        .filter(Boolean)
+        .join(' ');
+}
+/**
+ * Load ASMR entries from all daily JSONL files.
+ * Returns newest entries first, capped at MAX_ENTRIES.
+ */
+async function loadAllEntries() {
+    const entries = [];
+    if (!fs.existsSync(ASMR_LOG_DIR))
+        return entries;
+    const files = fs
+        .readdirSync(ASMR_LOG_DIR)
+        .filter(f => f.endsWith('.jsonl'))
+        .sort()
+        .reverse(); // newest date file first
+    for (const file of files) {
+        if (entries.length >= MAX_ENTRIES)
+            break;
+        const filePath = path.join(ASMR_LOG_DIR, file);
+        let lines;
+        try {
+            lines = fs.readFileSync(filePath, 'utf8').split('\n').filter(Boolean);
+        }
+        catch {
+            continue;
+        }
+        // Read lines in reverse order so newest entries within the day come first
+        for (let i = lines.length - 1; i >= 0; i--) {
+            if (entries.length >= MAX_ENTRIES)
+                break;
+            try {
+                entries.push(JSON.parse(lines[i]));
+            }
+            catch {
+                // Skip malformed JSONL line
+            }
+        }
+    }
+    return entries;
+}
+// ── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Retrieve the most relevant episodic memory entries for a given query.
+ *
+ * Uses cosine similarity over nomic-embed-text embeddings of the six-vector text.
+ * Sequential embedding (not parallel) to avoid Ollama overload.
+ *
+ * @param query   Natural-language retrieval query
+ * @param limit   Maximum number of results to return (default: 5)
+ * @returns       Array of ASMREntry sorted by descending similarity
+ */
+async function retrieveRelevantMemories(query, limit = 5) {
+    const entries = await loadAllEntries();
+    if (entries.length === 0)
+        return [];
+    const queryVec = await (0, brainx_embed_1.embed)(query);
+    const ranked = [];
+    // Sequential embedding — avoids saturating Ollama with parallel requests
+    for (const entry of entries) {
+        try {
+            const entryVec = await (0, brainx_embed_1.embed)(vectorText(entry));
+            const similarity = (0, brainx_embed_1.cosineSimilarity)(queryVec, entryVec);
+            ranked.push({ ...entry, similarity });
+        }
+        catch {
+            // Skip entries that fail to embed
+        }
+    }
+    ranked.sort((a, b) => b.similarity - a.similarity);
+    return ranked.slice(0, limit).map(({ similarity: _s, ...rest }) => rest);
+}
+// ── AMD-21 P3: Three-Tier Retrieval (Sprint 1537) ────────────────────────────
+//
+// Hot:   in-memory ring buffer, recent N turns per agent (O(1) read)
+// Warm:  BrainXClient.retrieve() — pgvector cosine search over recent embeds
+// Cold:  lazy scan of workspace/asmr/<agentId>/*.jsonl when hot+warm <maxResults
+//
+// Pipeline: hot → warm → (cold lazy) → dedupe → rank → cap at maxResults.
+// All three tiers fail-open (errors return empty hits, never throw).
+const crypto_1 = require("crypto");
+const brainx_client_1 = require("./brainx-client");
+// ── Hot-tier ring buffer ─────────────────────────────────────────────────────
+const HOT_BUFFER = new Map();
+const HOT_DEFAULT_CAPACITY = 20;
+/** Append a turn to the hot buffer. Caller-driven population. */
+function appendHotTurn(agentId, content, score = 1.0, capacity = HOT_DEFAULT_CAPACITY) {
+    const hit = {
+        source: 'hot',
+        content,
+        score,
+        ts: new Date().toISOString(),
+        provenance: `hot:turn:${agentId}`,
+    };
+    const buf = HOT_BUFFER.get(agentId) ?? [];
+    buf.push(hit);
+    while (buf.length > capacity)
+        buf.shift();
+    HOT_BUFFER.set(agentId, buf);
+}
+/** Test helper — clear the buffer (single agent or all). */
+function _clearHotBufferForTesting(agentId) {
+    if (agentId)
+        HOT_BUFFER.delete(agentId);
+    else
+        HOT_BUFFER.clear();
+}
+function readHotTier(agentId, hotTurns) {
+    const buf = HOT_BUFFER.get(agentId) ?? [];
+    // Newest last — return last N reversed so newest first.
+    return buf.slice(-hotTurns).reverse();
+}
+// ── Warm-tier ────────────────────────────────────────────────────────────────
+async function readWarmTier(query, agentId, warmDays, topK, client) {
+    try {
+        const sinceMs = Date.now() - warmDays * 24 * 60 * 60 * 1000;
+        const memories = await client.retrieve(query, { topK, tiers: ['HOT', 'WARM'] });
+        return memories
+            .filter((m) => {
+            // BrainXMemory rows expose a created_at-style field; tolerate either name.
+            const ts = m.createdAt ?? m.created_at ?? null;
+            if (!ts)
+                return true; // can't filter — keep
+            return new Date(ts).getTime() >= sinceMs;
+        })
+            .map((m) => ({
+            source: 'warm',
+            content: m.content ?? m.text ?? JSON.stringify(m),
+            score: typeof m.similarity === 'number' ? m.similarity : 0.5,
+            ts: m.createdAt ?? m.created_at ?? new Date().toISOString(),
+            provenance: `warm:brainx:${m.id ?? agentId}`,
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+// ── Cold-tier (lazy archive scan) ────────────────────────────────────────────
+async function readColdTier(agentId, coldRoot, thresholdDays, budget) {
+    if (budget <= 0)
+        return [];
+    const dir = path.join(coldRoot, agentId);
+    if (!fs.existsSync(dir))
+        return [];
+    const cutoff = Date.now() - thresholdDays * 24 * 60 * 60 * 1000;
+    const out = [];
+    try {
+        const files = fs.readdirSync(dir).filter(f => f.endsWith('.jsonl')).sort().reverse();
+        for (const file of files) {
+            if (out.length >= budget)
+                break;
+            const fp = path.join(dir, file);
+            const stat = fs.statSync(fp);
+            if (stat.mtimeMs > cutoff)
+                continue; // file too recent → not cold
+            const lines = fs.readFileSync(fp, 'utf8').split('\n').filter(Boolean);
+            for (let i = lines.length - 1; i >= 0 && out.length < budget; i--) {
+                try {
+                    const obj = JSON.parse(lines[i]);
+                    out.push({
+                        source: 'cold',
+                        content: obj.content ?? obj.text ?? obj.actionSummary ?? JSON.stringify(obj),
+                        score: typeof obj.score === 'number' ? obj.score : 0.3,
+                        ts: obj.ts ?? obj.timestamp ?? stat.mtime.toISOString(),
+                        provenance: `cold:archive:${file}`,
+                    });
+                }
+                catch { /* skip malformed line */ }
+            }
+        }
+    }
+    catch {
+        return out;
+    }
+    return out;
+}
+// ── Merge + dedupe ───────────────────────────────────────────────────────────
+function contentHash(s) {
+    return (0, crypto_1.createHash)('sha256').update(s).digest('hex').slice(0, 16);
+}
+function mergeAndDedupe(hot, warm, cold, cap) {
+    // Tier priority: hot > warm > cold. Same content from a higher tier wins.
+    const seen = new Map();
+    for (const h of [...hot, ...warm, ...cold]) {
+        const key = contentHash(h.content.trim());
+        if (!seen.has(key))
+            seen.set(key, h);
+    }
+    return Array.from(seen.values())
+        .sort((a, b) => b.score - a.score)
+        .slice(0, cap);
+}
+// ── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Three-tier retrieval over hot in-memory turns + warm BrainX vectors +
+ * cold archive scan. Returns ranked, deduped results with provenance tags
+ * and a per-tier latency breakdown.
+ *
+ * Cold tier only fires when hot+warm don't hit `maxResults` — keeps the
+ * common path fast.
+ *
+ * Never throws. All three tiers fail-open to empty hits on error.
+ */
+async function retrieveThreeTier(query, agentId, opts = {}) {
+    const hotTurns = opts.hotTurns ?? HOT_DEFAULT_CAPACITY;
+    const warmDays = opts.warmDays ?? 7;
+    const maxResults = opts.maxResults ?? 12;
+    const coldThresholdDays = opts.coldThresholdDays ?? 7;
+    const coldRoot = opts.coldRoot ?? path.join((0, engine_paths_1.resolveEnginePaths)().root, 'workspace', 'asmr');
+    const skipCold = opts.skipCold ?? false;
+    const brainx = opts.brainx ?? new brainx_client_1.BrainXClient(agentId);
+    const t0 = Date.now();
+    const tHotStart = Date.now();
+    const hot = readHotTier(agentId, hotTurns);
+    const hotMs = Date.now() - tHotStart;
+    const tWarmStart = Date.now();
+    const warm = await readWarmTier(query, agentId, warmDays, maxResults, brainx);
+    const warmMs = Date.now() - tWarmStart;
+    let cold = [];
+    let coldMs = 0;
+    const haveSoFar = hot.length + warm.length;
+    if (!skipCold && haveSoFar < maxResults) {
+        const tColdStart = Date.now();
+        cold = await readColdTier(agentId, coldRoot, coldThresholdDays, maxResults - haveSoFar);
+        coldMs = Date.now() - tColdStart;
+    }
+    const merged = mergeAndDedupe(hot, warm, cold, maxResults);
+    return {
+        hot,
+        warm,
+        cold,
+        merged,
+        latency_ms: { hot: hotMs, warm: warmMs, cold: coldMs, total: Date.now() - t0 },
+    };
+}