@gethmy/mcp 2.2.3 → 2.2.4

package/dist/lib/context-assembly.js

@@ -4,7 +4,7 @@
  * Token-budget-aware context constructor that assembles relevant memories
  * for a given task, producing a manifest of what was included/excluded.
  */
-import { checkPromotion } from "@harmony/memory";
+import { checkPromotion, discoverRelatedContext } from "@harmony/memory";
 // Constants
 const DEFAULT_TOKEN_BUDGET = 4000;
 const MAX_TOKENS_PER_ENTITY = 500;
@@ -25,6 +25,48 @@ const TIER_BUDGET_ALLOCATION = {
 };
 // Minimum guaranteed slots per tier
 const MIN_REFERENCE_SLOTS = 3;
+// Graph walk configuration
+const GRAPH_WALK_MAX_DEPTH = 1;
+const GRAPH_WALK_MAX_ENTITIES = 10;
+const GRAPH_WALK_MIN_CONFIDENCE = 0.5;
+const GRAPH_WALK_SEED_COUNT = 5;
+// Query expansion configuration
+const MAX_QUERY_VARIATIONS = 4;
+// LLM re-ranking configuration
+const RERANK_CLUSTER_THRESHOLD = 0.05;
+const RERANK_TOP_N = 10;
+const RERANK_MIN_CANDIDATES = 5;
+// Graph walk relation-type bonuses for relevance scoring
+const RELATION_BONUSES = {
+    depends_on: 0.15,
+    resolved_by: 0.2,
+    relates_to: 0.1,
+    implements: 0.15,
+    blocks: 0.15,
+    references: 0.1,
+    extends: 0.1,
+    caused_by: 0.15,
+};
+// Synonym map for query expansion (common dev term variations)
+// NOTE: Avoid circular references (auth->login, login->auth) — first synonym
+// is used for replacement, so each key should expand to non-overlapping terms.
+const QUERY_SYNONYMS = {
+    auth: ["authentication", "authorization", "session"],
+    authentication: ["auth", "session", "sign-in"],
+    login: ["sign-in", "authentication", "session"],
+    bug: ["error", "issue", "defect", "problem"],
+    error: ["exception", "failure", "issue"],
+    fix: ["resolve", "patch", "repair", "correct"],
+    deploy: ["deployment", "release", "ship", "publish"],
+    test: ["testing", "spec", "assertion", "verify"],
+    config: ["configuration", "settings", "setup"],
+    db: ["database", "storage", "persistence"],
+    database: ["storage", "persistence", "data store"],
+    api: ["endpoint", "route", "service"],
+    ui: ["frontend", "component", "view"],
+    perf: ["performance", "speed", "latency"],
+    performance: ["speed", "latency", "optimization"],
+};
 /**
  * Estimate token count (rough: 1 token per 4 chars)
  */
@@ -68,10 +110,65 @@ function truncateContent(content, maxTokens) {
     }
     return { text: result, truncated: true };
 }
+/**
+ * Escape regex metacharacters in a string for safe use in RegExp constructor.
+ */
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Expand a query into multiple search variations using synonym substitution.
+ * Returns the original query plus up to 3 additional variations (4 total).
+ */
+export function expandQuery(taskContext) {
+    const queries = [taskContext];
+    const lowerQueries = [taskContext.toLowerCase()];
+    const words = taskContext
+        .toLowerCase()
+        .split(/\W+/)
+        .filter((w) => w.length > 2);
+    // Find words that have synonym expansions
+    const expandableWords = words.filter((w) => QUERY_SYNONYMS[w]);
+    for (const word of expandableWords) {
+        const synonyms = QUERY_SYNONYMS[word];
+        if (!synonyms)
+            continue;
+        // Create a variation by replacing the word with its first synonym
+        const variation = taskContext.replace(new RegExp(`\\b${escapeRegex(word)}\\b`, "gi"), synonyms[0]);
+        const lowerVariation = variation.toLowerCase();
+        if (lowerVariation !== taskContext.toLowerCase() &&
+            !lowerQueries.includes(lowerVariation)) {
+            queries.push(variation);
+            lowerQueries.push(lowerVariation);
+        }
+        if (queries.length >= MAX_QUERY_VARIATIONS)
+            break;
+    }
+    // Also extract key noun phrases as a compact query
+    if (words.length >= 3) {
+        const keyPhrases = words
+            .filter((w) => ![
+            "the",
+            "and",
+            "for",
+            "with",
+            "this",
+            "that",
+            "from",
+            "into",
+        ].includes(w))
+            .slice(0, 4)
+            .join(" ");
+        if (!lowerQueries.includes(keyPhrases)) {
+            queries.push(keyPhrases);
+        }
+    }
+    return queries.slice(0, MAX_QUERY_VARIATIONS);
+}
 /**
  * Compute relevance score for an entity against task context.
  */
-export function computeRelevanceScore(entity, taskContext, cardLabels) {
+export function computeRelevanceScore(entity, taskContext, cardLabels, graphRelations) {
     const reasons = [];
     let score = 0;
     // 0. DB hybrid search signal (RRF score from FTS + vector fusion)
@@ -150,8 +247,26 @@ export function computeRelevanceScore(entity, taskContext, cardLabels) {
         score += 0.1;
         reasons.push("procedure_boost");
     }
+    // 7. Graph walk relation bonus: boost entities discovered via knowledge graph
+    if (graphRelations && graphRelations.length > 0) {
+        const entityRelations = graphRelations.filter((r) => r.source_id === entity.id || r.target_id === entity.id);
+        if (entityRelations.length > 0) {
+            // Take the highest relation bonus (don't stack all of them)
+            let bestBonus = 0;
+            let bestRelType = "";
+            for (const rel of entityRelations) {
+                const bonus = RELATION_BONUSES[rel.relation_type] ?? 0.1;
+                if (bonus > bestBonus) {
+                    bestBonus = bonus;
+                    bestRelType = rel.relation_type;
+                }
+            }
+            score += bestBonus;
+            reasons.push(`graph_walk(${bestRelType})`);
+        }
+    }
     // Clamp raw score to 0-1 range before applying tier weight
-    score = Math.min(score, 1.0);
+    score = Math.max(0, Math.min(score, 1.0));
     // Apply tier weight
     const tierWeight = TIER_WEIGHTS[entity.memory_tier];
     score *= tierWeight;
@@ -161,7 +276,7 @@ export function computeRelevanceScore(entity, taskContext, cardLabels) {
  * Assemble context from knowledge graph entities with token budget management.
  */
 export async function assembleContext(options) {
-    const { workspaceId, projectId, taskContext, cardLabels = [], tokenBudget = DEFAULT_TOKEN_BUDGET, client, } = options;
+    const { workspaceId, projectId, taskContext, cardLabels = [], tokenBudget = DEFAULT_TOKEN_BUDGET, client, graphWalkEnabled = true, queryExpansionEnabled = true, enableLlmReranking = false, rerankFn, } = options;
     const assemblyId = generateAssemblyId();
     const manifest = {
         assemblyId,
@@ -176,18 +291,30 @@ export async function assembleContext(options) {
             reference: { count: 0, tokens: 0 },
         },
     };
-    // Fetch candidate entities: search by task context + list by project
-    let candidates = [];
-    try {
-        // Full-text search by task context
-        const searchResult = await client.searchMemoryEntities(workspaceId, taskContext, { project_id: projectId, limit: 30 });
-        if (searchResult.entities?.length > 0) {
-            candidates = searchResult.entities.map(mapToContextEntity);
+    // Fetch candidate entities: search by task context (with query expansion) + list by project
+    const candidates = [];
+    // P1: Query expansion — search with multiple query variations to catch synonym mismatches
+    const queries = queryExpansionEnabled
+        ? expandQuery(taskContext)
+        : [taskContext];
+    const searchResults = await Promise.allSettled(queries.map((query) => client.searchMemoryEntities(workspaceId, query, {
+        project_id: projectId,
+        limit: 30,
+    })));
+    const candidateIds = new Set();
+    for (const result of searchResults) {
+        if (result.status !== "fulfilled")
+            continue;
+        if (result.value.entities?.length > 0) {
+            for (const raw of result.value.entities) {
+                const entity = mapToContextEntity(raw);
+                if (!candidateIds.has(entity.id)) {
+                    candidateIds.add(entity.id);
+                    candidates.push(entity);
+                }
+            }
         }
     }
-    catch {
-        // Search failed, fall back to listing
-    }
     // Also fetch by project scope if we have few candidates
     if (candidates.length < 10 && projectId) {
         try {
@@ -197,11 +324,13 @@ export async function assembleContext(options) {
                 limit: 30,
             });
             if (listResult.entities?.length > 0) {
-                const existingIds = new Set(candidates.map((c) => c.id));
-                const additional = listResult.entities
-                    .map(mapToContextEntity)
-                    .filter((e) => !existingIds.has(e.id));
-                candidates.push(...additional);
+                for (const raw of listResult.entities) {
+                    const entity = mapToContextEntity(raw);
+                    if (!candidateIds.has(entity.id)) {
+                        candidateIds.add(entity.id);
+                        candidates.push(entity);
+                    }
+                }
             }
         }
         catch {
@@ -218,17 +347,50 @@ export async function assembleContext(options) {
                 limit: 20,
             });
             if (wsResult.entities?.length > 0) {
-                const existingIds = new Set(candidates.map((c) => c.id));
-                const additional = wsResult.entities
-                    .map(mapToContextEntity)
-                    .filter((e) => !existingIds.has(e.id));
-                candidates.push(...additional);
+                for (const raw of wsResult.entities) {
+                    const entity = mapToContextEntity(raw);
+                    if (!candidateIds.has(entity.id)) {
+                        candidateIds.add(entity.id);
+                        candidates.push(entity);
+                    }
+                }
             }
         }
         catch {
             // Continue with what we have
         }
     }
+    // P0: Graph walk enrichment — discover related entities via knowledge graph
+    let graphRelations = [];
+    if (graphWalkEnabled && candidates.length > 0) {
+        try {
+            // Take top candidates by RRF score (or first N if no RRF scores)
+            const seedCandidates = [...candidates]
+                .sort((a, b) => (b.rrf_score ?? 0) - (a.rrf_score ?? 0))
+                .slice(0, GRAPH_WALK_SEED_COUNT);
+            const seedIds = seedCandidates.map((c) => c.id);
+            const walkResult = await discoverRelatedContext(client, seedIds, GRAPH_WALK_MAX_DEPTH, GRAPH_WALK_MAX_ENTITIES, GRAPH_WALK_MIN_CONFIDENCE);
+            graphRelations = walkResult.relations;
+            // Add discovered entities to candidate pool (skip those already present)
+            const newEntityIds = walkResult.entities
+                .filter((e) => !candidateIds.has(e.id))
+                .map((e) => e.id);
+            if (newEntityIds.length > 0) {
+                // Fetch full entity data in parallel (graph walk only returns summary fields)
+                const fetchResults = await Promise.allSettled(newEntityIds.map((id) => client.getMemoryEntity(id)));
+                for (const result of fetchResults) {
+                    if (result.status !== "fulfilled" || !result.value.entity)
+                        continue;
+                    const mapped = mapToContextEntity(result.value.entity);
+                    candidateIds.add(mapped.id);
+                    candidates.push(mapped);
+                }
+            }
+        }
+        catch {
+            // Graph walk failed, continue with search-only candidates
+        }
+    }
     if (candidates.length === 0) {
         return {
             context: "",
@@ -236,13 +398,43 @@ export async function assembleContext(options) {
             memories: [],
         };
     }
-    // Score all candidates
+    // Score all candidates (pass graph relations for relation-type bonuses)
     const scored = candidates.map((entity) => {
-        const { score, reasons } = computeRelevanceScore(entity, taskContext, cardLabels);
+        const { score, reasons } = computeRelevanceScore(entity, taskContext, cardLabels, graphRelations.length > 0 ? graphRelations : undefined);
         return { entity, score, reasons };
     });
     // Sort by score descending
     scored.sort((a, b) => b.score - a.score);
+    // P2: Optional LLM re-ranking when top scores are clustered
+    if (enableLlmReranking &&
+        rerankFn &&
+        scored.length >= RERANK_MIN_CANDIDATES) {
+        const topN = scored.slice(0, RERANK_TOP_N);
+        const scoreRange = topN[0].score - topN[topN.length - 1].score;
+        // Only re-rank when scores are tightly clustered
+        if (scoreRange <= RERANK_CLUSTER_THRESHOLD) {
+            try {
+                const rerankCandidates = topN.map((s) => ({
+                    id: s.entity.id,
+                    title: s.entity.title,
+                    snippet: s.entity.content.slice(0, 200),
+                }));
+                const rerankedIds = await rerankFn(taskContext, rerankCandidates);
+                // Reorder based on LLM ranking
+                const idOrder = new Map(rerankedIds.map((id, i) => [id, i]));
+                topN.sort((a, b) => {
+                    const aIdx = idOrder.get(a.entity.id) ?? 999;
+                    const bIdx = idOrder.get(b.entity.id) ?? 999;
+                    return aIdx - bIdx;
+                });
+                // Splice reranked items back in
+                scored.splice(0, topN.length, ...topN);
+            }
+            catch {
+                // Re-ranking failed, continue with static ordering
+            }
+        }
+    }
     // Reserve dedicated procedure budget, allocate remaining to tiers
     const procedureBudget = Math.floor(tokenBudget * PROCEDURE_BUDGET_FRACTION);
     const remainingBudget = tokenBudget - procedureBudget;

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.2.4",
   "description": "MCP server for Harmony Kanban board - enables AI coding agents to manage your boards",
   "publishConfig": {
     "access": "public"