opencode-lcm 0.11.0

package/src/archive-transform.ts

@@ -0,0 +1,147 @@
+import type { ConversationMessage, SearchResult } from './types.js';
+import { shortNodeID, truncate } from './utils.js';
+
+export type AutomaticRetrievalHit = {
+  kind: 'message' | 'summary' | 'artifact';
+  id: string;
+  label: string;
+  sessionID?: string;
+  snippet: string;
+};
+
+export type ArchiveSummaryRoot = {
+  nodeID: string;
+  summaryText: string;
+};
+
+export type ArchiveTransformWindow = {
+  anchor: ConversationMessage;
+  archived: ConversationMessage[];
+  recent: ConversationMessage[];
+  recentStart: number;
+};
+
+export type AutomaticRetrievalTelemetry = {
+  queries: string[];
+  rawResults: number;
+  stopReason: string;
+  scopeStats: Array<{
+    scope: string;
+    budget: number;
+    rawResults: number;
+    selectedHits: number;
+  }>;
+};
+
+type AutomaticRetrievalQuotas = {
+  message: number;
+  summary: number;
+  artifact: number;
+};
+
+function pluralize(count: number, singular: string, plural = `${singular}s`): string {
+  return count === 1 ? singular : plural;
+}
+
+function formatAutomaticRetrievalHit(hit: AutomaticRetrievalHit): string {
+  const session = hit.sessionID ? ` session=${hit.sessionID}` : '';
+  const id = hit.kind === 'summary' ? shortNodeID(hit.id) : hit.id;
+  const label = hit.label !== hit.kind ? ` (${hit.label})` : '';
+  return `${hit.kind}${session} id=${id}${label}: ${truncate(hit.snippet, 180)}`;
+}
+
+export function resolveArchiveTransformWindow(
+  messages: ConversationMessage[],
+  freshTailMessages: number,
+): ArchiveTransformWindow | undefined {
+  let latestUserIndex = -1;
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    if (messages[index]?.info.role === 'user') {
+      latestUserIndex = index;
+      break;
+    }
+  }
+  if (latestUserIndex < 0) return undefined;
+
+  let recentStart = Math.max(0, messages.length - Math.max(0, freshTailMessages));
+  if (latestUserIndex < recentStart) {
+    recentStart = latestUserIndex;
+  }
+  if (recentStart <= 0) return undefined;
+
+  return {
+    anchor: messages[latestUserIndex],
+    archived: messages.slice(0, recentStart),
+    recent: messages.slice(recentStart),
+    recentStart,
+  };
+}
+
+export function selectAutomaticRetrievalHits(input: {
+  recent: ConversationMessage[];
+  tokens: string[];
+  results: SearchResult[];
+  quotas: AutomaticRetrievalQuotas;
+  isFreshResult: (result: SearchResult, freshMessageIDs: Set<string>) => boolean;
+}): AutomaticRetrievalHit[] {
+  const freshMessageIDs = new Set(input.recent.map((message) => message.info.id));
+  const quotas = { ...input.quotas };
+  // With few tokens each one is critical — require at least 2 token matches when possible
+  const minSnippetMatches = input.tokens.length >= 2 ? 2 : 1;
+  const hits: AutomaticRetrievalHit[] = [];
+
+  for (const result of input.results) {
+    const kind =
+      result.type === 'summary'
+        ? 'summary'
+        : result.type.startsWith('artifact:')
+          ? 'artifact'
+          : 'message';
+    if (quotas[kind] <= 0) continue;
+    if (input.isFreshResult(result, freshMessageIDs)) continue;
+
+    const lowerSnippet = result.snippet.toLowerCase();
+    const matchedTokens = input.tokens.filter((token) => lowerSnippet.includes(token)).length;
+    if (matchedTokens < minSnippetMatches && input.tokens.length > 1) continue;
+
+    hits.push({
+      kind,
+      id: result.id,
+      label: result.type,
+      sessionID: result.sessionID,
+      snippet: result.snippet,
+    });
+    quotas[kind] -= 1;
+    if (quotas.message <= 0 && quotas.summary <= 0 && quotas.artifact <= 0) break;
+  }
+
+  return hits;
+}
+
+export function renderAutomaticRetrievalContext(
+  scopes: string | string[],
+  hits: AutomaticRetrievalHit[],
+  maxChars: number,
+  _telemetry?: AutomaticRetrievalTelemetry,
+): string {
+  const scopeLabel = Array.isArray(scopes) ? scopes.join(' -> ') : scopes;
+  const lines = [
+    `[Archived by opencode-lcm: recalled ${hits.length} archived ${pluralize(hits.length, 'hit')} for this turn (scope=${scopeLabel}).]`,
+    `Archived hits: ${hits.map((hit) => formatAutomaticRetrievalHit(hit)).join(' | ')}`,
+  ];
+
+  return truncate(lines.join('\n'), maxChars);
+}
+
+export function buildActiveSummaryText(
+  roots: ArchiveSummaryRoot[],
+  archivedCount: number,
+  maxChars: number,
+): string {
+  const lines = [
+    `[Archived by opencode-lcm: compacted ${archivedCount} older conversation ${pluralize(archivedCount, 'turn')} into ${roots.length} archived summary ${pluralize(roots.length, 'node')}.]`,
+    `Summary roots: ${roots.map((node) => `${node.nodeID}: ${truncate(node.summaryText, 140)}`).join(' | ')}`,
+  ];
+
+  return truncate(lines.join('\n'), maxChars);
+}

package/src/bun-sqlite.d.ts

@@ -0,0 +1,18 @@
+declare module 'bun:sqlite' {
+  export class Database {
+    constructor(path: string, opts?: { create: boolean });
+    exec(sql: string): void;
+    close(): void;
+    prepare(sql: string): {
+      run(...args: unknown[]): void;
+      get(...args: unknown[]): Record<string, unknown>;
+      all(...args: unknown[]): Record<string, unknown>[];
+      values(...args: unknown[]): unknown[][];
+    };
+    query(sql: string): {
+      run(...args: unknown[]): void;
+      get(...args: unknown[]): Record<string, unknown>;
+      all(...args: unknown[]): Record<string, unknown>[];
+    };
+  }
+}

package/src/constants.ts

@@ -0,0 +1,20 @@
+/**
+ * Store-level constants used across the SQLite LCM store.
+ * These are configuration-like values that control store behavior.
+ */
+
+// Summary DAG configuration
+export const SUMMARY_LEAF_MESSAGES = 6;
+export const SUMMARY_BRANCH_FACTOR = 3;
+export const SUMMARY_NODE_CHAR_LIMIT = 260;
+
+// Store schema
+export const STORE_SCHEMA_VERSION = 1;
+
+// Message retrieval limits
+export const EXPAND_MESSAGE_LIMIT = 6;
+
+// Automatic retrieval configuration
+export const AUTOMATIC_RETRIEVAL_QUERY_TOKENS = 8;
+export const AUTOMATIC_RETRIEVAL_RECENT_MESSAGES = 3;
+export const AUTOMATIC_RETRIEVAL_QUERY_VARIANTS = 8;

package/src/doctor.ts

@@ -0,0 +1,83 @@
+export type DoctorSessionIssue = {
+  sessionID: string;
+  issues: string[];
+};
+
+export type DoctorCountCheck = {
+  expected: number;
+  actual: number;
+};
+
+export type DoctorReport = {
+  scope: string;
+  checkedSessions: number;
+  summarySessionsNeedingRebuild: DoctorSessionIssue[];
+  lineageSessionsNeedingRefresh: string[];
+  orphanSummaryEdges: number;
+  messageFts: DoctorCountCheck;
+  summaryFts: DoctorCountCheck;
+  artifactFts: DoctorCountCheck;
+  orphanArtifactBlobs: number;
+  status: 'clean' | 'issues-found' | 'repaired';
+  appliedActions?: string[];
+};
+
+function formatCountCheck(label: string, value: DoctorCountCheck): string[] {
+  return [
+    `${label}_expected=${value.expected}`,
+    `${label}_actual=${value.actual}`,
+    `${label}_delta=${value.expected - value.actual}`,
+  ];
+}
+
+export function formatDoctorReport(report: DoctorReport, limit: number): string {
+  const issueCount =
+    report.summarySessionsNeedingRebuild.length +
+    report.lineageSessionsNeedingRefresh.length +
+    report.orphanSummaryEdges +
+    Math.abs(report.messageFts.expected - report.messageFts.actual) +
+    Math.abs(report.summaryFts.expected - report.summaryFts.actual) +
+    Math.abs(report.artifactFts.expected - report.artifactFts.actual) +
+    report.orphanArtifactBlobs;
+
+  const lines = [
+    `checked_scope=${report.scope}`,
+    `checked_sessions=${report.checkedSessions}`,
+    `summary_sessions_needing_rebuild=${report.summarySessionsNeedingRebuild.length}`,
+    `lineage_sessions_needing_refresh=${report.lineageSessionsNeedingRefresh.length}`,
+    `orphan_summary_edges=${report.orphanSummaryEdges}`,
+    ...formatCountCheck('message_fts', report.messageFts),
+    ...formatCountCheck('summary_fts', report.summaryFts),
+    ...formatCountCheck('artifact_fts', report.artifactFts),
+    `orphan_artifact_blobs=${report.orphanArtifactBlobs}`,
+    `issues=${issueCount}`,
+    `status=${report.status}`,
+  ];
+
+  if (report.summarySessionsNeedingRebuild.length > 0) {
+    lines.push(
+      'summary_session_preview:',
+      ...report.summarySessionsNeedingRebuild
+        .slice(0, limit)
+        .map((issue) => `- ${issue.sessionID}: ${issue.issues.join(', ')}`),
+    );
+  }
+
+  if (report.lineageSessionsNeedingRefresh.length > 0) {
+    lines.push(
+      'lineage_session_preview:',
+      ...report.lineageSessionsNeedingRefresh.slice(0, limit).map((sessionID) => `- ${sessionID}`),
+    );
+  }
+
+  if (report.appliedActions && report.appliedActions.length > 0) {
+    lines.push(
+      'applied_actions:',
+      ...report.appliedActions.slice(0, limit).map((action) => `- ${action}`),
+    );
+  } else if (report.status === 'issues-found') {
+    lines.push('Re-run with apply=true to repair the issues above.');
+  }
+
+  return lines.join('\n');
+}

package/src/index.ts

@@ -0,0 +1,330 @@
+import { type Hooks, type PluginInput, tool } from '@opencode-ai/plugin';
+
+import { resolveOptions } from './options.js';
+import { SqliteLcmStore } from './store.js';
+
+type PluginWithOptions = (ctx: PluginInput, rawOptions?: unknown) => Promise<Hooks>;
+
+export const OpencodeLcmPlugin: PluginWithOptions = async (ctx, rawOptions) => {
+  const options = resolveOptions(rawOptions);
+  const store = new SqliteLcmStore(ctx.directory, options);
+
+  await store.init();
+
+  return {
+    event: async ({ event }) => {
+      await store.captureDeferred(event);
+    },
+
+    tool: {
+      lcm_status: tool({
+        description: 'Show archived LCM capture stats',
+        args: {},
+        async execute() {
+          const stats = await store.stats();
+          const lines = [
+            `schema_version=${stats.schemaVersion}`,
+            `total_events=${stats.totalEvents}`,
+            `session_count=${stats.sessionCount}`,
+            `root_sessions=${stats.rootSessionCount}`,
+            `branched_sessions=${stats.branchedSessionCount}`,
+            `pinned_sessions=${stats.pinnedSessionCount}`,
+            `worktrees=${stats.worktreeCount}`,
+            `latest_event_at=${stats.latestEventAt ?? 'n/a'}`,
+            `summary_nodes=${stats.summaryNodeCount}`,
+            `summary_states=${stats.summaryStateCount}`,
+            `artifacts=${stats.artifactCount}`,
+            `artifact_blobs=${stats.artifactBlobCount}`,
+            `shared_artifact_blobs=${stats.sharedArtifactBlobCount}`,
+            `orphan_artifact_blobs=${stats.orphanArtifactBlobCount}`,
+            `default_grep_scope=${options.scopeDefaults.grep}`,
+            `default_describe_scope=${options.scopeDefaults.describe}`,
+            `scope_profiles=${options.scopeProfiles.length}`,
+            `retention_stale_session_days=${options.retention.staleSessionDays ?? 'disabled'}`,
+            `retention_deleted_session_days=${options.retention.deletedSessionDays ?? 'disabled'}`,
+            `retention_orphan_blob_days=${options.retention.orphanBlobDays ?? 'disabled'}`,
+            `automatic_retrieval_enabled=${options.automaticRetrieval.enabled}`,
+            `automatic_retrieval_max_chars=${options.automaticRetrieval.maxChars}`,
+            `automatic_retrieval_min_tokens=${options.automaticRetrieval.minTokens}`,
+            `automatic_retrieval_message_hits=${options.automaticRetrieval.maxMessageHits}`,
+            `automatic_retrieval_summary_hits=${options.automaticRetrieval.maxSummaryHits}`,
+            `automatic_retrieval_artifact_hits=${options.automaticRetrieval.maxArtifactHits}`,
+            `automatic_retrieval_scope_order=${options.automaticRetrieval.scopeOrder.join(',')}`,
+            `automatic_retrieval_scope_budgets=session:${options.automaticRetrieval.scopeBudgets.session},root:${options.automaticRetrieval.scopeBudgets.root},worktree:${options.automaticRetrieval.scopeBudgets.worktree},all:${options.automaticRetrieval.scopeBudgets.all}`,
+            `automatic_retrieval_stop_target_hits=${options.automaticRetrieval.stop.targetHits}`,
+            `automatic_retrieval_stop_on_first_scope_with_hits=${options.automaticRetrieval.stop.stopOnFirstScopeWithHits}`,
+            `fresh_tail_messages=${options.freshTailMessages}`,
+            `min_messages_for_transform=${options.minMessagesForTransform}`,
+            `large_content_threshold=${options.largeContentThreshold}`,
+            `binary_preview_providers=${options.binaryPreviewProviders.join(',')}`,
+            `preview_byte_peek=${options.previewBytePeek}`,
+            `privacy_exclude_tool_prefixes=${options.privacy.excludeToolPrefixes.join(',')}`,
+            `privacy_exclude_path_patterns=${options.privacy.excludePathPatterns.length}`,
+            `privacy_redact_patterns=${options.privacy.redactPatterns.length}`,
+            ...Object.entries(stats.eventTypes)
+              .sort((a, b) => b[1] - a[1])
+              .slice(0, 10)
+              .map(([type, count]) => `${type}=${count}`),
+          ];
+          return lines.join('\n');
+        },
+      }),
+
+      lcm_resume: tool({
+        description: 'Show the latest archived resume note',
+        args: {
+          sessionID: tool.schema.string().optional(),
+        },
+        async execute(args) {
+          return await store.resume(args.sessionID);
+        },
+      }),
+
+      lcm_grep: tool({
+        description: 'Search archived LCM capture with scope',
+        args: {
+          query: tool.schema.string().min(1),
+          sessionID: tool.schema.string().optional(),
+          scope: tool.schema.string().optional(),
+          limit: tool.schema.number().int().min(1).max(20).optional(),
+        },
+        async execute(args) {
+          const results = await store.grep({
+            query: args.query,
+            sessionID: args.sessionID,
+            scope: args.scope,
+            limit: args.limit ?? 5,
+          });
+          if (results.length === 0) return 'No archived matches found.';
+
+          return results
+            .map((result) => {
+              const suffix = result.sessionID ? ` session=${result.sessionID}` : '';
+              return `[${result.type}]${suffix} ${result.snippet}`;
+            })
+            .join('\n\n');
+        },
+      }),
+
+      lcm_describe: tool({
+        description: 'Summarize archived session capture with scope',
+        args: {
+          sessionID: tool.schema.string().optional(),
+          scope: tool.schema.string().optional(),
+        },
+        async execute(args) {
+          return await store.describe({
+            sessionID: args.sessionID,
+            scope: args.scope,
+          });
+        },
+      }),
+
+      lcm_lineage: tool({
+        description: 'Show archived branch lineage for a session',
+        args: {
+          sessionID: tool.schema.string().optional(),
+        },
+        async execute(args) {
+          return await store.lineage(args.sessionID);
+        },
+      }),
+
+      lcm_pin_session: tool({
+        description: 'Pin a session so retention pruning will skip it',
+        args: {
+          sessionID: tool.schema.string().optional(),
+          reason: tool.schema.string().optional(),
+        },
+        async execute(args) {
+          return await store.pinSession({
+            sessionID: args.sessionID,
+            reason: args.reason,
+          });
+        },
+      }),
+
+      lcm_unpin_session: tool({
+        description: 'Remove a session retention pin',
+        args: {
+          sessionID: tool.schema.string().optional(),
+        },
+        async execute(args) {
+          return await store.unpinSession({
+            sessionID: args.sessionID,
+          });
+        },
+      }),
+
+      lcm_expand: tool({
+        description: 'Expand archived summary nodes into targeted descendants or raw messages',
+        args: {
+          sessionID: tool.schema.string().optional(),
+          nodeID: tool.schema.string().optional(),
+          query: tool.schema.string().optional(),
+          depth: tool.schema.number().int().min(1).max(4).optional(),
+          messageLimit: tool.schema.number().int().min(1).max(20).optional(),
+          includeRaw: tool.schema.boolean().optional(),
+        },
+        async execute(args) {
+          return await store.expand({
+            sessionID: args.sessionID,
+            nodeID: args.nodeID,
+            query: args.query,
+            depth: args.depth,
+            messageLimit: args.messageLimit,
+            includeRaw: args.includeRaw,
+          });
+        },
+      }),
+
+      lcm_artifact: tool({
+        description: 'View externalized archived content by artifact ID',
+        args: {
+          artifactID: tool.schema.string().min(1),
+          chars: tool.schema.number().int().min(200).max(20000).optional(),
+        },
+        async execute(args) {
+          return await store.artifact({
+            artifactID: args.artifactID,
+            chars: args.chars,
+          });
+        },
+      }),
+
+      lcm_blob_stats: tool({
+        description: 'Show deduplicated artifact blob stats',
+        args: {
+          limit: tool.schema.number().int().min(1).max(20).optional(),
+        },
+        async execute(args) {
+          return await store.blobStats({
+            limit: args.limit,
+          });
+        },
+      }),
+
+      lcm_blob_gc: tool({
+        description: 'Preview or delete orphaned artifact blobs',
+        args: {
+          apply: tool.schema.boolean().optional(),
+          limit: tool.schema.number().int().min(1).max(50).optional(),
+        },
+        async execute(args) {
+          return await store.gcBlobs({
+            apply: args.apply,
+            limit: args.limit,
+          });
+        },
+      }),
+
+      lcm_doctor: tool({
+        description: 'Inspect or repair archive summaries and indexes',
+        args: {
+          apply: tool.schema.boolean().optional(),
+          sessionID: tool.schema.string().optional(),
+          limit: tool.schema.number().int().min(1).max(50).optional(),
+        },
+        async execute(args) {
+          return await store.doctor({
+            apply: args.apply,
+            sessionID: args.sessionID,
+            limit: args.limit,
+          });
+        },
+      }),
+
+      lcm_retention_report: tool({
+        description: 'Preview stale-session and orphan-blob retention candidates',
+        args: {
+          staleSessionDays: tool.schema.number().min(0).optional(),
+          deletedSessionDays: tool.schema.number().min(0).optional(),
+          orphanBlobDays: tool.schema.number().min(0).optional(),
+          limit: tool.schema.number().int().min(1).max(50).optional(),
+        },
+        async execute(args) {
+          return await store.retentionReport({
+            staleSessionDays: args.staleSessionDays,
+            deletedSessionDays: args.deletedSessionDays,
+            orphanBlobDays: args.orphanBlobDays,
+            limit: args.limit,
+          });
+        },
+      }),
+
+      lcm_retention_prune: tool({
+        description: 'Preview or apply stale-session and orphan-blob retention pruning',
+        args: {
+          apply: tool.schema.boolean().optional(),
+          staleSessionDays: tool.schema.number().min(0).optional(),
+          deletedSessionDays: tool.schema.number().min(0).optional(),
+          orphanBlobDays: tool.schema.number().min(0).optional(),
+          limit: tool.schema.number().int().min(1).max(50).optional(),
+        },
+        async execute(args) {
+          return await store.retentionPrune({
+            apply: args.apply,
+            staleSessionDays: args.staleSessionDays,
+            deletedSessionDays: args.deletedSessionDays,
+            orphanBlobDays: args.orphanBlobDays,
+            limit: args.limit,
+          });
+        },
+      }),
+
+      lcm_export_snapshot: tool({
+        description: 'Export a portable long-memory snapshot to a JSON file',
+        args: {
+          filePath: tool.schema.string().min(1),
+          sessionID: tool.schema.string().optional(),
+          scope: tool.schema.string().optional(),
+        },
+        async execute(args) {
+          return await store.exportSnapshot({
+            filePath: args.filePath,
+            sessionID: args.sessionID,
+            scope: args.scope,
+          });
+        },
+      }),
+
+      lcm_import_snapshot: tool({
+        description: 'Import a portable long-memory snapshot from a JSON file',
+        args: {
+          filePath: tool.schema.string().min(1),
+          mode: tool.schema.string().optional(),
+          worktreeMode: tool.schema.string().optional(),
+        },
+        async execute(args) {
+          return await store.importSnapshot({
+            filePath: args.filePath,
+            mode: args.mode === 'merge' ? 'merge' : 'replace',
+            worktreeMode:
+              args.worktreeMode === 'preserve' || args.worktreeMode === 'current'
+                ? args.worktreeMode
+                : 'auto',
+          });
+        },
+      }),
+    },
+
+    'experimental.chat.messages.transform': async (_input, output) => {
+      await store.transformMessages(output.messages);
+    },
+
+    'experimental.chat.system.transform': async (_input, output) => {
+      const hint = store.systemHint();
+      if (!hint) return;
+      output.system.push(hint);
+    },
+
+    'experimental.session.compacting': async (input, output) => {
+      const note = await store.buildCompactionContext(input.sessionID);
+      if (!note) return;
+      if (output.context.some((entry) => entry.includes('LCM prototype resume note'))) return;
+      output.context.push(note);
+    },
+  };
+};
+
+export default OpencodeLcmPlugin;

package/src/logging.ts

@@ -0,0 +1,41 @@
+/**
+ * Lightweight structured logging interface for opencode-lcm.
+ * Silent by default so plugin logs do not corrupt the host terminal UI.
+ */
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+export interface Logger {
+  debug(message: string, context?: Record<string, unknown>): void;
+  info(message: string, context?: Record<string, unknown>): void;
+  warn(message: string, context?: Record<string, unknown>): void;
+  error(message: string, context?: Record<string, unknown>): void;
+}
+
+function isTruthyEnvFlag(value: string | undefined): boolean {
+  if (!value) return false;
+  const normalized = value.trim().toLowerCase();
+  return normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'on';
+}
+
+const silentLogger: Logger = {
+  debug() {},
+  info() {},
+  warn() {},
+  error() {},
+};
+
+let currentLogger: Logger = silentLogger;
+
+export function setLogger(logger: Logger): void {
+  currentLogger = logger;
+}
+
+export function getLogger(): Logger {
+  return currentLogger;
+}
+
+export function isStartupLoggingEnabled(): boolean {
+  if (typeof process !== 'object' || !process?.env) return false;
+  return isTruthyEnvFlag(process.env.OPENCODE_LCM_STARTUP_LOG);
+}