opencode-swarm 7.39.0 → 7.40.0

package/dist/index.js

@@ -48,7 +48,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "opencode-swarm",
-    version: "7.39.0",
+    version: "7.40.0",
     description: "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
     main: "dist/index.js",
     types: "dist/index.d.ts",
@@ -15581,6 +15581,13 @@ var init_schema = __esm(() => {
     redaction: exports_external.object({
       rejectDurableSecrets: exports_external.boolean().default(true)
     }).default({ rejectDurableSecrets: true }),
+    maintenance: exports_external.object({
+      lowUtilityMaxConfidence: exports_external.number().min(0).max(1).default(0.45),
+      lowUtilityMinAgeDays: exports_external.number().int().min(1).max(3650).default(30)
+    }).default({
+      lowUtilityMaxConfidence: 0.45,
+      lowUtilityMinAgeDays: 30
+    }),
     hardDelete: exports_external.boolean().default(false)
   });
   CuratorConfigSchema = exports_external.object({
@@ -66897,6 +66904,10 @@ function resolveMemoryConfig(input) {
     redaction: {
       ...DEFAULT_MEMORY_CONFIG.redaction,
       ...input?.redaction ?? {}
+    },
+    maintenance: {
+      ...DEFAULT_MEMORY_CONFIG.maintenance,
+      ...input?.maintenance ?? {}
     }
   };
 }
@@ -66928,6 +66939,10 @@ var init_config3 = __esm(() => {
     redaction: {
       rejectDurableSecrets: true
     },
+    maintenance: {
+      lowUtilityMaxConfidence: 0.45,
+      lowUtilityMinAgeDays: 30
+    },
     hardDelete: false
   };
   DURABLE_MEMORY_KINDS = new Set([
@@ -67340,6 +67355,167 @@ var init_curator_decision_helpers = __esm(() => {
   init_schema2();
 });
 
+// src/memory/maintenance.ts
+async function buildMemoryMaintenanceReport(provider, options = {}) {
+  const now = options.now ?? new Date;
+  const limit = Math.max(1, Math.trunc(options.limit ?? 20));
+  const memories = await provider.list({
+    includeExpired: true,
+    includeInactive: true
+  });
+  const proposals = await loadMaintenanceProposals(provider, limit);
+  const recallUsage = provider.listRecallUsage ? await provider.listRecallUsage() : [];
+  const usageByMemory = summarizeRecallByMemory(recallUsage);
+  const usageByRole = summarizeRecallByRole(recallUsage);
+  const activeMemories = memories.filter((memory) => isActiveMemory(memory, now));
+  const deletedMemories = memories.filter((memory) => memory.metadata.deleted === true);
+  const expiredScratchMemories = memories.filter((memory) => memory.kind === "scratch" && isExpired(memory, now));
+  const supersededMemories = memories.filter((memory) => Boolean(memory.supersededBy));
+  const lowUtilityMemories = activeMemories.filter((memory) => isLowUtility(memory, usageByMemory, now, {
+    maxConfidence: options.lowUtilityMaxConfidence ?? DEFAULT_LOW_UTILITY_MAX_CONFIDENCE,
+    minAgeDays: options.lowUtilityMinAgeDays ?? DEFAULT_LOW_UTILITY_MIN_AGE_DAYS
+  })).sort(memorySort);
+  const neverRecalledMemories = activeMemories.filter((memory) => !usageByMemory.has(memory.id)).sort(memorySort);
+  const rejectedProposalReasons = proposals.filter((proposal) => proposal.status === "rejected").sort(proposalSort);
+  const pendingProposals = proposals.filter((proposal) => proposal.status === "pending").sort(proposalSort);
+  return {
+    generatedAt: now.toISOString(),
+    totalMemories: memories.length,
+    activeMemories: activeMemories.length,
+    deletedMemories: deletedMemories.slice(0, limit),
+    expiredScratchMemories: expiredScratchMemories.slice(0, limit),
+    supersededMemories: supersededMemories.slice(0, limit),
+    supersededChains: buildSupersededChains(memories).slice(0, limit),
+    lowUtilityMemories: lowUtilityMemories.slice(0, limit),
+    neverRecalledMemories: neverRecalledMemories.slice(0, limit),
+    mostRecalledMemories: Array.from(usageByMemory.values()).sort((a, b) => b.count - a.count || b.lastRecalledAt.localeCompare(a.lastRecalledAt) || a.memoryId.localeCompare(b.memoryId)).slice(0, limit),
+    recallByAgentRole: Array.from(usageByRole.values()).sort((a, b) => b.count - a.count || a.agentRole.localeCompare(b.agentRole)).slice(0, limit),
+    rejectedProposalReasons: rejectedProposalReasons.slice(0, limit),
+    pendingProposals: pendingProposals.slice(0, limit),
+    recallEventCount: recallUsage.length
+  };
+}
+function shouldCompactMemory(memory, now = new Date) {
+  if (memory.metadata.deleted === true)
+    return "deleted";
+  if (memory.supersededBy)
+    return "superseded";
+  if (memory.kind === "scratch" && isExpired(memory, now)) {
+    return "expired_scratch";
+  }
+  return null;
+}
+function isActiveMemory(memory, now) {
+  return memory.metadata.deleted !== true && !memory.supersededBy && !isExpired(memory, now);
+}
+function isLowUtility(memory, usageByMemory, now, options) {
+  if (usageByMemory.has(memory.id))
+    return false;
+  const updated = Date.parse(memory.updatedAt);
+  const ageDays = Number.isFinite(updated) ? (now.getTime() - updated) / (24 * 60 * 60 * 1000) : 0;
+  return memory.confidence <= options.maxConfidence || ageDays >= options.minAgeDays;
+}
+function summarizeRecallByMemory(usageEvents) {
+  const byMemory = new Map;
+  for (const event of usageEvents) {
+    event.memoryIds.forEach((memoryId, index) => {
+      const role = event.agentRole ?? "unknown";
+      const existing = byMemory.get(memoryId) ?? {
+        memoryId,
+        count: 0,
+        lastRecalledAt: event.timestamp,
+        agentRoles: {},
+        averageScore: 0,
+        scoreTotal: 0,
+        scoreCount: 0
+      };
+      existing.count++;
+      existing.lastRecalledAt = event.timestamp > existing.lastRecalledAt ? event.timestamp : existing.lastRecalledAt;
+      existing.agentRoles[role] = (existing.agentRoles[role] ?? 0) + 1;
+      const score = event.scores[index];
+      if (typeof score === "number" && Number.isFinite(score)) {
+        existing.scoreTotal += score;
+        existing.scoreCount++;
+        existing.averageScore = existing.scoreTotal / existing.scoreCount;
+      }
+      byMemory.set(memoryId, existing);
+    });
+  }
+  return new Map(Array.from(byMemory, ([memoryId, value]) => [
+    memoryId,
+    {
+      memoryId,
+      count: value.count,
+      lastRecalledAt: value.lastRecalledAt,
+      agentRoles: value.agentRoles,
+      averageScore: value.averageScore
+    }
+  ]));
+}
+async function loadMaintenanceProposals(provider, limit) {
+  if (!provider.listProposals)
+    return [];
+  const [pending, rejected, recent] = await Promise.all([
+    provider.listProposals({ status: "pending", limit }),
+    provider.listProposals({ status: "rejected", limit }),
+    provider.listProposals({ limit: Math.max(limit * 4, 100) })
+  ]);
+  const byId = new Map;
+  for (const proposal of [...pending, ...rejected, ...recent]) {
+    byId.set(proposal.id, proposal);
+  }
+  return Array.from(byId.values());
+}
+function summarizeRecallByRole(usageEvents) {
+  const byRole = new Map;
+  for (const event of usageEvents) {
+    const role = event.agentRole ?? "unknown";
+    const existing = byRole.get(role) ?? {
+      agentRole: role,
+      count: 0,
+      memoryIds: {}
+    };
+    existing.count++;
+    for (const memoryId of event.memoryIds) {
+      existing.memoryIds[memoryId] = (existing.memoryIds[memoryId] ?? 0) + 1;
+    }
+    byRole.set(role, existing);
+  }
+  return byRole;
+}
+function buildSupersededChains(memories) {
+  const byId = new Map(memories.map((memory) => [memory.id, memory]));
+  const supersededIds = new Set(memories.filter((memory) => memory.supersededBy).map((memory) => memory.id));
+  const roots = memories.filter((memory) => memory.supersededBy && !(memory.supersedes ?? []).some((id) => supersededIds.has(id)));
+  return roots.map((root) => {
+    const chain = [root.id];
+    const seen = new Set(chain);
+    let cursor = root;
+    while (cursor?.supersededBy && !seen.has(cursor.supersededBy)) {
+      chain.push(cursor.supersededBy);
+      seen.add(cursor.supersededBy);
+      cursor = byId.get(cursor.supersededBy);
+    }
+    return {
+      rootId: root.id,
+      chain,
+      reason: typeof root.metadata.supersedeReason === "string" ? root.metadata.supersedeReason : undefined
+    };
+  });
+}
+function memorySort(a, b) {
+  return b.updatedAt.localeCompare(a.updatedAt) || a.id.localeCompare(b.id);
+}
+function proposalSort(a, b) {
+  const aTime = a.reviewedAt ?? a.createdAt;
+  const bTime = b.reviewedAt ?? b.createdAt;
+  return bTime.localeCompare(aTime) || a.id.localeCompare(b.id);
+}
+var DEFAULT_LOW_UTILITY_MAX_CONFIDENCE = 0.45, DEFAULT_LOW_UTILITY_MIN_AGE_DAYS = 30;
+var init_maintenance = __esm(() => {
+  init_schema2();
+});
+
 // src/memory/role-profiles.ts
 function resolveMemoryRecallProfile(agentRole) {
   const role = normalizeMemoryAgentRole(agentRole);
@@ -67727,16 +67903,21 @@ class LocalJsonlMemoryProvider {
   }
   async recordRecallUsage(event) {
     await this.initialize();
-    await this.audit("recall", event.bundleId, JSON.stringify({
-      query: event.query,
-      scopes: event.scopes,
-      kinds: event.kinds,
-      memoryIds: event.memoryIds,
-      scores: event.scores,
-      tokenEstimate: event.tokenEstimate,
-      agentRole: event.agentRole,
-      runId: event.runId
-    }));
+    await this.audit("recall", event.bundleId, undefined, event);
+  }
+  async listRecallUsage(filter = {}) {
+    await this.initialize();
+    const events = await readAuditEvents(this.pathFor("audit"));
+    const usage = [];
+    for (const event of events) {
+      if (event.operation !== "recall")
+        continue;
+      const parsed = parseRecallUsageEvent(event);
+      if (parsed)
+        usage.push(parsed);
+    }
+    usage.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+    return usage.slice(0, filter.limit ?? usage.length);
   }
   async list(filter = {}) {
     await this.initialize();
@@ -67756,7 +67937,9 @@ class LocalJsonlMemoryProvider {
         return !Number.isFinite(expires) || expires > now;
       });
     }
-    records = records.filter((record3) => !record3.supersededBy && record3.metadata.deleted !== true);
+    if (!filter.includeInactive) {
+      records = records.filter((record3) => !record3.supersededBy && record3.metadata.deleted !== true);
+    }
     records.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
     return records.slice(0, filter.limit ?? records.length);
   }
@@ -67868,6 +68051,41 @@ class LocalJsonlMemoryProvider {
     await writeJsonlAtomic(this.pathFor("memories"), Array.from(this.memories.values()));
     await this.audit("compact", "memories");
   }
+  async compactMaintenance(options = {}) {
+    await this.initialize();
+    const now = options.now ? new Date(options.now) : new Date;
+    const kept = [];
+    const result = {
+      dryRun: options.dryRun !== false,
+      removedDeleted: 0,
+      removedSuperseded: 0,
+      removedExpiredScratch: 0,
+      remaining: 0
+    };
+    for (const memory of this.memories.values()) {
+      const compactReason = shouldCompactMemory(memory, now);
+      if (compactReason === "deleted") {
+        result.removedDeleted++;
+        continue;
+      }
+      if (compactReason === "superseded") {
+        result.removedSuperseded++;
+        continue;
+      }
+      if (compactReason === "expired_scratch") {
+        result.removedExpiredScratch++;
+        continue;
+      }
+      kept.push(memory);
+    }
+    result.remaining = kept.length;
+    if (result.dryRun)
+      return result;
+    this.memories = new Map(kept.map((memory) => [memory.id, memory]));
+    await writeJsonlAtomic(this.pathFor("memories"), kept);
+    await this.audit("compact", "memories", "removed deleted, superseded, and expired scratch memories", result);
+    return result;
+  }
   async audit(operation, targetId, reason, eventJson) {
     const event = {
       id: randomUUID4(),
@@ -67946,6 +68164,46 @@ async function readJsonl(filePath) {
   }
   return records;
 }
+async function readAuditEvents(filePath) {
+  const values = await readJsonl(filePath);
+  const events = [];
+  for (const value of values) {
+    if (!value || typeof value !== "object")
+      continue;
+    const candidate = value;
+    if (typeof candidate.id !== "string" || typeof candidate.operation !== "string" || typeof candidate.targetId !== "string" || typeof candidate.timestamp !== "string") {
+      continue;
+    }
+    events.push(candidate);
+  }
+  return events;
+}
+function parseRecallUsageEvent(event) {
+  const raw = event.eventJson ?? event.reason;
+  if (typeof raw !== "string" && (!raw || typeof raw !== "object")) {
+    return null;
+  }
+  try {
+    const parsed = typeof raw === "string" ? JSON.parse(raw) : raw;
+    if (!Array.isArray(parsed.memoryIds) || typeof parsed.query !== "string") {
+      return null;
+    }
+    return {
+      bundleId: typeof parsed.bundleId === "string" ? parsed.bundleId : event.targetId,
+      query: parsed.query,
+      scopes: Array.isArray(parsed.scopes) ? parsed.scopes : [],
+      kinds: Array.isArray(parsed.kinds) ? parsed.kinds : undefined,
+      memoryIds: parsed.memoryIds.filter((memoryId) => typeof memoryId === "string"),
+      scores: Array.isArray(parsed.scores) ? parsed.scores.filter((score) => typeof score === "number" && Number.isFinite(score)) : [],
+      tokenEstimate: typeof parsed.tokenEstimate === "number" ? parsed.tokenEstimate : 0,
+      agentRole: typeof parsed.agentRole === "string" ? parsed.agentRole : undefined,
+      runId: typeof parsed.runId === "string" ? parsed.runId : undefined,
+      timestamp: typeof parsed.timestamp === "string" ? parsed.timestamp : event.timestamp
+    };
+  } catch {
+    return null;
+  }
+}
 async function appendJsonl(filePath, value) {
   await mkdir9(path39.dirname(filePath), { recursive: true });
   await appendFile5(filePath, `${JSON.stringify(value)}
@@ -67965,6 +68223,7 @@ var init_local_jsonl_provider = __esm(() => {
   init_config3();
   init_curator_decision_helpers();
   init_errors6();
+  init_maintenance();
   init_schema2();
   init_scoring();
 });
@@ -68296,6 +68555,10 @@ class SQLiteMemoryProvider {
       redaction: {
         ...DEFAULT_MEMORY_CONFIG.redaction,
         ...config3.redaction ?? {}
+      },
+      maintenance: {
+        ...DEFAULT_MEMORY_CONFIG.maintenance,
+        ...config3.maintenance ?? {}
       }
     };
   }
@@ -68401,6 +68664,26 @@ class SQLiteMemoryProvider {
 			) VALUES (?, ?, ?, ?)`, [randomUUID5(), event.bundleId, event.timestamp, JSON.stringify(event)]);
     await this.event("recall", event.bundleId, JSON.stringify(event));
   }
+  async listRecallUsage(filter = {}) {
+    await this.initialize();
+    const rows = typeof filter.limit === "number" ? this.requireDb().query(`SELECT usage_json
+				FROM memory_recall_usage
+				ORDER BY timestamp DESC
+				LIMIT ?`).all(Math.max(1, Math.trunc(filter.limit))) : this.requireDb().query(`SELECT usage_json
+				FROM memory_recall_usage
+				ORDER BY timestamp DESC
+				`).all();
+    const events = [];
+    for (const row of rows) {
+      try {
+        const parsed = JSON.parse(row.usage_json);
+        if (Array.isArray(parsed.memoryIds) && typeof parsed.query === "string") {
+          events.push(parsed);
+        }
+      } catch {}
+    }
+    return events;
+  }
   async list(filter = {}) {
     await this.initialize();
     let records = Array.from(this.memories.values());
@@ -68419,7 +68702,9 @@ class SQLiteMemoryProvider {
         return !Number.isFinite(expires) || expires > now;
       });
     }
-    records = records.filter((record3) => !record3.supersededBy && record3.metadata.deleted !== true);
+    if (!filter.includeInactive) {
+      records = records.filter((record3) => !record3.supersededBy && record3.metadata.deleted !== true);
+    }
     records.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
     return records.slice(0, filter.limit ?? records.length);
   }
@@ -68500,6 +68785,52 @@ class SQLiteMemoryProvider {
       proposals: proposals.length
     };
   }
+  async compactMaintenance(options = {}) {
+    await this.initialize();
+    const now = options.now ? new Date(options.now) : new Date;
+    const kept = [];
+    const removeIds = [];
+    const result = {
+      dryRun: options.dryRun !== false,
+      removedDeleted: 0,
+      removedSuperseded: 0,
+      removedExpiredScratch: 0,
+      remaining: 0
+    };
+    for (const memory of this.memories.values()) {
+      const compactReason = shouldCompactMemory(memory, now);
+      if (compactReason === "deleted") {
+        result.removedDeleted++;
+        removeIds.push(memory.id);
+        continue;
+      }
+      if (compactReason === "superseded") {
+        result.removedSuperseded++;
+        removeIds.push(memory.id);
+        continue;
+      }
+      if (compactReason === "expired_scratch") {
+        result.removedExpiredScratch++;
+        removeIds.push(memory.id);
+        continue;
+      }
+      kept.push(memory);
+    }
+    result.remaining = kept.length;
+    if (result.dryRun)
+      return result;
+    const db = this.requireDb();
+    const compact = db.transaction(() => {
+      for (const id of removeIds) {
+        db.run("DELETE FROM memory_items WHERE id = ?", [id]);
+        this.deleteMemoryFts(id);
+      }
+      this.insertEvent("compact", "memory_items", "removed deleted, superseded, and expired scratch memories", JSON.stringify(result));
+    });
+    compact();
+    this.memories = new Map(kept.map((memory) => [memory.id, memory]));
+    return result;
+  }
   hasMigration(name2) {
     const row = this.requireDb().query("SELECT version, name FROM schema_migrations WHERE name = ? LIMIT 1").get(name2);
     return Boolean(row);
@@ -68976,6 +69307,7 @@ var init_sqlite_provider = __esm(() => {
   init_curator_decision_helpers();
   init_errors6();
   init_jsonl_migration();
+  init_maintenance();
   init_schema2();
   init_scoring();
   FTS_INDEX_COLUMNS = [
@@ -70391,6 +70723,7 @@ var init_memory = __esm(() => {
   init_injector();
   init_jsonl_migration();
   init_local_jsonl_provider();
+  init_maintenance();
   init_prompt_block();
   init_recall_planner();
   init_redaction();
@@ -70409,6 +70742,10 @@ async function handleMemoryCommand(_directory, _args) {
     "## Swarm Memory",
     "",
     "- `/swarm memory status` - show provider, SQLite path, JSONL files, and last migration report",
+    "- `/swarm memory pending` - show pending proposals and recent rejection reasons",
+    "- `/swarm memory recall-log` - summarize recall usage by agent role and memory ID",
+    "- `/swarm memory stale` - list expired scratch, superseded, deleted, and low-utility memories",
+    "- `/swarm memory compact` - dry-run compaction; pass `--confirm` to remove deleted, superseded, and expired scratch records",
     "- `/swarm memory export` - export current memory and proposals to `.swarm/memory/export/*.jsonl`",
     "- `/swarm memory import` - import `.swarm/memory/{memories,proposals}.jsonl` into SQLite",
     "- `/swarm memory migrate` - run the one-time legacy JSONL to SQLite migration",
@@ -70430,6 +70767,7 @@ async function handleMemoryStatusCommand(directory, _args) {
     `- Storage: \`${storageDir}\``,
     `- SQLite path: \`${sqlitePath}\``,
     `- SQLite database exists: \`${existsSync25(sqlitePath)}\``,
+    `- Automatic destructive cleanup: \`disabled\``,
     "",
     "### Legacy JSONL"
   ];
@@ -70454,6 +70792,119 @@ async function handleMemoryStatusCommand(directory, _args) {
   return lines.join(`
 `);
 }
+async function handleMemoryPendingCommand(directory, args2) {
+  const parsed = parseMaintenanceArgs(args2, {
+    usage: "Usage: /swarm memory pending [--limit <n>]",
+    allowConfirm: false
+  });
+  if ("error" in parsed)
+    return parsed.error;
+  const config3 = resolveCommandMemoryConfig(directory);
+  const provider = createMaintenanceProvider(directory, config3);
+  try {
+    await provider.initialize?.();
+    const report = await buildMemoryMaintenanceReport(provider, {
+      ...maintenanceReportOptions(config3, parsed.limit)
+    });
+    const lines = [
+      "## Swarm Memory Pending",
+      "",
+      `- Pending proposals shown: \`${report.pendingProposals.length}\``,
+      `- Rejected proposal reasons shown: \`${report.rejectedProposalReasons.length}\``
+    ];
+    appendProposalLines(lines, "Pending proposals", report.pendingProposals);
+    appendProposalLines(lines, "Rejected proposal reasons", report.rejectedProposalReasons);
+    return lines.join(`
+`);
+  } finally {
+    await provider.close?.();
+  }
+}
+async function handleMemoryRecallLogCommand(directory, args2) {
+  const parsed = parseMaintenanceArgs(args2, {
+    usage: "Usage: /swarm memory recall-log [--limit <n>]",
+    allowConfirm: false
+  });
+  if ("error" in parsed)
+    return parsed.error;
+  const config3 = resolveCommandMemoryConfig(directory);
+  const provider = createMaintenanceProvider(directory, config3);
+  try {
+    await provider.initialize?.();
+    const report = await buildMemoryMaintenanceReport(provider, {
+      ...maintenanceReportOptions(config3, parsed.limit)
+    });
+    const lines = [
+      "## Swarm Memory Recall Log",
+      "",
+      `- Recall events scanned: \`${report.recallEventCount}\``,
+      `- Most-recalled memories shown: \`${report.mostRecalledMemories.length}\``,
+      `- Never-recalled memories shown: \`${report.neverRecalledMemories.length}\``
+    ];
+    appendRecallRoleLines(lines, report.recallByAgentRole);
+    appendRecallMemoryLines(lines, report.mostRecalledMemories);
+    appendMemoryLines(lines, "Never-recalled memories", report.neverRecalledMemories);
+    return lines.join(`
+`);
+  } finally {
+    await provider.close?.();
+  }
+}
+async function handleMemoryStaleCommand(directory, args2) {
+  const parsed = parseMaintenanceArgs(args2, {
+    usage: "Usage: /swarm memory stale [--limit <n>]",
+    allowConfirm: false
+  });
+  if ("error" in parsed)
+    return parsed.error;
+  const config3 = resolveCommandMemoryConfig(directory);
+  const provider = createMaintenanceProvider(directory, config3);
+  try {
+    await provider.initialize?.();
+    const report = await buildMemoryMaintenanceReport(provider, {
+      ...maintenanceReportOptions(config3, parsed.limit)
+    });
+    const lines = [
+      "## Swarm Memory Stale",
+      "",
+      `- Active memories: \`${report.activeMemories}\``,
+      `- Expired scratch memories shown: \`${report.expiredScratchMemories.length}\``,
+      `- Deleted tombstones shown: \`${report.deletedMemories.length}\``,
+      `- Superseded memories shown: \`${report.supersededMemories.length}\``,
+      `- Low-utility memories shown: \`${report.lowUtilityMemories.length}\``
+    ];
+    appendMemoryLines(lines, "Expired scratch memories", report.expiredScratchMemories);
+    appendMemoryLines(lines, "Deleted tombstones", report.deletedMemories);
+    appendSupersededChains(lines, report);
+    appendMemoryLines(lines, "Low-utility memories", report.lowUtilityMemories);
+    return lines.join(`
+`);
+  } finally {
+    await provider.close?.();
+  }
+}
+async function handleMemoryCompactCommand(directory, args2) {
+  const parsed = parseMaintenanceArgs(args2, {
+    usage: "Usage: /swarm memory compact [--confirm]",
+    allowConfirm: true,
+    allowLimit: false
+  });
+  if ("error" in parsed)
+    return parsed.error;
+  const provider = createMaintenanceProvider(directory, resolveCommandMemoryConfig(directory));
+  try {
+    await provider.initialize?.();
+    if (!provider.compactMaintenance) {
+      return "Memory provider does not support compaction.";
+    }
+    const result = await provider.compactMaintenance({
+      dryRun: !parsed.confirm
+    });
+    return formatCompactResult(result, parsed.confirm);
+  } finally {
+    await provider.close?.();
+  }
+}
 async function handleMemoryMigrateCommand(directory, _args) {
   const config3 = {
     ...resolveCommandMemoryConfig(directory),
@@ -70510,6 +70961,16 @@ async function handleMemoryExportCommand(directory, _args) {
     await provider.close?.();
   }
 }
+function createMaintenanceProvider(directory, config3) {
+  return createConfiguredMemoryProvider(directory, config3);
+}
+function maintenanceReportOptions(config3, limit) {
+  return {
+    limit,
+    lowUtilityMaxConfidence: config3.maintenance.lowUtilityMaxConfidence,
+    lowUtilityMinAgeDays: config3.maintenance.lowUtilityMinAgeDays
+  };
+}
 async function handleMemoryEvaluateCommand(directory, args2) {
   const parsed = parseEvaluateArgs(directory, args2);
   if ("error" in parsed)
@@ -70568,6 +71029,28 @@ function parseEvaluateArgs(directory, args2) {
   }
   return { json: json3, fixtureDirectory };
 }
+function parseMaintenanceArgs(args2, options) {
+  let limit = 20;
+  let confirm = false;
+  const allowLimit = options.allowLimit ?? true;
+  for (let i2 = 0;i2 < args2.length; i2++) {
+    const arg = args2[i2];
+    if (arg === "--confirm" && options.allowConfirm) {
+      confirm = true;
+      continue;
+    }
+    if (arg === "--limit" && allowLimit) {
+      const next = args2[i2 + 1];
+      if (!next || !/^\d+$/.test(next))
+        return { error: options.usage };
+      limit = Math.min(100, Math.max(1, Number(next)));
+      i2++;
+      continue;
+    }
+    return { error: options.usage };
+  }
+  return { limit, confirm };
+}
 function resolvePackageRootFromModule(modulePath) {
   const moduleDir = path45.dirname(modulePath);
   const leaf = path45.basename(moduleDir);
@@ -70618,6 +71101,80 @@ function appendInvalidRows(lines, invalidRows) {
     lines.push(`- ... ${invalidRows.length - 20} more`);
   }
 }
+function appendProposalLines(lines, title, proposals) {
+  lines.push("", `### ${title}`);
+  if (proposals.length === 0) {
+    lines.push("- none");
+    return;
+  }
+  for (const proposal of proposals) {
+    const reason = proposal.status === "rejected" ? ` - ${proposal.rejectionReason ?? "no reason recorded"}` : "";
+    lines.push(`- \`${proposal.id}\` ${proposal.operation} ${proposal.targetMemoryId ?? proposal.proposedRecord?.id ?? "new"} (${proposal.status})${reason}`);
+  }
+}
+function appendMemoryLines(lines, title, memories) {
+  lines.push("", `### ${title}`);
+  if (memories.length === 0) {
+    lines.push("- none");
+    return;
+  }
+  for (const memory of memories) {
+    lines.push(`- \`${memory.id}\` ${memory.kind} confidence=${memory.confidence.toFixed(2)} updated=${memory.updatedAt} - ${truncate(memory.text, 100)}`);
+  }
+}
+function appendRecallRoleLines(lines, roles) {
+  lines.push("", "### Recall by agent role");
+  if (roles.length === 0) {
+    lines.push("- none");
+    return;
+  }
+  for (const role of roles) {
+    const memoryCount = Object.keys(role.memoryIds).length;
+    lines.push(`- \`${role.agentRole}\`: ${role.count} recall event(s), ${memoryCount} memory ID(s)`);
+  }
+}
+function appendRecallMemoryLines(lines, memories) {
+  lines.push("", "### Most-recalled memories");
+  if (memories.length === 0) {
+    lines.push("- none");
+    return;
+  }
+  for (const memory of memories) {
+    lines.push(`- \`${memory.memoryId}\`: ${memory.count} hit(s), last=${memory.lastRecalledAt}, avgScore=${memory.averageScore.toFixed(3)}`);
+  }
+}
+function appendSupersededChains(lines, report) {
+  lines.push("", "### Superseded chains");
+  if (report.supersededChains.length === 0) {
+    lines.push("- none");
+    return;
+  }
+  for (const chain of report.supersededChains) {
+    const reason = chain.reason ? ` - ${chain.reason}` : "";
+    lines.push(`- ${chain.chain.map((id) => `\`${id}\``).join(" -> ")}${reason}`);
+  }
+}
+function formatCompactResult(result, confirmed) {
+  const lines = [
+    "## Swarm Memory Compact",
+    "",
+    `- Mode: \`${confirmed ? "confirmed" : "dry-run"}\``,
+    `- Deleted tombstones: \`${result.removedDeleted}\``,
+    `- Superseded records: \`${result.removedSuperseded}\``,
+    `- Expired scratch records: \`${result.removedExpiredScratch}\``,
+    `- Remaining memories: \`${result.remaining}\``
+  ];
+  if (!confirmed) {
+    lines.push("", "No records were removed. Re-run `/swarm memory compact --confirm` to apply this compaction.");
+  }
+  return lines.join(`
+`);
+}
+function truncate(value, maxLength) {
+  if (value.length <= maxLength)
+    return value;
+  return `${value.slice(0, maxLength - 3)}...`;
+}
 var PACKAGE_ROOT;
 var init_memory2 = __esm(() => {
   init_loader();
@@ -79002,7 +79559,7 @@ function classifySwarmCommandToolUse(resolved) {
       return { allowed: true };
     return {
       allowed: false,
-      message: "Use `/swarm memory status`, `/swarm memory export`, or `/swarm memory evaluate --json` through swarm_command. Memory import and migrate are intentionally excluded from chat-tool execution."
+      message: "Use `/swarm memory status`, `/swarm memory pending`, `/swarm memory recall-log`, `/swarm memory stale`, `/swarm memory export`, or `/swarm memory evaluate --json` through swarm_command. Memory import, migrate, and compact are intentionally excluded from chat-tool execution."
     };
   }
   if (canonicalKey === "memory evaluate") {
@@ -79015,6 +79572,17 @@ function classifySwarmCommandToolUse(resolved) {
       message: "Usage through swarm_command: `/swarm memory evaluate --json`. Custom fixture directories are only available through direct user command execution."
     };
   }
+  if (canonicalKey === "memory pending" || canonicalKey === "memory recall-log" || canonicalKey === "memory stale") {
+    if (args2.length === 0)
+      return { allowed: true };
+    if (args2.length === 2 && args2[0] === "--limit" && /^\d+$/.test(args2[1])) {
+      return { allowed: true };
+    }
+    return {
+      allowed: false,
+      message: `Usage through swarm_command: \`/swarm ${canonicalKey}\` or ` + `\`/swarm ${canonicalKey} --limit <n>\`.`
+    };
+  }
   if (canonicalKey === "retrieve") {
     if (args2.length !== 1 || !SUMMARY_ID_PATTERN.test(args2[0])) {
       return {
@@ -79066,7 +79634,7 @@ function classifySwarmCommandChatFallbackUse(resolved) {
       message: "/swarm config doctor --fix is not available through chat fallback because it can modify configuration files. Run the CLI command directly when you intend to apply fixes."
     };
   }
-  if (canonicalKey === "knowledge migrate" || canonicalKey === "knowledge quarantine" || canonicalKey === "knowledge restore" || canonicalKey === "memory import" || canonicalKey === "memory migrate") {
+  if (canonicalKey === "knowledge migrate" || canonicalKey === "knowledge quarantine" || canonicalKey === "knowledge restore" || canonicalKey === "memory import" || canonicalKey === "memory migrate" || canonicalKey === "memory compact") {
     return {
       allowed: false,
       message: `/swarm ${canonicalKey} is not available through chat fallback because it mutates .swarm state. ` + "Run the CLI command directly after confirming the intended state change."
@@ -79099,6 +79667,10 @@ var init_tool_policy = __esm(() => {
     "knowledge",
     "memory",
     "memory status",
+    "memory pending",
+    "memory recall-log",
+    "memory compact",
+    "memory stale",
     "memory export",
     "memory evaluate",
     "memory import",
@@ -79125,6 +79697,9 @@ var init_tool_policy = __esm(() => {
     "knowledge",
     "memory",
     "memory status",
+    "memory pending",
+    "memory recall-log",
+    "memory stale",
     "memory export",
     "memory evaluate",
     "sync-plan",
@@ -79137,7 +79712,8 @@ var init_tool_policy = __esm(() => {
     "rollback",
     "checkpoint",
     "memory import",
-    "memory migrate"
+    "memory migrate",
+    "memory compact"
   ]);
   NO_ARGS = new Set([
     "agents",
@@ -80132,6 +80708,34 @@ Subcommands:
       args: "",
       category: "diagnostics"
     },
+    "memory pending": {
+      handler: (ctx) => handleMemoryPendingCommand(ctx.directory, ctx.args),
+      description: "Show pending Swarm memory proposals and rejection reasons",
+      subcommandOf: "memory",
+      args: "--limit <n>",
+      category: "diagnostics"
+    },
+    "memory recall-log": {
+      handler: (ctx) => handleMemoryRecallLogCommand(ctx.directory, ctx.args),
+      description: "Summarize Swarm memory recall usage",
+      subcommandOf: "memory",
+      args: "--limit <n>",
+      category: "diagnostics"
+    },
+    "memory compact": {
+      handler: (ctx) => handleMemoryCompactCommand(ctx.directory, ctx.args),
+      description: "Compact deleted, superseded, and expired scratch memories",
+      subcommandOf: "memory",
+      args: "--confirm",
+      category: "utility"
+    },
+    "memory stale": {
+      handler: (ctx) => handleMemoryStaleCommand(ctx.directory, ctx.args),
+      description: "List stale and low-utility Swarm memories",
+      subcommandOf: "memory",
+      args: "--limit <n>",
+      category: "diagnostics"
+    },
     "memory export": {
       handler: (ctx) => handleMemoryExportCommand(ctx.directory, ctx.args),
       description: "Export current Swarm memory to JSONL files",