memorix 1.2.6 → 1.2.7

package/src/memory/compaction.ts

@@ -0,0 +1,165 @@
+import type { CompactionCheckpoint } from '../types.js';
+import type { NormalizedHookInput } from '../hooks/types.js';
+import { countTextTokens, truncateToTokenBudget } from '../compact/token-budget.js';
+import { sanitizeCredentials } from './secret-filter.js';
+import { CompactionCheckpointStore } from '../store/compaction-checkpoint-store.js';
+
+const DEFAULT_WORKSET_BUDGET = 420;
+const MIN_WORKSET_BUDGET = 48;
+
+export interface CompactionWorkset {
+  checkpointId: string;
+  text: string;
+  tokens: number;
+}
+
+export interface BuildCompactionWorksetOptions {
+  task?: string;
+  maxTokens?: number;
+}
+
+function normalizeBudget(value: number | undefined): number {
+  if (!Number.isFinite(value) || value == null) return DEFAULT_WORKSET_BUDGET;
+  return Math.max(MIN_WORKSET_BUDGET, Math.min(2_000, Math.floor(value)));
+}
+
+function sourceLabel(checkpoint: CompactionCheckpoint): string {
+  if (checkpoint.captureKind === 'native-summary') return 'native host summary';
+  if (checkpoint.captureKind === 'preflight') return 'pre-compact lifecycle marker';
+  return 'host lifecycle marker';
+}
+
+/**
+ * Render a small, source-aware continuation packet. It never replays a full
+ * transcript and never promotes a native summary into durable knowledge.
+ */
+export function buildCompactionWorkset(
+  checkpoint: CompactionCheckpoint,
+  options: BuildCompactionWorksetOptions = {},
+): CompactionWorkset {
+  const budget = normalizeBudget(options.maxTokens);
+  const task = options.task?.trim()
+    ? truncateToTokenBudget(sanitizeCredentials(options.task.trim()), Math.max(8, Math.floor(budget * 0.25)))
+    : '';
+  const headerLines = [
+    '## Compact Continuation',
+    `- Host: ${checkpoint.agent} (${sourceLabel(checkpoint)})`,
+    `- Trigger: ${checkpoint.reason}`,
+    task ? `- Task now: ${task}` : '',
+    '- Current code remains authoritative.',
+  ].filter(Boolean);
+  const header = `${headerLines.join('\n')}\n\n`;
+  const fallback = checkpoint.captureKind === 'native-summary'
+    ? ''
+    : 'The host did not expose a native compact summary. Reconstruct only what the current task needs from current code and Memorix evidence.';
+  const source = sanitizeCredentials(checkpoint.summary?.trim() || fallback);
+  const available = Math.max(0, budget - countTextTokens(header) - 4);
+  let excerpt = source ? truncateToTokenBudget(source, available) : '';
+  let text = `${header}${excerpt ? `### Host checkpoint\n${excerpt}` : ''}`.trim();
+  while (excerpt && countTextTokens(text) > budget) {
+    const nextExcerptBudget = Math.max(1, Math.floor(countTextTokens(excerpt) * 0.8));
+    excerpt = truncateToTokenBudget(excerpt, nextExcerptBudget);
+    text = `${header}${excerpt ? `### Host checkpoint\n${excerpt}` : ''}`.trim();
+  }
+  if (countTextTokens(text) > budget) text = truncateToTokenBudget(text, budget);
+  return {
+    checkpointId: checkpoint.id,
+    text,
+    tokens: countTextTokens(text),
+  };
+}
+
+function sourceEvent(input: NormalizedHookInput): string {
+  const raw = input.raw;
+  const event = raw.hook_event_name ?? raw.event ?? raw.type;
+  return typeof event === 'string' && event ? event : input.event;
+}
+
+/**
+ * Persist only the host lifecycle evidence available in a normalized hook.
+ * The caller owns error handling so an unavailable local DB never blocks a
+ * host-native compaction.
+ */
+export async function captureCompactionCheckpoint(
+  input: NormalizedHookInput,
+): Promise<CompactionCheckpoint | null> {
+  const isCompactResume = input.event === 'session_start'
+    && input.sessionStartReason?.trim().toLowerCase() === 'compact';
+  if (input.event !== 'pre_compact' && input.event !== 'post_compact' && !isCompactResume) return null;
+  if (!input.sessionId || !input.cwd) return null;
+
+  const [
+    { detectProject },
+    { getProjectDataDir },
+    { initAliasRegistry, registerAlias },
+  ] = await Promise.all([
+    import('../project/detector.js'),
+    import('../store/persistence.js'),
+    import('../project/aliases.js'),
+  ]);
+  const project = detectProject(input.cwd);
+  if (!project) return null;
+  const dataDir = await getProjectDataDir(project.id);
+  initAliasRegistry(dataDir);
+  const projectId = await registerAlias(project);
+  const store = new CompactionCheckpointStore(dataDir);
+
+  if (input.event === 'pre_compact') {
+    return store.recordPreflight({
+      projectId,
+      sessionId: input.sessionId,
+      agent: input.agent,
+      reason: input.compaction?.reason,
+      sourceEvent: sourceEvent(input),
+      transcriptAvailable: Boolean(input.transcriptPath),
+      capturedAt: input.timestamp,
+    });
+  }
+
+  return store.complete({
+    projectId,
+    sessionId: input.sessionId,
+    agent: input.agent,
+    reason: input.compaction?.reason,
+    sourceEvent: sourceEvent(input),
+    sourceKey: input.compaction?.sourceKey,
+    summary: input.compaction?.summary,
+    tokensBefore: input.compaction?.tokensBefore,
+    firstKeptEntryId: input.compaction?.firstKeptEntryId,
+    details: input.compaction?.details,
+    completedAt: input.timestamp,
+  });
+}
+
+/**
+ * Take the latest undelivered compact checkpoint for an exact host session.
+ * Delivery is opt-in at adapter boundaries; this helper never injects content
+ * into a host by itself.
+ */
+export async function consumeCompactionWorkset(
+  input: NormalizedHookInput,
+  options: BuildCompactionWorksetOptions = {},
+): Promise<CompactionWorkset | null> {
+  if (!input.sessionId || !input.cwd) return null;
+  const [
+    { detectProject },
+    { getProjectDataDir },
+    { initAliasRegistry, registerAlias },
+  ] = await Promise.all([
+    import('../project/detector.js'),
+    import('../store/persistence.js'),
+    import('../project/aliases.js'),
+  ]);
+  const project = detectProject(input.cwd);
+  if (!project) return null;
+  const dataDir = await getProjectDataDir(project.id);
+  initAliasRegistry(dataDir);
+  const projectId = await registerAlias(project);
+  const store = new CompactionCheckpointStore(dataDir);
+  const checkpoint = store.findUndelivered(projectId, input.sessionId, input.agent);
+  if (!checkpoint) return null;
+  const workset = buildCompactionWorkset(checkpoint, options);
+  if (!workset.text) return null;
+  store.markDelivered(checkpoint.id);
+  return workset;
+}

package/src/server/tool-profile.ts

@@ -68,6 +68,7 @@ export const TOOL_PROFILES: Record<string, ReadonlyArray<ToolProfile>> = Object.
   memorix_rules_sync:         ['full'],
   memorix_workspace_sync:     ['full'],
   memorix_ingest_image:       ['full'],
+  memorix_compaction_checkpoint: ['full'],
 
   // ── MCP Official Memory Server compatibility (KG tools) ──────────
   // These are only useful to users specifically migrating from the

package/src/server.ts

@@ -3974,6 +3974,100 @@ export async function createMemorixServer(
     },
   );
 
+  /**
+   * memorix_compaction_checkpoint — Advanced inspection of native host
+   * compaction checkpoints. Automatic recovery does not need this tool; it is
+   * deliberately full-profile only so normal MCP startup stays compact.
+   */
+  server.registerTool(
+    'memorix_compaction_checkpoint',
+    {
+      title: 'Compact Continuity Checkpoints',
+      description:
+        'Inspect, preview, or archive bounded checkpoints recorded around a host-native context compaction. ' +
+        'Use only to debug or explicitly review compaction continuity. These are lifecycle records, not durable memories or transcript backups. ' +
+        'CLI equivalent: memorix checkpoint list|show|context|archive.',
+      inputSchema: {
+        action: z.enum(['list', 'show', 'context', 'archive']).default('list'),
+        id: z.string().optional().describe('Checkpoint ID for show, context, or archive'),
+        sessionId: z.string().optional().describe('Optional host session ID filter'),
+        agent: z.string().optional().describe('Optional host agent filter'),
+        task: z.string().optional().describe('Current task for a bounded context preview'),
+        maxTokens: z.number().optional().describe('Maximum tokens for action=context (default: 420)'),
+        limit: z.number().optional().describe('Maximum records for action=list (default: 20)'),
+        includeArchived: z.boolean().optional().default(false).describe('Include archived records in action=list'),
+      },
+    },
+    async ({ action, id, sessionId, agent, task, maxTokens, limit, includeArchived }) => {
+      const unresolved = requireResolvedProject('inspect compact continuity checkpoints');
+      if (unresolved) return unresolved;
+
+      const [{ CompactionCheckpointStore }, { buildCompactionWorkset }] = await Promise.all([
+        import('./store/compaction-checkpoint-store.js'),
+        import('./memory/compaction.js'),
+      ]);
+      const store = new CompactionCheckpointStore(projectDir);
+      const assertCheckpoint = (checkpointId: string) => {
+        const checkpoint = store.get(checkpointId);
+        if (!checkpoint || checkpoint.projectId !== project.id) return null;
+        return checkpoint;
+      };
+
+      if (action === 'list') {
+        const checkpoints = store.list({
+          projectId: project.id,
+          sessionId: sessionId?.trim() || undefined,
+          agent: agent?.trim() || undefined,
+          includeArchived: Boolean(includeArchived),
+          limit: limit != null ? Math.max(1, Math.min(100, coerceNumber(limit, 20))) : 20,
+        });
+        return {
+          content: [{ type: 'text' as const, text: JSON.stringify({ projectId: project.id, checkpoints }, null, 2) }],
+        };
+      }
+
+      if (!id?.trim()) {
+        return {
+          content: [{ type: 'text' as const, text: 'id is required for this checkpoint action.' }],
+          isError: true,
+        };
+      }
+      const checkpoint = assertCheckpoint(id.trim());
+      if (!checkpoint) {
+        return {
+          content: [{ type: 'text' as const, text: `Checkpoint "${id.trim()}" was not found for the current project.` }],
+          isError: true,
+        };
+      }
+
+      if (action === 'show') {
+        return {
+          content: [{ type: 'text' as const, text: JSON.stringify({ projectId: project.id, checkpoint }, null, 2) }],
+        };
+      }
+      if (action === 'context') {
+        const workset = buildCompactionWorkset(checkpoint, {
+          task: task?.trim(),
+          maxTokens: maxTokens != null ? coerceNumber(maxTokens, 420) : 420,
+        });
+        return {
+          content: [{ type: 'text' as const, text: workset.text }],
+        };
+      }
+
+      const archived = store.archive(checkpoint.id);
+      if (!archived) {
+        return {
+          content: [{ type: 'text' as const, text: `Checkpoint "${checkpoint.id}" is already archived.` }],
+          isError: true,
+        };
+      }
+      return {
+        content: [{ type: 'text' as const, text: `Archived compact checkpoint ${archived.id}.` }],
+      };
+    },
+  );
+
   // ============================================================
   // Export / Import
   // ============================================================

package/src/store/compaction-checkpoint-store.ts

@@ -0,0 +1,397 @@
+import { createHash, randomUUID } from 'node:crypto';
+import type {
+  CompactionCaptureKind,
+  CompactionCheckpoint,
+  CompactionCheckpointStatus,
+  CompactionReason,
+} from '../types.js';
+import { sanitizeCredentials } from '../memory/secret-filter.js';
+import { getDatabase } from './sqlite-db.js';
+
+const MAX_SUMMARY_CHARS = 24_000;
+const MAX_DETAILS_CHARS = 4_000;
+
+export interface RecordCompactionPreflightInput {
+  projectId: string;
+  sessionId: string;
+  agent: string;
+  reason?: CompactionReason;
+  sourceEvent: string;
+  transcriptAvailable?: boolean;
+  capturedAt?: string;
+}
+
+export interface CompleteCompactionCheckpointInput {
+  projectId: string;
+  sessionId: string;
+  agent: string;
+  reason?: CompactionReason;
+  sourceEvent: string;
+  sourceKey?: string;
+  summary?: string;
+  tokensBefore?: number;
+  firstKeptEntryId?: string;
+  details?: Record<string, unknown>;
+  completedAt?: string;
+}
+
+export interface ListCompactionCheckpointsOptions {
+  projectId: string;
+  sessionId?: string;
+  agent?: string;
+  includeArchived?: boolean;
+  limit?: number;
+}
+
+export interface FindLatestCompletedCheckpointOptions {
+  /**
+   * A Hook may already have delivered this exact host session's checkpoint via
+   * an official native context channel. Do not put it back into its generic
+   * Autopilot brief on a later event from the same session.
+   */
+  excludeSession?: {
+    sessionId: string;
+    agent: string;
+  };
+}
+
+function optionalText(value: unknown): string | undefined {
+  return typeof value === 'string' && value ? value : undefined;
+}
+
+function optionalNumber(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function parseDetails(value: unknown): Record<string, unknown> | undefined {
+  if (typeof value !== 'string' || !value) return undefined;
+  try {
+    const parsed = JSON.parse(value);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? parsed as Record<string, unknown>
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function sanitizeSummary(value: string | undefined): string | undefined {
+  if (!value?.trim()) return undefined;
+  return sanitizeCredentials(value).slice(0, MAX_SUMMARY_CHARS).trim() || undefined;
+}
+
+function sanitizeDetails(value: Record<string, unknown> | undefined): Record<string, unknown> | undefined {
+  if (!value) return undefined;
+  try {
+    const sanitized = sanitizeCredentials(JSON.stringify(value));
+    if (sanitized.length > MAX_DETAILS_CHARS) return { truncated: true };
+    const parsed = JSON.parse(sanitized);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? parsed as Record<string, unknown>
+      : undefined;
+  } catch {
+    return { unavailable: true };
+  }
+}
+
+function sourceKeyFor(input: CompleteCompactionCheckpointInput, summary?: string): string {
+  if (input.sourceKey?.trim()) return input.sourceKey.trim().slice(0, 300);
+  const material = [
+    input.projectId,
+    input.sessionId,
+    input.agent,
+    input.sourceEvent,
+    summary ?? '',
+    input.tokensBefore ?? '',
+    input.firstKeptEntryId ?? '',
+  ].join('\u0000');
+  return `derived:${createHash('sha256').update(material).digest('hex').slice(0, 32)}`;
+}
+
+function rowToCheckpoint(row: any): CompactionCheckpoint {
+  return {
+    id: row.id,
+    projectId: row.project_id,
+    sessionId: row.session_id,
+    agent: row.agent,
+    phase: row.phase,
+    captureKind: row.capture_kind,
+    reason: row.reason,
+    sourceEvent: row.source_event,
+    sourceKey: row.source_key,
+    ...(optionalText(row.summary) ? { summary: row.summary } : {}),
+    ...(optionalNumber(row.tokens_before) !== undefined ? { tokensBefore: Number(row.tokens_before) } : {}),
+    ...(optionalText(row.first_kept_entry_id) ? { firstKeptEntryId: row.first_kept_entry_id } : {}),
+    ...(parseDetails(row.details_json) ? { details: parseDetails(row.details_json) } : {}),
+    transcriptAvailable: Boolean(row.transcript_available),
+    status: row.status as CompactionCheckpointStatus,
+    preCapturedAt: row.pre_captured_at,
+    ...(optionalText(row.completed_at) ? { completedAt: row.completed_at } : {}),
+    ...(optionalText(row.delivered_at) ? { deliveredAt: row.delivered_at } : {}),
+    deliveryCount: Number(row.delivery_count ?? 0),
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+function safeReason(value: CompactionReason | undefined): CompactionReason {
+  return value === 'manual' || value === 'auto' ? value : 'unknown';
+}
+
+function safeLimit(value: number | undefined, fallback: number): number {
+  if (!Number.isFinite(value) || value == null) return fallback;
+  return Math.max(1, Math.min(500, Math.floor(value)));
+}
+
+/**
+ * SQLite persistence for host-native compaction lifecycle records.
+ *
+ * The store deliberately keeps evidence separate from Observations so a
+ * compactor's summary cannot silently become durable project knowledge.
+ */
+export class CompactionCheckpointStore {
+  private readonly db: any;
+
+  constructor(dataDir: string) {
+    this.db = getDatabase(dataDir);
+  }
+
+  recordPreflight(input: RecordCompactionPreflightInput): CompactionCheckpoint {
+    const pending = this.db.prepare(`
+      SELECT * FROM compaction_checkpoints
+      WHERE project_id = ? AND session_id = ? AND agent = ?
+        AND phase = 'pre' AND status = 'active'
+      ORDER BY pre_captured_at DESC, created_at DESC
+      LIMIT 1
+    `).get(input.projectId, input.sessionId, input.agent);
+    if (pending) return rowToCheckpoint(pending);
+
+    const now = input.capturedAt ?? new Date().toISOString();
+    const checkpoint: CompactionCheckpoint = {
+      id: randomUUID(),
+      projectId: input.projectId,
+      sessionId: input.sessionId,
+      agent: input.agent,
+      phase: 'pre',
+      captureKind: 'preflight',
+      reason: safeReason(input.reason),
+      sourceEvent: input.sourceEvent,
+      sourceKey: `pre:${randomUUID()}`,
+      transcriptAvailable: Boolean(input.transcriptAvailable),
+      status: 'active',
+      preCapturedAt: now,
+      deliveryCount: 0,
+      createdAt: now,
+      updatedAt: now,
+    };
+    this.insert(checkpoint);
+    return checkpoint;
+  }
+
+  complete(input: CompleteCompactionCheckpointInput): CompactionCheckpoint {
+    const completedAt = input.completedAt ?? new Date().toISOString();
+    const summary = sanitizeSummary(input.summary);
+    const pending = this.db.prepare(`
+      SELECT * FROM compaction_checkpoints
+      WHERE project_id = ? AND session_id = ? AND agent = ?
+        AND phase = 'pre' AND status = 'active'
+      ORDER BY pre_captured_at DESC, created_at DESC
+      LIMIT 1
+    `).get(input.projectId, input.sessionId, input.agent);
+
+    // Hosts such as Codex and Claude expose a post-compact lifecycle signal
+    // but no event ID. Correlate it with the newest preflight marker so two
+    // compactions in one long session remain distinct. With no fresh marker,
+    // treat another identical lifecycle signal as a duplicate rather than
+    // creating a stream of empty checkpoints.
+    if (!input.sourceKey?.trim() && !summary && input.tokensBefore === undefined && !input.firstKeptEntryId && !pending) {
+      const priorLifecycle = this.db.prepare(`
+        SELECT * FROM compaction_checkpoints
+        WHERE project_id = ? AND session_id = ? AND agent = ?
+          AND phase = 'complete' AND capture_kind = 'lifecycle'
+          AND source_event = ? AND status = 'active'
+        ORDER BY completed_at DESC, created_at DESC
+        LIMIT 1
+      `).get(input.projectId, input.sessionId, input.agent, input.sourceEvent);
+      if (priorLifecycle) return rowToCheckpoint(priorLifecycle);
+    }
+
+    const sourceKey = input.sourceKey?.trim()
+      ? input.sourceKey.trim().slice(0, 300)
+      : pending
+        ? `lifecycle:${pending.id}`
+        : sourceKeyFor(input, summary);
+    const existing = this.db.prepare(`
+      SELECT * FROM compaction_checkpoints
+      WHERE project_id = ? AND source_key = ?
+      LIMIT 1
+    `).get(input.projectId, sourceKey);
+    if (existing) return rowToCheckpoint(existing);
+
+    const captureKind: CompactionCaptureKind = summary ? 'native-summary' : 'lifecycle';
+    const details = sanitizeDetails(input.details);
+
+    if (pending) {
+      const checkpoint = rowToCheckpoint(pending);
+      const nextReason = safeReason(input.reason) === 'unknown'
+        ? checkpoint.reason
+        : safeReason(input.reason);
+      this.db.prepare(`
+        UPDATE compaction_checkpoints
+        SET phase = 'complete', capture_kind = ?, reason = ?, source_event = ?, source_key = ?,
+            summary = ?, tokens_before = ?, first_kept_entry_id = ?, details_json = ?,
+            completed_at = ?, updated_at = ?
+        WHERE id = ?
+      `).run(
+        captureKind,
+        nextReason,
+        input.sourceEvent,
+        sourceKey,
+        summary ?? null,
+        input.tokensBefore ?? null,
+        input.firstKeptEntryId ?? null,
+        JSON.stringify(details ?? {}),
+        completedAt,
+        completedAt,
+        checkpoint.id,
+      );
+      return this.get(checkpoint.id)!;
+    }
+
+    const checkpoint: CompactionCheckpoint = {
+      id: randomUUID(),
+      projectId: input.projectId,
+      sessionId: input.sessionId,
+      agent: input.agent,
+      phase: 'complete',
+      captureKind,
+      reason: safeReason(input.reason),
+      sourceEvent: input.sourceEvent,
+      sourceKey,
+      ...(summary ? { summary } : {}),
+      ...(input.tokensBefore !== undefined ? { tokensBefore: input.tokensBefore } : {}),
+      ...(input.firstKeptEntryId ? { firstKeptEntryId: input.firstKeptEntryId } : {}),
+      ...(details ? { details } : {}),
+      transcriptAvailable: false,
+      status: 'active',
+      preCapturedAt: completedAt,
+      completedAt,
+      deliveryCount: 0,
+      createdAt: completedAt,
+      updatedAt: completedAt,
+    };
+    this.insert(checkpoint);
+    return checkpoint;
+  }
+
+  get(id: string): CompactionCheckpoint | undefined {
+    const row = this.db.prepare('SELECT * FROM compaction_checkpoints WHERE id = ?').get(id);
+    return row ? rowToCheckpoint(row) : undefined;
+  }
+
+  list(options: ListCompactionCheckpointsOptions): CompactionCheckpoint[] {
+    const conditions = ['project_id = ?'];
+    const values: unknown[] = [options.projectId];
+    if (options.sessionId) {
+      conditions.push('session_id = ?');
+      values.push(options.sessionId);
+    }
+    if (options.agent) {
+      conditions.push('agent = ?');
+      values.push(options.agent);
+    }
+    if (!options.includeArchived) {
+      conditions.push("status = 'active'");
+    }
+    const rows = this.db.prepare(`
+      SELECT * FROM compaction_checkpoints
+      WHERE ${conditions.join(' AND ')}
+      ORDER BY COALESCE(completed_at, pre_captured_at) DESC, created_at DESC
+      LIMIT ?
+    `).all(...values, safeLimit(options.limit, 20));
+    return rows.map(rowToCheckpoint);
+  }
+
+  findUndelivered(projectId: string, sessionId: string, agent: string): CompactionCheckpoint | undefined {
+    const row = this.db.prepare(`
+      SELECT * FROM compaction_checkpoints
+      WHERE project_id = ? AND session_id = ? AND agent = ?
+        AND phase = 'complete' AND status = 'active' AND delivered_at IS NULL
+      ORDER BY completed_at DESC, created_at DESC
+      LIMIT 1
+    `).get(projectId, sessionId, agent);
+    return row ? rowToCheckpoint(row) : undefined;
+  }
+
+  findLatestCompleted(
+    projectId: string,
+    options: FindLatestCompletedCheckpointOptions = {},
+  ): CompactionCheckpoint | undefined {
+    const excludeSession = options.excludeSession;
+    const exclusion = excludeSession
+      ? ' AND NOT (session_id = ? AND agent = ? )'
+      : '';
+    const values = excludeSession
+      ? [projectId, excludeSession.sessionId, excludeSession.agent]
+      : [projectId];
+    const row = this.db.prepare(`
+      SELECT * FROM compaction_checkpoints
+      WHERE project_id = ? AND phase = 'complete' AND status = 'active'
+      ${exclusion}
+      ORDER BY completed_at DESC, created_at DESC
+      LIMIT 1
+    `).get(...values);
+    return row ? rowToCheckpoint(row) : undefined;
+  }
+
+  archive(id: string, archivedAt = new Date().toISOString()): CompactionCheckpoint | undefined {
+    const result = this.db.prepare(`
+      UPDATE compaction_checkpoints
+      SET status = 'archived', updated_at = ?
+      WHERE id = ? AND status = 'active'
+    `).run(archivedAt, id);
+    return Number(result.changes ?? 0) > 0 ? this.get(id) : undefined;
+  }
+
+  markDelivered(id: string, deliveredAt = new Date().toISOString()): CompactionCheckpoint | undefined {
+    const result = this.db.prepare(`
+      UPDATE compaction_checkpoints
+      SET delivered_at = ?, delivery_count = delivery_count + 1, updated_at = ?
+      WHERE id = ? AND phase = 'complete' AND status = 'active' AND delivered_at IS NULL
+    `).run(deliveredAt, deliveredAt, id);
+    return Number(result.changes ?? 0) > 0 ? this.get(id) : undefined;
+  }
+
+  private insert(checkpoint: CompactionCheckpoint): void {
+    this.db.prepare(`
+      INSERT INTO compaction_checkpoints (
+        id, project_id, session_id, agent, phase, capture_kind, reason,
+        source_event, source_key, summary, tokens_before, first_kept_entry_id,
+        details_json, transcript_available, status, pre_captured_at, completed_at,
+        delivered_at, delivery_count, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      checkpoint.id,
+      checkpoint.projectId,
+      checkpoint.sessionId,
+      checkpoint.agent,
+      checkpoint.phase,
+      checkpoint.captureKind,
+      checkpoint.reason,
+      checkpoint.sourceEvent,
+      checkpoint.sourceKey,
+      checkpoint.summary ?? null,
+      checkpoint.tokensBefore ?? null,
+      checkpoint.firstKeptEntryId ?? null,
+      JSON.stringify(checkpoint.details ?? {}),
+      checkpoint.transcriptAvailable ? 1 : 0,
+      checkpoint.status,
+      checkpoint.preCapturedAt,
+      checkpoint.completedAt ?? null,
+      checkpoint.deliveredAt ?? null,
+      checkpoint.deliveryCount,
+      checkpoint.createdAt,
+      checkpoint.updatedAt,
+    );
+  }
+}