@unblocklabs/unblock-memory 0.7.3 → 0.7.4

package/dist/src/agent-transcript.d.ts

@@ -1,8 +1,39 @@
 import type { DatabaseSync } from "node:sqlite";
-/** The OpenClaw agent database versions whose transcript layout we read. */
+/** Identity fence, not a payload-format allowlist. Required capabilities are checked below. */
 export declare function agentTranscriptSchemaVersion(db: DatabaseSync, errorMessage?: string): number;
 export declare function assertAgentTranscriptIdentity(db: DatabaseSync, agentId: string, version: number, errorMessage?: string): void;
-export declare function assertAgentTranscriptSchema(db: DatabaseSync, agentId: string, errorMessage?: string): void;
-export declare const ACTIVE_EVENTS_FROM = "FROM session_transcript_active_events a\n  JOIN transcript_events e ON e.session_id=a.session_id AND e.seq=a.event_seq";
-export declare const ACTIVE_EVENT_COUNT_SQL = "SELECT COUNT(*) n,COALESCE(SUM(length(e.event_json)),0) bytes\n  FROM session_transcript_active_events a\n  JOIN transcript_events e ON e.session_id=a.session_id AND e.seq=a.event_seq WHERE a.session_id=?";
-export declare const ACTIVE_EVENT_ROWS_SQL = "SELECT e.seq,e.event_json eventJson,e.created_at createdAt\n  FROM session_transcript_active_events a\n  JOIN transcript_events e ON e.session_id=a.session_id AND e.seq=a.event_seq WHERE a.session_id=? ORDER BY a.active_position";
+type AgentTranscriptRow = {
+    seq: number;
+    eventJson: string;
+    createdAt: number;
+};
+type TranscriptSnapshot = {
+    kind: "ready";
+    rows: AgentTranscriptRow[];
+} | {
+    kind: "cold";
+} | {
+    kind: "oversized";
+} | {
+    kind: "unreadable";
+};
+/**
+ * One read-only storage boundary for full-fidelity active transcripts. The public
+ * SDK's full reader may restore cold archives; its read-only catalog truncates and
+ * redacts content. Neither currently provides the contract these consumers need.
+ * Keep payload SQL here until the SDK offers a bounded, full-fidelity read-only API.
+ */
+export declare class AgentTranscriptReader {
+    #private;
+    readonly db: DatabaseSync;
+    constructor(db: DatabaseSync, agentId: string, errorMessage?: string);
+    /** Include storage availability in incremental fingerprints, not just hot row counts. */
+    coldSql(sessionIdExpression: string): string;
+    /** Caller owns a transaction so metadata, cold marker, bounds and rows share one snapshot. */
+    read(sessionId: string, limits?: {
+        maxEvents?: number;
+        maxBytes?: number;
+        maxSeq?: number;
+    }): TranscriptSnapshot;
+}
+export {};

package/dist/src/agent-transcript.js

@@ -1,8 +1,9 @@
-/** The OpenClaw agent database versions whose transcript layout we read. */
+import { zstdDecompressSync } from "node:zlib";
+/** Identity fence, not a payload-format allowlist. Required capabilities are checked below. */
 export function agentTranscriptSchemaVersion(db, errorMessage) {
     const version = db.prepare("PRAGMA user_version").get()?.user_version;
-    if (typeof version !== "number" || ![17, 18, 19].includes(version)) {
-        throw new Error(errorMessage ?? "unsupported OpenClaw agent database schema: expected one of 17, 18, 19, " +
+    if (typeof version !== "number" || !Number.isSafeInteger(version) || version < 17) {
+        throw new Error(errorMessage ?? "unsupported OpenClaw agent database schema: expected 17 or newer, " +
             `found ${String(version ?? "unknown")}`);
     }
     return version;
@@ -18,12 +19,101 @@ export function assertAgentTranscriptIdentity(db, agentId, version, errorMessage
         fail(`OpenClaw agent database belongs to ${String(meta?.agentId)}, not ${agentId}`);
     }
 }
-export function assertAgentTranscriptSchema(db, agentId, errorMessage) {
-    assertAgentTranscriptIdentity(db, agentId, agentTranscriptSchemaVersion(db, errorMessage), errorMessage);
-}
-export const ACTIVE_EVENTS_FROM = `FROM session_transcript_active_events a
+const ACTIVE_EVENTS_FROM = `FROM session_transcript_active_events a
   JOIN transcript_events e ON e.session_id=a.session_id AND e.seq=a.event_seq`;
-export const ACTIVE_EVENT_COUNT_SQL = `SELECT COUNT(*) n,COALESCE(SUM(length(e.event_json)),0) bytes
-  ${ACTIVE_EVENTS_FROM} WHERE a.session_id=?`;
-export const ACTIVE_EVENT_ROWS_SQL = `SELECT e.seq,e.event_json eventJson,e.created_at createdAt
-  ${ACTIVE_EVENTS_FROM} WHERE a.session_id=? ORDER BY a.active_position`;
+const MAX_COMPRESSED_BYTES = 4 * 1024 * 1024;
+const utf8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+/**
+ * One read-only storage boundary for full-fidelity active transcripts. The public
+ * SDK's full reader may restore cold archives; its read-only catalog truncates and
+ * redacts content. Neither currently provides the contract these consumers need.
+ * Keep payload SQL here until the SDK offers a bounded, full-fidelity read-only API.
+ */
+export class AgentTranscriptReader {
+    db;
+    #schemaVersion;
+    #compressed;
+    #cold;
+    #utf8Storage;
+    constructor(db, agentId, errorMessage) {
+        this.db = db;
+        const version = agentTranscriptSchemaVersion(db, errorMessage);
+        this.#schemaVersion = version;
+        this.#utf8Storage = db.prepare("PRAGMA encoding").get()?.encoding === "UTF-8";
+        assertAgentTranscriptIdentity(db, agentId, version, errorMessage);
+        const required = {
+            transcript_events: ["session_id", "seq", "event_json", "created_at"],
+            session_transcript_active_events: ["session_id", "active_position", "event_seq"],
+        };
+        const columns = (table) => new Set(db.prepare(`PRAGMA table_info(${table})`).all().map(row => row.name));
+        for (const [table, names] of Object.entries(required)) {
+            const found = columns(table);
+            if (names.some(name => !found.has(name)))
+                throw new Error(`Unsupported transcript capabilities: ${table}`);
+        }
+        const payload = columns("transcript_events");
+        this.#compressed = payload.has("event_zstd") && payload.has("event_utf8_bytes");
+        if ((version >= 23 || payload.has("event_zstd") || payload.has("event_utf8_bytes")) && !this.#compressed) {
+            throw new Error("Unsupported transcript compression capabilities");
+        }
+        this.#cold = columns("session_transcript_cold_archives").has("session_id");
+        if (version >= 20 && !this.#cold)
+            throw new Error("Unsupported transcript cold-storage capabilities");
+    }
+    /** Include storage availability in incremental fingerprints, not just hot row counts. */
+    coldSql(sessionIdExpression) {
+        return this.#cold ? `EXISTS (SELECT 1 FROM session_transcript_cold_archives cold WHERE cold.session_id=${sessionIdExpression})` : "0";
+    }
+    /** Caller owns a transaction so metadata, cold marker, bounds and rows share one snapshot. */
+    read(sessionId, limits = {}) {
+        if (!this.db.isTransaction)
+            throw new Error("Transcript read requires a snapshot transaction");
+        // Long-lived audit/source readers may outlive a host migration. Reopen before
+        // trusting cached capabilities; absence of old hot rows is not deletion proof.
+        if (this.db.prepare("PRAGMA user_version").get()?.user_version !== this.#schemaVersion)
+            return { kind: "unreadable" };
+        if (this.#cold && this.db.prepare("SELECT 1 FROM session_transcript_cold_archives WHERE session_id=?").get(sessionId)) {
+            return { kind: "cold" };
+        }
+        const maxEvents = limits.maxEvents ?? 50_000, maxBytes = limits.maxBytes ?? 64 * 1024 * 1024;
+        const maxSeq = limits.maxSeq ?? Number.MAX_SAFE_INTEGER;
+        // SQLite's BLOB length measures the database encoding, not decoded UTF-8.
+        // Non-UTF-8 stores still enforce the byte budget below during bounded iteration.
+        const bytes = !this.#utf8Storage ? "0" : this.#compressed
+            ? "COALESCE(length(CAST(e.event_json AS BLOB)),e.event_utf8_bytes,0)" : "length(CAST(e.event_json AS BLOB))";
+        const size = this.db.prepare(`SELECT COUNT(*) n,COALESCE(SUM(${bytes}),0) bytes
+      ${ACTIVE_EVENTS_FROM} WHERE a.session_id=? AND e.seq<=?`).get(sessionId, maxSeq);
+        if (Number(size.n) > maxEvents || Number(size.bytes) > maxBytes)
+            return { kind: "oversized" };
+        const rows = [];
+        let totalBytes = 0;
+        for (const row of this.db.prepare(`SELECT e.seq,e.event_json eventJson,e.created_at createdAt
+      ${this.#compressed ? ",e.event_zstd compressed,e.event_utf8_bytes rawBytes" : ""}
+      ${ACTIVE_EVENTS_FROM} WHERE a.session_id=? AND e.seq<=? ORDER BY a.active_position`).iterate(sessionId, maxSeq)) {
+            let eventJson;
+            if (typeof row.eventJson === "string")
+                eventJson = row.eventJson;
+            else {
+                const compressed = row.compressed, rawBytes = row.rawBytes;
+                if (!(compressed instanceof Uint8Array) || !compressed.byteLength || compressed.byteLength > MAX_COMPRESSED_BYTES ||
+                    typeof rawBytes !== "number" || !Number.isSafeInteger(rawBytes) || rawBytes <= 0 || rawBytes > MAX_COMPRESSED_BYTES) {
+                    return { kind: "unreadable" };
+                }
+                try {
+                    const decoded = zstdDecompressSync(compressed, { maxOutputLength: rawBytes });
+                    if (decoded.byteLength !== rawBytes)
+                        return { kind: "unreadable" };
+                    eventJson = utf8.decode(decoded);
+                }
+                catch {
+                    return { kind: "unreadable" };
+                }
+            }
+            totalBytes += Buffer.byteLength(eventJson);
+            if (totalBytes > maxBytes)
+                return { kind: "oversized" };
+            rows.push({ seq: Number(row.seq), eventJson, createdAt: Number(row.createdAt) });
+        }
+        return { kind: "ready", rows };
+    }
+}

package/dist/src/inside-out-sources.js

@@ -5,7 +5,7 @@ import { createZstdDecompress, zstdDecompressSync } from "node:zlib";
 import { createInterface } from "node:readline";
 import { PassThrough } from "node:stream";
 import { pipeline } from "node:stream/promises";
-import { ACTIVE_EVENTS_FROM, assertAgentTranscriptSchema } from "./agent-transcript.js";
+import { AgentTranscriptReader } from "./agent-transcript.js";
 /** Files contain branch trees; keep the selected leaf, not abandoned sibling conversations. */
 function selectedBranch(events) {
     const nodes = new Map(events.filter(e => e.id).map(e => [e.id, e]));
@@ -57,10 +57,11 @@ export async function* readInsideOutSources(paths, errors) {
         const db = new DatabaseSync(paths.databasePath, { readOnly: true });
         try {
             db.exec("PRAGMA busy_timeout=1000");
-            assertAgentTranscriptSchema(db, paths.agentId);
+            const transcripts = new AgentTranscriptReader(db, paths.agentId);
             const sessions = db.prepare(`SELECT w.session_id sessionId, COALESCE(w.channel,c.channel,'local') channel,
         COALESCE(w.account_id,c.account_id,'') account, COALESCE(r.generation,'') revision,
-        COALESCE((SELECT MAX(seq) FROM transcript_events WHERE session_id=w.session_id),0) tail FROM session_windows w
+        COALESCE((SELECT MAX(seq) FROM transcript_events WHERE session_id=w.session_id),0) tail,
+        ${transcripts.coldSql("w.session_id")} cold FROM session_windows w
         LEFT JOIN conversations c ON c.conversation_id=w.primary_conversation_id
         LEFT JOIN transcript_rewrite_watermarks r ON r.session_id=w.session_id
         WHERE (? IS NULL OR w.session_id=?) ORDER BY w.started_at,w.session_id`).all(paths.sessionId ?? null, paths.sessionId ?? null);
@@ -83,15 +84,23 @@ export async function* readInsideOutSources(paths, errors) {
             }
             for (const s of sessions) {
                 const sessionId = String(s.sessionId), source = `live:${sessionId}`;
-                yield { source, sessionId, revision: String(s.revision), signature: JSON.stringify([s.revision, s.tail]), read: () => {
-                        const events = db.prepare(`SELECT e.seq,e.event_json eventJson,e.created_at createdAt
-            ${ACTIVE_EVENTS_FROM} WHERE a.session_id=? AND e.seq<=? ORDER BY a.active_position`).all(sessionId, s.tail).map(row => {
-                            const event = JSON.parse(String(row.eventJson));
-                            event.seq = Number(row.seq);
-                            event.timestamp ??= new Date(Number(row.createdAt)).toISOString();
-                            return event;
-                        });
-                        return { sessionId, source, events, ...metadata.get(sessionId) };
+                yield { source, sessionId, revision: String(s.revision), signature: JSON.stringify([s.revision, s.tail, s.cold]), read: () => {
+                        db.exec("BEGIN");
+                        try {
+                            const snapshot = transcripts.read(sessionId, { maxSeq: Number(s.tail) });
+                            if (snapshot.kind !== "ready")
+                                throw new Error(`Transcript unavailable: ${snapshot.kind}`);
+                            const events = snapshot.rows.map(row => {
+                                const event = JSON.parse(row.eventJson);
+                                event.seq = row.seq;
+                                event.timestamp ??= new Date(row.createdAt).toISOString();
+                                return event;
+                            });
+                            return { sessionId, source, events, ...metadata.get(sessionId) };
+                        }
+                        finally {
+                            db.exec("COMMIT");
+                        }
                     } };
             }
         }

package/dist/src/response-episodes.d.ts

@@ -48,12 +48,12 @@ export declare function responseEpisodes(session: ResponseSession, rows: readonl
     episodes: ResponseEpisode[];
     coverage: ResponseCoverage;
 };
-/** Bounded, read-only active transcript snapshot; archived/deleted branches are excluded. */
+/** Bounded, read-only active transcript snapshot; cold history is deferred, inactive branches excluded. */
 export declare class ResponseTranscriptReader {
     #private;
     constructor(path: string, agentId: string);
     sessions(config: ResponseAuditConfig, now: number, after?: string): ResponseSession[];
-    /** null = confirmed absent/ineligible; undefined = over budget, not evidence of deletion. */
+    /** null = confirmed absent/ineligible; undefined = unavailable/over budget, never evidence of deletion. */
     read(input: ResponseSession | string, config: ResponseAuditConfig): (ReturnType<typeof responseEpisodes> & {
         revision: string;
     }) | null | undefined;

package/dist/src/response-episodes.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { DatabaseSync } from "node:sqlite";
-import { ACTIVE_EVENT_COUNT_SQL, ACTIVE_EVENT_ROWS_SQL, assertAgentTranscriptSchema } from "./agent-transcript.js";
+import { AgentTranscriptReader } from "./agent-transcript.js";
 import { messageText } from "./whisperer-context.js";
 import { responseUserText } from "./response-text.js";
 export const RESPONSE_EXTRACTOR_VERSION = 5;
@@ -176,14 +176,15 @@ export function responseEpisodes(session, rows, config) {
     }
     return { episodes, coverage };
 }
-/** Bounded, read-only active transcript snapshot; archived/deleted branches are excluded. */
+/** Bounded, read-only active transcript snapshot; cold history is deferred, inactive branches excluded. */
 export class ResponseTranscriptReader {
     #db;
+    #transcripts;
     constructor(path, agentId) {
         this.#db = new DatabaseSync(path, { readOnly: true });
         try {
             this.#db.exec("PRAGMA query_only=ON; PRAGMA busy_timeout=1000");
-            assertAgentTranscriptSchema(this.#db, agentId, "Unsupported response-audit transcript schema or agent");
+            this.#transcripts = new AgentTranscriptReader(this.#db, agentId, "Unsupported response-audit transcript schema or agent");
         }
         catch (error) {
             this.#db.close();
@@ -191,17 +192,55 @@ export class ResponseTranscriptReader {
         }
     }
     sessions(config, now, after = "") {
-        return this.#db.prepare(`SELECT w.session_id sessionId, COALESCE(w.account_id,c.account_id,'') accountId,
+        // Page metadata candidates, then apply the approved-sender filter to decoded
+        // events before the audit cap. Unrelated Slack traffic must not hide previews.
+        const candidates = this.#db.prepare(`SELECT w.session_id sessionId, COALESCE(w.account_id,c.account_id,'') accountId,
       w.chat_type chatType, w.primary_conversation_id conversationId
       FROM session_windows w JOIN conversations c ON c.conversation_id=w.primary_conversation_id
       WHERE COALESCE(w.channel,c.channel)='slack' AND w.chat_type IN (${config.chatTypes.map(() => "?").join(",")})
       AND w.session_id>?
       AND EXISTS (SELECT 1 FROM transcript_events e JOIN session_transcript_active_events a
-        ON a.session_id=e.session_id AND a.event_seq=e.seq WHERE e.session_id=w.session_id AND e.created_at >= ?
-        AND json_extract(e.event_json,'$.message.role')='user'
-        AND json_extract(e.event_json,'$.message.__openclaw.senderId') IN (${config.senderIds.map(() => "?").join(",")}))
-      ORDER BY w.session_id LIMIT 101`)
-            .all(...config.chatTypes, after, now - config.lookbackDays * 86400_000, ...config.senderIds);
+        ON a.session_id=e.session_id AND a.event_seq=e.seq WHERE e.session_id=w.session_id AND e.created_at >= ?)
+      ORDER BY w.session_id LIMIT 101`);
+        const since = now - config.lookbackDays * 86400_000;
+        const sessions = [];
+        this.#db.exec("BEGIN");
+        try {
+            while (sessions.length < 101) {
+                const page = candidates.all(...config.chatTypes, after, since);
+                for (const session of page) {
+                    const snapshot = this.#transcripts.read(session.sessionId, { maxEvents: MAX_EVENTS, maxBytes: MAX_SESSION_BYTES });
+                    // Saved unavailable sessions are reconciled separately by the caller.
+                    if (snapshot.kind !== "ready")
+                        continue;
+                    const approved = snapshot.rows.some(row => {
+                        if (row.createdAt < since)
+                            return false;
+                        let event;
+                        try {
+                            event = record(JSON.parse(row.eventJson));
+                        }
+                        catch {
+                            return false;
+                        }
+                        const message = record(event?.message), sender = record(message?.__openclaw)?.senderId;
+                        return event?.type === "message" && message?.role === "user" &&
+                            typeof sender === "string" && config.senderIds.includes(sender);
+                    });
+                    if (approved)
+                        sessions.push(session);
+                    if (sessions.length === 101)
+                        break;
+                }
+                if (page.length < 101)
+                    break;
+                after = page.at(-1).sessionId;
+            }
+            return sessions;
+        }
+        finally {
+            this.#db.exec("COMMIT");
+        }
     }
     read(input, config, previousRevision) {
         this.#db.exec("BEGIN");
@@ -216,10 +255,10 @@ export class ResponseTranscriptReader {
                 return null;
             const session = { sessionId, accountId: String(window.accountId),
                 conversationId: String(window.conversationId), chatType: String(window.chatType) };
-            const count = this.#db.prepare(ACTIVE_EVENT_COUNT_SQL).get(session.sessionId);
-            if (Number(count.n) > MAX_EVENTS || Number(count.bytes) > MAX_SESSION_BYTES)
+            const snapshot = this.#transcripts.read(session.sessionId, { maxEvents: MAX_EVENTS, maxBytes: MAX_SESSION_BYTES });
+            if (snapshot.kind !== "ready")
                 return undefined;
-            const rows = this.#db.prepare(ACTIVE_EVENT_ROWS_SQL).all(session.sessionId);
+            const rows = snapshot.rows;
             // Exact active content catches in-place edits and branch changes even when writer
             // watermarks are absent. Raw text is never retained in the checkpoint database.
             const revision = hash([RESPONSE_EXTRACTOR_VERSION, session, config.historyMessages, [...config.senderIds].sort(), rows]);

package/dist/src/session-sync.d.ts

@@ -1,6 +1,6 @@
 import type { ChatType } from "./config.js";
 import { type SessionMetadata, type SessionProjectionInput, type SessionMessageSpan } from "./session-projector.js";
-export declare const PROJECTOR_VERSION = 7;
+export declare const PROJECTOR_VERSION = 8;
 type IndexedSession = SessionMetadata & {
     sourceGeneration: string;
     maxSeq: number;

package/dist/src/session-sync.js

@@ -3,10 +3,10 @@ import { existsSync, lstatSync, readFileSync, statSync } from "node:fs";
 import { chmod, mkdir, readFile, rename, unlink, utimes, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { DatabaseSync } from "node:sqlite";
-import { ACTIVE_EVENTS_FROM, agentTranscriptSchemaVersion, assertAgentTranscriptIdentity } from "./agent-transcript.js";
+import { AgentTranscriptReader, agentTranscriptSchemaVersion, assertAgentTranscriptIdentity } from "./agent-transcript.js";
 import { projectSessionDocument, sessionDocumentPath, } from "./session-projector.js";
 const MANIFEST_VERSION = 1;
-export const PROJECTOR_VERSION = 7;
+export const PROJECTOR_VERSION = 8;
 // Source lives in src/, published code in dist/src/. Read our own pinned dependency
 // metadata, not QMD internals (which may also be substituted by runtime inspectors).
 const sourcePackage = new URL("../package.json", import.meta.url);
@@ -91,6 +91,7 @@ function readSnapshot(params) {
     try {
         db.exec("PRAGMA query_only = ON; PRAGMA busy_timeout = 5000; BEGIN");
         assertSchema(db, params.agentId);
+        const transcripts = new AgentTranscriptReader(db, params.agentId);
         const placeholders = params.chatTypes.map(() => "?").join(", ");
         const windows = db.prepare(`
       SELECT
@@ -104,7 +105,8 @@ function readSnapshot(params) {
         COALESCE(window.started_at, window.created_at) AS startedAt,
         rewrite.generation AS sourceGeneration,
         MAX(active.event_seq) AS maxSeq,
-        COUNT(active.event_seq) AS activeEventCount
+        COUNT(active.event_seq) AS activeEventCount,
+        ${transcripts.coldSql("window.session_id")} AS cold
       FROM session_windows AS window
       LEFT JOIN conversations AS conversation
         ON conversation.conversation_id = window.primary_conversation_id
@@ -116,15 +118,9 @@ function readSnapshot(params) {
       GROUP BY window.session_id
       ORDER BY window.created_at, window.session_id
     `).all(...params.chatTypes);
-        const readEvents = db.prepare(`
-      SELECT a.session_id AS sessionId, e.event_json AS eventJson,
-             e.created_at AS createdAt
-      ${ACTIVE_EVENTS_FROM}
-      WHERE a.session_id = ?
-      ORDER BY a.active_position
-    `);
         const events = new Map();
         const changed = new Set();
+        const unavailable = new Set();
         for (const window of windows) {
             const metadata = {
                 sessionId: window.sessionId,
@@ -137,7 +133,7 @@ function readSnapshot(params) {
             const previous = params.previousManifest.sessions[window.sessionId];
             const documentPath = sessionDocumentPath(metadata);
             const sourceFingerprint = JSON.stringify(window);
-            const unchanged = !params.force &&
+            const unchanged = !window.cold && !params.force &&
                 (previous ? previous.sourceFingerprint === sourceFingerprint &&
                     previous.projectorVersion === PROJECTOR_VERSION &&
                     previous.documentPath === documentPath &&
@@ -145,12 +141,22 @@ function readSnapshot(params) {
                     params.previousManifest.ignoredSessions?.[window.sessionId] === sourceFingerprint);
             if (!unchanged) {
                 changed.add(window.sessionId);
-                if (!params.metadataOnly)
-                    events.set(window.sessionId, readEvents.all(window.sessionId));
+                if (!params.metadataOnly) {
+                    try {
+                        const snapshot = transcripts.read(window.sessionId);
+                        if (snapshot.kind === "ready")
+                            events.set(window.sessionId, snapshot.rows.map(row => ({ ...row, sessionId: window.sessionId })));
+                        else
+                            unavailable.add(window.sessionId);
+                    }
+                    catch {
+                        unavailable.add(window.sessionId);
+                    }
+                }
             }
         }
         db.exec("COMMIT");
-        return { windows, events, changed };
+        return { windows, events, changed, unavailable };
     }
     catch (error) {
         try {
@@ -262,6 +268,12 @@ export async function syncSessionProjections(params) {
             startedAt: window.startedAt,
         };
         const documentPath = sessionDocumentPath(metadata);
+        if (snapshot.unavailable.has(window.sessionId)) {
+            counts.failed += 1;
+            if (previous)
+                sessions[window.sessionId] = previous;
+            continue;
+        }
         if (events === undefined) {
             if (previous)
                 sessions[window.sessionId] = previous;

package/dist/src/training-input.d.ts

@@ -48,6 +48,10 @@ export declare class TrainingTranscriptReader {
         }[];
     } | {
         oversized: true;
+        unavailable?: undefined;
+    } | {
+        unavailable: true;
+        oversized?: undefined;
     } | null;
     close(): void;
 }

package/dist/src/training-input.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { DatabaseSync } from "node:sqlite";
-import { ACTIVE_EVENT_COUNT_SQL, ACTIVE_EVENT_ROWS_SQL, assertAgentTranscriptSchema } from "./agent-transcript.js";
+import { AgentTranscriptReader } from "./agent-transcript.js";
 import { messageText } from "./whisperer-context.js";
 import { conversationUserText } from "./response-text.js";
 import { prepareQueryConversation, QUERY_CONTRACT, QueryInputBudgetError } from "./query-contract.js";
@@ -133,12 +133,13 @@ export function trainingExamples(rows, renew) {
 /** Only active events; no Markdown projections, archived branches, or tool bodies. */
 export class TrainingTranscriptReader {
     #db;
+    #transcripts;
     #lineage;
     constructor(path, agentId) {
         this.#db = new DatabaseSync(path, { readOnly: true });
         try {
             this.#db.exec("PRAGMA query_only=ON; PRAGMA busy_timeout=1000");
-            assertAgentTranscriptSchema(this.#db, agentId, "Unsupported training transcript schema or agent");
+            this.#transcripts = new AgentTranscriptReader(this.#db, agentId, "Unsupported training transcript schema or agent");
             const columns = this.#db.prepare("PRAGMA table_info(session_windows)").all().map(c => c.name);
             this.#lineage = ["parent_session_key", "spawned_by", "plugin_owner_id", "hook_external_content_source"].every(c => columns.includes(c));
         }
@@ -161,11 +162,12 @@ export class TrainingTranscriptReader {
                 /:(?:cron|subagent|heartbeat|hook)(?::|$)/i.test(String(session.session_key)) ||
                 session.parent_session_key || session.spawned_by || session.plugin_owner_id || session.hook_external_content_source)
                 return null;
-            const size = this.#db.prepare(ACTIVE_EVENT_COUNT_SQL).get(sessionId);
-            if (Number(size.n) > 50_000 || Number(size.bytes) > 32_000_000)
+            const snapshot = this.#transcripts.read(sessionId, { maxEvents: 50_000, maxBytes: 32_000_000 });
+            if (snapshot.kind === "oversized")
                 return { oversized: true };
-            const rows = this.#db.prepare(ACTIVE_EVENT_ROWS_SQL).iterate(sessionId);
-            return trainingExamples(rows, renew);
+            if (snapshot.kind !== "ready")
+                return { unavailable: true };
+            return trainingExamples(snapshot.rows, renew);
         }
         finally {
             this.#db.exec("COMMIT");

package/dist/src/training-queries.d.ts

@@ -34,6 +34,7 @@ export declare function generateTrainingQueries(source: Source, store: TrainingS
         sessions: number;
         excludedSessions: number;
         oversizedSessions: number;
+        unavailableSessions: number;
         eligible: number;
         users: number;
         filtered: number;
@@ -79,6 +80,7 @@ export declare function evaluateTrainingQueries(source: Source, store: TrainingS
         sessions: number;
         excludedSessions: number;
         oversizedSessions: number;
+        unavailableSessions: number;
         eligible: number;
         users: number;
         filtered: number;

package/dist/src/training.d.ts

@@ -13,6 +13,7 @@ export declare function collectTraining(source: Source, store?: TrainingStore, o
     sessions: number;
     excludedSessions: number;
     oversizedSessions: number;
+    unavailableSessions: number;
     eligible: number;
     users: number;
     filtered: number;
@@ -39,6 +40,7 @@ export declare function runTraining(source: Source, store: TrainingStore, config
         sessions: number;
         excludedSessions: number;
         oversizedSessions: number;
+        unavailableSessions: number;
         eligible: number;
         users: number;
         filtered: number;

package/dist/src/training.js

@@ -5,7 +5,7 @@ import { judgeTrainingInput, TRAINING_GATE_QUESTIONS } from "./training-gate.js"
 export function collectTraining(source, store, options = {}) {
     const since = options.since ?? 0, until = options.until ?? Number.MAX_SAFE_INTEGER;
     const reader = new TrainingTranscriptReader(source.databasePath, source.agentId);
-    const result = { sessions: 0, excludedSessions: 0, oversizedSessions: 0, eligible: 0,
+    const result = { sessions: 0, excludedSessions: 0, oversizedSessions: 0, unavailableSessions: 0, eligible: 0,
         users: 0, filtered: 0, oversized: 0, unanswered: 0, added: 0, changed: 0, unchanged: 0, retired: 0,
         review: [] };
     try {
@@ -14,6 +14,11 @@ export function collectTraining(source, store, options = {}) {
             store?.renew();
             const extracted = reader.read(id, () => store?.renew());
             result.sessions++;
+            if (extracted && "unavailable" in extracted) {
+                result.unavailableSessions++;
+                store?.unavailable(id);
+                continue;
+            }
             if (extracted && "oversized" in extracted) {
                 result.oversizedSessions++;
                 store?.unavailable(id);

package/docs/memory-training.md

@@ -78,7 +78,9 @@ bytes, so changed corpus content still invalidates caches.
 
 ## Input and historical boundaries
 
-Read original agent SQLite active-branch conversations (schema 17–19), including
+Read original agent SQLite active-branch conversations through the shared read-only
+adapter, including compressed payloads, while deferring cold or oversized sessions
+without retiring their previously collected examples. This includes
 direct/group/channel chats, excluding cron, heartbeat, spawned/subagent, hook/plugin
 and untyped diagnostic sessions. Exclude explicit bots, synthetic messages,
 analysis/thinking, errors and tool payloads. Ordinary older users need not have

package/docs/response-audit.md

@@ -202,8 +202,8 @@ factual verification. Week buckets
 may be partial, and several exchanges in one session are not independent. Wilson
 intervals are descriptive, not calibrated confidence about overall agent ability.
 
-Each run selects at most 100 recent sessions for inference, each at most 2,000 active events/2M
-characters; episodes must fit 24K characters and six feedback messages without
+Each run selects at most 100 recent sessions containing approved-sender messages for inference,
+each at most 2,000 active events/2M decoded UTF-8 bytes; episodes must fit 24K characters and six feedback messages without
 truncating the answer. Coverage counts describe the scanned sessions; only episodes
 within `lookbackDays` are judged. Caps, failures and no-feedback cases remain visible.
 Saved sessions in the report window are also reconciled independently of that

package/docs/retrieval.md

@@ -155,13 +155,19 @@ fits. The default is `500`; the original semantic chunk is preserved when
 neither complete context fits, so expansion never clips the matched evidence.
 Run
 `memory_sync_sessions` to start a refresh, then use `memory_sync_status` to
-check its progress or result. The read-only adapter explicitly supports OpenClaw
-agent database schemas 17, 18, and 19 and validates its required columns before
-reading. Projections are private derived Markdown under the
+check its progress or result. The shared read-only transcript adapter validates
+agent identity and the storage capabilities it needs, rather than rejecting every
+new schema number. It reads both text and bounded Zstd payloads (schema 23+),
+counts decoded UTF-8 bytes for budgets, and preserves previous projections when
+history is cold, oversized, or unreadable. Cold history is deferred until restored
+by OpenClaw; the plugin never restores or migrates the source database. The public
+full-transcript SDK reader currently permits restoration, while its read-only
+catalog redacts and truncates text, so neither supplies this full-fidelity read-only
+contract. Extraction retains its supported host cursor API. Projections are private derived Markdown under the
 agent's `unblock-memory/sessions` state directory and can be rebuilt from
 OpenClaw at any time. Their embedded text contains only `# Transcript` and
 role-labeled, timestamped speaker messages; filtering metadata remains in the
-session manifest. Projection v7 also retains message metadata and exact character
+session manifest. Projection v8 retains message metadata and exact character
 boundaries there, without duplicating message bodies. Readers use those boundaries
 only when the projection hash matches the indexed document. Older/mismatched snapshots
 use a conservative heading parser that skips code fences and blockquotes; an unfenced

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "unblock-memory",
   "name": "Unblock Memory",
-  "version": "0.7.3",
+  "version": "0.7.4",
   "description": "Indexes, retrieves, and analyzes configured workspace memory with existing QMD vectors.",
   "kind": "memory",
   "activation": { "onStartup": true },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unblocklabs/unblock-memory",
-  "version": "0.7.3",
+  "version": "0.7.4",
   "description": "Workspace-native memory for OpenClaw, powered by QMD",
   "type": "module",
   "license": "MIT",