opencode-lcm 0.11.0 → 0.12.0

package/README.md

@@ -1,9 +1,10 @@
-# opencode-lcm
+# Opencode-lcm (Lossless Context Memory)
 
+[![npm version](https://img.shields.io/npm/v/opencode-lcm)](https://www.npmjs.com/package/opencode-lcm)
 [![CI](https://github.com/Plutarch01/opencode-lcm/actions/workflows/ci.yml/badge.svg)](https://github.com/Plutarch01/opencode-lcm/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A transparent long-memory plugin for [OpenCode](https://github.com/sst/opencode), based on the [Lossless Context Memory (LCM)](https://papers.voltropy.com/LCM) research. It captures older session context outside the active prompt, compresses it into searchable summaries and artifacts, then automatically recalls relevant details back into the prompt when the current turn needs them. The model does not become smarter, but it behaves much better across long, compacted sessions because important prior context stops disappearing.
+A transparent long-memory plugin for [OpenCode](https://github.com/sst/opencode), based on the [Lossless Context Memory (LCM)](https://papers.voltropy.com/LCM) research by Voltropy. It captures older session context outside the active prompt, compresses it into searchable summaries and artifacts, then automatically recalls relevant details back into the prompt when the current turn needs them. The model does not become smarter, but it behaves much better across long, compacted sessions because important prior context stops disappearing.
 
 <!-- Add a demo screenshot or GIF here -->
 <!-- ![opencode-lcm in action](assets/images/lcm-demo.png) -->
@@ -31,12 +32,24 @@ OpenCode will automatically download the latest version from npm on startup. No
 ### From source
 
 ```sh
-git clone https://github.com/plutarch01/opencode-lcm.git
+git clone https://github.com/Plutarch01/opencode-lcm.git
 cd opencode-lcm
 npm install
 npm run build
 ```
 
+Then copy or symlink the built plugin into your plugins directory:
+
+```sh
+# Project-level
+cp dist/index.js .opencode/plugins/opencode-lcm.js
+
+# Or global
+cp dist/index.js ~/.config/opencode/plugins/opencode-lcm.js
+```
+
+Local plugins in `.opencode/plugins/` or `~/.config/opencode/plugins/` are loaded automatically by OpenCode at startup.
+
 ## How It Works
 
 OpenCode handles compaction normally — when the conversation gets too large, it shrinks the prompt. `opencode-lcm` works alongside that by saving older details *outside* the prompt, then searching that archive later to pull back only what matters.

package/dist/store.d.ts

@@ -78,8 +78,14 @@ type SqliteRuntimeOptions = {
     isBunRuntime?: boolean;
     platform?: string | undefined;
 };
+type CaptureHydrationMode = 'full' | 'targeted';
+type CaptureHydrationOptions = {
+    isBunRuntime?: boolean;
+    platform?: string | undefined;
+};
 export declare function resolveSqliteRuntimeCandidates(options?: SqliteRuntimeOptions): SqliteRuntime[];
 export declare function resolveSqliteRuntime(options?: SqliteRuntimeOptions): SqliteRuntime;
+export declare function resolveCaptureHydrationMode(options?: CaptureHydrationOptions): CaptureHydrationMode;
 export declare class SqliteLcmStore {
     private readonly options;
     private static readonly deferredPartUpdateDelayMs;
@@ -141,10 +147,6 @@ export declare class SqliteLcmStore {
     private shouldRecordEvent;
     private shouldSyncDerivedLineageSubtree;
     private shouldCleanupOrphanBlobsForEvent;
-    private captureArtifactHydrationMessageIDs;
-    private archivedMessageIDs;
-    private didArchivedMessagesChange;
-    private isArchivedMessage;
     private shouldSyncDerivedSessionStateForEvent;
     private syncAllDerivedSessionStateSync;
     private syncDerivedSessionStateSync;
@@ -296,6 +298,10 @@ export declare class SqliteLcmStore {
     private readSessionSync;
     private prepareSessionForPersistence;
     private sanitizeParentSessionIDSync;
+    private readSessionForCaptureSync;
+    private readMessageSync;
+    private readMessageCountSync;
+    private isMessageArchivedSync;
     private persistCapturedSession;
     private persistSession;
     private persistStoredSessionSync;

package/dist/store.js

@@ -167,6 +167,14 @@ function getDeferredPartUpdateKey(event) {
 function compareMessages(a, b) {
     return a.info.time.created - b.info.time.created;
 }
+function emptySession(sessionID) {
+    return {
+        sessionID,
+        updatedAt: 0,
+        eventCount: 0,
+        messages: [],
+    };
+}
 function buildSummaryNodeID(sessionID, level, slot) {
     return `sum_${hashContent(`summary:${sessionID}`).slice(0, 12)}_l${level}_p${slot}`;
 }
@@ -347,6 +355,15 @@ export function resolveSqliteRuntimeCandidates(options) {
 export function resolveSqliteRuntime(options) {
     return resolveSqliteRuntimeCandidates(options)[0];
 }
+export function resolveCaptureHydrationMode(options) {
+    const isBunRuntime = options?.isBunRuntime ?? (typeof globalThis === 'object' && 'Bun' in globalThis);
+    const platform = options?.platform ?? process.platform;
+    // The targeted fresh-tail capture path is safe under Node, but the bundled
+    // Bun runtime on Windows has been the only environment where users have
+    // reported native crashes in this hot path. Keep the older full-session
+    // hydration there until Bun/Windows is proven stable again.
+    return isBunRuntime && platform === 'win32' ? 'full' : 'targeted';
+}
 function isSqliteRuntimeImportError(runtime, error) {
     const code = typeof error === 'object' && error && 'code' in error && typeof error.code === 'string'
         ? error.code
@@ -820,15 +837,15 @@ export class SqliteLcmStore {
             return;
         if (!this.shouldPersistSessionForEvent(normalized.type))
             return;
-        const session = this.readSessionSync(normalized.sessionID, {
-            artifactMessageIDs: this.captureArtifactHydrationMessageIDs(normalized),
-        });
+        const session = resolveCaptureHydrationMode() === 'targeted'
+            ? this.readSessionForCaptureSync(normalized)
+            : this.readSessionSync(normalized.sessionID);
         const previousParentSessionID = session.parentSessionID;
+        const shouldSyncDerivedState = this.shouldSyncDerivedSessionStateForEvent(session, normalized);
         let next = this.applyEvent(session, normalized);
         next.updatedAt = Math.max(next.updatedAt, normalized.timestamp);
         next.eventCount += 1;
         next = this.prepareSessionForPersistence(next);
-        const shouldSyncDerivedState = this.shouldSyncDerivedSessionStateForEvent(session, next, normalized);
         await this.persistCapturedSession(next, normalized);
         if (this.shouldRefreshLineageForEvent(normalized.type)) {
             this.refreshAllLineageSync();
@@ -1206,54 +1223,33 @@ export class SqliteLcmStore {
             eventType === 'message.part.updated' ||
             eventType === 'message.part.removed');
     }
-    captureArtifactHydrationMessageIDs(event) {
-        const payload = event.payload;
-        switch (payload.type) {
-            case 'message.updated':
-                return [payload.properties.info.id];
-            case 'message.part.updated':
-                return [payload.properties.part.messageID];
-            case 'message.part.removed':
-                return [payload.properties.messageID];
-            default:
-                return [];
-        }
-    }
-    archivedMessageIDs(messages) {
-        return this.getArchivedMessages(messages).map((message) => message.info.id);
-    }
-    didArchivedMessagesChange(before, after) {
-        const beforeIDs = this.archivedMessageIDs(before);
-        const afterIDs = this.archivedMessageIDs(after);
-        if (beforeIDs.length !== afterIDs.length)
-            return true;
-        return beforeIDs.some((messageID, index) => messageID !== afterIDs[index]);
-    }
-    isArchivedMessage(messages, messageID) {
-        if (!messageID)
-            return false;
-        return this.archivedMessageIDs(messages).includes(messageID);
-    }
-    shouldSyncDerivedSessionStateForEvent(previous, next, event) {
+    shouldSyncDerivedSessionStateForEvent(session, event) {
         const payload = event.payload;
         switch (payload.type) {
             case 'message.updated': {
-                const messageID = payload.properties.info.id;
-                return (this.didArchivedMessagesChange(previous.messages, next.messages) ||
-                    this.isArchivedMessage(previous.messages, messageID) ||
-                    this.isArchivedMessage(next.messages, messageID));
+                const existing = session.messages.find((message) => message.info.id === payload.properties.info.id);
+                if (existing) {
+                    return this.isMessageArchivedSync(session.sessionID, existing.info.id, existing.info.time.created);
+                }
+                return this.readMessageCountSync(session.sessionID) >= this.options.freshTailMessages;
+            }
+            case 'message.removed': {
+                const existing = safeQueryOne(this.getDb().prepare('SELECT created_at FROM messages WHERE session_id = ? AND message_id = ?'), [session.sessionID, payload.properties.messageID], 'shouldSyncDerivedSessionStateForEvent.messageRemoved');
+                if (!existing)
+                    return false;
+                return this.readMessageCountSync(session.sessionID) > this.options.freshTailMessages;
             }
-            case 'message.removed':
-                return this.didArchivedMessagesChange(previous.messages, next.messages);
             case 'message.part.updated': {
-                const messageID = payload.properties.part.messageID;
-                return (this.isArchivedMessage(previous.messages, messageID) ||
-                    this.isArchivedMessage(next.messages, messageID));
+                const message = session.messages.find((entry) => entry.info.id === payload.properties.part.messageID);
+                if (!message)
+                    return false;
+                return this.isMessageArchivedSync(session.sessionID, message.info.id, message.info.time.created);
             }
             case 'message.part.removed': {
-                const messageID = payload.properties.messageID;
-                return (this.isArchivedMessage(previous.messages, messageID) ||
-                    this.isArchivedMessage(next.messages, messageID));
+                const message = session.messages.find((entry) => entry.info.id === payload.properties.messageID);
+                if (!message)
+                    return false;
+                return this.isMessageArchivedSync(session.sessionID, message.info.id, message.info.time.created);
             }
             default:
                 return false;
@@ -3361,7 +3357,7 @@ export class SqliteLcmStore {
             const row = sessionMap.get(sessionID);
             const messages = messagesBySession.get(sessionID) ?? [];
             if (!row) {
-                return { sessionID, updatedAt: 0, eventCount: 0, messages };
+                return { ...emptySession(sessionID), messages };
             }
             return {
                 sessionID: row.session_id,
@@ -3380,7 +3376,7 @@ export class SqliteLcmStore {
             };
         });
     }
-    readSessionSync(sessionID, options) {
+    readSessionSync(sessionID) {
         const db = this.getDb();
         const row = safeQueryOne(db.prepare('SELECT * FROM sessions WHERE session_id = ?'), [sessionID], 'readSessionSync');
         const messageRows = db
@@ -3390,11 +3386,7 @@ export class SqliteLcmStore {
             .prepare('SELECT * FROM parts WHERE session_id = ? ORDER BY message_id ASC, sort_key ASC, part_id ASC')
             .all(sessionID);
         const artifactsByPart = new Map();
-        const artifactMessageIDs = options?.artifactMessageIDs;
-        const artifacts = artifactMessageIDs === undefined
-            ? this.readArtifactsForSessionSync(sessionID)
-            : [...new Set(artifactMessageIDs)].flatMap((messageID) => this.readArtifactsForMessageSync(messageID));
-        for (const artifact of artifacts) {
+        for (const artifact of this.readArtifactsForSessionSync(sessionID)) {
             const list = artifactsByPart.get(artifact.partID) ?? [];
             list.push(artifact);
             artifactsByPart.set(artifact.partID, list);
@@ -3413,12 +3405,7 @@ export class SqliteLcmStore {
             parts: partsByMessage.get(messageRow.message_id) ?? [],
         }));
         if (!row) {
-            return {
-                sessionID,
-                updatedAt: 0,
-                eventCount: 0,
-                messages,
-            };
+            return { ...emptySession(sessionID), messages };
         }
         return {
             sessionID: row.session_id,
@@ -3462,6 +3449,73 @@ export class SqliteLcmStore {
         }
         return parentSessionID;
     }
+    readSessionForCaptureSync(event) {
+        const sessionID = event.sessionID;
+        if (!sessionID)
+            return emptySession('');
+        const session = this.readSessionHeaderSync(sessionID) ?? emptySession(sessionID);
+        const payload = event.payload;
+        switch (payload.type) {
+            case 'message.updated': {
+                const message = this.readMessageSync(sessionID, payload.properties.info.id);
+                if (message)
+                    session.messages = [message];
+                return session;
+            }
+            case 'message.part.updated': {
+                const message = this.readMessageSync(sessionID, payload.properties.part.messageID);
+                if (message)
+                    session.messages = [message];
+                return session;
+            }
+            case 'message.part.removed': {
+                const message = this.readMessageSync(sessionID, payload.properties.messageID);
+                if (message)
+                    session.messages = [message];
+                return session;
+            }
+            default:
+                return session;
+        }
+    }
+    readMessageSync(sessionID, messageID) {
+        const db = this.getDb();
+        const row = safeQueryOne(db.prepare('SELECT * FROM messages WHERE session_id = ? AND message_id = ?'), [sessionID, messageID], 'readMessageSync');
+        if (!row)
+            return undefined;
+        const artifactsByPart = new Map();
+        for (const artifact of this.readArtifactsForMessageSync(messageID)) {
+            const list = artifactsByPart.get(artifact.partID) ?? [];
+            list.push(artifact);
+            artifactsByPart.set(artifact.partID, list);
+        }
+        const parts = db
+            .prepare('SELECT * FROM parts WHERE session_id = ? AND message_id = ? ORDER BY sort_key ASC, part_id ASC')
+            .all(sessionID, messageID);
+        return {
+            info: parseJson(row.info_json),
+            parts: parts.map((partRow) => {
+                const part = parseJson(partRow.part_json);
+                hydratePartFromArtifacts(part, artifactsByPart.get(part.id) ?? []);
+                return part;
+            }),
+        };
+    }
+    readMessageCountSync(sessionID) {
+        const row = this.getDb()
+            .prepare('SELECT COUNT(*) AS count FROM messages WHERE session_id = ?')
+            .get(sessionID);
+        return row.count;
+    }
+    isMessageArchivedSync(sessionID, messageID, createdAt) {
+        const row = this.getDb()
+            .prepare(`SELECT COUNT(*) AS count
+         FROM messages
+         WHERE session_id = ?
+           AND (created_at > ? OR (created_at = ? AND message_id > ?))`)
+            .get(sessionID, createdAt, createdAt, messageID);
+        return row.count >= this.options.freshTailMessages;
+    }
     async persistCapturedSession(session, event) {
         const payload = event.payload;
         switch (payload.type) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-lcm",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Long-memory plugin for OpenCode with context-mode interop",
   "type": "module",
   "main": "./dist/index.js",

package/src/store.ts

@@ -303,10 +303,6 @@ function readSessionStats(db: SqlDatabaseLike): {
   };
 }
 
-type ReadSessionOptions = {
-  artifactMessageIDs?: string[];
-};
-
 function extractSessionID(event: unknown): string | undefined {
   const record = asRecord(event);
   if (!record) return undefined;
@@ -364,6 +360,15 @@ function compareMessages(a: ConversationMessage, b: ConversationMessage): number
   return a.info.time.created - b.info.time.created;
 }
 
+function emptySession(sessionID: string): NormalizedSession {
+  return {
+    sessionID,
+    updatedAt: 0,
+    eventCount: 0,
+    messages: [],
+  };
+}
+
 function buildSummaryNodeID(sessionID: string, level: number, slot: number): string {
   return `sum_${hashContent(`summary:${sessionID}`).slice(0, 12)}_l${level}_p${slot}`;
 }
@@ -529,6 +534,11 @@ type SqliteRuntimeOptions = {
   isBunRuntime?: boolean;
   platform?: string | undefined;
 };
+type CaptureHydrationMode = 'full' | 'targeted';
+type CaptureHydrationOptions = {
+  isBunRuntime?: boolean;
+  platform?: string | undefined;
+};
 
 function normalizeSqliteRuntimeOverride(value: string | undefined): SqliteRuntime | 'auto' {
   const normalized = value?.trim().toLowerCase();
@@ -554,6 +564,20 @@ export function resolveSqliteRuntime(options?: SqliteRuntimeOptions): SqliteRunt
   return resolveSqliteRuntimeCandidates(options)[0];
 }
 
+export function resolveCaptureHydrationMode(
+  options?: CaptureHydrationOptions,
+): CaptureHydrationMode {
+  const isBunRuntime =
+    options?.isBunRuntime ?? (typeof globalThis === 'object' && 'Bun' in globalThis);
+  const platform = options?.platform ?? process.platform;
+
+  // The targeted fresh-tail capture path is safe under Node, but the bundled
+  // Bun runtime on Windows has been the only environment where users have
+  // reported native crashes in this hot path. Keep the older full-session
+  // hydration there until Bun/Windows is proven stable again.
+  return isBunRuntime && platform === 'win32' ? 'full' : 'targeted';
+}
+
 function isSqliteRuntimeImportError(runtime: SqliteRuntime, error: unknown): boolean {
   const code =
     typeof error === 'object' && error && 'code' in error && typeof error.code === 'string'
@@ -1096,19 +1120,16 @@ export class SqliteLcmStore {
     if (!normalized.sessionID) return;
     if (!this.shouldPersistSessionForEvent(normalized.type)) return;
 
-    const session = this.readSessionSync(normalized.sessionID, {
-      artifactMessageIDs: this.captureArtifactHydrationMessageIDs(normalized),
-    });
+    const session =
+      resolveCaptureHydrationMode() === 'targeted'
+        ? this.readSessionForCaptureSync(normalized)
+        : this.readSessionSync(normalized.sessionID);
     const previousParentSessionID = session.parentSessionID;
+    const shouldSyncDerivedState = this.shouldSyncDerivedSessionStateForEvent(session, normalized);
     let next = this.applyEvent(session, normalized);
     next.updatedAt = Math.max(next.updatedAt, normalized.timestamp);
     next.eventCount += 1;
     next = this.prepareSessionForPersistence(next);
-    const shouldSyncDerivedState = this.shouldSyncDerivedSessionStateForEvent(
-      session,
-      next,
-      normalized,
-    );
 
     await this.persistCapturedSession(next, normalized);
 
@@ -1645,70 +1666,58 @@ export class SqliteLcmStore {
     );
   }
 
-  private captureArtifactHydrationMessageIDs(event: CapturedEvent): string[] {
-    const payload = event.payload as Event;
-
-    switch (payload.type) {
-      case 'message.updated':
-        return [payload.properties.info.id];
-      case 'message.part.updated':
-        return [payload.properties.part.messageID];
-      case 'message.part.removed':
-        return [payload.properties.messageID];
-      default:
-        return [];
-    }
-  }
-
-  private archivedMessageIDs(messages: ConversationMessage[]): string[] {
-    return this.getArchivedMessages(messages).map((message) => message.info.id);
-  }
-
-  private didArchivedMessagesChange(
-    before: ConversationMessage[],
-    after: ConversationMessage[],
-  ): boolean {
-    const beforeIDs = this.archivedMessageIDs(before);
-    const afterIDs = this.archivedMessageIDs(after);
-    if (beforeIDs.length !== afterIDs.length) return true;
-    return beforeIDs.some((messageID, index) => messageID !== afterIDs[index]);
-  }
-
-  private isArchivedMessage(messages: ConversationMessage[], messageID?: string): boolean {
-    if (!messageID) return false;
-    return this.archivedMessageIDs(messages).includes(messageID);
-  }
-
   private shouldSyncDerivedSessionStateForEvent(
-    previous: NormalizedSession,
-    next: NormalizedSession,
+    session: NormalizedSession,
     event: CapturedEvent,
   ): boolean {
     const payload = event.payload as Event;
 
     switch (payload.type) {
       case 'message.updated': {
-        const messageID = payload.properties.info.id;
-        return (
-          this.didArchivedMessagesChange(previous.messages, next.messages) ||
-          this.isArchivedMessage(previous.messages, messageID) ||
-          this.isArchivedMessage(next.messages, messageID)
+        const existing = session.messages.find(
+          (message) => message.info.id === payload.properties.info.id,
         );
+        if (existing) {
+          return this.isMessageArchivedSync(
+            session.sessionID,
+            existing.info.id,
+            existing.info.time.created,
+          );
+        }
+
+        return this.readMessageCountSync(session.sessionID) >= this.options.freshTailMessages;
+      }
+      case 'message.removed': {
+        const existing = safeQueryOne<{ created_at: number }>(
+          this.getDb().prepare(
+            'SELECT created_at FROM messages WHERE session_id = ? AND message_id = ?',
+          ),
+          [session.sessionID, payload.properties.messageID],
+          'shouldSyncDerivedSessionStateForEvent.messageRemoved',
+        );
+        if (!existing) return false;
+        return this.readMessageCountSync(session.sessionID) > this.options.freshTailMessages;
       }
-      case 'message.removed':
-        return this.didArchivedMessagesChange(previous.messages, next.messages);
       case 'message.part.updated': {
-        const messageID = payload.properties.part.messageID;
-        return (
-          this.isArchivedMessage(previous.messages, messageID) ||
-          this.isArchivedMessage(next.messages, messageID)
+        const message = session.messages.find(
+          (entry) => entry.info.id === payload.properties.part.messageID,
+        );
+        if (!message) return false;
+        return this.isMessageArchivedSync(
+          session.sessionID,
+          message.info.id,
+          message.info.time.created,
         );
       }
       case 'message.part.removed': {
-        const messageID = payload.properties.messageID;
-        return (
-          this.isArchivedMessage(previous.messages, messageID) ||
-          this.isArchivedMessage(next.messages, messageID)
+        const message = session.messages.find(
+          (entry) => entry.info.id === payload.properties.messageID,
+        );
+        if (!message) return false;
+        return this.isMessageArchivedSync(
+          session.sessionID,
+          message.info.id,
+          message.info.time.created,
         );
       }
       default:
@@ -4496,7 +4505,7 @@ export class SqliteLcmStore {
       const row = sessionMap.get(sessionID);
       const messages = messagesBySession.get(sessionID) ?? [];
       if (!row) {
-        return { sessionID, updatedAt: 0, eventCount: 0, messages };
+        return { ...emptySession(sessionID), messages };
       }
       return {
         sessionID: row.session_id,
@@ -4516,7 +4525,7 @@ export class SqliteLcmStore {
     });
   }
 
-  private readSessionSync(sessionID: string, options?: ReadSessionOptions): NormalizedSession {
+  private readSessionSync(sessionID: string): NormalizedSession {
     const db = this.getDb();
     const row = safeQueryOne<SessionRow>(
       db.prepare('SELECT * FROM sessions WHERE session_id = ?'),
@@ -4534,14 +4543,7 @@ export class SqliteLcmStore {
       )
       .all(sessionID) as PartRow[];
     const artifactsByPart = new Map<string, ArtifactData[]>();
-    const artifactMessageIDs = options?.artifactMessageIDs;
-    const artifacts =
-      artifactMessageIDs === undefined
-        ? this.readArtifactsForSessionSync(sessionID)
-        : [...new Set(artifactMessageIDs)].flatMap((messageID) =>
-            this.readArtifactsForMessageSync(messageID),
-          );
-    for (const artifact of artifacts) {
+    for (const artifact of this.readArtifactsForSessionSync(sessionID)) {
       const list = artifactsByPart.get(artifact.partID) ?? [];
       list.push(artifact);
       artifactsByPart.set(artifact.partID, list);
@@ -4563,12 +4565,7 @@ export class SqliteLcmStore {
     }));
 
     if (!row) {
-      return {
-        sessionID,
-        updatedAt: 0,
-        eventCount: 0,
-        messages,
-      };
+      return { ...emptySession(sessionID), messages };
     }
 
     return {
@@ -4622,6 +4619,85 @@ export class SqliteLcmStore {
     return parentSessionID;
   }
 
+  private readSessionForCaptureSync(event: CapturedEvent): NormalizedSession {
+    const sessionID = event.sessionID;
+    if (!sessionID) return emptySession('');
+
+    const session = this.readSessionHeaderSync(sessionID) ?? emptySession(sessionID);
+    const payload = event.payload as Event;
+
+    switch (payload.type) {
+      case 'message.updated': {
+        const message = this.readMessageSync(sessionID, payload.properties.info.id);
+        if (message) session.messages = [message];
+        return session;
+      }
+      case 'message.part.updated': {
+        const message = this.readMessageSync(sessionID, payload.properties.part.messageID);
+        if (message) session.messages = [message];
+        return session;
+      }
+      case 'message.part.removed': {
+        const message = this.readMessageSync(sessionID, payload.properties.messageID);
+        if (message) session.messages = [message];
+        return session;
+      }
+      default:
+        return session;
+    }
+  }
+
+  private readMessageSync(sessionID: string, messageID: string): ConversationMessage | undefined {
+    const db = this.getDb();
+    const row = safeQueryOne<MessageRow>(
+      db.prepare('SELECT * FROM messages WHERE session_id = ? AND message_id = ?'),
+      [sessionID, messageID],
+      'readMessageSync',
+    );
+    if (!row) return undefined;
+
+    const artifactsByPart = new Map<string, ArtifactData[]>();
+    for (const artifact of this.readArtifactsForMessageSync(messageID)) {
+      const list = artifactsByPart.get(artifact.partID) ?? [];
+      list.push(artifact);
+      artifactsByPart.set(artifact.partID, list);
+    }
+
+    const parts = db
+      .prepare(
+        'SELECT * FROM parts WHERE session_id = ? AND message_id = ? ORDER BY sort_key ASC, part_id ASC',
+      )
+      .all(sessionID, messageID) as PartRow[];
+
+    return {
+      info: parseJson<Message>(row.info_json),
+      parts: parts.map((partRow) => {
+        const part = parseJson<Part>(partRow.part_json);
+        hydratePartFromArtifacts(part, artifactsByPart.get(part.id) ?? []);
+        return part;
+      }),
+    };
+  }
+
+  private readMessageCountSync(sessionID: string): number {
+    const row = this.getDb()
+      .prepare('SELECT COUNT(*) AS count FROM messages WHERE session_id = ?')
+      .get(sessionID) as { count: number };
+    return row.count;
+  }
+
+  private isMessageArchivedSync(sessionID: string, messageID: string, createdAt: number): boolean {
+    const row = this.getDb()
+      .prepare(
+        `SELECT COUNT(*) AS count
+         FROM messages
+         WHERE session_id = ?
+           AND (created_at > ? OR (created_at = ? AND message_id > ?))`,
+      )
+      .get(sessionID, createdAt, createdAt, messageID) as { count: number };
+    return row.count >= this.options.freshTailMessages;
+  }
+
   private async persistCapturedSession(
     session: NormalizedSession,
     event: CapturedEvent,