@gethmy/mcp 2.2.3 → 2.3.0

package/dist/lib/memory-cleanup.js

@@ -0,0 +1,426 @@
+/**
+ * Unified Memory Cleanup
+ *
+ * Orchestrates a 5-stage cleanup pipeline: prune stale drafts, consolidate
+ * similar memories, detect orphans, detect duplicates, and backfill embeddings.
+ *
+ * All stages are non-fatal — individual failures are collected but never block
+ * the remaining stages. Defaults to dry-run mode (preview only).
+ */
+import { evaluateLifecycle } from "@harmony/memory";
+import { consolidateMemories, } from "./consolidation.js";
+import { findSimilarEntities } from "./graph-expansion.js";
+const ALL_STEPS = [
+    "prune",
+    "consolidate",
+    "orphans",
+    "duplicates",
+    "backfill",
+];
+// ---------------------------------------------------------------------------
+// Main orchestrator
+// ---------------------------------------------------------------------------
+export async function runMemoryCleanup(client, 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: "",
+    };
+    // Fetch all entities once (shared across steps)
+    let entities = [];
+    try {
+        const listResult = await client.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;
+    }
+    // Stage 1: Prune stale drafts
+    if (steps.includes("prune")) {
+        try {
+            report.steps.prune = runPruneStep(entities, maxAgeDays);
+            if (!dryRun) {
+                for (const item of report.steps.prune.items) {
+                    try {
+                        await client.deleteMemoryEntity(item.id);
+                        report.steps.prune.pruned++;
+                    }
+                    catch {
+                        // Non-fatal
+                    }
+                }
+                report.summary.actionsTaken += report.steps.prune.pruned;
+            }
+            report.summary.issuesFound += report.steps.prune.staleDraftsFound;
+        }
+        catch (err) {
+            report.errors.push({
+                step: "prune",
+                message: err.message,
+            });
+        }
+    }
+    // Stage 2: Consolidate similar memories
+    if (steps.includes("consolidate")) {
+        try {
+            const result = await consolidateMemories(client, 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,
+            });
+        }
+    }
+    // Stage 3: Detect orphans
+    if (steps.includes("orphans")) {
+        try {
+            report.steps.orphans = await runOrphanStep(client, entities, orphanAgeDays);
+            if (!dryRun) {
+                for (const item of report.steps.orphans.items) {
+                    try {
+                        await client.deleteMemoryEntity(item.id);
+                        report.steps.orphans.removed++;
+                    }
+                    catch {
+                        // Non-fatal
+                    }
+                }
+                report.summary.actionsTaken += report.steps.orphans.removed;
+            }
+            report.summary.issuesFound += report.steps.orphans.orphansFound;
+        }
+        catch (err) {
+            report.errors.push({
+                step: "orphans",
+                message: err.message,
+            });
+        }
+    }
+    // Stage 4: Detect duplicates
+    if (steps.includes("duplicates")) {
+        try {
+            report.steps.duplicates = await runDuplicateStep(client, entities, workspaceId, projectId);
+            if (!dryRun) {
+                for (const pair of report.steps.duplicates.pairs) {
+                    try {
+                        await client.deleteMemoryEntity(pair.removeId);
+                        report.steps.duplicates.resolved++;
+                    }
+                    catch {
+                        // Non-fatal
+                    }
+                }
+                report.summary.actionsTaken += report.steps.duplicates.resolved;
+            }
+            report.summary.issuesFound += report.steps.duplicates.duplicatePairsFound;
+        }
+        catch (err) {
+            report.errors.push({
+                step: "duplicates",
+                message: err.message,
+            });
+        }
+    }
+    // Stage 5: Backfill embeddings
+    if (steps.includes("backfill")) {
+        try {
+            if (dryRun) {
+                // In dry-run, just report that backfill would run
+                report.steps.backfill = {
+                    processed: 0,
+                    remaining: -1,
+                    errors: [],
+                };
+            }
+            else {
+                const result = await client.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;
+}
+// ---------------------------------------------------------------------------
+// Step implementations
+// ---------------------------------------------------------------------------
+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 lifecycle = evaluateLifecycle(entity);
+        stale.push({
+            id: entity.id,
+            title: entity.title,
+            ageDays: Math.round(ageDays),
+            decayScore: Math.round(lifecycle.decay.score * 100) / 100,
+        });
+    }
+    return { staleDraftsFound: stale.length, pruned: 0, items: stale };
+}
+async function runOrphanStep(client, entities, orphanAgeDays) {
+    const now = Date.now();
+    const result = { orphansFound: 0, removed: 0, items: [] };
+    // Pre-filter: only check entities that look like orphan candidates
+    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 client.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 {
+            // Non-fatal: skip this entity
+        }
+    }
+    return result;
+}
+async function runDuplicateStep(client, 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(client, 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;
+            // Keep the one with higher confidence, more accesses, or higher tier
+            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;
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const TIER_WEIGHTS = {
+    reference: 3,
+    episode: 2,
+    draft: 1,
+};
+function entityQualityScore(entity) {
+    return (entity.confidence +
+        (TIER_WEIGHTS[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 intersection = 0;
+    for (const w of wordsA) {
+        if (wordsB.has(w))
+            intersection++;
+    }
+    // Jaccard similarity
+    const union = wordsA.size + wordsB.size - intersection;
+    return union > 0 ? intersection / union : 0;
+}
+// ---------------------------------------------------------------------------
+// Health report renderer
+// ---------------------------------------------------------------------------
+function generateHealthReport(report) {
+    const mode = report.dryRun ? "Dry Run (preview)" : "Executed";
+    const lines = [
+        "# Memory Health Report\n",
+        `**Mode:** ${mode} | **Entities:** ${report.summary.totalEntities} | **Issues:** ${report.summary.issuesFound} | **Actions:** ${report.summary.actionsTaken}`,
+        "",
+    ];
+    // Prune
+    if (report.steps.prune) {
+        const p = report.steps.prune;
+        lines.push("## Stale Drafts");
+        if (p.staleDraftsFound === 0) {
+            lines.push("No stale drafts found.\n");
+        }
+        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("");
+        }
+    }
+    // Consolidate
+    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.\n`);
+        }
+        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("");
+        }
+    }
+    // Orphans
+    if (report.steps.orphans) {
+        const o = report.steps.orphans;
+        lines.push("## Orphaned Entities");
+        if (o.orphansFound === 0) {
+            lines.push("No orphans found.\n");
+        }
+        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("");
+        }
+    }
+    // Duplicates
+    if (report.steps.duplicates) {
+        const d = report.steps.duplicates;
+        lines.push("## Near-Duplicates");
+        if (d.duplicatePairsFound === 0) {
+            lines.push("No duplicates found.\n");
+        }
+        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("");
+        }
+    }
+    // Backfill
+    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}).\n`);
+        }
+        else {
+            lines.push(`Processed ${b.processed} entities. ${b.remaining} still need embeddings.\n`);
+        }
+    }
+    // Errors
+    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("\n");
+}

package/dist/lib/prompt-builder.js

@@ -301,7 +301,11 @@ export function generatePrompt(options) {
     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)`);
     // Output suggestions
     sections.push(`\n## Suggested Outputs`);
     roleFraming.outputSuggestions.forEach((s) => {

package/dist/lib/server.js

@@ -11,6 +11,7 @@ import { consolidateMemories } from "./consolidation.js";
 import { assembleContext, cacheManifest, computeRelevanceScore, getCachedManifest, mapToContextEntity, recordContextFeedback, trackSessionAssembly, } from "./context-assembly.js";
 import { autoExpandGraph } from "./graph-expansion.js";
 import { runLifecycleMaintenance } from "./lifecycle-maintenance.js";
+import { runMemoryCleanup } from "./memory-cleanup.js";
 import { onboardNewUser } from "./onboard.js";
 const memorySessions = new Map();
 function initMemorySession(cardId, agentIdentifier, agentName) {
@@ -1450,6 +1451,47 @@ const 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: [],
+        },
+    },
 };
 // Resource URIs
 const RESOURCES = [
@@ -3215,6 +3257,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(client, 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}`);
     }

package/dist/lib/skills.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { areSkillsInstalled } from "./config.js";
-export const SKILLS_VERSION = "3";
+export const SKILLS_VERSION = "4";
 const VERSION_MARKER_PREFIX = "<!-- skills-version:";
 /**
  * Legacy workflow prompt used by Codex, Cursor agents.
@@ -202,6 +202,30 @@ Do not start an agent session.
 
 ---
 
+## Step E: Auto-Detect Card for Implementation Tasks
+
+**IMPORTANT:** This step applies when you are about to implement a plan, feature, or fix
+that was NOT started via /hmy. Before writing any code, check if the work maps to an
+existing Harmony card.
+
+### When to run this check
+- User says "implement this plan", "build this feature", "fix this bug" (without /hmy)
+- You are about to execute a plan file
+- Skip if: the user already started with /hmy, or no Harmony MCP tools are available
+
+### Detection steps
+1. Call \`harmony_search_cards\` with keywords from the plan title or task description
+2. If a card matches (same feature/fix described), tell the user:
+   "This maps to card #N — starting a session to track progress."
+3. Call \`harmony_start_agent_session\` with \`moveToColumn: "In Progress"\`, \`addLabels: ["agent"]\`
+4. Track progress with \`harmony_update_agent_progress\` at milestones
+5. When done, call \`harmony_end_agent_session\` with \`status: "completed"\`, \`moveToColumn: "Review"\`
+
+### If no match
+Proceed normally without a session. No action needed.
+
+---
+
 ## Key Tools Reference
 
 **Cards:** \`harmony_get_card\`, \`harmony_get_card_by_short_id\`, \`harmony_search_cards\`, \`harmony_create_card\`, \`harmony_update_card\`, \`harmony_move_card\`, \`harmony_delete_card\`, \`harmony_assign_card\`

package/dist/lib/tui/setup.js

@@ -204,6 +204,17 @@ When given a card reference (e.g., #42 or a card name), follow this workflow:
 7. Update progress periodically with \`harmony_update_agent_progress\`
 8. When done, call \`harmony_end_agent_session\` and move to "Review"
 
+## Auto-Detect Card for Implementation Tasks
+
+Before implementing a plan or feature, check if it maps to an existing Harmony card:
+
+1. Use \`harmony_search_cards\` with keywords from the task description
+2. If a match is found, call \`harmony_start_agent_session\` (agentIdentifier: "claude-code", agentName: "Claude Code", moveToColumn: "In Progress", addLabels: ["agent"])
+3. Update progress with \`harmony_update_agent_progress\` at milestones
+4. When done, call \`harmony_end_agent_session\` with status: "completed", moveToColumn: "Review"
+
+Skip if: work was already started with a card reference, or no matching card exists.
+
 ## Available Harmony Tools
 
 - \`harmony_get_card\`, \`harmony_get_card_by_short_id\`, \`harmony_search_cards\` - Find cards

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/mcp",
-  "version": "2.2.3",
+  "version": "2.3.0",
   "description": "MCP server for Harmony Kanban board - enables AI coding agents to manage your boards",
   "publishConfig": {
     "access": "public"