@gethmy/mcp 2.2.4 → 2.3.0

package/src/active-learning.ts

@@ -111,15 +111,15 @@ export interface MidSessionContext {
  * Called from harmony_update_agent_progress.
  */
 export async function extractMidSessionLearnings(
-  client: HarmonyApiClient,
+  _client: HarmonyApiClient,
   ctx: MidSessionContext,
 ): Promise<{ count: number; entityIds: string[] }> {
   const workspaceId = getActiveWorkspaceId();
   if (!workspaceId) return { count: 0, entityIds: [] };
 
-  const projectId = getActiveProjectId() || undefined;
+  const _projectId = getActiveProjectId() || undefined;
   const now = Date.now();
-  const entityIds: string[] = [];
+  const _entityIds: string[] = [];
 
   const history = sessionTaskHistory.get(ctx.cardId);
 
@@ -164,83 +164,31 @@ export async function extractMidSessionLearnings(
     }
   }
 
-  // Rule 1: Status transitions to "blocked" → create error entity immediately
+  // Rule 1: Status transitions to "blocked" → track but DON'T create mid-session entities.
+  // Blockers are captured at session end with full context — mid-session entities are
+  // low-confidence duplicates that add noise to the knowledge graph.
   if (ctx.status === "blocked" && ctx.blockers?.length) {
-    for (const blocker of ctx.blockers) {
-      try {
-        const result = await client.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}":\n\n${blocker}\n\nAgent: ${ctx.agentName}\nProgress: ${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 as { id: string };
-        if (entity?.id) entityIds.push(entity.id);
-      } catch {
-        // Non-fatal
-      }
-    }
     sessionTaskHistory.set(ctx.cardId, {
       lastTask: ctx.currentTask || "",
       lastExtractionAt: now,
       steps: history?.steps || [],
     });
-    return { count: entityIds.length, entityIds };
+    return { count: 0, entityIds: [] };
   }
 
-  // Rule 2: Task changed significantly → capture context entity
+  // Rule 2: Task transitions are tracked in step history (above) but no longer
+  // create separate context entities. The step history feeds procedure extraction
+  // at session end, which is more valuable than individual transition snapshots.
   if (ctx.currentTask) {
-    const previousTask = history?.lastTask || "";
-    const similarity = levenshteinSimilarity(previousTask, ctx.currentTask);
-
-    if (similarity < 0.6 && previousTask.length > 0) {
-      try {
-        const result = await client.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}".\n\nPrevious: ${previousTask}\nCurrent: ${ctx.currentTask}\nProgress: ${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 as { id: string };
-        if (entity?.id) entityIds.push(entity.id);
-      } catch {
-        // Non-fatal
-      }
-    }
-
-    // Update lastExtractionAt only when entities were created
     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: [] };
 }
 
 /**
@@ -589,51 +537,71 @@ export async function extractLearnings(
       ? `\nRelated: ${relatedEntityTitles.map((t) => `[[${t}]]`).join(", ")}`
       : "";
 
-  // Rule 1: Session had blockers → create error entities
+  // Rule 1: Session had blockers → create error entity (only for substantial blockers)
+  // Skip trivial blocker strings — only store if the blocker text contains
+  // enough detail to be useful to a future agent (>80 chars).
   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}":\n\n${blocker}\n\nAgent: ${session.agentName}\nSession 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,
-        },
-      });
+      if (blocker.length < 80) continue; // Skip trivial blockers like "stuck" or "waiting on API"
+
+      // Dedup: check if a similar error entity already exists
+      let isDuplicate = false;
+      try {
+        const similar = await findSimilarEntities(
+          client,
+          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 {
+        /* non-fatal */
+      }
+
+      if (!isDuplicate) {
+        learnings.push({
+          title: `Blocker: ${blocker.slice(0, 100)}`,
+          content: `Encountered while working on "${session.cardTitle}":\n\n${blocker}\n\nAgent: ${session.agentName}\nSession status: ${session.status}`,
+          type: "error",
+          tier: "episode",
+          confidence: 0.6,
+          tags: [
+            "auto-extracted",
+            "blocker",
+            ...session.cardLabels.slice(0, 3),
+          ],
+          metadata: {
+            source: "active_learning",
+            card_id: session.cardId,
+          },
+        });
+      }
     }
   }
 
-  // Rule 2: Session completed → create lesson entity summarizing work
-  // Only create when there's meaningful content beyond "completed X at 100%"
-  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) {
+  // Rule 2: Session paused with blockers → create lesson (paused only, not clean completions).
+  // Clean completions produce no reusable knowledge — the work is in the code/PR.
+  // Only create a lesson when the session was interrupted (paused with blockers),
+  // so a future agent can understand what was left unfinished and why.
+  if (session.status === "paused" && (session.blockers?.length ?? 0) > 0) {
     const durationInfo = session.sessionDurationMs
       ? `\nDuration: ${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("; ")}`
+          ? `Blockers: ${session.blockers.join("; ")}`
           : "",
         `\nAgent: ${session.agentName}`,
         wikiLinksLine,
@@ -641,11 +609,11 @@ export async function extractLearnings(
         .filter(Boolean)
         .join("\n"),
       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: {
@@ -655,45 +623,30 @@ export async function extractLearnings(
     });
   }
 
-  // Rule 3: Card had "bug" label + completed → create solution entity
-  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 ? `\nApproach: ${session.currentTask}` : "",
-        `\nAgent: ${session.agentName}`,
-        wikiLinksLine,
-      ]
-        .filter(Boolean)
-        .join("\n"),
-      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,
-      },
-    });
-  }
+  // Rule 3: Bug solution — REMOVED.
+  // Storing "Resolved bug: {card title}" with no detail about the actual fix
+  // adds zero value. The real solution is in the code diff / PR. Agents should
+  // use `harmony_remember` to store non-obvious root cause details manually.
 
   // Store learnings, tracking entity ID → learning for graph expansion
   const entityIds: string[] = [];
 
   // Rule 4: Successful session with tracked steps → create or reinforce procedure entity
+  // Thresholds raised: require 5+ distinct steps AND 10+ minute duration to avoid
+  // creating "procedures" from trivial tasks (e.g., a 2-step "investigate → fix" session).
   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; // 10 minutes
+  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(
       client,
       session,
@@ -784,27 +737,12 @@ export async function extractLearnings(
     );
   }
 
-  // Detect recurring patterns across sessions (fire-and-forget)
-  if (entityIds.length > 0) {
-    detectAndCreatePatterns(
-      client,
-      entityIds,
-      session,
-      workspaceId,
-      projectId,
-    ).catch(() => {});
-  }
-
-  // Detect recurring causal patterns (error→solution chains across sessions)
-  if (createdPairs.length > 0) {
-    detectCausalPatterns(
-      client,
-      createdPairs,
-      session,
-      workspaceId,
-      projectId,
-    ).catch(() => {});
-  }
+  // Pattern detection DISABLED — these create noise entities like
+  // "Pattern: recurring procedure (N instances)" that are just catalogs of
+  // entity titles, eating token budget with zero actionable content.
+  // The consolidation tool (harmony_consolidate_memories) serves a similar
+  // purpose and can be improved separately with LLM synthesis.
+  // See: https://github.com/getharmony/getharmony/issues/memory-quality
 
   // Clean up mid-session tracking
   clearMidSessionTracking(session.cardId);

package/src/consolidation.ts

@@ -34,7 +34,7 @@ export interface ConsolidationResult {
 
 export interface ConsolidationOptions {
   dryRun?: boolean;
-  minClusterSize?: number;
+  minClusterSize?: number; // Default: 3 (was 2 — raised to avoid premature merging)
 }
 
 /**
@@ -52,7 +52,7 @@ export async function consolidateMemories(
   options?: ConsolidationOptions,
 ): Promise<ConsolidationResult> {
   const dryRun = options?.dryRun !== false; // default true
-  const minClusterSize = options?.minClusterSize ?? 2;
+  const minClusterSize = options?.minClusterSize ?? 3; // raised from 2 to reduce noise
 
   const result: ConsolidationResult = {
     consolidated: 0,
@@ -153,11 +153,10 @@ export async function consolidateMemories(
       const mergedTitle = deriveClusterTitle(cluster, type);
       const memberTitles = cluster.map((e) => e.title);
 
-      // Merge content as bullet points
-      const mergedContent = [
-        `Consolidated from ${cluster.length} ${type} memories:\n`,
-        ...cluster.map((e) => `- **${e.title}**: ${e.content.slice(0, 200)}`),
-      ].join("\n");
+      // Synthesize content: extract unique knowledge from each member,
+      // not just a bullet list of titles. Each member's content is trimmed
+      // to its first meaningful paragraph (skipping headers and metadata).
+      const mergedContent = synthesizeClusterContent(cluster, type);
 
       // Max confidence from cluster members
       const maxConfidence = Math.max(...cluster.map((e) => e.confidence));
@@ -241,6 +240,76 @@ export async function consolidateMemories(
   return result;
 }
 
+/**
+ * Synthesize cluster content by extracting unique, actionable knowledge
+ * from each member entity. Skips boilerplate (headers, metadata, agent names)
+ * and deduplicates similar lines across members.
+ */
+function synthesizeClusterContent(
+  cluster: MemoryEntity[],
+  type: string,
+): string {
+  // Lines to skip: headers, agent metadata, timestamps, progress percentages
+  const SKIP_PATTERNS = [
+    /^##\s/,
+    /^Agent:/,
+    /^Duration:/,
+    /^Labels:/,
+    /^Progress:/,
+    /^Session status:/,
+    /^Completed at/,
+    /^Final state:/,
+    /^Related:/,
+    /^When working on:/,
+    /^\d+\.\s+.+\(\d+%,\s*\+\d+%\)/, // procedure step with progress percentages
+    /^Last updated:/,
+    /^Recurring pattern:/,
+    /^Consolidated from/,
+  ];
+
+  const seenLines = new Set<string>();
+  const knowledgeLines: string[] = [];
+
+  for (const entity of cluster) {
+    const lines = entity.content.split("\n").map((l) => l.trim());
+
+    for (const line of lines) {
+      if (!line || line.length < 20) continue;
+      if (SKIP_PATTERNS.some((p) => p.test(line))) continue;
+
+      // Normalize for dedup: lowercase, strip markdown formatting
+      const normalized = line
+        .toLowerCase()
+        .replace(/[*_`#[\]]/g, "")
+        .trim();
+      if (seenLines.has(normalized)) continue;
+      seenLines.add(normalized);
+
+      knowledgeLines.push(line);
+    }
+  }
+
+  if (knowledgeLines.length === 0) {
+    // Fallback: if no knowledge was extractable, use a compact summary
+    return `${cluster.length} related ${type} entities consolidated. Original titles:\n${cluster.map((e) => `- ${e.title}`).join("\n")}`;
+  }
+
+  // Cap at ~400 tokens worth of content (1600 chars)
+  const MAX_CHARS = 1600;
+  const result: string[] = [
+    `Consolidated knowledge from ${cluster.length} ${type} entities:\n`,
+  ];
+  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("\n");
+}
+
 /**
  * Derive a cluster title from the most common meaningful words across member titles.
  */
@@ -303,12 +372,12 @@ function deriveClusterTitle(cluster: MemoryEntity[], type: string): string {
     }
   }
 
-  // Sort by frequency, take top 3
+  // Sort by frequency, take top 4 for more descriptive titles
   const topWords = [...wordCounts.entries()]
     .sort((a, b) => b[1] - a[1])
-    .slice(0, 3)
-    .map(([word]) => word);
+    .slice(0, 4)
+    .map(([word]) => word[0].toUpperCase() + word.slice(1));
 
-  const suffix = topWords.length > 0 ? topWords.join(", ") : "various";
-  return `Consolidated ${type}: ${suffix}`;
+  const suffix = topWords.length > 0 ? topWords.join(" / ") : "Various";
+  return `${type[0].toUpperCase() + type.slice(1)}: ${suffix}`;
 }

package/src/context-assembly.ts

@@ -87,7 +87,7 @@ export interface AssembledContext {
 // Constants
 const DEFAULT_TOKEN_BUDGET = 4000;
 const MAX_TOKENS_PER_ENTITY = 500;
-const MIN_RELEVANCE_THRESHOLD = 0.1;
+const MIN_RELEVANCE_THRESHOLD = 0.15; // raised from 0.1 to filter low-signal entities
 
 // Tier weight multipliers for relevance scoring
 const TIER_WEIGHTS: Record<MemoryTier, number> = {
@@ -106,8 +106,8 @@ const TIER_BUDGET_ALLOCATION: Record<MemoryTier, number> = {
   draft: 0.1,
 };
 
-// Minimum guaranteed slots per tier
-const MIN_REFERENCE_SLOTS = 3;
+// Minimum guaranteed slots per tier (reduced from 3 to avoid filling context with noise)
+const MIN_REFERENCE_SLOTS = 1;
 
 // Graph walk configuration
 const GRAPH_WALK_MAX_DEPTH = 1;
@@ -163,6 +163,55 @@ function estimateTokens(text: string): number {
   return Math.ceil(text.length / 4);
 }
 
+/**
+ * Content quality gate: filter out entities that waste token budget.
+ * Returns true if the entity passes quality checks.
+ */
+function passesQualityGate(entity: ContextEntity): boolean {
+  const content = entity.content.trim();
+
+  // Gate 1: Minimum content length — entities with <50 chars of content
+  // are too shallow to provide value (e.g., "Resolved bug: Fix login button")
+  if (content.length < 50) return false;
+
+  // Gate 2: Title-content similarity — skip entities where content is just
+  // the title restated. Normalize both and check if content adds anything.
+  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) {
+    // Content is barely longer than the title — likely just a reformulation
+    return false;
+  }
+
+  // Gate 3: Pattern noise detection — skip "Pattern: recurring X (N instances)"
+  // and "Consolidated from N type memories:" entities that are just catalogs
+  if (
+    entity.type === "pattern" &&
+    /recurring .+ \(\d+ instances\)/i.test(entity.title)
+  ) {
+    // Check if content is just a member list (lines starting with "- ")
+    const lines = content.split("\n").filter((l) => l.trim().length > 0);
+    const bulletLines = lines.filter((l) => l.trim().startsWith("- "));
+    if (bulletLines.length > lines.length * 0.6) return false;
+  }
+
+  // Gate 4: Procedure quality — procedures must contain actual steps,
+  // not just a card title wrapped in a template
+  if (entity.type === "procedure") {
+    // Count numbered steps (1. ..., 2. ..., etc.)
+    const stepCount = (content.match(/^\d+\.\s/gm) || []).length;
+    if (stepCount < 3) return false;
+  }
+
+  return true;
+}
+
 /**
  * Generate a unique assembly ID
  */
@@ -569,8 +618,30 @@ export async function assembleContext(
     };
   }
 
+  // Quality gate: filter out low-value entities before scoring
+  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: [],
+    };
+  }
+
   // Score all candidates (pass graph relations for relation-type bonuses)
-  const scored = candidates.map((entity) => {
+  const scored = qualityCandidates.map((entity) => {
     const { score, reasons } = computeRelevanceScore(
       entity,
       taskContext,