dsh-tdai-memory 0.1.0

package/vendor/tdai/core/conversation/l0-recorder.js

@@ -0,0 +1,420 @@
+/**
+ * L0 Conversation Recorder: records raw conversation messages to local JSONL files.
+ *
+ * Triggered from agent_end hook. Receives the conversation messages directly from
+ * the hook context (no file I/O needed), sanitizes them, filters out noise, and
+ * writes to ~/.openclaw/memory-tdai/conversations/YYYY-MM-DD.jsonl
+ *
+ * Design decisions:
+ * - Uses JSONL format (**one message per line** — flat, easy to grep/stream)
+ * - One file per day (all sessions merged into the same daily file)
+ * - sessionKey is stored as a field in each JSONL line, not in the filename
+ * - Independent from system session files — format fully controlled by plugin
+ * - Messages are sanitized to remove injected tags (prevent feedback loops)
+ * - Short/long/command messages are filtered out
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import crypto from "node:crypto";
+import { sanitizeText, stripCodeBlocks, shouldCaptureL0 } from "../../utils/sanitize.js";
+import { formatLocalDate } from "../../utils/time.js";
+/**
+ * Generate a short unique message ID.
+ */
+function generateMessageId() {
+    return `msg_${Date.now()}_${crypto.randomBytes(3).toString("hex")}`;
+}
+const TAG = "[memory-tdai][l0]";
+// ============================
+// Core function
+// ============================
+/**
+ * Record a conversation round to the L0 JSONL file.
+ *
+ * Only records **incremental** messages (new since the last capture).
+ * Uses `afterTimestamp` as the primary filter to skip already-captured history.
+ *
+ * @param sessionKey - The session key for this conversation
+ * @param rawMessages - Raw messages from the agent_end hook context (full session history)
+ * @param baseDir - Base data directory (~/.openclaw/memory-tdai/)
+ * @param logger - Optional logger
+ * @param originalUserText - Clean original user prompt (pre-prependContext)
+ * @param afterTimestamp - Epoch ms cursor: only messages with timestamp > this are new.
+ *                         Pass 0 or omit for the first capture of a session.
+ * @returns Filtered messages (for L1 to use directly), or empty array if nothing worth recording
+ */
+export async function recordConversation(params) {
+    const { sessionKey, sessionId, rawMessages, baseDir, logger, originalUserText, afterTimestamp, originalUserMessageCount } = params;
+    // Step 1: Position slice + extract user/assistant messages.
+    //
+    // Dual protection against duplicate capture:
+    //   Layer 1 (position slice): Use originalUserMessageCount (cached at before_prompt_build)
+    //     to slice rawMessages — only keep messages added AFTER the prompt build, i.e. this
+    //     turn's new messages. This is immune to timestamp drift after gateway restarts.
+    //   Layer 2 (timestamp cursor): The existing afterTimestamp filter below acts as a fallback
+    //     when the position slice is unavailable (cache expired, process restart, etc.).
+    const usePositionSlice = originalUserMessageCount != null && originalUserMessageCount > 0
+        && originalUserMessageCount <= rawMessages.length;
+    const slicedMessages = usePositionSlice
+        ? rawMessages.slice(originalUserMessageCount)
+        : rawMessages;
+    const allExtracted = extractUserAssistantMessages(slicedMessages);
+    if (usePositionSlice) {
+        logger?.debug?.(`${TAG} Position slice: ${rawMessages.length} raw → ${slicedMessages.length} new (sliceStart=${originalUserMessageCount})`);
+    }
+    // Diagnostic: check whether the framework actually provides timestamp on raw messages.
+    // If all raw timestamps are missing, the timestamp cursor is effectively useless and
+    // position slice becomes the sole incremental mechanism.
+    if (slicedMessages.length > 0) {
+        const firstRaw = slicedMessages[0];
+        const rawTs = firstRaw?.timestamp;
+        const hasRawTs = typeof rawTs === "number";
+        logger?.debug?.(`${TAG} Raw message[0] timestamp probe: ${hasRawTs ? `present (${rawTs})` : `missing (type=${typeof rawTs}, value=${String(rawTs)})`}`);
+    }
+    logger?.debug?.(`${TAG} Extracted ${allExtracted.length} user/assistant messages from ${slicedMessages.length} total`);
+    // Step 1.5: Incremental filter — only keep messages newer than the cursor.
+    //
+    // Uses strict greater-than (>) which is safe because:
+    //   - The cursor is set to max(timestamps) of the LAST recorded batch.
+    //   - The next agent turn's messages will have timestamps strictly greater than
+    //     the previous turn (there's at least one LLM API call between turns, which
+    //     takes hundreds of milliseconds minimum — no same-millisecond collision).
+    //   - All messages within a single turn are captured together as one batch,
+    //     so even if multiple messages share the same timestamp, they are either
+    //     all included (new batch) or all excluded (already captured).
+    //   - If a message lacks a timestamp field, extractUserAssistantMessages()
+    //     assigns Date.now() at extraction time, which is always > previous cursor.
+    const cursor = afterTimestamp ?? 0;
+    const extracted = cursor !== 0
+        ? allExtracted.filter((m) => m.timestamp > cursor)
+        : allExtracted;
+    if (extracted.length > 0) {
+        const first = extracted[0];
+        logger?.debug?.(`${TAG} First captured message: role=${first.role}, ts=${first.timestamp}, ` +
+            `date=${new Date(first.timestamp).toISOString()}, content=${first.content.slice(0, 80)}${first.content.length > 80 ? "…" : ""}`);
+    }
+    if (cursor > 0) {
+        logger?.debug?.(`${TAG} Incremental filter: ${allExtracted.length} total → ${extracted.length} new (cursor=${cursor})`);
+        // Safety valve: if timestamp filter passed everything through and position slice
+        // was not available, this likely indicates timestamp drift after a gateway restart.
+        if (!usePositionSlice && extracted.length === allExtracted.length && allExtracted.length > 8) {
+            logger?.warn?.(`${TAG} ⚠ Safety valve: all ${allExtracted.length} messages passed timestamp filter (cursor=${cursor}) — ` +
+                `possible timestamp drift after gateway restart. Position slice was not available (no cached messageCount).`);
+        }
+    }
+    if (extracted.length === 0) {
+        logger?.debug?.(`${TAG} No new user/assistant messages to record`);
+        return [];
+    }
+    // Step 2: Replace polluted user messages with cached original prompt.
+    //
+    // Background:
+    //   The framework appends the user's message to the session after before_prompt_build,
+    //   then injects prependContext into it. So the user message in rawMessages is polluted.
+    //   We cached the clean prompt (originalUserText) and the message count at
+    //   before_prompt_build time (originalUserMessageCount) to identify which raw message
+    //   is the real user input.
+    //
+    // Strategy:
+    //   When position slice is active, the polluted user message is slicedMessages[0].
+    //   Otherwise, fall back to rawMessages[originalUserMessageCount].
+    //   In both cases, find the timestamp and match it in `extracted` for replacement.
+    //   If matching fails, skip replacement — sanitizeText() in Step 3 is the safety net.
+    if (originalUserText) {
+        // Determine the target raw message that contains the polluted user prompt
+        const targetRaw = usePositionSlice
+            ? slicedMessages[0]
+            : (originalUserMessageCount != null && originalUserMessageCount >= 0 && originalUserMessageCount < rawMessages.length)
+                ? rawMessages[originalUserMessageCount]
+                : undefined;
+        const targetTs = targetRaw && typeof targetRaw.timestamp === "number" ? targetRaw.timestamp : undefined;
+        if (targetTs != null) {
+            let replaced = false;
+            for (let i = 0; i < extracted.length; i++) {
+                if (extracted[i].role === "user" && extracted[i].timestamp === targetTs) {
+                    logger?.debug?.(`${TAG} Replacing user message at timestamp=${targetTs} with cached original prompt ` +
+                        `(${originalUserText.length} chars, was ${extracted[i].content.length} chars) [positionSlice=${usePositionSlice}]`);
+                    extracted[i] = { ...extracted[i], content: originalUserText };
+                    replaced = true;
+                    break;
+                }
+            }
+            if (!replaced) {
+                logger?.warn?.(`${TAG} Target user message (ts=${targetTs}) not found in extracted batch — ` +
+                    `possibly filtered by cursor. Skipping replacement, will rely on sanitizeText().`);
+            }
+        }
+        else if (targetRaw) {
+            logger?.warn?.(`${TAG} Target raw message has no valid timestamp — ` +
+                `skipping replacement, will rely on sanitizeText().`);
+        }
+        else {
+            logger?.warn?.(`${TAG} Have originalUserText but cannot locate target raw message — ` +
+                `skipping replacement, will rely on sanitizeText().`);
+        }
+    }
+    // Step 3: Sanitize and filter
+    const filtered = extracted
+        .map((m) => {
+        let content = sanitizeText(m.content);
+        // Strip fenced code blocks from assistant replies to reduce embedding noise
+        if (m.role === "assistant") {
+            content = stripCodeBlocks(content);
+        }
+        return { id: m.id, role: m.role, content, timestamp: m.timestamp };
+    })
+        .filter((m) => shouldCaptureL0(m.content));
+    logger?.debug?.(`${TAG} After sanitize+filter: ${filtered.length} messages (from ${extracted.length})`);
+    if (filtered.length === 0) {
+        logger?.debug?.(`${TAG} All messages filtered out, skipping L0 write`);
+        return [];
+    }
+    // Step 4: Write to JSONL file — one message per line (flat format)
+    const now = new Date().toISOString();
+    const lines = [];
+    for (const msg of filtered) {
+        const record = {
+            sessionKey,
+            sessionId: sessionId || "",
+            recordedAt: now,
+            id: msg.id,
+            role: msg.role,
+            content: msg.content,
+            timestamp: msg.timestamp,
+        };
+        lines.push(JSON.stringify(record));
+    }
+    const shardDate = formatLocalDate(new Date());
+    const outDir = path.join(baseDir, "conversations");
+    const outPath = path.join(outDir, `${shardDate}.jsonl`);
+    try {
+        await fs.mkdir(outDir, { recursive: true });
+        // Append each message as its own JSONL line
+        await fs.appendFile(outPath, lines.join("\n") + "\n", "utf-8");
+        logger?.debug?.(`${TAG} Recorded ${filtered.length} messages to ${outPath}`);
+    }
+    catch (err) {
+        logger?.error(`${TAG} Failed to write L0 file: ${err instanceof Error ? err.message : String(err)}`);
+        // Return filtered messages anyway so L1 can still process them
+    }
+    return filtered;
+}
+/**
+ * Read all L0 conversation records for a session.
+ * Returns records in chronological order.
+ *
+ * File format: `YYYY-MM-DD.jsonl` (daily files, all sessions merged).
+ * Each line is an L0MessageRecord; filtered by sessionKey at line level.
+ */
+export async function readConversationRecords(sessionKey, baseDir, logger) {
+    const conversationsDir = path.join(baseDir, "conversations");
+    // Daily file pattern: YYYY-MM-DD.jsonl
+    const dateFilePattern = /^\d{4}-\d{2}-\d{2}\.jsonl$/;
+    let entries;
+    try {
+        const dirEntries = await fs.readdir(conversationsDir, { withFileTypes: true });
+        entries = dirEntries
+            .filter((entry) => entry.isFile())
+            .map((entry) => entry.name);
+    }
+    catch {
+        // Directory doesn't exist yet — normal for first conversation
+        return [];
+    }
+    const targetFiles = entries
+        .filter((name) => dateFilePattern.test(name))
+        .sort();
+    if (targetFiles.length === 0) {
+        return [];
+    }
+    const records = [];
+    for (const fileName of targetFiles) {
+        const filePath = path.join(conversationsDir, fileName);
+        let raw;
+        try {
+            raw = await fs.readFile(filePath, "utf-8");
+        }
+        catch {
+            logger?.warn?.(`${TAG} Failed to read L0 file: ${filePath}`);
+            continue;
+        }
+        const lines = raw.split("\n").filter((line) => line.trim());
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            try {
+                const parsed = JSON.parse(line);
+                // Filter by sessionKey at line level
+                const lineSessionKey = parsed.sessionKey;
+                if (lineSessionKey !== sessionKey)
+                    continue;
+                if (typeof parsed.role === "string" && typeof parsed.content === "string") {
+                    // Flat format: { sessionKey, sessionId, recordedAt, id, role, content, timestamp }
+                    // Wrap into L0ConversationRecord for uniform downstream consumption
+                    const msg = {
+                        id: (typeof parsed.id === "string" && parsed.id) ? parsed.id : generateMessageId(),
+                        role: parsed.role,
+                        content: parsed.content,
+                        timestamp: typeof parsed.timestamp === "number" ? parsed.timestamp : Date.now(),
+                    };
+                    records.push({
+                        sessionKey: parsed.sessionKey || sessionKey,
+                        sessionId: parsed.sessionId || "",
+                        recordedAt: parsed.recordedAt || new Date().toISOString(),
+                        messageCount: 1,
+                        messages: [msg],
+                    });
+                }
+                else {
+                    logger?.warn?.(`${TAG} Unrecognized JSONL line format in ${filePath}:${i + 1}`);
+                }
+            }
+            catch {
+                logger?.warn?.(`${TAG} Skipping malformed JSONL line in ${filePath}:${i + 1}`);
+            }
+        }
+    }
+    records.sort((a, b) => {
+        const ta = Date.parse(a.recordedAt);
+        const tb = Date.parse(b.recordedAt);
+        const na = Number.isFinite(ta) ? ta : Number.POSITIVE_INFINITY;
+        const nb = Number.isFinite(tb) ? tb : Number.POSITIVE_INFINITY;
+        return na - nb;
+    });
+    return records;
+}
+/**
+ * Read L0 messages across all conversation records for a session,
+ * optionally filtered by a cursor timestamp (messages after the cursor).
+ *
+ * When `limit` is provided, only the **newest** `limit` messages are returned
+ * (matching the DB path's `ORDER BY timestamp DESC LIMIT ?` behavior).
+ * Returned messages are always in chronological order (oldest → newest).
+ *
+ * NOTE: potential optimization — records are chronologically ordered (append-only JSONL),
+ * so a reverse scan could skip entire old records. Deferred for now; see Issue 5 in
+ * docs/05-known-issues.md.
+ */
+export async function readConversationMessages(sessionKey, baseDir, afterTimestamp, logger, limit) {
+    const records = await readConversationRecords(sessionKey, baseDir, logger);
+    const allMessages = [];
+    for (const record of records) {
+        for (const msg of record.messages) {
+            if (afterTimestamp && msg.timestamp <= afterTimestamp)
+                continue;
+            allMessages.push(msg);
+        }
+    }
+    // Truncate to newest `limit` messages (keep tail, since array is chronological)
+    if (limit != null && limit > 0 && allMessages.length > limit) {
+        logger?.debug?.(`${TAG} readConversationMessages: truncating ${allMessages.length} → ${limit} (newest)`);
+        return allMessages.slice(-limit);
+    }
+    return allMessages;
+}
+/**
+ * Read L0 messages for a session, grouped by sessionId.
+ *
+ * Within the same sessionKey, different sessionIds represent different conversation
+ * instances (e.g. after /reset). L1 extraction should process each group independently
+ * so that each group's sessionId is correctly associated with its extracted memories.
+ *
+ * When `limit` is provided, only the **newest** `limit` messages (across all groups)
+ * are retained — matching the DB path's `ORDER BY recorded_at DESC LIMIT ?` behavior.
+ * Groups that become empty after truncation are dropped.
+ *
+ * Groups are returned in chronological order (by earliest message timestamp).
+ * Messages within each group are also in chronological order.
+ *
+ * @param afterRecordedAtMs - Epoch ms cursor: only messages with recordedAt > this are included.
+ */
+export async function readConversationMessagesGroupedBySessionId(sessionKey, baseDir, afterRecordedAtMs, logger, limit) {
+    const records = await readConversationRecords(sessionKey, baseDir, logger);
+    // Collect all messages with their sessionId, filtering by recorded_at cursor
+    const allMessages = [];
+    for (const record of records) {
+        const sid = record.sessionId || "";
+        const recMs = Date.parse(record.recordedAt) || 0;
+        if (afterRecordedAtMs && recMs <= afterRecordedAtMs)
+            continue;
+        for (const msg of record.messages) {
+            allMessages.push({ sessionId: sid, msg: { ...msg, recordedAtMs: recMs } });
+        }
+    }
+    // Sort by timestamp ASC (chronological) — records are already roughly ordered
+    // by recordedAt, but messages within may not be perfectly sorted by timestamp.
+    allMessages.sort((a, b) => a.msg.timestamp - b.msg.timestamp);
+    // Truncate to newest `limit` messages (keep tail)
+    let selected = allMessages;
+    if (limit != null && limit > 0 && allMessages.length > limit) {
+        logger?.debug?.(`${TAG} readConversationMessagesGroupedBySessionId: truncating ${allMessages.length} → ${limit} (newest)`);
+        selected = allMessages.slice(-limit);
+    }
+    // Re-group by sessionId
+    const groupMap = new Map();
+    for (const { sessionId, msg } of selected) {
+        let group = groupMap.get(sessionId);
+        if (!group) {
+            group = [];
+            groupMap.set(sessionId, group);
+        }
+        group.push(msg);
+    }
+    // Convert to array, sorted by earliest message timestamp in each group
+    const groups = [];
+    for (const [sessionId, messages] of groupMap) {
+        if (messages.length > 0) {
+            groups.push({ sessionId, messages });
+        }
+    }
+    groups.sort((a, b) => a.messages[0].timestamp - b.messages[0].timestamp);
+    return groups;
+}
+// ============================
+// Helpers
+// ============================
+/**
+ * Extract user and assistant messages from raw hook message array.
+ */
+function extractUserAssistantMessages(messages) {
+    const result = [];
+    for (const msg of messages) {
+        if (!msg || typeof msg !== "object")
+            continue;
+        const m = msg;
+        const role = m.role;
+        if (role !== "user" && role !== "assistant")
+            continue;
+        let content;
+        if (typeof m.content === "string") {
+            content = m.content;
+        }
+        else if (Array.isArray(m.content)) {
+            const textParts = [];
+            for (const part of m.content) {
+                if (part &&
+                    typeof part === "object" &&
+                    part.type === "text") {
+                    const text = part.text;
+                    if (typeof text === "string")
+                        textParts.push(text);
+                }
+            }
+            content = textParts.join("\n");
+        }
+        // Strip inline base64 image data URIs that some providers embed in string content.
+        // These are not useful for memory and would pollute FTS / embedding indexes.
+        if (content && /data:image\/[a-z+]+;base64,/i.test(content)) {
+            content = content.replace(/data:image\/[a-z+]+;base64,[A-Za-z0-9+/=]+/gi, "[image]");
+        }
+        if (content && content.trim()) {
+            const ts = typeof m.timestamp === "number" ? m.timestamp : Date.now();
+            result.push({
+                id: (typeof m.id === "string" && m.id) ? m.id : generateMessageId(),
+                role: role,
+                content: content.trim(),
+                timestamp: ts,
+            });
+        }
+    }
+    return result;
+}

package/vendor/tdai/core/hooks/auto-capture.js

@@ -0,0 +1,236 @@
+/**
+ * auto-capture hook (v3): records conversation messages locally (L0),
+ * then notifies the MemoryPipelineManager for L1/L2/L3 scheduling.
+ *
+ * Key design decisions:
+ * - Always write L0 locally via l0-recorder.
+ * - When VectorStore + EmbeddingService are available, also write L0 vector index.
+ * - Notify MemoryPipelineManager for L1/L2/L3 trigger evaluation.
+ * - L1 Runner reads from VectorStore DB (primary) or L0 JSONL files (fallback).
+ * - Extraction is NOT triggered here. The pipeline manager decides when.
+ */
+import crypto from "node:crypto";
+import { CheckpointManager } from "../../utils/checkpoint.js";
+import { recordConversation } from "../conversation/l0-recorder.js";
+const TAG = "[memory-tdai] [capture]";
+/**
+ * Generate a unique L0 record ID for vector indexing.
+ * Includes an index to distinguish multiple messages within the same round.
+ */
+function generateL0RecordId(sessionKey, index) {
+    return `l0_${sessionKey}_${Date.now()}_${index}_${crypto.randomBytes(3).toString("hex")}`;
+}
+export async function performAutoCapture(params) {
+    const { messages, sessionKey, sessionId, cfg, pluginDataDir, logger, scheduler, originalUserText, originalUserMessageCount, pluginStartTimestamp, vectorStore, embeddingService, bgTaskRegistry, } = params;
+    const tCaptureStart = performance.now();
+    const checkpoint = new CheckpointManager(pluginDataDir, logger);
+    // ============================
+    // Step 1 + 2: L0 recording + checkpoint update (ATOMIC)
+    // ============================
+    // These steps are combined inside captureAtomically() to prevent the race
+    // condition where two concurrent agent_end events both read the same stale
+    // cursor and produce duplicate L0 records. The file lock is held for the
+    // entire read-cursor → recordConversation → advance-cursor sequence.
+    const tL0RecordStart = performance.now();
+    let filteredMessages = [];
+    try {
+        await checkpoint.captureAtomically(sessionKey, pluginStartTimestamp, async (afterTimestamp) => {
+            logger?.debug?.(`${TAG} L0 capture cursor (per-session, atomic): afterTimestamp=${afterTimestamp} session=${sessionKey}`);
+            if (afterTimestamp === pluginStartTimestamp && pluginStartTimestamp && pluginStartTimestamp > 0) {
+                logger?.debug?.(`${TAG} No per-session checkpoint cursor found for session=${sessionKey} — ` +
+                    `using pluginStartTimestamp as floor: ` +
+                    `${afterTimestamp} (${new Date(afterTimestamp).toISOString()})`);
+            }
+            filteredMessages = await recordConversation({
+                sessionKey,
+                sessionId,
+                rawMessages: messages,
+                baseDir: pluginDataDir,
+                logger,
+                originalUserText,
+                afterTimestamp,
+                originalUserMessageCount,
+            });
+            if (filteredMessages.length === 0) {
+                return null; // Nothing captured — cursor stays unchanged
+            }
+            logger?.debug?.(`${TAG} L0 recorded: ${filteredMessages.length} messages for session ${sessionKey}`);
+            const maxTs = Math.max(...filteredMessages.map((m) => m.timestamp));
+            return { maxTimestamp: maxTs, messageCount: filteredMessages.length };
+        });
+    }
+    catch (err) {
+        logger?.error(`${TAG} L0 recording failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const tL0RecordEnd = performance.now();
+    // ============================
+    // Step 1.5: L0 vector indexing
+    // ============================
+    // Two paths depending on store capabilities:
+    //
+    // A) Store supports updateL0Embedding (sqlite):
+    //    - Write metadata + FTS immediately WITHOUT embedding (~ms)
+    //    - Fire-and-forget background task: embedBatch + updateL0Embedding
+    //    - PERF: avoids blocking agent_end with 2-3s embedding calls
+    //
+    // B) Store does NOT support updateL0Embedding (VDB / remote):
+    //    - Embed synchronously, then upsertL0 with embedding in one call
+    //    - VDB backends handle embedding server-side or need it upfront
+    const tL0VecStart = performance.now();
+    let l0VectorsWritten = 0;
+    let l0EmbedTotalMs = 0;
+    let l0UpsertTotalMs = 0;
+    logger?.debug?.(`${TAG} [L0-vec-index] Check: filteredMessages=${filteredMessages.length}, ` +
+        `vectorStore=${vectorStore ? "available" : "UNAVAILABLE"}, ` +
+        `embeddingService=${embeddingService ? "available" : "UNAVAILABLE"}`);
+    const supportsBgEmbed = vectorStore?.supportsDeferredEmbedding === true;
+    if (filteredMessages.length > 0 && vectorStore) {
+        const now = new Date().toISOString();
+        const bgRecords = [];
+        logger?.debug?.(`${TAG} [L0-vec-index] START indexing ${filteredMessages.length} message(s) for session ${sessionKey} ` +
+            `(mode=${supportsBgEmbed ? "async-bg" : "sync"})`);
+        for (let i = 0; i < filteredMessages.length; i++) {
+            const msg = filteredMessages[i];
+            try {
+                const l0Record = {
+                    id: generateL0RecordId(sessionKey, i),
+                    sessionKey,
+                    sessionId: sessionId || "",
+                    role: msg.role,
+                    messageText: msg.content,
+                    recordedAt: now,
+                    timestamp: msg.timestamp,
+                };
+                let embedding;
+                if (!supportsBgEmbed && embeddingService) {
+                    // Path B (VDB): embed synchronously — needed for upsertL0
+                    // Skip local embed when using server-side embedding (NoopEmbeddingService, dims=0)
+                    if (embeddingService.getDimensions() === 0) {
+                        logger?.debug?.(`${TAG} [L0-vec-index] Server-side embedding (dims=0), skipping local embed for message ${i}`);
+                    }
+                    else {
+                        const tEmbedStart = performance.now();
+                        try {
+                            embedding = await embeddingService.embed(msg.content);
+                            l0EmbedTotalMs += performance.now() - tEmbedStart;
+                            logger?.debug?.(`${TAG} [L0-vec-index] Embedding OK: dims=${embedding.length}, ` +
+                                `norm=${Math.sqrt(Array.from(embedding).reduce((s, v) => s + v * v, 0)).toFixed(4)}`);
+                        }
+                        catch (embedErr) {
+                            l0EmbedTotalMs += performance.now() - tEmbedStart;
+                            logger?.warn(`${TAG} [L0-vec-index] Embedding FAILED for message ${i}, ` +
+                                `will write metadata only: ${embedErr instanceof Error ? embedErr.message : String(embedErr)}`);
+                        }
+                    }
+                }
+                // Path A (sqlite): pass undefined embedding — metadata + FTS only
+                // Path B (VDB): pass embedding (may be undefined on failure)
+                const tUpsertStart = performance.now();
+                const upsertOk = await vectorStore.upsertL0(l0Record, supportsBgEmbed ? undefined : embedding);
+                l0UpsertTotalMs += performance.now() - tUpsertStart;
+                if (upsertOk) {
+                    l0VectorsWritten++;
+                    if (supportsBgEmbed) {
+                        bgRecords.push({ recordId: l0Record.id, content: msg.content });
+                    }
+                }
+                else {
+                    logger?.warn(`${TAG} [L0-vec-index] upsertL0 returned false for message ${i}`);
+                }
+            }
+            catch (err) {
+                logger?.warn?.(`${TAG} [L0-vec-index] FAILED for message ${i} (non-blocking): ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        const modeLabel = supportsBgEmbed ? "metadata-only, embed=background" : `embed=${l0EmbedTotalMs.toFixed(0)}ms, upsert=${l0UpsertTotalMs.toFixed(0)}ms`;
+        logger?.debug?.(`${TAG} [L0-vec-index] DONE: ${l0VectorsWritten}/${filteredMessages.length} records written (${modeLabel})`);
+        // Path A only: fire-and-forget background embedding for sqlite stores
+        if (supportsBgEmbed && bgRecords.length > 0 && embeddingService) {
+            const bgVectorStore = vectorStore;
+            const bgEmbeddingService = embeddingService;
+            const bgSnapshot = [...bgRecords];
+            const bgLogger = logger;
+            // Do NOT await — runs in background after response is sent.
+            //
+            // Register the task in bgTaskRegistry (if provided) so TdaiCore.destroy()
+            // can await it before closing vectorStore / embeddingService.  The
+            // ``.finally`` clean-up ensures the entry is removed on both success
+            // and failure; without that the set would leak and eventually block
+            // shutdown indefinitely.
+            const bgPromise = (async () => {
+                const tBgStart = performance.now();
+                try {
+                    const texts = bgSnapshot.map((r) => r.content);
+                    const embeddings = await bgEmbeddingService.embedBatch(texts);
+                    let bgUpdated = 0;
+                    for (let i = 0; i < bgSnapshot.length; i++) {
+                        try {
+                            const ok = await bgVectorStore.updateL0Embedding(bgSnapshot[i].recordId, embeddings[i]);
+                            if (ok)
+                                bgUpdated++;
+                        }
+                        catch (err) {
+                            bgLogger?.warn?.(`${TAG} [L0-vec-index-bg] Failed to update embedding for ${bgSnapshot[i].recordId}: ` +
+                                `${err instanceof Error ? err.message : String(err)}`);
+                        }
+                    }
+                    const bgMs = performance.now() - tBgStart;
+                    bgLogger?.debug?.(`${TAG} [L0-vec-index-bg] Background embedding complete: ${bgUpdated}/${bgSnapshot.length} vectors updated (${bgMs.toFixed(0)}ms)`);
+                }
+                catch (err) {
+                    const bgMs = performance.now() - tBgStart;
+                    bgLogger?.warn?.(`${TAG} [L0-vec-index-bg] Background embedding failed (${bgMs.toFixed(0)}ms, non-fatal): ` +
+                        `${err instanceof Error ? err.message : String(err)}`);
+                }
+            })();
+            if (bgTaskRegistry) {
+                bgTaskRegistry.add(bgPromise);
+                void bgPromise.finally(() => {
+                    bgTaskRegistry.delete(bgPromise);
+                });
+            }
+        }
+    }
+    else if (filteredMessages.length > 0) {
+        logger?.warn(`${TAG} [L0-vec-index] SKIPPED: vectorStore not available`);
+    }
+    const tL0VecEnd = performance.now();
+    // ============================
+    // Step 3: Notify scheduler of this conversation round
+    // ============================
+    const tNotifyStart = performance.now();
+    // Pass empty array: L1 Runner reads from VectorStore DB (or L0 JSONL fallback), not from in-memory buffers.
+    if (scheduler) {
+        await scheduler.notifyConversation(sessionKey, []);
+        logger?.debug?.(`${TAG} Scheduler notified of conversation round (sessionKey=${sessionKey})`);
+        const totalMs = performance.now() - tCaptureStart;
+        const vecDetail = supportsBgEmbed
+            ? `metadata-only, embed=background, msgs=${filteredMessages.length}`
+            : `embed=${l0EmbedTotalMs.toFixed(0)}ms, upsert=${l0UpsertTotalMs.toFixed(0)}ms, msgs=${filteredMessages.length}`;
+        logger?.info(`${TAG} ⏱ Capture timing: total=${totalMs.toFixed(0)}ms, ` +
+            `l0Record+checkpoint=${(tL0RecordEnd - tL0RecordStart).toFixed(0)}ms, ` +
+            `l0VecIndex=${(tL0VecEnd - tL0VecStart).toFixed(0)}ms (${vecDetail}), ` +
+            `notify=${(performance.now() - tNotifyStart).toFixed(0)}ms`);
+        return {
+            schedulerNotified: true,
+            l0RecordedCount: filteredMessages.length,
+            l0VectorsWritten,
+            filteredMessages,
+        };
+    }
+    const totalMs = performance.now() - tCaptureStart;
+    const vecDetail = supportsBgEmbed
+        ? `metadata-only, embed=background, msgs=${filteredMessages.length}`
+        : `embed=${l0EmbedTotalMs.toFixed(0)}ms, upsert=${l0UpsertTotalMs.toFixed(0)}ms, msgs=${filteredMessages.length}`;
+    logger?.info(`${TAG} ⏱ Capture timing: total=${totalMs.toFixed(0)}ms, ` +
+        `l0Record+checkpoint=${(tL0RecordEnd - tL0RecordStart).toFixed(0)}ms, ` +
+        `l0VecIndex=${(tL0VecEnd - tL0VecStart).toFixed(0)}ms (${vecDetail}), ` +
+        `notify=${(performance.now() - tNotifyStart).toFixed(0)}ms`);
+    logger?.debug?.(`${TAG} No scheduler provided, skipping notification`);
+    return {
+        schedulerNotified: false,
+        l0RecordedCount: filteredMessages.length,
+        l0VectorsWritten,
+        filteredMessages,
+    };
+}