@gethmy/mcp 2.3.2 → 2.3.4

package/src/memory-cleanup.ts

@@ -49,6 +49,43 @@ export interface CleanupOptions {
   orphanAgeDays?: 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 {
   staleDraftsFound: number;
   pruned: number;
@@ -654,3 +691,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,7 @@ import {
 } from "./context-assembly.js";
 import { autoExpandGraph } from "./graph-expansion.js";
 import { runLifecycleMaintenance } from "./lifecycle-maintenance.js";
-import { runMemoryCleanup } from "./memory-cleanup.js";
+import { runMemoryCleanup, purgeMemories, type PurgeFilters } from "./memory-cleanup.js";
 import { onboardNewUser } from "./onboard.js";
 import type { PromptVariant } from "./prompt-builder.js";
 
@@ -721,6 +721,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"],
     },
@@ -1683,6 +1699,60 @@ const TOOLS = {
       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: [],
+    },
+  },
 };
 
 // Resource URIs
@@ -2643,18 +2713,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;
       }
 
@@ -4056,6 +4134,50 @@ 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 +4231,7 @@ export class HarmonyMCPServer {
     );
 
     // Graceful shutdown: end all auto-sessions
+    let exitCode = 0;
     const handleShutdown = async () => {
       try {
         await shutdownAllSessions();
@@ -4116,10 +4239,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 {