@gethmy/mcp 2.2.4 → 2.3.1

package/dist/lib/active-learning.js

@@ -49,13 +49,13 @@ function levenshteinSimilarity(a, b) {
  * Extract learnings from mid-session progress updates.
  * Called from harmony_update_agent_progress.
  */
-export async function extractMidSessionLearnings(client, ctx) {
+export 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);
     // Always track step history regardless of rate limit
     if (ctx.currentTask) {
@@ -91,82 +91,29 @@ export async function extractMidSessionLearnings(client, ctx) {
             return { count: 0, entityIds: [] };
         }
     }
-    // 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;
-                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;
-                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: [] };
 }
 /**
  * Clean up mid-session tracking for a card (call on session end).
@@ -402,47 +349,61 @@ export async function extractLearnings(client, session) {
     const wikiLinksLine = relatedEntityTitles.length > 0
         ? `\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,
@@ -450,11 +411,11 @@ export async function extractLearnings(client, session) {
                 .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: {
@@ -463,39 +424,24 @@ export async function extractLearnings(client, session) {
             },
         });
     }
-    // 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 = [];
     // 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, stepHistory.steps, workspaceId, projectId, wikiLinksLine);
         if (procedureResult) {
             if (procedureResult.mode === "created") {
@@ -547,14 +493,12 @@ export async function extractLearnings(client, session) {
     if (createdPairs.length >= 2) {
         linkSessionEntities(client, createdPairs, workspaceId, projectId).catch(() => { });
     }
-    // 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);
     return { count: entityIds.length, entityIds };

package/dist/lib/api-client.js

@@ -314,6 +314,12 @@ export class HarmonyApiClient {
     async endAgentSession(cardId, data) {
         return this.request("DELETE", `/cards/${cardId}/agent-context`, data);
     }
+    async flushActivityLog(cardId, data) {
+        return this.request("POST", `/cards/${cardId}/agent-activity-log`, data);
+    }
+    async getActivityLog(cardId, sessionId) {
+        return this.request("GET", `/cards/${cardId}/agent-activity-log?sessionId=${sessionId}`);
+    }
     async getAgentSession(cardId, options) {
         const params = new URLSearchParams();
         if (options?.includeEnded)

package/dist/lib/consolidation.js

@@ -15,7 +15,7 @@ import { findSimilarEntities } from "./graph-expansion.js";
  */
 export async function consolidateMemories(client, workspaceId, projectId, options) {
     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 = {
         consolidated: 0,
         clustersFound: 0,
@@ -92,11 +92,10 @@ export async function consolidateMemories(client, workspaceId, projectId, option
             // Derive title from most common words across cluster titles
             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));
             // Union of all tags (deduped)
@@ -173,6 +172,67 @@ export async function consolidateMemories(client, workspaceId, projectId, option
     }
     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, type) {
+    // 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();
+    const knowledgeLines = [];
+    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 = [
+        `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.
  */
@@ -233,11 +293,11 @@ function deriveClusterTitle(cluster, type) {
             wordCounts.set(word, (wordCounts.get(word) || 0) + 1);
         }
     }
-    // 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);
-    const suffix = topWords.length > 0 ? topWords.join(", ") : "various";
-    return `Consolidated ${type}: ${suffix}`;
+        .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}`;
 }

package/dist/lib/context-assembly.js

@@ -8,7 +8,7 @@ import { checkPromotion, discoverRelatedContext } from "@harmony/memory";
 // 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 = {
     reference: 1.0,
@@ -23,8 +23,8 @@ const TIER_BUDGET_ALLOCATION = {
     episode: 0.3,
     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;
 const GRAPH_WALK_MAX_ENTITIES = 10;
@@ -73,6 +73,50 @@ const QUERY_SYNONYMS = {
 function estimateTokens(text) {
     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) {
+    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
  */
@@ -398,8 +442,29 @@ export async function assembleContext(options) {
             memories: [],
         };
     }
+    // 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, cardLabels, graphRelations.length > 0 ? graphRelations : undefined);
         return { entity, score, reasons };
     });