@gethmy/mcp 2.3.3 → 2.4.0

package/src/memory-cleanup.ts

@@ -15,6 +15,7 @@ import {
   consolidateMemories,
 } from "./consolidation.js";
 import { findSimilarEntities } from "./graph-expansion.js";
+import { type AuditReport, runMemoryAudit } from "./memory-audit.js";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -39,7 +40,8 @@ export type CleanupStep =
   | "consolidate"
   | "orphans"
   | "duplicates"
-  | "backfill";
+  | "backfill"
+  | "audit";
 
 export interface CleanupOptions {
   dryRun?: boolean;
@@ -47,6 +49,45 @@ export interface CleanupOptions {
   maxAgeDays?: number;
   minClusterSize?: number;
   orphanAgeDays?: number;
+  auditArchiveBelow?: number;
+  auditDeleteBelow?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Purge types
+// ---------------------------------------------------------------------------
+
+export interface PurgeFilters {
+  tier?: "draft" | "episode" | "reference";
+  scope?: string;
+  type?: string;
+  olderThanDays?: number;
+  maxConfidence?: number;
+  tags?: string[];
+}
+
+export interface PurgeOptions {
+  dryRun?: boolean;
+  filters: PurgeFilters;
+}
+
+export interface PurgeReport {
+  success: boolean;
+  dryRun: boolean;
+  timestamp: string;
+  workspace: { id: string; projectId: string };
+  filters: PurgeFilters;
+  matched: number;
+  purged: number;
+  items: Array<{
+    id: string;
+    title: string;
+    type: string;
+    tier: string;
+    confidence: number;
+    ageDays: number;
+  }>;
+  errors: Array<{ entityId: string; message: string }>;
 }
 
 interface PruneStepResult {
@@ -98,6 +139,15 @@ interface BackfillStepResult {
   errors: Array<{ entity_id: string; error: string }>;
 }
 
+interface AuditStepResult {
+  scanned: number;
+  legacyCount: number;
+  buckets: { keep: number; review: number; archive: number; delete: number };
+  actions: { flaggedReview: number; archived: number; deleted: number };
+  lowestScore: number | null;
+  report: AuditReport;
+}
+
 export interface CleanupReport {
   success: boolean;
   dryRun: boolean;
@@ -116,6 +166,7 @@ export interface CleanupReport {
     orphans?: OrphanStepResult;
     duplicates?: DuplicateStepResult;
     backfill?: BackfillStepResult;
+    audit?: AuditStepResult;
   };
 
   errors: Array<{ step: string; message: string }>;
@@ -128,6 +179,7 @@ const ALL_STEPS: CleanupStep[] = [
   "orphans",
   "duplicates",
   "backfill",
+  "audit",
 ];
 
 const MS_PER_DAY = 1000 * 60 * 60 * 24;
@@ -322,6 +374,55 @@ export async function runMemoryCleanup(
     }
   }
 
+  // Stage 6: Quality audit — rate every entity against modern standards
+  if (steps.includes("audit")) {
+    try {
+      const auditReport = await runMemoryAudit(client, workspaceId, projectId, {
+        dryRun,
+        archiveBelow: options?.auditArchiveBelow,
+        deleteBelow: options?.auditDeleteBelow,
+      });
+      const low =
+        auditReport.lowest.length > 0 ? auditReport.lowest[0].score : null;
+      report.steps.audit = {
+        scanned: auditReport.summary.scanned,
+        legacyCount: auditReport.summary.legacyCount,
+        buckets: {
+          keep: auditReport.summary.keep,
+          review: auditReport.summary.review,
+          archive: auditReport.summary.archive,
+          delete: auditReport.summary.delete,
+        },
+        actions: auditReport.actionsTaken,
+        lowestScore: low,
+        report: auditReport,
+      };
+      report.summary.issuesFound +=
+        auditReport.summary.review +
+        auditReport.summary.archive +
+        auditReport.summary.delete;
+      if (!dryRun) {
+        report.summary.actionsTaken +=
+          auditReport.actionsTaken.flaggedReview +
+          auditReport.actionsTaken.archived +
+          auditReport.actionsTaken.deleted;
+      }
+      for (const err of auditReport.errors) {
+        report.errors.push({
+          step: `audit:${err.step}`,
+          message: err.entityId
+            ? `${err.entityId}: ${err.message}`
+            : err.message,
+        });
+      }
+    } catch (err) {
+      report.errors.push({
+        step: "audit",
+        message: (err as Error).message,
+      });
+    }
+  }
+
   report.healthReport = generateHealthReport(report);
   return report;
 }
@@ -639,6 +740,30 @@ function generateHealthReport(report: CleanupReport): string {
     }
   }
 
+  // Audit
+  if (report.steps.audit) {
+    const a = report.steps.audit;
+    lines.push("## Quality Audit");
+    lines.push(
+      `Scanned ${a.scanned} entities. Legacy signals on ${a.legacyCount}.`,
+    );
+    lines.push(
+      `Buckets — keep: ${a.buckets.keep}, review: ${a.buckets.review}, archive: ${a.buckets.archive}, delete: ${a.buckets.delete}.`,
+    );
+    if (!report.dryRun) {
+      lines.push(
+        `Actions — flagged: ${a.actions.flaggedReview}, archived: ${a.actions.archived}, deleted: ${a.actions.deleted}.`,
+      );
+    }
+    if (a.report.lowest.length > 0) {
+      const worst = a.report.lowest[0];
+      lines.push(
+        `Lowest score: **${worst.score}** — "${worst.title}" (${worst.reasons.slice(0, 2).join(", ") || "—"}).`,
+      );
+    }
+    lines.push("");
+  }
+
   // Errors
   if (report.errors.length > 0) {
     lines.push("## Errors");
@@ -654,3 +779,124 @@ function generateHealthReport(report: CleanupReport): string {
 
   return lines.join("\n");
 }
+
+// ---------------------------------------------------------------------------
+// Purge — filtered bulk deletion
+// ---------------------------------------------------------------------------
+
+export async function purgeMemories(
+  client: HarmonyApiClient,
+  workspaceId: string,
+  projectId: string,
+  options: PurgeOptions,
+): Promise<PurgeReport> {
+  const dryRun = options.dryRun !== false;
+  const { filters } = options;
+
+  // Safety: require at least one narrowing filter
+  const hasFilter =
+    filters.tier ||
+    filters.scope ||
+    filters.type ||
+    filters.olderThanDays !== undefined ||
+    filters.maxConfidence !== undefined ||
+    (filters.tags && filters.tags.length > 0);
+
+  if (!hasFilter) {
+    throw new Error(
+      "At least one narrowing filter (tier, scope, type, olderThanDays, maxConfidence, tags) is required.",
+    );
+  }
+
+  // Paginate through all matching entities
+  const allMatches: MemoryEntity[] = [];
+  let offset = 0;
+  const pageSize = 100;
+  const now = Date.now();
+
+  while (true) {
+    const result = await client.listMemoryEntities({
+      workspace_id: workspaceId,
+      project_id: projectId,
+      type: filters.type,
+      scope: filters.scope,
+      tags: filters.tags,
+      limit: pageSize,
+      offset,
+    });
+
+    const entities = (result.entities || []) as MemoryEntity[];
+    if (entities.length === 0) break;
+
+    // Client-side filtering for fields the API doesn't support natively
+    for (const entity of entities) {
+      if (filters.tier && entity.memory_tier !== filters.tier) continue;
+      if (
+        filters.maxConfidence !== undefined &&
+        entity.confidence > filters.maxConfidence
+      )
+        continue;
+      if (filters.olderThanDays !== undefined) {
+        const ref = entity.last_accessed_at || entity.created_at;
+        const ageDays = (now - new Date(ref).getTime()) / MS_PER_DAY;
+        if (ageDays < filters.olderThanDays) continue;
+      }
+      allMatches.push(entity);
+    }
+
+    if (entities.length < pageSize) break;
+    offset += pageSize;
+  }
+
+  // Build preview items
+  const items = allMatches.map((e) => ({
+    id: e.id,
+    title: e.title,
+    type: e.type,
+    tier: e.memory_tier,
+    confidence: e.confidence,
+    ageDays: Math.round(
+      (now - new Date(e.last_accessed_at || e.created_at).getTime()) /
+        MS_PER_DAY,
+    ),
+  }));
+
+  // Execute deletions if not dry-run
+  const errors: Array<{ entityId: string; message: string }> = [];
+  let purged = 0;
+
+  if (!dryRun) {
+    // Delete in batches to avoid overwhelming the API
+    for (let i = 0; i < allMatches.length; i += CONCURRENCY_LIMIT) {
+      const batch = allMatches.slice(i, i + CONCURRENCY_LIMIT);
+      const results = await Promise.allSettled(
+        batch.map((e) => client.deleteMemoryEntity(e.id)),
+      );
+      for (let j = 0; j < results.length; j++) {
+        if (results[j].status === "fulfilled") {
+          purged++;
+        } else {
+          errors.push({
+            entityId: batch[j].id,
+            message:
+              results[j].status === "rejected"
+                ? String((results[j] as PromiseRejectedResult).reason)
+                : "Unknown error",
+          });
+        }
+      }
+    }
+  }
+
+  return {
+    success: errors.length === 0,
+    dryRun,
+    timestamp: new Date().toISOString(),
+    workspace: { id: workspaceId, projectId },
+    filters,
+    matched: allMatches.length,
+    purged: dryRun ? 0 : purged,
+    items,
+    errors,
+  };
+}

package/src/server.ts

@@ -58,7 +58,12 @@ import {
 } from "./context-assembly.js";
 import { autoExpandGraph } from "./graph-expansion.js";
 import { runLifecycleMaintenance } from "./lifecycle-maintenance.js";
-import { runMemoryCleanup } from "./memory-cleanup.js";
+import { runMemoryAudit } from "./memory-audit.js";
+import {
+  type PurgeFilters,
+  purgeMemories,
+  runMemoryCleanup,
+} from "./memory-cleanup.js";
 import { onboardNewUser } from "./onboard.js";
 import type { PromptVariant } from "./prompt-builder.js";
 
@@ -721,6 +726,22 @@ const TOOLS = {
           type: "number",
           description: "Updated time estimate",
         },
+        actions: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              description: {
+                type: "string",
+                description:
+                  "What was done, e.g. 'Edited CardDetailSheet.tsx — added done toggle'",
+              },
+            },
+            required: ["description"],
+          },
+          description:
+            "Actions performed since last update. Each becomes a visible activity log entry.",
+        },
       },
       required: ["cardId", "agentIdentifier", "agentName"],
     },
@@ -1641,7 +1662,7 @@ const TOOLS = {
 
   harmony_cleanup_memories: {
     description:
-      "Run a unified memory cleanup: prune stale drafts, consolidate similar memories, detect orphans and duplicates, and backfill embeddings. Returns a health report. Dry-run by default — run with dryRun=false to execute.",
+      "Run a unified memory cleanup: prune stale drafts, consolidate similar memories, detect orphans and duplicates, backfill embeddings, and optionally run a quality audit. Returns a health report. Dry-run by default — run with dryRun=false to execute.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1662,10 +1683,17 @@ const TOOLS = {
           type: "array",
           items: {
             type: "string",
-            enum: ["prune", "consolidate", "orphans", "duplicates", "backfill"],
+            enum: [
+              "prune",
+              "consolidate",
+              "orphans",
+              "duplicates",
+              "backfill",
+              "audit",
+            ],
           },
           description:
-            "Which cleanup steps to run (default: all). Options: prune, consolidate, orphans, duplicates, backfill.",
+            "Which cleanup steps to run (default: all). Options: prune, consolidate, orphans, duplicates, backfill, audit.",
         },
         maxAgeDays: {
           type: "number",
@@ -1679,6 +1707,106 @@ const TOOLS = {
           type: "number",
           description: "Min age in days for orphan detection (default: 14)",
         },
+        auditArchiveBelow: {
+          type: "number",
+          description: "Audit: archive entities scoring below this (default: 40)",
+        },
+        auditDeleteBelow: {
+          type: "number",
+          description: "Audit: delete entities scoring below this (default: 20)",
+        },
+      },
+      required: [],
+    },
+  },
+  harmony_audit_memories: {
+    description:
+      "Rate every memory against state-of-the-art quality standards (confidence, decay, structural completeness, content, tier-age fit, access). Flags legacy entities from before recent optimizations (default confidence, missing embeddings, stuck drafts). Buckets: keep (≥70), review (40-69), archive (20-39), delete (<20). Dry-run by default.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspaceId: {
+          type: "string",
+          description: "Workspace ID (optional if context set)",
+        },
+        projectId: {
+          type: "string",
+          description: "Project ID (optional)",
+        },
+        dryRun: {
+          type: "boolean",
+          description:
+            "Preview audit without flagging/archiving/deleting (default: true)",
+        },
+        archiveBelow: {
+          type: "number",
+          description:
+            "Score threshold below which entities are archived (confidence set to 0.25). Default: 40",
+        },
+        deleteBelow: {
+          type: "number",
+          description:
+            "Score threshold below which entities are hard-deleted. Default: 20. Set to 0 to never delete.",
+        },
+        limit: {
+          type: "number",
+          description:
+            "Max number of entities to audit (default: 500). Paginated fetch.",
+        },
+      },
+      required: [],
+    },
+  },
+  harmony_purge_memories: {
+    description:
+      "Bulk-delete memory entities matching filters within a project. Requires at least one narrowing filter (tier, scope, type, olderThanDays, maxConfidence, tags). Dry-run by default — preview what would be deleted before executing.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspaceId: {
+          type: "string",
+          description: "Workspace ID (optional if context set)",
+        },
+        projectId: {
+          type: "string",
+          description:
+            "Project ID (required — purge is project-scoped). Falls back to active project context.",
+        },
+        dryRun: {
+          type: "boolean",
+          description:
+            "Preview what would be deleted without executing (default: true)",
+        },
+        tier: {
+          type: "string",
+          enum: ["draft", "episode", "reference"],
+          description: 'Filter by memory tier (e.g. "draft")',
+        },
+        scope: {
+          type: "string",
+          description:
+            'Filter by scope (e.g. "private", "project", "workspace")',
+        },
+        type: {
+          type: "string",
+          description:
+            'Filter by entity type (e.g. "error", "pattern", "lesson", "decision")',
+        },
+        olderThanDays: {
+          type: "number",
+          description:
+            "Only include entities not accessed in at least this many days",
+        },
+        maxConfidence: {
+          type: "number",
+          description:
+            "Only include entities with confidence at or below this value (e.g. 0.3 for low-confidence junk)",
+        },
+        tags: {
+          type: "array",
+          items: { type: "string" },
+          description: "Only include entities matching these tags",
+        },
       },
       required: [],
     },
@@ -2643,18 +2771,26 @@ async function handleToolCall(
         args.progressPercent !== undefined
           ? z.number().min(0).max(100).parse(args.progressPercent)
           : undefined;
-      // Merge any pending memory actions into the progress update
-      const callerRecentActions = args.recentActions as
-        | { action: string; ts: string }[]
+      // Convert actions parameter to recentActions format and merge with memory actions
+      const callerActions = args.actions as
+        | { description: string }[]
         | undefined;
+      const now = new Date().toISOString();
+      const callerRecentActions: { action: string; ts: string }[] = [
+        ...((args.recentActions as { action: string; ts: string }[]) || []),
+        ...(callerActions || []).map((a) => ({
+          action: a.description,
+          ts: now,
+        })),
+      ];
       const memSession = getMemorySession(cardId);
       let mergedRecentActions: { action: string; ts: string }[] | undefined;
       if (memSession?.dirty) {
         mergedRecentActions = mergeMemoryActionsInto(
           cardId,
-          callerRecentActions || [],
+          callerRecentActions,
         );
-      } else if (callerRecentActions) {
+      } else if (callerRecentActions.length > 0) {
         mergedRecentActions = callerRecentActions;
       }
 
@@ -4013,6 +4149,37 @@ async function handleToolCall(
       };
     }
 
+    case "harmony_audit_memories": {
+      const workspaceId =
+        (args.workspaceId as string) || deps.getActiveWorkspaceId();
+      if (!workspaceId) {
+        throw new Error(
+          "No workspace specified. Use harmony_set_workspace_context or provide workspaceId.",
+        );
+      }
+      const projectId =
+        (args.projectId as string) || deps.getActiveProjectId() || undefined;
+
+      const report = await runMemoryAudit(client, workspaceId, projectId, {
+        dryRun: args.dryRun as boolean | undefined,
+        archiveBelow: args.archiveBelow as number | undefined,
+        deleteBelow: args.deleteBelow as number | undefined,
+        limit: args.limit as number | undefined,
+      });
+
+      return {
+        success: report.success,
+        dryRun: report.dryRun,
+        summary: report.summary,
+        distribution: report.distribution,
+        legacyBreakdown: report.legacyBreakdown,
+        actionsTaken: report.actionsTaken,
+        lowest: report.lowest,
+        errors: report.errors,
+        healthReport: report.healthReport,
+      };
+    }
+
     case "harmony_cleanup_memories": {
       const workspaceId =
         (args.workspaceId as string) || deps.getActiveWorkspaceId();
@@ -4030,6 +4197,7 @@ async function handleToolCall(
         "orphans",
         "duplicates",
         "backfill",
+        "audit",
       ];
       const rawSteps = args.steps as string[] | undefined;
       const steps = rawSteps?.filter((s) => validSteps.includes(s));
@@ -4041,10 +4209,14 @@ async function handleToolCall(
 
       const report = await runMemoryCleanup(client, workspaceId, projectId, {
         dryRun: args.dryRun as boolean | undefined,
-        steps,
+        steps: steps as
+          | ("prune" | "consolidate" | "orphans" | "duplicates" | "backfill" | "audit")[]
+          | undefined,
         maxAgeDays: args.maxAgeDays as number | undefined,
         minClusterSize: args.minClusterSize as number | undefined,
         orphanAgeDays: args.orphanAgeDays as number | undefined,
+        auditArchiveBelow: args.auditArchiveBelow as number | undefined,
+        auditDeleteBelow: args.auditDeleteBelow as number | undefined,
       });
 
       return {
@@ -4056,6 +4228,49 @@ async function handleToolCall(
       };
     }
 
+    case "harmony_purge_memories": {
+      const workspaceId =
+        (args.workspaceId as string) || deps.getActiveWorkspaceId();
+      if (!workspaceId) {
+        throw new Error(
+          "No workspace specified. Use harmony_set_workspace_context or provide workspaceId.",
+        );
+      }
+      const projectId = (args.projectId as string) || deps.getActiveProjectId();
+      if (!projectId) {
+        throw new Error(
+          "No project specified. Purge requires a project scope. Use harmony_set_project_context or provide projectId.",
+        );
+      }
+
+      const filters: PurgeFilters = {};
+      if (args.tier) filters.tier = args.tier as PurgeFilters["tier"];
+      if (args.scope) filters.scope = args.scope as string;
+      if (args.type) filters.type = args.type as string;
+      if (args.olderThanDays !== undefined)
+        filters.olderThanDays = args.olderThanDays as number;
+      if (args.maxConfidence !== undefined)
+        filters.maxConfidence = args.maxConfidence as number;
+      if (args.tags) filters.tags = args.tags as string[];
+
+      const report = await purgeMemories(client, workspaceId, projectId, {
+        dryRun: args.dryRun as boolean | undefined,
+        filters,
+      });
+
+      return {
+        success: report.success,
+        dryRun: report.dryRun,
+        matched: report.matched,
+        purged: report.purged,
+        items: report.items,
+        errors: report.errors,
+        message: report.dryRun
+          ? `Found ${report.matched} entities matching filters. Run with dryRun=false to delete.`
+          : `Purged ${report.purged} of ${report.matched} matching entities.`,
+      };
+    }
+
     default:
       throw new Error(`Unknown tool: ${name}`);
   }
@@ -4109,6 +4324,7 @@ export class HarmonyMCPServer {
     );
 
     // Graceful shutdown: end all auto-sessions
+    let exitCode = 0;
     const handleShutdown = async () => {
       try {
         await shutdownAllSessions();
@@ -4116,10 +4332,20 @@ export class HarmonyMCPServer {
         // Best-effort
       }
       destroyAutoSession();
-      process.exit(0);
+      process.exit(exitCode);
     };
     process.on("SIGINT", handleShutdown);
     process.on("SIGTERM", handleShutdown);
+    process.on("uncaughtException", (err) => {
+      console.error("MCP server uncaught exception:", err);
+      exitCode = 1;
+      handleShutdown();
+    });
+    process.on("unhandledRejection", (reason) => {
+      console.error("MCP server unhandled rejection:", reason);
+      exitCode = 1;
+      handleShutdown();
+    });
 
     // Attempt startup sync (non-blocking, best-effort)
     try {