@gethmy/mcp 2.2.4 → 2.3.0

package/dist/index.js

@@ -7078,6 +7078,29 @@ __export(exports_context_assembly, {
 function estimateTokens(text) {
   return Math.ceil(text.length / 4);
 }
+function passesQualityGate(entity) {
+  const content = entity.content.trim();
+  if (content.length < 50)
+    return false;
+  const normalizedTitle = entity.title.toLowerCase().replace(/[^a-z0-9\s]/g, "").trim();
+  const normalizedContent = content.toLowerCase().replace(/[^a-z0-9\s]/g, "").trim();
+  if (normalizedContent.length < normalizedTitle.length * 1.5) {
+    return false;
+  }
+  if (entity.type === "pattern" && /recurring .+ \(\d+ instances\)/i.test(entity.title)) {
+    const lines = content.split(`
+`).filter((l) => l.trim().length > 0);
+    const bulletLines = lines.filter((l) => l.trim().startsWith("- "));
+    if (bulletLines.length > lines.length * 0.6)
+      return false;
+  }
+  if (entity.type === "procedure") {
+    const stepCount = (content.match(/^\d+\.\s/gm) || []).length;
+    if (stepCount < 3)
+      return false;
+  }
+  return true;
+}
 function generateAssemblyId() {
   return `ctx_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
 }
@@ -7337,7 +7360,27 @@ async function assembleContext(options) {
       memories: []
     };
   }
-  const scored = candidates.map((entity) => {
+  const qualityCandidates = candidates.filter((entity) => {
+    if (passesQualityGate(entity))
+      return true;
+    manifest.excluded.push({
+      entityId: entity.id,
+      title: entity.title,
+      type: entity.type,
+      tier: entity.memory_tier,
+      relevanceScore: 0,
+      reason: "failed_quality_gate"
+    });
+    return false;
+  });
+  if (qualityCandidates.length === 0) {
+    return {
+      context: "",
+      manifest,
+      memories: []
+    };
+  }
+  const scored = qualityCandidates.map((entity) => {
     const { score, reasons } = computeRelevanceScore(entity, taskContext, cardLabels, graphRelations.length > 0 ? graphRelations : undefined);
     return { entity, score, reasons };
   });
@@ -7674,7 +7717,7 @@ async function recordContextFeedback(client2, cardId, sessionStatus, progressPer
   sessionAssemblyMap.delete(cardId);
   return { adjusted };
 }
-var DEFAULT_TOKEN_BUDGET = 4000, MAX_TOKENS_PER_ENTITY = 500, MIN_RELEVANCE_THRESHOLD = 0.1, TIER_WEIGHTS, PROCEDURE_BUDGET_FRACTION = 0.15, TIER_BUDGET_ALLOCATION, MIN_REFERENCE_SLOTS = 3, GRAPH_WALK_MAX_DEPTH = 1, GRAPH_WALK_MAX_ENTITIES = 10, GRAPH_WALK_MIN_CONFIDENCE = 0.5, GRAPH_WALK_SEED_COUNT = 5, MAX_QUERY_VARIATIONS = 4, RERANK_CLUSTER_THRESHOLD = 0.05, RERANK_TOP_N = 10, RERANK_MIN_CANDIDATES = 5, RELATION_BONUSES, QUERY_SYNONYMS, manifestCache, MAX_CACHE_SIZE = 50, sessionAssemblyMap, MAX_SESSION_MAP_SIZE = 100;
+var DEFAULT_TOKEN_BUDGET = 4000, MAX_TOKENS_PER_ENTITY = 500, MIN_RELEVANCE_THRESHOLD = 0.15, TIER_WEIGHTS, PROCEDURE_BUDGET_FRACTION = 0.15, TIER_BUDGET_ALLOCATION, MIN_REFERENCE_SLOTS = 1, GRAPH_WALK_MAX_DEPTH = 1, GRAPH_WALK_MAX_ENTITIES = 10, GRAPH_WALK_MIN_CONFIDENCE = 0.5, GRAPH_WALK_SEED_COUNT = 5, MAX_QUERY_VARIATIONS = 4, RERANK_CLUSTER_THRESHOLD = 0.05, RERANK_TOP_N = 10, RERANK_MIN_CANDIDATES = 5, RELATION_BONUSES, QUERY_SYNONYMS, manifestCache, MAX_CACHE_SIZE = 50, sessionAssemblyMap, MAX_SESSION_MAP_SIZE = 100;
 var init_context_assembly = __esm(() => {
   init_dist();
   TIER_WEIGHTS = {
@@ -7842,7 +7885,11 @@ ${card.description}`);
   roleFraming.focus.forEach((f) => {
     sections.push(`- ${f}`);
   });
-  sections.push(`- **Memory:** When you discover important domain knowledge, architectural decisions, or infrastructure details, store them via \`harmony_remember\`. Focus on durable knowledge that future agents would benefit from — not ephemeral task details (those are auto-extracted from your session).`);
+  sections.push(`- **Memory:** Store reusable knowledge via \`harmony_remember\`. Only store what a future agent couldn't easily discover from the code itself, applies beyond this specific card, and includes a "because" (not just what, but why).`);
+  sections.push(`  - GOOD: "BoardContext card state must use moveCard action, never direct setState — optimistic updates depend on action ordering"`);
+  sections.push(`  - GOOD: "Mobile bottom bar is 64px, overlaps fixed-position drawers — always add pb-16 to drawer content"`);
+  sections.push(`  - BAD: "Fixed the login button" (no reusable knowledge — the fix is in the code)`);
+  sections.push(`  - BAD: "Completed card #42" (ephemeral, auto-tracked by session)`);
   sections.push(`
 ## Suggested Outputs`);
   roleFraming.outputSuggestions.forEach((s) => {
@@ -24291,13 +24338,13 @@ function levenshteinSimilarity(a, b) {
   const maxLen = Math.max(sa.length, sb.length);
   return 1 - matrix[sa.length][sb.length] / maxLen;
 }
-async function extractMidSessionLearnings(client2, ctx) {
+async function extractMidSessionLearnings(_client, ctx) {
   const workspaceId = getActiveWorkspaceId();
   if (!workspaceId)
     return { count: 0, entityIds: [] };
-  const projectId = getActiveProjectId() || undefined;
+  const _projectId = getActiveProjectId() || undefined;
   const now = Date.now();
-  const entityIds = [];
+  const _entityIds = [];
   const history = sessionTaskHistory.get(ctx.cardId);
   if (ctx.currentTask) {
     const previousTask = history?.lastTask || "";
@@ -24330,81 +24377,22 @@ async function extractMidSessionLearnings(client2, ctx) {
     }
   }
   if (ctx.status === "blocked" && ctx.blockers?.length) {
-    for (const blocker of ctx.blockers) {
-      try {
-        const result = await client2.createMemoryEntity({
-          workspace_id: workspaceId,
-          project_id: projectId,
-          type: "error",
-          scope: "project",
-          memory_tier: "draft",
-          title: `Blocker (mid-session): ${blocker.slice(0, 100)}`,
-          content: `Encountered while working on "${ctx.cardTitle}":
-
-${blocker}
-
-Agent: ${ctx.agentName}
-Progress: ${ctx.progressPercent ?? "unknown"}%`,
-          confidence: 0.5,
-          tags: ["auto-extracted", "blocker", "mid-session"],
-          metadata: {
-            source: "mid_session",
-            card_id: ctx.cardId
-          },
-          agent_identifier: ctx.agentIdentifier
-        });
-        const entity = result.entity;
-        if (entity?.id)
-          entityIds.push(entity.id);
-      } catch {}
-    }
     sessionTaskHistory.set(ctx.cardId, {
       lastTask: ctx.currentTask || "",
       lastExtractionAt: now,
       steps: history?.steps || []
     });
-    return { count: entityIds.length, entityIds };
+    return { count: 0, entityIds: [] };
   }
   if (ctx.currentTask) {
-    const previousTask = history?.lastTask || "";
-    const similarity = levenshteinSimilarity(previousTask, ctx.currentTask);
-    if (similarity < 0.6 && previousTask.length > 0) {
-      try {
-        const result = await client2.createMemoryEntity({
-          workspace_id: workspaceId,
-          project_id: projectId,
-          type: "context",
-          scope: "project",
-          memory_tier: "draft",
-          title: `Task transition: ${ctx.cardTitle}`,
-          content: `Agent transitioned tasks on "${ctx.cardTitle}".
-
-Previous: ${previousTask}
-Current: ${ctx.currentTask}
-Progress: ${ctx.progressPercent ?? "unknown"}%`,
-          confidence: 0.5,
-          tags: ["auto-extracted", "task-transition", "mid-session"],
-          metadata: {
-            source: "mid_session",
-            card_id: ctx.cardId,
-            previous_task: previousTask,
-            current_task: ctx.currentTask
-          },
-          agent_identifier: ctx.agentIdentifier
-        });
-        const entity = result.entity;
-        if (entity?.id)
-          entityIds.push(entity.id);
-      } catch {}
-    }
     const currentHistory = sessionTaskHistory.get(ctx.cardId);
     sessionTaskHistory.set(ctx.cardId, {
       lastTask: ctx.currentTask,
-      lastExtractionAt: entityIds.length > 0 ? now : currentHistory?.lastExtractionAt ?? 0,
+      lastExtractionAt: currentHistory?.lastExtractionAt ?? 0,
       steps: currentHistory?.steps || []
     });
   }
-  return { count: entityIds.length, entityIds };
+  return { count: 0, entityIds: [] };
 }
 function clearMidSessionTracking(cardId) {
   sessionTaskHistory.delete(cardId);
@@ -24588,49 +24576,60 @@ async function extractLearnings(client2, session) {
 Related: ${relatedEntityTitles.map((t) => `[[${t}]]`).join(", ")}` : "";
   if (session.blockers && session.blockers.length > 0) {
     for (const blocker of session.blockers) {
-      learnings.push({
-        title: `Blocker: ${blocker.slice(0, 100)}`,
-        content: `Encountered while working on "${session.cardTitle}":
+      if (blocker.length < 80)
+        continue;
+      let isDuplicate = false;
+      try {
+        const similar = await findSimilarEntities(client2, blocker.slice(0, 200), blocker, workspaceId, { projectId, limit: 3, minRrfScore: 0.05 });
+        isDuplicate = similar.some((e) => e.type === "error" && (e.rrf_score ?? 0) >= 0.06);
+      } catch {}
+      if (!isDuplicate) {
+        learnings.push({
+          title: `Blocker: ${blocker.slice(0, 100)}`,
+          content: `Encountered while working on "${session.cardTitle}":
 
 ${blocker}
 
 Agent: ${session.agentName}
 Session status: ${session.status}`,
-        type: "error",
-        tier: "reference",
-        confidence: 0.7,
-        tags: ["auto-extracted", "blocker", ...session.cardLabels.slice(0, 3)],
-        metadata: {
-          source: "active_learning",
-          card_id: session.cardId
-        }
-      });
+          type: "error",
+          tier: "episode",
+          confidence: 0.6,
+          tags: [
+            "auto-extracted",
+            "blocker",
+            ...session.cardLabels.slice(0, 3)
+          ],
+          metadata: {
+            source: "active_learning",
+            card_id: session.cardId
+          }
+        });
+      }
     }
   }
-  const hasMeaningfulContent = (session.blockers?.length ?? 0) > 0 || session.status === "paused" || (session.cardSubtasks?.length ?? 0) > 0 && session.cardSubtasks?.some((s) => !s.done);
-  if (session.status === "completed" && hasMeaningfulContent) {
+  if (session.status === "paused" && (session.blockers?.length ?? 0) > 0) {
     const durationInfo = session.sessionDurationMs ? `
 Duration: ${Math.round(session.sessionDurationMs / 60000)} minutes` : "";
     learnings.push({
-      title: `Session: ${session.cardTitle}`,
+      title: `Paused: ${session.cardTitle}`,
       content: [
-        `Completed work on "${session.cardTitle}".`,
-        session.currentTask ? `Final task: ${session.currentTask}` : "",
+        `Paused work on "${session.cardTitle}".`,
+        session.currentTask ? `Last task: ${session.currentTask}` : "",
         session.progressPercent !== undefined ? `Progress: ${session.progressPercent}%` : "",
         durationInfo,
-        session.cardLabels.length > 0 ? `Labels: ${session.cardLabels.join(", ")}` : "",
-        session.blockers?.length ? `Blockers encountered: ${session.blockers.join("; ")}` : "",
+        session.blockers?.length ? `Blockers: ${session.blockers.join("; ")}` : "",
         `
 Agent: ${session.agentName}`,
         wikiLinksLine
       ].filter(Boolean).join(`
 `),
       type: "lesson",
-      tier: "episode",
-      confidence: 0.7,
+      tier: "draft",
+      confidence: 0.6,
       tags: [
         "auto-extracted",
-        "session-summary",
+        "session-paused",
         ...session.cardLabels.slice(0, 3)
       ],
       metadata: {
@@ -24639,35 +24638,14 @@ Agent: ${session.agentName}`,
       }
     });
   }
-  const hasBugLabel = session.cardLabels.some((l) => ["bug", "fix", "hotfix", "defect", "error"].includes(l.toLowerCase()));
-  if (hasBugLabel && session.status === "completed") {
-    learnings.push({
-      title: `Solution: ${session.cardTitle}`,
-      content: [
-        `Resolved bug: "${session.cardTitle}"`,
-        session.currentTask ? `
-Approach: ${session.currentTask}` : "",
-        `
-Agent: ${session.agentName}`,
-        wikiLinksLine
-      ].filter(Boolean).join(`
-`),
-      type: "solution",
-      tier: "reference",
-      confidence: 0.8,
-      tags: ["auto-extracted", "bug-fix", ...session.cardLabels.slice(0, 3)],
-      metadata: {
-        source: "active_learning",
-        card_id: session.cardId,
-        auto_confidence: true
-      }
-    });
-  }
   const entityIds = [];
   const stepHistory = sessionTaskHistory.get(session.cardId);
-  const hasEnoughSteps = stepHistory && stepHistory.steps.length >= 2;
+  const MIN_PROCEDURE_STEPS = 5;
+  const MIN_PROCEDURE_DURATION_MS = 10 * 60 * 1000;
+  const hasEnoughSteps = stepHistory && stepHistory.steps.length >= MIN_PROCEDURE_STEPS;
+  const hasMinDuration = (session.sessionDurationMs ?? 0) >= MIN_PROCEDURE_DURATION_MS;
   const isSuccessful = session.status === "completed" && (session.progressPercent === undefined || session.progressPercent >= 85) && !session.blockers?.length;
-  if (isSuccessful && hasEnoughSteps) {
+  if (isSuccessful && hasEnoughSteps && hasMinDuration) {
     const procedureResult = await extractOrReinforceProcedure(client2, session, stepHistory.steps, workspaceId, projectId, wikiLinksLine);
     if (procedureResult) {
       if (procedureResult.mode === "created") {
@@ -24711,218 +24689,9 @@ Agent: ${session.agentName}`,
   if (createdPairs.length >= 2) {
     linkSessionEntities(client2, createdPairs, workspaceId, projectId).catch(() => {});
   }
-  if (entityIds.length > 0) {
-    detectAndCreatePatterns(client2, entityIds, session, workspaceId, projectId).catch(() => {});
-  }
-  if (createdPairs.length > 0) {
-    detectCausalPatterns(client2, createdPairs, session, workspaceId, projectId).catch(() => {});
-  }
   clearMidSessionTracking(session.cardId);
   return { count: entityIds.length, entityIds };
 }
-var PATTERN_THRESHOLD = 3;
-async function detectAndCreatePatterns(client2, newEntityIds, session, workspaceId, projectId) {
-  const patternEntityIds = [];
-  for (const newEntityId of newEntityIds) {
-    try {
-      const { entity: rawEntity } = await client2.getMemoryEntity(newEntityId);
-      const entity = rawEntity;
-      if (!entity?.type)
-        continue;
-      const similar = await findSimilarEntities(client2, entity.title, entity.content, workspaceId, { projectId, limit: 30, minRrfScore: 0.01 });
-      const existing = similar.filter((c) => !newEntityIds.includes(c.id) && c.type === entity.type);
-      if (existing.length < PATTERN_THRESHOLD)
-        continue;
-      const memberTitles = [
-        entity.title,
-        ...existing.slice(0, 4).map((e) => e.title)
-      ];
-      const patternTitle = `Pattern: recurring ${entity.type} (${existing.length + 1} instances)`;
-      const { entities: existingPatterns } = await client2.listMemoryEntities({
-        workspace_id: workspaceId,
-        project_id: projectId,
-        type: "pattern",
-        limit: 10
-      });
-      const matchingPattern = existingPatterns.find((p) => p.metadata?.pattern_type === entity.type);
-      let patternId = null;
-      if (matchingPattern) {
-        patternId = matchingPattern.id;
-        await client2.updateMemoryEntity(patternId, {
-          content: `Recurring pattern: ${entity.type} entities appearing ${existing.length + 1} times.
-
-Members:
-${memberTitles.map((t) => `- ${t}`).join(`
-`)}
-
-Last updated: ${new Date().toISOString()}`,
-          metadata: {
-            pattern_count: existing.length + 1,
-            pattern_type: entity.type,
-            last_updated: new Date().toISOString()
-          }
-        });
-      } else {
-        const result = await client2.createMemoryEntity({
-          workspace_id: workspaceId,
-          project_id: projectId,
-          type: "pattern",
-          scope: "project",
-          memory_tier: "reference",
-          title: patternTitle,
-          content: `Recurring pattern: ${entity.type} entities detected ${existing.length + 1} times.
-
-Members:
-${memberTitles.map((t) => `- ${t}`).join(`
-`)}`,
-          confidence: 0.75,
-          tags: ["auto-extracted", "pattern", entity.type],
-          metadata: {
-            source: "pattern_detection",
-            pattern_type: entity.type,
-            pattern_count: existing.length + 1
-          },
-          agent_identifier: session.agentIdentifier
-        });
-        const created = result.entity;
-        if (created?.id) {
-          patternId = created.id;
-          patternEntityIds.push(patternId);
-        }
-      }
-      if (!patternId)
-        continue;
-      const toLink = [newEntityId, ...existing.slice(0, 4).map((e) => e.id)];
-      for (const sourceId of toLink) {
-        try {
-          await client2.createMemoryRelation({
-            source_id: sourceId,
-            target_id: patternId,
-            relation_type: "part_of",
-            confidence: 0.75
-          });
-        } catch {}
-      }
-    } catch {}
-  }
-  return patternEntityIds;
-}
-var CAUSAL_PATTERN_THRESHOLD = 3;
-async function detectCausalPatterns(client2, createdPairs, session, workspaceId, projectId) {
-  const patternIds = [];
-  const errors3 = createdPairs.filter((p) => p.learning.type === "error");
-  const solutions = createdPairs.filter((p) => p.learning.type === "solution");
-  if (errors3.length === 0 || solutions.length === 0)
-    return patternIds;
-  for (const errorPair of errors3) {
-    try {
-      const similarErrors = await findSimilarEntities(client2, errorPair.learning.title, errorPair.learning.content, workspaceId, {
-        projectId,
-        limit: 20,
-        minRrfScore: 0.03,
-        excludeIds: createdPairs.map((p) => p.id),
-        type: "error"
-      });
-      const resolvedErrors = [];
-      for (const similar of similarErrors.slice(0, 10)) {
-        try {
-          const { outgoing } = await client2.getRelatedEntities(similar.id);
-          const resolvedByRel = outgoing.find((r) => r.relation_type === "resolved_by");
-          if (resolvedByRel) {
-            resolvedErrors.push({
-              errorId: similar.id,
-              errorTitle: similar.title,
-              solutionTitle: resolvedByRel.target_title || "unknown"
-            });
-          }
-        } catch {}
-      }
-      if (resolvedErrors.length + 1 < CAUSAL_PATTERN_THRESHOLD)
-        continue;
-      const { entities: existingPatterns } = await client2.listMemoryEntities({
-        workspace_id: workspaceId,
-        project_id: projectId,
-        type: "pattern",
-        limit: 10
-      });
-      const matchingPattern = existingPatterns.find((p) => p.metadata?.pattern_chain_type === "error_resolved_by_solution");
-      if (matchingPattern) {
-        await client2.updateMemoryEntity(matchingPattern.id, {
-          content: [
-            `Recurring error→solution chain detected (${resolvedErrors.length + 1} instances).`,
-            "",
-            "## Error→Solution Pairs",
-            `- ${errorPair.learning.title} → ${solutions[0].learning.title}`,
-            ...resolvedErrors.slice(0, 5).map((r) => `- ${r.errorTitle} → ${r.solutionTitle}`),
-            "",
-            `Last updated: ${new Date().toISOString()}`
-          ].join(`
-`),
-          metadata: {
-            pattern_chain_type: "error_resolved_by_solution",
-            pattern_count: resolvedErrors.length + 1,
-            last_updated: new Date().toISOString()
-          }
-        });
-        for (const pair of [errorPair, solutions[0]]) {
-          try {
-            await client2.createMemoryRelation({
-              source_id: pair.id,
-              target_id: matchingPattern.id,
-              relation_type: "part_of",
-              confidence: 0.75
-            });
-          } catch {}
-        }
-      } else {
-        const result = await client2.createMemoryEntity({
-          workspace_id: workspaceId,
-          project_id: projectId,
-          type: "pattern",
-          scope: "project",
-          memory_tier: "reference",
-          title: `Pattern: recurring error→solution chain (${resolvedErrors.length + 1} instances)`,
-          content: [
-            `Recurring error→solution chain detected across ${resolvedErrors.length + 1} sessions.`,
-            "",
-            "## Error→Solution Pairs",
-            `- ${errorPair.learning.title} → ${solutions[0].learning.title}`,
-            ...resolvedErrors.slice(0, 5).map((r) => `- ${r.errorTitle} → ${r.solutionTitle}`)
-          ].join(`
-`),
-          confidence: 0.8,
-          tags: ["auto-extracted", "pattern", "causal-chain"],
-          metadata: {
-            source: "causal_pattern_detection",
-            pattern_chain_type: "error_resolved_by_solution",
-            pattern_count: resolvedErrors.length + 1
-          },
-          agent_identifier: session.agentIdentifier
-        });
-        const created = result.entity;
-        if (created?.id) {
-          patternIds.push(created.id);
-          const memberIds = [
-            errorPair.id,
-            solutions[0].id,
-            ...resolvedErrors.slice(0, 4).map((r) => r.errorId)
-          ];
-          for (const memberId of memberIds) {
-            try {
-              await client2.createMemoryRelation({
-                source_id: memberId,
-                target_id: created.id,
-                relation_type: "part_of",
-                confidence: 0.75
-              });
-            } catch {}
-          }
-        }
-      }
-    } catch {}
-  }
-  return patternIds;
-}
 async function detectContradictions(client2, entityId, entityType, title, content, tags, workspaceId, projectId) {
   if (!CONTRADICTION_TYPES.has(entityType))
     return [];
@@ -25735,7 +25504,7 @@ async function autoEndSession(client3, cardId, status) {
 // src/consolidation.ts
 async function consolidateMemories(client3, workspaceId, projectId, options) {
   const dryRun = options?.dryRun !== false;
-  const minClusterSize = options?.minClusterSize ?? 2;
+  const minClusterSize = options?.minClusterSize ?? 3;
   const result = {
     consolidated: 0,
     clustersFound: 0,
@@ -25800,12 +25569,7 @@ async function consolidateMemories(client3, workspaceId, projectId, options) {
       result.clustersFound++;
       const mergedTitle = deriveClusterTitle(cluster, type);
       const memberTitles = cluster.map((e) => e.title);
-      const mergedContent = [
-        `Consolidated from ${cluster.length} ${type} memories:
-`,
-        ...cluster.map((e) => `- **${e.title}**: ${e.content.slice(0, 200)}`)
-      ].join(`
-`);
+      const mergedContent = synthesizeClusterContent(cluster, type);
       const maxConfidence = Math.max(...cluster.map((e) => e.confidence));
       const allTags = [...new Set(cluster.flatMap((e) => e.tags || []))];
       const detail = {
@@ -25867,6 +25631,60 @@ async function consolidateMemories(client3, workspaceId, projectId, options) {
   }
   return result;
 }
+function synthesizeClusterContent(cluster, type) {
+  const SKIP_PATTERNS = [
+    /^##\s/,
+    /^Agent:/,
+    /^Duration:/,
+    /^Labels:/,
+    /^Progress:/,
+    /^Session status:/,
+    /^Completed at/,
+    /^Final state:/,
+    /^Related:/,
+    /^When working on:/,
+    /^\d+\.\s+.+\(\d+%,\s*\+\d+%\)/,
+    /^Last updated:/,
+    /^Recurring pattern:/,
+    /^Consolidated from/
+  ];
+  const seenLines = new Set;
+  const knowledgeLines = [];
+  for (const entity of cluster) {
+    const lines = entity.content.split(`
+`).map((l) => l.trim());
+    for (const line of lines) {
+      if (!line || line.length < 20)
+        continue;
+      if (SKIP_PATTERNS.some((p) => p.test(line)))
+        continue;
+      const normalized = line.toLowerCase().replace(/[*_`#[\]]/g, "").trim();
+      if (seenLines.has(normalized))
+        continue;
+      seenLines.add(normalized);
+      knowledgeLines.push(line);
+    }
+  }
+  if (knowledgeLines.length === 0) {
+    return `${cluster.length} related ${type} entities consolidated. Original titles:
+${cluster.map((e) => `- ${e.title}`).join(`
+`)}`;
+  }
+  const MAX_CHARS = 1600;
+  const result = [
+    `Consolidated knowledge from ${cluster.length} ${type} entities:
+`
+  ];
+  let charCount = result[0].length;
+  for (const line of knowledgeLines) {
+    if (charCount + line.length + 3 > MAX_CHARS)
+      break;
+    result.push(`- ${line}`);
+    charCount += line.length + 3;
+  }
+  return result.join(`
+`);
+}
 function deriveClusterTitle(cluster, type) {
   const stopWords = new Set([
     "the",
@@ -25921,9 +25739,9 @@ function deriveClusterTitle(cluster, type) {
       wordCounts.set(word, (wordCounts.get(word) || 0) + 1);
     }
   }
-  const topWords = [...wordCounts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 3).map(([word]) => word);
-  const suffix = topWords.length > 0 ? topWords.join(", ") : "various";
-  return `Consolidated ${type}: ${suffix}`;
+  const topWords = [...wordCounts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 4).map(([word]) => word[0].toUpperCase() + word.slice(1));
+  const suffix = topWords.length > 0 ? topWords.join(" / ") : "Various";
+  return `${type[0].toUpperCase() + type.slice(1)}: ${suffix}`;
 }
 
 // src/server.ts
@@ -25999,6 +25817,371 @@ async function runLifecycleMaintenance(client3, workspaceId, projectId) {
   return result;
 }
 
+// src/memory-cleanup.ts
+init_dist();
+var ALL_STEPS = [
+  "prune",
+  "consolidate",
+  "orphans",
+  "duplicates",
+  "backfill"
+];
+async function runMemoryCleanup(client3, workspaceId, projectId, options) {
+  const dryRun = options?.dryRun !== false;
+  const steps = options?.steps ?? ALL_STEPS;
+  const maxAgeDays = options?.maxAgeDays ?? 30;
+  const minClusterSize = options?.minClusterSize ?? 3;
+  const orphanAgeDays = options?.orphanAgeDays ?? 14;
+  const report = {
+    success: true,
+    dryRun,
+    timestamp: new Date().toISOString(),
+    workspace: { id: workspaceId, projectId },
+    summary: { totalEntities: 0, issuesFound: 0, actionsTaken: 0 },
+    steps: {},
+    errors: [],
+    healthReport: ""
+  };
+  let entities = [];
+  try {
+    const listResult = await client3.listMemoryEntities({
+      workspace_id: workspaceId,
+      project_id: projectId,
+      limit: 200
+    });
+    entities = listResult.entities || [];
+    report.summary.totalEntities = entities.length;
+  } catch (err) {
+    report.errors.push({
+      step: "init",
+      message: `Failed to fetch entities: ${err.message}`
+    });
+    report.success = false;
+    report.healthReport = generateHealthReport(report);
+    return report;
+  }
+  if (steps.includes("prune")) {
+    try {
+      report.steps.prune = runPruneStep(entities, maxAgeDays);
+      if (!dryRun) {
+        for (const item of report.steps.prune.items) {
+          try {
+            await client3.deleteMemoryEntity(item.id);
+            report.steps.prune.pruned++;
+          } catch {}
+        }
+        report.summary.actionsTaken += report.steps.prune.pruned;
+      }
+      report.summary.issuesFound += report.steps.prune.staleDraftsFound;
+    } catch (err) {
+      report.errors.push({
+        step: "prune",
+        message: err.message
+      });
+    }
+  }
+  if (steps.includes("consolidate")) {
+    try {
+      const result = await consolidateMemories(client3, workspaceId, projectId, {
+        dryRun,
+        minClusterSize
+      });
+      report.steps.consolidate = {
+        clustersFound: result.clustersFound,
+        entitiesProcessed: result.entitiesProcessed,
+        consolidated: result.consolidated,
+        details: result.details
+      };
+      report.summary.issuesFound += result.clustersFound;
+      if (!dryRun)
+        report.summary.actionsTaken += result.consolidated;
+    } catch (err) {
+      report.errors.push({
+        step: "consolidate",
+        message: err.message
+      });
+    }
+  }
+  if (steps.includes("orphans")) {
+    try {
+      report.steps.orphans = await runOrphanStep(client3, entities, orphanAgeDays);
+      if (!dryRun) {
+        for (const item of report.steps.orphans.items) {
+          try {
+            await client3.deleteMemoryEntity(item.id);
+            report.steps.orphans.removed++;
+          } catch {}
+        }
+        report.summary.actionsTaken += report.steps.orphans.removed;
+      }
+      report.summary.issuesFound += report.steps.orphans.orphansFound;
+    } catch (err) {
+      report.errors.push({
+        step: "orphans",
+        message: err.message
+      });
+    }
+  }
+  if (steps.includes("duplicates")) {
+    try {
+      report.steps.duplicates = await runDuplicateStep(client3, entities, workspaceId, projectId);
+      if (!dryRun) {
+        for (const pair of report.steps.duplicates.pairs) {
+          try {
+            await client3.deleteMemoryEntity(pair.removeId);
+            report.steps.duplicates.resolved++;
+          } catch {}
+        }
+        report.summary.actionsTaken += report.steps.duplicates.resolved;
+      }
+      report.summary.issuesFound += report.steps.duplicates.duplicatePairsFound;
+    } catch (err) {
+      report.errors.push({
+        step: "duplicates",
+        message: err.message
+      });
+    }
+  }
+  if (steps.includes("backfill")) {
+    try {
+      if (dryRun) {
+        report.steps.backfill = {
+          processed: 0,
+          remaining: -1,
+          errors: []
+        };
+      } else {
+        const result = await client3.backfillEmbeddings(workspaceId);
+        report.steps.backfill = {
+          processed: result.processed,
+          remaining: result.remaining,
+          errors: result.errors || []
+        };
+        report.summary.actionsTaken += result.processed;
+      }
+    } catch (err) {
+      report.errors.push({
+        step: "backfill",
+        message: err.message
+      });
+    }
+  }
+  report.healthReport = generateHealthReport(report);
+  return report;
+}
+function runPruneStep(entities, maxAgeDays) {
+  const now = Date.now();
+  const drafts = entities.filter((e) => e.memory_tier === "draft");
+  const stale = [];
+  for (const entity of drafts) {
+    const ageDays = (now - new Date(entity.created_at).getTime()) / (1000 * 60 * 60 * 24);
+    if (ageDays < maxAgeDays)
+      continue;
+    const lifecycle2 = evaluateLifecycle(entity);
+    stale.push({
+      id: entity.id,
+      title: entity.title,
+      ageDays: Math.round(ageDays),
+      decayScore: Math.round(lifecycle2.decay.score * 100) / 100
+    });
+  }
+  return { staleDraftsFound: stale.length, pruned: 0, items: stale };
+}
+async function runOrphanStep(client3, entities, orphanAgeDays) {
+  const now = Date.now();
+  const result = { orphansFound: 0, removed: 0, items: [] };
+  const candidates = entities.filter((e) => {
+    if (e.memory_tier === "reference")
+      return false;
+    if (e.access_count >= 2)
+      return false;
+    const ageDays = (now - new Date(e.created_at).getTime()) / (1000 * 60 * 60 * 24);
+    return ageDays >= orphanAgeDays;
+  });
+  for (const entity of candidates) {
+    try {
+      const related = await client3.getRelatedEntities(entity.id);
+      const totalRelations = (related.outgoing?.length || 0) + (related.incoming?.length || 0);
+      if (totalRelations > 0)
+        continue;
+      const ageDays = (now - new Date(entity.created_at).getTime()) / (1000 * 60 * 60 * 24);
+      result.items.push({
+        id: entity.id,
+        title: entity.title,
+        type: entity.type,
+        tier: entity.memory_tier,
+        ageDays: Math.round(ageDays),
+        accessCount: entity.access_count
+      });
+      result.orphansFound++;
+    } catch {}
+  }
+  return result;
+}
+async function runDuplicateStep(client3, entities, workspaceId, projectId) {
+  const result = {
+    duplicatePairsFound: 0,
+    resolved: 0,
+    pairs: []
+  };
+  const seenPairs = new Set;
+  const flaggedForRemoval = new Set;
+  for (const entity of entities) {
+    if (flaggedForRemoval.has(entity.id))
+      continue;
+    let similar;
+    try {
+      similar = await findSimilarEntities(client3, entity.title, entity.content, workspaceId, { projectId, limit: 5, minRrfScore: 0.05, excludeIds: [entity.id] });
+    } catch {
+      continue;
+    }
+    for (const match of similar) {
+      if (flaggedForRemoval.has(match.id))
+        continue;
+      const pairKey = [entity.id, match.id].sort().join(":");
+      if (seenPairs.has(pairKey))
+        continue;
+      seenPairs.add(pairKey);
+      const sim = titleSimilarity(entity.title, match.title);
+      if (sim < 0.85)
+        continue;
+      const entityScore = entityQualityScore(entity);
+      const matchEntity = entities.find((e) => e.id === match.id);
+      const matchScore = matchEntity ? entityQualityScore(matchEntity) : match.confidence;
+      const [keep, remove] = entityScore >= matchScore ? [entity, { id: match.id, title: match.title }] : [{ id: match.id, title: match.title }, entity];
+      flaggedForRemoval.add(remove.id);
+      result.pairs.push({
+        keepId: keep.id,
+        keepTitle: keep.title,
+        removeId: remove.id,
+        removeTitle: remove.title,
+        similarity: Math.round(sim * 100) / 100
+      });
+      result.duplicatePairsFound++;
+    }
+  }
+  return result;
+}
+var TIER_WEIGHTS2 = {
+  reference: 3,
+  episode: 2,
+  draft: 1
+};
+function entityQualityScore(entity) {
+  return entity.confidence + (TIER_WEIGHTS2[entity.memory_tier] || 0) + Math.min(entity.access_count, 10) * 0.1;
+}
+function titleSimilarity(a, b) {
+  const na = a.toLowerCase().trim();
+  const nb = b.toLowerCase().trim();
+  if (na === nb)
+    return 1;
+  const wordsA = new Set(na.split(/\W+/).filter(Boolean));
+  const wordsB = new Set(nb.split(/\W+/).filter(Boolean));
+  if (wordsA.size === 0 || wordsB.size === 0)
+    return 0;
+  let intersection3 = 0;
+  for (const w of wordsA) {
+    if (wordsB.has(w))
+      intersection3++;
+  }
+  const union3 = wordsA.size + wordsB.size - intersection3;
+  return union3 > 0 ? intersection3 / union3 : 0;
+}
+function generateHealthReport(report) {
+  const mode = report.dryRun ? "Dry Run (preview)" : "Executed";
+  const lines = [
+    `# Memory Health Report
+`,
+    `**Mode:** ${mode} | **Entities:** ${report.summary.totalEntities} | **Issues:** ${report.summary.issuesFound} | **Actions:** ${report.summary.actionsTaken}`,
+    ""
+  ];
+  if (report.steps.prune) {
+    const p = report.steps.prune;
+    lines.push("## Stale Drafts");
+    if (p.staleDraftsFound === 0) {
+      lines.push(`No stale drafts found.
+`);
+    } else {
+      lines.push(`Found **${p.staleDraftsFound}** stale drafts${!report.dryRun ? ` (pruned ${p.pruned})` : ""}:`);
+      lines.push("| Title | Age | Decay |");
+      lines.push("|-------|-----|-------|");
+      for (const item of p.items.slice(0, 20)) {
+        lines.push(`| ${item.title} | ${item.ageDays}d | ${item.decayScore} |`);
+      }
+      lines.push("");
+    }
+  }
+  if (report.steps.consolidate) {
+    const c = report.steps.consolidate;
+    lines.push("## Consolidation");
+    if (c.clustersFound === 0) {
+      lines.push(`Scanned ${c.entitiesProcessed} draft/episode entities — no clusters found.
+`);
+    } else {
+      lines.push(`Found **${c.clustersFound}** clusters across ${c.entitiesProcessed} entities:`);
+      for (const d of c.details.slice(0, 10)) {
+        lines.push(`- **${d.mergedTitle}** — ${d.clusterSize} entities`);
+      }
+      lines.push("");
+    }
+  }
+  if (report.steps.orphans) {
+    const o = report.steps.orphans;
+    lines.push("## Orphaned Entities");
+    if (o.orphansFound === 0) {
+      lines.push(`No orphans found.
+`);
+    } else {
+      lines.push(`Found **${o.orphansFound}** orphans${!report.dryRun ? ` (removed ${o.removed})` : ""}:`);
+      lines.push("| Title | Type | Tier | Age | Accesses |");
+      lines.push("|-------|------|------|-----|----------|");
+      for (const item of o.items.slice(0, 20)) {
+        lines.push(`| ${item.title} | ${item.type} | ${item.tier} | ${item.ageDays}d | ${item.accessCount} |`);
+      }
+      lines.push("");
+    }
+  }
+  if (report.steps.duplicates) {
+    const d = report.steps.duplicates;
+    lines.push("## Near-Duplicates");
+    if (d.duplicatePairsFound === 0) {
+      lines.push(`No duplicates found.
+`);
+    } else {
+      lines.push(`Found **${d.duplicatePairsFound}** duplicate pairs${!report.dryRun ? ` (resolved ${d.resolved})` : ""}:`);
+      for (const pair of d.pairs.slice(0, 20)) {
+        lines.push(`- "${pair.keepTitle}" ~ "${pair.removeTitle}" (${Math.round(pair.similarity * 100)}% similar, keep first)`);
+      }
+      lines.push("");
+    }
+  }
+  if (report.steps.backfill) {
+    const b = report.steps.backfill;
+    lines.push("## Embedding Coverage");
+    if (report.dryRun) {
+      lines.push("Backfill will run when executed with `dryRun: false`.\n");
+    } else if (b.remaining === 0) {
+      lines.push(`All embeddings up to date (processed ${b.processed}).
+`);
+    } else {
+      lines.push(`Processed ${b.processed} entities. ${b.remaining} still need embeddings.
+`);
+    }
+  }
+  if (report.errors.length > 0) {
+    lines.push("## Errors");
+    for (const e of report.errors) {
+      lines.push(`- **${e.step}:** ${e.message}`);
+    }
+    lines.push("");
+  }
+  if (report.dryRun) {
+    lines.push("---\n*Run with `dryRun: false` to execute cleanup.*");
+  }
+  return lines.join(`
+`);
+}
+
 // src/onboard.ts
 async function onboardNewUser(params) {
   const {
@@ -27433,6 +27616,47 @@ var TOOLS = {
       },
       required: []
     }
+  },
+  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.",
+    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 cleanup without executing changes (default: true)"
+        },
+        steps: {
+          type: "array",
+          items: {
+            type: "string",
+            enum: ["prune", "consolidate", "orphans", "duplicates", "backfill"]
+          },
+          description: "Which cleanup steps to run (default: all). Options: prune, consolidate, orphans, duplicates, backfill."
+        },
+        maxAgeDays: {
+          type: "number",
+          description: "Max age in days for stale draft pruning (default: 30)"
+        },
+        minClusterSize: {
+          type: "number",
+          description: "Min cluster size for consolidation (default: 3)"
+        },
+        orphanAgeDays: {
+          type: "number",
+          description: "Min age in days for orphan detection (default: 14)"
+        }
+      },
+      required: []
+    }
   }
 };
 var RESOURCES = [
@@ -28943,6 +29167,27 @@ async function handleToolCall(name, args, deps) {
         message: `Processed ${entitiesProcessed} entities, created ${relationsCreated} new relations.`
       };
     }
+    case "harmony_cleanup_memories": {
+      const workspaceId = args.workspaceId || deps.getActiveWorkspaceId();
+      if (!workspaceId) {
+        throw new Error("No workspace specified. Use harmony_set_workspace_context or provide workspaceId.");
+      }
+      const projectId = args.projectId || deps.getActiveProjectId() || undefined;
+      const report = await runMemoryCleanup(client3, workspaceId, projectId, {
+        dryRun: args.dryRun,
+        steps: args.steps,
+        maxAgeDays: args.maxAgeDays,
+        minClusterSize: args.minClusterSize,
+        orphanAgeDays: args.orphanAgeDays
+      });
+      return {
+        success: report.success,
+        dryRun: report.dryRun,
+        summary: report.summary,
+        errors: report.errors,
+        healthReport: report.healthReport
+      };
+    }
     default:
       throw new Error(`Unknown tool: ${name}`);
   }