@qearlyao/familiar 0.2.5 → 0.4.0

package/dist/{image-gen.js → media/image-gen.js}

@@ -4,11 +4,11 @@ import { homedir } from "node:os";
 import { basename, isAbsolute, relative, resolve } from "node:path";
 import { findEnvKeys, generateImages, getEnvApiKey, getImageModels, getImageProviders, } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
+import { parseModelRef } from "../models/index.js";
+import { imageMimeTypeFromPath, sniffImageMimeType } from "../util/image-mime.js";
 import { ensureGeneratedAttachmentsDir } from "./generated-media.js";
 import { ensureInlineImageDerivative } from "./image-derivatives.js";
 import { promptImagesFromAttachments } from "./inbound-attachments.js";
-import { parseModelRef } from "./models.js";
-import { imageMimeTypeFromPath, sniffImageMimeType } from "./util/image-mime.js";
 const IMAGE_GEN_NOTICE_PREFIX = "Generated image attachment:";
 const OPENROUTER_IMAGE_BASE_URL = "https://openrouter.ai/api/v1";
 const imageGenSchema = Type.Object({

package/dist/{inbound-attachments.js → media/inbound-attachments.js}

@@ -1,56 +1,43 @@
 import { createHash, randomUUID } from "node:crypto";
 import { mkdir, readdir, readFile, unlink, writeFile } from "node:fs/promises";
 import { basename, extname, resolve } from "node:path";
+import { IMAGE_EXTENSION_BY_MIME, sniffImageMimeType } from "../util/image-mime.js";
+import { MAX_INBOUND_ATTACHMENT_BYTES, MAX_INBOUND_ATTACHMENTS, MAX_INBOUND_TOTAL_BYTES } from "./attachment-limits.js";
 import { attachmentsDir, publicAttachmentPath } from "./generated-media.js";
 import { ensureInlineImageDerivative, MAX_INLINE_IMAGE_BASE64_BYTES } from "./image-derivatives.js";
 import { deriveInboundAttachmentText } from "./media-understanding.js";
-import { IMAGE_EXTENSION_BY_MIME, sniffImageMimeType } from "./util/image-mime.js";
+export { MAX_INBOUND_ATTACHMENT_BYTES, MAX_INBOUND_ATTACHMENTS, MAX_INBOUND_TOTAL_BYTES, } from "./attachment-limits.js";
 export { MAX_INLINE_IMAGE_BASE64_BYTES } from "./image-derivatives.js";
-export const MAX_INBOUND_ATTACHMENTS = 4;
-export const MAX_INBOUND_ATTACHMENT_BYTES = 12 * 1024 * 1024;
-export const MAX_INBOUND_TOTAL_BYTES = 24 * 1024 * 1024;
 const TEXT_ATTACHMENT_PREVIEW_LINES = 2;
 const TEXT_ATTACHMENT_PREVIEW_CHARS = 1000;
-const ALLOWED_MIME_TYPES = new Set([
-    "image/jpeg",
-    "image/png",
-    "image/gif",
-    "image/webp",
-    "audio/mpeg",
-    "audio/ogg",
-    "audio/wav",
-    "audio/webm",
-    "video/mp4",
-    "video/webm",
-    "application/pdf",
-    "text/plain",
-]);
-const EXTENSIONS_BY_MIME = {
-    ...IMAGE_EXTENSION_BY_MIME,
-    "audio/mpeg": ".mp3",
-    "audio/ogg": ".ogg",
-    "audio/wav": ".wav",
-    "audio/webm": ".webm",
-    "video/mp4": ".mp4",
-    "video/webm": ".webm",
-    "application/pdf": ".pdf",
-    "text/plain": ".txt",
+const MP4_FILE_TYPE_BRANDS = new Set(["avc1", "dash", "iso2", "isom", "M4V ", "mp41", "mp42", "MSNV"]);
+const ATTACHMENT_MIME_POLICY = {
+    ...Object.fromEntries(Object.entries(IMAGE_EXTENSION_BY_MIME).map(([mimeType, extension]) => [
+        mimeType,
+        { kind: "image", extension },
+    ])),
+    "audio/mpeg": { kind: "audio", extension: ".mp3" },
+    "audio/ogg": { kind: "audio", extension: ".ogg" },
+    "audio/wav": { kind: "audio", extension: ".wav" },
+    "audio/webm": { kind: "audio", extension: ".webm" },
+    "video/mp4": { kind: "video", extension: ".mp4" },
+    "video/quicktime": { kind: "video", extension: ".mov" },
+    "video/webm": { kind: "video", extension: ".webm" },
+    "application/pdf": { kind: "file", extension: ".pdf" },
+    "text/plain": { kind: "file", extension: ".txt" },
 };
+const MIME_TYPE_BY_EXTENSION = Object.fromEntries(Object.entries(ATTACHMENT_MIME_POLICY)
+    .filter(([, policy]) => policy.kind === "video")
+    .map(([mimeType, policy]) => [policy.extension, mimeType]));
+function mimePolicy(mimeType) {
+    return ATTACHMENT_MIME_POLICY[mimeType];
+}
 function safeName(name, fallback) {
     const base = basename(name || fallback)
         .replace(/[^A-Za-z0-9._=-]+/g, "_")
         .slice(0, 120);
     return base || fallback;
 }
-function kindFromMime(mimeType) {
-    if (mimeType.startsWith("image/"))
-        return "image";
-    if (mimeType.startsWith("audio/"))
-        return "audio";
-    if (mimeType.startsWith("video/"))
-        return "video";
-    return "file";
-}
 function textAttachmentPreview(buffer, mimeType) {
     if (mimeType !== "text/plain")
         return undefined;
@@ -84,7 +71,22 @@ function sniffText(buffer) {
     }
     return "text/plain";
 }
-function sniffMimeType(buffer, declared) {
+function mimeFromExtension(name) {
+    if (!name)
+        return undefined;
+    return MIME_TYPE_BY_EXTENSION[extname(name).toLowerCase()];
+}
+function sniffVideoMimeType(buffer) {
+    if (buffer.subarray(0, 4).equals(Buffer.from([0x1a, 0x45, 0xdf, 0xa3])))
+        return "video/webm";
+    if (buffer.length < 12 || buffer.subarray(4, 8).toString("ascii") !== "ftyp")
+        return undefined;
+    const brand = buffer.subarray(8, 12).toString("ascii");
+    if (brand === "qt  ")
+        return "video/quicktime";
+    return MP4_FILE_TYPE_BRANDS.has(brand) ? "video/mp4" : undefined;
+}
+function sniffMimeType(buffer, declared, name) {
     let detected = sniffImageMimeType(buffer);
     if (!detected && buffer.subarray(0, 4).toString("ascii") === "%PDF")
         detected = "application/pdf";
@@ -97,8 +99,10 @@ function sniffMimeType(buffer, declared) {
     else if (buffer.subarray(0, 4).toString("ascii") === "RIFF" && buffer.subarray(8, 12).toString("ascii") === "WAVE") {
         detected = "audio/wav";
     }
-    const mime = detected ?? sniffText(buffer) ?? declared;
-    if (!mime || !ALLOWED_MIME_TYPES.has(mime)) {
+    detected ??= sniffVideoMimeType(buffer);
+    const declaredMime = declared && mimePolicy(declared) ? declared : undefined;
+    const mime = detected ?? sniffText(buffer) ?? declaredMime ?? mimeFromExtension(name);
+    if (!mime || !mimePolicy(mime)) {
         throw new Error(`Unsupported attachment type: ${declared || detected || "unknown"}`);
     }
     return mime;
@@ -106,7 +110,7 @@ function sniffMimeType(buffer, declared) {
 function canonicalName(name, fallbackStem, mimeType) {
     const current = safeName(name, fallbackStem);
     const stem = current.replace(/\.[^.]+$/, "");
-    return `${stem}${EXTENSIONS_BY_MIME[mimeType] || extname(current) || ""}`;
+    return `${stem}${mimePolicy(mimeType)?.extension || extname(current) || ""}`;
 }
 async function fetchRemoteAttachment(input, signal) {
     if (!input.url)
@@ -175,14 +179,14 @@ export async function materializeInboundAttachments(config, inputs) {
         if (totalBytes > MAX_INBOUND_TOTAL_BYTES) {
             throw new Error(`Attachments are too large: max ${MAX_INBOUND_TOTAL_BYTES} bytes total`);
         }
-        const mimeType = sniffMimeType(buffer, input.mimeType);
+        const mimeType = sniffMimeType(buffer, input.mimeType, input.name);
         const id = input.id || randomUUID();
         const cleanName = canonicalName(input.name, `attachment-${index + 1}`, mimeType);
         const sha256 = createHash("sha256").update(buffer).digest("hex");
         prepared.push({
             id,
             name: cleanName,
-            kind: kindFromMime(mimeType),
+            kind: mimePolicy(mimeType)?.kind ?? "file",
             mimeType,
             size: buffer.byteLength,
             sha256,

package/dist/media/media-understanding.js

@@ -0,0 +1,215 @@
+import { readFile } from "node:fs/promises";
+import { createPartFromUri, createUserContent, FileState, GoogleGenAI } from "@google/genai";
+import { parseModelRef, resolveModel } from "../models/index.js";
+const GEMINI_API_VERSION_PATTERN = /\/(v1(?:beta|alpha)?|v\d+beta\d*)\/?$/;
+const AUDIO_UNDERSTANDING_TIMEOUT_MS = 30_000;
+const VIDEO_UNDERSTANDING_TIMEOUT_MS = 5 * 60_000;
+const GEMINI_FILE_POLL_INTERVAL_MS = 2_000;
+const GEMINI_FILE_DELETE_TIMEOUT_MS = 5_000;
+function normalizeDerivedText(text) {
+    return text.trim().replace(/\n{3,}/g, "\n\n");
+}
+function labelForAttachment(kind) {
+    if (kind === "audio")
+        return "transcription";
+    if (kind === "video")
+        return "summary";
+    return "text";
+}
+function geminiHttpOptions(config) {
+    const ref = parseModelRef(`google/${config.mediaUnderstanding.video.model}`);
+    const model = ref ? resolveModel(ref, config) : undefined;
+    const baseUrl = model?.baseUrl;
+    if (!baseUrl)
+        return { timeout: VIDEO_UNDERSTANDING_TIMEOUT_MS };
+    const match = baseUrl.match(GEMINI_API_VERSION_PATTERN);
+    if (!match)
+        return { baseUrl, timeout: VIDEO_UNDERSTANDING_TIMEOUT_MS };
+    return {
+        baseUrl: baseUrl.slice(0, match.index),
+        apiVersion: match[1],
+        timeout: VIDEO_UNDERSTANDING_TIMEOUT_MS,
+    };
+}
+function timedOut(error) {
+    return (error instanceof Error &&
+        (/timed out|timeout/i.test(error.message) || error.name === "AbortError" || error.name === "TimeoutError"));
+}
+function videoTimeoutError() {
+    return new Error(`Gemini video understanding timed out after ${Math.round(VIDEO_UNDERSTANDING_TIMEOUT_MS / 60_000)} minutes.`);
+}
+function remainingVideoUnderstandingMs(deadline) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0)
+        throw videoTimeoutError();
+    return remaining;
+}
+class VideoUnderstandingDeadline {
+    expiresAt = Date.now() + VIDEO_UNDERSTANDING_TIMEOUT_MS;
+    signal() {
+        return AbortSignal.timeout(remainingVideoUnderstandingMs(this.expiresAt));
+    }
+    async sleep(ms) {
+        const delay = Math.min(ms, remainingVideoUnderstandingMs(this.expiresAt));
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        remainingVideoUnderstandingMs(this.expiresAt);
+    }
+}
+function fallbackDerivedText(attachment, error) {
+    if (!attachment.mimeType?.startsWith("video/"))
+        return undefined;
+    const detail = timedOut(error)
+        ? `Automatic video understanding timed out after ${Math.round(VIDEO_UNDERSTANDING_TIMEOUT_MS / 60_000)} minutes.`
+        : "Automatic video understanding failed before a summary was produced.";
+    return {
+        provider: "local",
+        model: "media-understanding-note",
+        label: "note",
+        text: detail,
+    };
+}
+async function waitForGeminiFileActive(ai, uploaded, deadline) {
+    let file = uploaded;
+    let polled = false;
+    for (;;) {
+        if (file.state === FileState.ACTIVE)
+            return file;
+        if (file.state === FileState.FAILED) {
+            throw new Error(file.error?.message ?? "Gemini file processing failed");
+        }
+        if (!file.name)
+            throw new Error("Gemini file upload did not return a file name");
+        if (polled)
+            await deadline.sleep(GEMINI_FILE_POLL_INTERVAL_MS);
+        file = await ai.files.get({
+            name: file.name,
+            config: { abortSignal: deadline.signal() },
+        });
+        polled = true;
+    }
+}
+async function deleteGeminiFile(ai, name) {
+    try {
+        await ai.files.delete({ name, config: { abortSignal: AbortSignal.timeout(GEMINI_FILE_DELETE_TIMEOUT_MS) } });
+    }
+    catch (error) {
+        console.warn("Gemini file cleanup failed", error);
+    }
+}
+async function transcribeAudioAttachment(config, attachment) {
+    if (!attachment.localPath || !attachment.mimeType?.startsWith("audio/"))
+        return undefined;
+    const apiKey = process.env[config.mediaUnderstanding.audio.apiKeyEnv];
+    if (!apiKey) {
+        console.warn(`media understanding skipped: ${config.mediaUnderstanding.audio.apiKeyEnv} is not set`);
+        return undefined;
+    }
+    const form = new FormData();
+    form.set("model", config.mediaUnderstanding.audio.model);
+    form.set("file", new Blob([await readFile(attachment.localPath)], { type: attachment.mimeType }), attachment.name);
+    const response = await fetch("https://api.groq.com/openai/v1/audio/transcriptions", {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+        },
+        body: form,
+        signal: AbortSignal.timeout(AUDIO_UNDERSTANDING_TIMEOUT_MS),
+    });
+    if (!response.ok)
+        throw new Error(`Groq transcription failed: HTTP ${response.status}`);
+    const parsed = (await response.json());
+    const text = parsed.text?.trim();
+    if (!text)
+        return undefined;
+    return {
+        provider: "groq",
+        model: config.mediaUnderstanding.audio.model,
+        text: normalizeDerivedText(text),
+        label: labelForAttachment(attachment.kind),
+    };
+}
+async function summarizeVideoAttachment(config, attachment) {
+    if (!attachment.localPath || !attachment.mimeType?.startsWith("video/"))
+        return undefined;
+    const apiKey = process.env[config.mediaUnderstanding.video.apiKeyEnv];
+    if (!apiKey) {
+        console.warn(`media understanding skipped: ${config.mediaUnderstanding.video.apiKeyEnv} is not set`);
+        return undefined;
+    }
+    const ai = new GoogleGenAI({ apiKey, httpOptions: geminiHttpOptions(config) });
+    const deadline = new VideoUnderstandingDeadline();
+    let uploadedName;
+    try {
+        const uploaded = await ai.files.upload({
+            file: attachment.localPath,
+            config: {
+                mimeType: attachment.mimeType,
+                displayName: attachment.name,
+                abortSignal: deadline.signal(),
+            },
+        });
+        uploadedName = uploaded.name;
+        const file = await waitForGeminiFileActive(ai, uploaded, deadline);
+        const fileUri = file.uri ?? uploaded.uri;
+        if (!fileUri)
+            throw new Error("Gemini file upload did not return a file URI");
+        const response = await ai.models.generateContent({
+            model: config.mediaUnderstanding.video.model,
+            contents: createUserContent([
+                {
+                    text: "Provide a concise description of this video, including any spoken content if present, and summarize the key visible events.",
+                },
+                createPartFromUri(fileUri, file.mimeType ?? uploaded.mimeType ?? attachment.mimeType),
+            ]),
+            config: { abortSignal: deadline.signal() },
+        });
+        const text = response.text?.trim();
+        if (!text)
+            return undefined;
+        return {
+            provider: "google",
+            model: config.mediaUnderstanding.video.model,
+            text: normalizeDerivedText(text),
+            label: labelForAttachment(attachment.kind),
+        };
+    }
+    finally {
+        if (uploadedName)
+            await deleteGeminiFile(ai, uploadedName);
+    }
+}
+export async function deriveInboundAttachmentText(config, attachments) {
+    const next = [];
+    for (const attachment of attachments) {
+        if (attachment.derived?.text || !attachment.localPath) {
+            next.push(attachment);
+            continue;
+        }
+        try {
+            if (attachment.mimeType?.startsWith("audio/")) {
+                const text = await transcribeAudioAttachment(config, attachment);
+                if (text) {
+                    next.push({ ...attachment, derived: { ...(attachment.derived ?? {}), text } });
+                    continue;
+                }
+            }
+            if (attachment.mimeType?.startsWith("video/")) {
+                const text = await summarizeVideoAttachment(config, attachment);
+                if (text) {
+                    next.push({ ...attachment, derived: { ...(attachment.derived ?? {}), text } });
+                    continue;
+                }
+            }
+        }
+        catch (error) {
+            console.error("media understanding failed", error);
+            const fallback = fallbackDerivedText(attachment, error);
+            if (fallback) {
+                next.push({ ...attachment, derived: { ...(attachment.derived ?? {}), text: fallback } });
+                continue;
+            }
+        }
+        next.push(attachment);
+    }
+    return next;
+}

package/dist/memory/index/store.js

@@ -11,6 +11,11 @@ export class MemoryIndexStore {
     embeddingProvider;
     embeddingModel;
     embeddingDimensions;
+    vectorCapabilityValue;
+    findChunkIdByHashStmt;
+    insertChunkStmt;
+    insertFtsStmt;
+    insertMemoryVecStmt;
     constructor(options) {
         if (!options.db && !options.path)
             throw new Error("MemoryIndexStore requires a db or path");
@@ -32,6 +37,16 @@ export class MemoryIndexStore {
             embeddingModel: this.embeddingModel,
             embeddingDimensions: this.embeddingDimensions,
         });
+        this.vectorCapabilityValue = readMeta(this.db, "vector_capability") === "sqlite-vec" ? "sqlite-vec" : "blob-js";
+        this.findChunkIdByHashStmt = this.db.prepare("SELECT id FROM memory_chunks WHERE content_hash = ?");
+        this.insertChunkStmt = this.db.prepare(`INSERT INTO memory_chunks (
+					content_hash, corpus, text_full, snippet, token_count, metadata_json, embedding_model,
+					embedding_dimensions, embedding
+				 ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+        this.insertFtsStmt = this.db.prepare("INSERT INTO memory_fts(rowid, text_full, snippet) VALUES (?, ?, ?)");
+        if (this.vectorCapabilityValue === "sqlite-vec") {
+            this.insertMemoryVecStmt = this.db.prepare("INSERT INTO memory_vec(rowid, embedding) VALUES (CAST(? AS INTEGER), ?)");
+        }
     }
     static open(config) {
         return new MemoryIndexStore({
@@ -80,9 +95,7 @@ export class MemoryIndexStore {
                     this.insertSourceMapping(preloadedId, item);
                     continue;
                 }
-                const existing = this.db
-                    .prepare("SELECT id FROM memory_chunks WHERE content_hash = ?")
-                    .get(item.contentHash);
+                const existing = this.findChunkIdByHashStmt.get(item.contentHash);
                 if (existing)
                     this.insertSourceMapping(existing.id, item);
             }
@@ -333,7 +346,7 @@ export class MemoryIndexStore {
         };
     }
     vectorCapability() {
-        return readMeta(this.db, "vector_capability") === "sqlite-vec" ? "sqlite-vec" : "blob-js";
+        return this.vectorCapabilityValue;
     }
     vectorRowCount() {
         try {
@@ -377,26 +390,17 @@ export class MemoryIndexStore {
             ? { id: knownId }
             : knownMissingHashes?.has(item.contentHash)
                 ? undefined
-                : this.db.prepare("SELECT id FROM memory_chunks WHERE content_hash = ?").get(item.contentHash);
+                : this.findChunkIdByHashStmt.get(item.contentHash);
         if (existing) {
             knownIds.set(item.contentHash, existing.id);
             this.insertSourceMapping(existing.id, item);
             return existing.id;
         }
-        const result = this.db
-            .prepare(`INSERT INTO memory_chunks (
-					content_hash, corpus, text_full, snippet, token_count, metadata_json, embedding_model,
-					embedding_dimensions, embedding
-				 ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-            .run(item.contentHash, item.corpus, item.text, item.snippet, item.tokenCount, item.metadataJson, this.embeddingModel, this.embeddingDimensions, encodeVector(item.embedding));
+        const result = this.insertChunkStmt.run(item.contentHash, item.corpus, item.text, item.snippet, item.tokenCount, item.metadataJson, this.embeddingModel, this.embeddingDimensions, encodeVector(item.embedding));
         const id = Number(result.lastInsertRowid);
-        this.db
-            .prepare("INSERT INTO memory_fts(rowid, text_full, snippet) VALUES (?, ?, ?)")
-            .run(id, item.text, item.snippet);
+        this.insertFtsStmt.run(id, item.text, item.snippet);
         if (this.vectorCapability() === "sqlite-vec") {
-            this.db
-                .prepare("INSERT INTO memory_vec(rowid, embedding) VALUES (CAST(? AS INTEGER), ?)")
-                .run(id, encodeVector(item.embedding));
+            this.insertMemoryVecStmt.run(id, encodeVector(item.embedding));
         }
         knownIds.set(item.contentHash, id);
         this.insertSourceMapping(id, item);

package/dist/memory/index/vector-codec.js

@@ -15,8 +15,8 @@ export function cosineDistance(a, b) {
     let aNorm = 0;
     let bNorm = 0;
     for (let index = 0; index < a.length; index++) {
-        const av = a[index] ?? 0;
-        const bv = b[index] ?? 0;
+        const av = a[index];
+        const bv = b[index];
         dot += av * bv;
         aNorm += av * av;
         bNorm += bv * bv;

package/dist/memory/lcm/context-transformer.js

@@ -176,8 +176,12 @@ export class LcmContextTransformer {
             tokensSaved = Math.max(0, candidate.chunkTokens - summaryItem.tokens);
             await this.condenseRuntimeSummaries({ state, sessionKey: input.sessionKey, signal: input.signal });
         };
-        input.state.compactionQueue = input.state.compactionQueue.then(run, run);
-        await input.state.compactionQueue;
+        // Serialize compactions per state: run after the prior one settles. Keep the shared
+        // compactionQueue non-rejecting so a failure here can't poison the next caller's link,
+        // and await the real work promise so this caller still surfaces its own error.
+        const settled = input.state.compactionQueue.then(run);
+        input.state.compactionQueue = settled.catch(() => undefined);
+        await settled;
         return { compacted, tokensSaved };
     }
     async persistRuntimeSummary(input) {

package/dist/memory/lcm/segment-manager.js

@@ -19,8 +19,12 @@ export class LcmSegmentManager {
     }
     subscribeRuntime(runtime, sessionId) {
         const unsubscribe = runtime.subscribe((record) => {
-            this.projectionQueue = this.projectionQueue.then(() => this.projectRuntimeRecord(runtime, record, sessionId), () => this.projectRuntimeRecord(runtime, record, sessionId));
-            void this.projectionQueue.catch((error) => {
+            // Serialize projections; the prior link is always non-rejecting (see the .catch
+            // below), so each projection runs once after it. Count + log failures in the same
+            // chain and recover, so the stored queue never carries a rejection forward.
+            this.projectionQueue = this.projectionQueue
+                .then(() => this.projectRuntimeRecord(runtime, record, sessionId))
+                .catch((error) => {
                 this.projectionFailures += 1;
                 console.error(`memory projection failed for ${runtime.channelKey}`, error);
             });

package/dist/memory/lcm/store/index-ids.js

@@ -0,0 +1,6 @@
+export function lcmRecordIndexSourceId(id) {
+    return `lcm_record:${id}`;
+}
+export function lcmSummaryIndexSourceId(id) {
+    return `lcm_summary:${id}`;
+}

package/dist/memory/lcm/store/inserts.js

@@ -0,0 +1,31 @@
+import { jsonOrNull, sourceRecordIdToString } from "./serialization.js";
+export function insertRecordPrepared(db, normalized) {
+    const inserted = db
+        .prepare(`INSERT INTO lcm_records (
+				record_key, segment_id, kind, text_full, happened_at, session_id, channel_key,
+				channel_id, job_id, source_type, source_path, source_line, source_record_id,
+				source_message_id, source_ref, attachments_json, metadata_json, parts_json
+			 ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(normalized.recordKey, normalized.segmentId, normalized.kind, normalized.text, normalized.happenedAt, normalized.sessionId, normalized.channelKey, normalized.channelId, normalized.jobId, normalized.source.sourceType, normalized.source.sourcePath ?? null, normalized.source.sourceLine ?? null, sourceRecordIdToString(normalized.source.sourceRecordId), normalized.source.sourceMessageId ?? null, normalized.source.sourceRef ?? null, jsonOrNull(normalized.attachments), jsonOrNull(normalized.metadata), jsonOrNull(normalized.parts));
+    const id = Number(inserted.lastInsertRowid);
+    if (normalized.kind !== "boundary") {
+        db.prepare("INSERT INTO lcm_records_fts(rowid, text_full) VALUES (?, ?)").run(id, normalized.text);
+    }
+    const row = db.prepare("SELECT * FROM lcm_records WHERE id = ?").get(id);
+    if (!row)
+        throw new Error(`Failed to read inserted LCM record: ${id}`);
+    return row;
+}
+export function insertSummaryPrepared(db, normalized, insertEdges) {
+    const inserted = db
+        .prepare(`INSERT INTO lcm_summaries (
+				summary_key, segment_id, depth, status, text_full, pinned,
+				covers_from_record_id, covers_to_record_id, snapshot_json, source_type, source_path,
+				source_line, source_record_id, source_message_id, source_ref, metadata_json
+			 ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(normalized.summaryKey, normalized.segmentId, normalized.depth, normalized.status, normalized.text, normalized.pinned ? 1 : 0, normalized.coversFromRecordId, normalized.coversToRecordId, null, normalized.source.sourceType, normalized.source.sourcePath ?? null, normalized.source.sourceLine ?? null, sourceRecordIdToString(normalized.source.sourceRecordId), normalized.source.sourceMessageId ?? null, normalized.source.sourceRef ?? null, jsonOrNull(normalized.metadata));
+    const id = Number(inserted.lastInsertRowid);
+    db.prepare("INSERT INTO lcm_summaries_fts(rowid, text_full) VALUES (?, ?)").run(id, normalized.text);
+    insertEdges(id, normalized.sourceItems, normalized.parents);
+    return id;
+}

package/dist/memory/lcm/store/normalizers.js

@@ -0,0 +1,91 @@
+import { stableHash } from "./serialization.js";
+export function normalizeSource(source) {
+    return {
+        sourceType: source.sourceType,
+        sourcePath: source.sourcePath ?? null,
+        sourceLine: source.sourceLine ?? null,
+        sourceRecordId: source.sourceRecordId ?? null,
+        sourceMessageId: source.sourceMessageId ?? null,
+        sourceRef: source.sourceRef ?? null,
+    };
+}
+export function normalizeRecordInput(input) {
+    const text = (input.text ?? "").trim();
+    if (!text && input.kind !== "boundary")
+        throw new Error("LCM record text must not be empty");
+    const source = normalizeSource(input.source);
+    const happenedAt = input.happenedAt ?? new Date().toISOString();
+    const parts = input.parts?.length ? input.parts : null;
+    const normalizedText = text || "Session boundary";
+    return {
+        segmentId: input.segmentId,
+        kind: input.kind,
+        text: normalizedText,
+        parts,
+        happenedAt,
+        sessionId: input.sessionId ?? null,
+        channelKey: input.channelKey ?? null,
+        channelId: input.channelId ?? null,
+        jobId: input.jobId ?? null,
+        source,
+        attachments: input.attachments?.length ? input.attachments : null,
+        metadata: input.metadata ?? null,
+        recordKey: computeLcmRecordKey({ ...input, happenedAt }),
+    };
+}
+export function normalizeSummaryInput(input) {
+    const text = (input.text ?? "").trim();
+    const source = normalizeSource(input.source);
+    const status = input.status ?? (text ? "ready" : "placeholder");
+    const normalizedText = text || "";
+    return {
+        segmentId: input.segmentId,
+        depth: input.depth,
+        status,
+        text: normalizedText,
+        pinned: input.pinned ?? false,
+        coversFromRecordId: input.coversFromRecordId ?? null,
+        coversToRecordId: input.coversToRecordId ?? null,
+        source,
+        sourceItems: input.sourceItems ?? [],
+        parents: input.parents ?? [],
+        metadata: input.metadata ?? null,
+        summaryKey: stableHash({
+            segmentId: input.segmentId,
+            depth: input.depth,
+            status,
+            text: normalizedText,
+            coversFromRecordId: input.coversFromRecordId ?? null,
+            coversToRecordId: input.coversToRecordId ?? null,
+            source,
+            parents: input.parents ?? [],
+        }),
+    };
+}
+export function computeLcmRecordKey(input) {
+    const text = (input.text ?? "").trim();
+    if (!text && input.kind !== "boundary")
+        throw new Error("LCM record text must not be empty");
+    const parts = input.parts?.length ? input.parts : null;
+    return stableHash({
+        segmentId: input.segmentId,
+        kind: input.kind,
+        text: text || "Session boundary",
+        parts,
+        happenedAt: input.happenedAt ?? new Date().toISOString(),
+        source: normalizeSource(input.source),
+    });
+}
+export function dedupeSummaryParentIds(values) {
+    const seen = new Set();
+    const result = [];
+    for (const value of values) {
+        if (!Number.isInteger(value) || value <= 0)
+            throw new Error("LCM summary parents must be positive integer ids");
+        if (seen.has(value))
+            continue;
+        seen.add(value);
+        result.push(value);
+    }
+    return result;
+}