@gethmy/mcp 2.8.4 → 2.8.6

package/dist/cli.js

@@ -1123,10 +1123,14 @@ function getDisplayLinkType(linkType, direction) {
 }
 // ../harmony-shared/dist/commentSerializer.js
 var CONFLICT_INSTRUCTION = "When two comments conflict, prefer the latest created_at, UNLESS a later " + "comment explicitly confirms or restates the earlier finding. Evaluate " + "substance, not just recency. Cite the comment id(s) you relied on.";
+function sanitizeHeaderField(value) {
+  return value.replace(/[\]\r\n|<>]/g, " ").trim() || "—";
+}
 function authorLabel(c) {
   if (c.author_type === "agent")
     return "AI agent";
-  return c.author?.full_name || c.author?.email || "teammate";
+  const raw = c.author?.full_name || "teammate";
+  return sanitizeHeaderField(raw);
 }
 function criticalIds(comments) {
   const keep = new Set;
@@ -1183,9 +1187,15 @@ function serializeCommentThread(comments, options = {}) {
     if (c.resolved_at)
       tags.push("resolved");
     const tagStr = tags.length ? ` | ${tags.join(" | ")}` : "";
-    const header = `[${ref(c.id)} | ${c.author_type} | ${authorLabel(c)} | ${c.comment_type} | ${c.created_at}${tagStr}]`;
-    lines.push({ at: c.created_at, text: `${header}
-${c.body.trim()}` });
+    const header = `[${sanitizeHeaderField(ref(c.id))} | ${sanitizeHeaderField(c.author_type)} | ${authorLabel(c)} | ${sanitizeHeaderField(c.comment_type)} | ${sanitizeHeaderField(c.created_at)}${tagStr}]`;
+    const fencedBody = c.body.trim().replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+    lines.push({
+      at: c.created_at,
+      text: `${header}
+<comment-body>
+${fencedBody}
+</comment-body>`
+    });
   }
   for (const a of activity) {
     const actor = a.actor ? `${a.actor} ` : "";
@@ -1710,6 +1720,10 @@ class HarmonyApiClient {
       params.set("type", options.type);
     if (options?.limit !== undefined)
       params.set("limit", String(options.limit));
+    for (const tag of options?.tags ?? [])
+      params.append("tags", tag);
+    if (options?.include_superseded)
+      params.set("include_superseded", "true");
     return this.request("GET", `/memory/search?${params.toString()}`);
   }
   async getVaultIndex(options) {
@@ -2027,7 +2041,6 @@ function resolveAgentIdentity(info) {
 }
 var AUTO_START_TRIGGERS = new Set([
   "harmony_generate_prompt",
-  "harmony_update_card",
   "harmony_create_subtask",
   "harmony_toggle_subtask",
   "harmony_update_subtask"
@@ -2059,6 +2072,10 @@ async function trackActivity(cardId, options) {
   const client3 = options?.client ?? clientGetter?.();
   if (!client3)
     return;
+  const info = clientInfoGetter?.() ?? null;
+  if (!info?.name)
+    return;
+  const { agentIdentifier, agentName } = resolveAgentIdentity(info);
   const toEnd = [];
   for (const [otherCardId, session] of activeSessions) {
     if (otherCardId !== cardId && !session.isExplicit) {
@@ -2068,8 +2085,6 @@ async function trackActivity(cardId, options) {
   for (const otherCardId of toEnd) {
     await autoEndSession(client3, otherCardId, "completed");
   }
-  const info = clientInfoGetter?.() ?? null;
-  const { agentIdentifier, agentName } = resolveAgentIdentity(info);
   try {
     await client3.startAgentSession(cardId, {
       agentIdentifier,
@@ -2189,6 +2204,90 @@ async function autoExpandGraph(client3, entityId, title, content, _tags, workspa
     return { relationsCreated: 0 };
   }
 }
+async function findSimilarEntities(client3, title, content, workspaceId, options) {
+  const contentSnippet = content.slice(0, 200).trim();
+  const query = [title, contentSnippet].filter(Boolean).join(" ");
+  try {
+    const { entities } = await client3.searchMemoryEntities(workspaceId, query, {
+      project_id: options?.projectId,
+      limit: options?.limit ?? 20,
+      type: options?.type
+    });
+    const minScore = options?.minRrfScore ?? 0;
+    const excludeSet = new Set(options?.excludeIds || []);
+    return entities.filter((e) => {
+      if (excludeSet.has(e.id))
+        return false;
+      if (minScore > 0 && (e.rrf_score ?? 0) < minScore)
+        return false;
+      return true;
+    });
+  } catch {
+    return [];
+  }
+}
+var SUPERSEDE_RRF_THRESHOLD = 0.029;
+var SUPERSEDE_TITLE_OVERLAP = 0.5;
+var TITLE_STOPWORDS = new Set([
+  "a",
+  "an",
+  "the",
+  "and",
+  "or",
+  "of",
+  "to",
+  "in",
+  "on",
+  "for",
+  "with",
+  "is",
+  "are",
+  "be",
+  "by",
+  "at",
+  "as"
+]);
+function significantTitleTokens(title) {
+  return new Set(title.toLowerCase().replace(/[^a-z0-9\s]/g, " ").split(/\s+/).filter((t) => t.length > 2 && !TITLE_STOPWORDS.has(t)));
+}
+function jaccard(a, b) {
+  if (a.size === 0 || b.size === 0)
+    return 0;
+  let intersection = 0;
+  for (const t of a)
+    if (b.has(t))
+      intersection++;
+  return intersection / (a.size + b.size - intersection);
+}
+async function findSupersedeCandidates(client3, title, content, type, workspaceId, options) {
+  const rrfThreshold = options?.rrfThreshold ?? SUPERSEDE_RRF_THRESHOLD;
+  const titleOverlap = options?.titleOverlap ?? SUPERSEDE_TITLE_OVERLAP;
+  const candidateTokens = significantTitleTokens(title);
+  try {
+    const hits = await findSimilarEntities(client3, title, content, workspaceId, {
+      projectId: options?.projectId,
+      type,
+      limit: options?.limit ?? 10,
+      minRrfScore: rrfThreshold
+    });
+    return hits.filter((e) => {
+      if (options?.scope && e.scope !== undefined) {
+        if (e.scope !== options.scope)
+          return false;
+      }
+      if (e.superseded_at) {
+        return false;
+      }
+      return jaccard(candidateTokens, significantTitleTokens(e.title)) >= titleOverlap;
+    }).map((e) => ({
+      id: e.id,
+      title: e.title,
+      score: e.rrf_score ?? 0
+    }));
+  } catch {
+    return [];
+  }
+}
 
 // src/memory-floor.ts
 var STOP_WORDS = new Set([
@@ -2327,6 +2426,10 @@ var DEFAULT_WEIGHTS = {
   recency: 0.25,
   importance: 0.2
 };
+var USAGE_BUMP_SCALE = 0.6;
+var USAGE_BUMP_MAX = 2;
+var FEEDBACK_BUMP_SCALE = 0.8;
+var FEEDBACK_BUMP_MAX = 2;
 var TYPE_TAU_SECONDS = {
   preference: Number.POSITIVE_INFINITY,
   pattern: 60 * 60 * 24 * 180,
@@ -2382,8 +2485,37 @@ function recencyDecay(lastAccessedAt, createdAt, type, now) {
   const dtSec = Math.max(0, (now.getTime() - t) / 1000);
   return clamp01(Math.exp(-dtSec / tau));
 }
-function importanceNorm(raw, type) {
+function baseImportance(raw, type) {
   let v = typeof raw === "number" ? raw : TYPE_IMPORTANCE_DEFAULT[type] ?? 5;
+  if (v < 1)
+    v = 1;
+  if (v > 10)
+    v = 10;
+  return v;
+}
+function usageBump(accessCount) {
+  const n = typeof accessCount === "number" && accessCount > 0 ? accessCount : 0;
+  if (n === 0)
+    return 0;
+  return Math.min(USAGE_BUMP_MAX, USAGE_BUMP_SCALE * Math.log(1 + n));
+}
+function feedbackBump(feedback) {
+  const up = typeof feedback?.up === "number" ? feedback.up : 0;
+  const down = typeof feedback?.down === "number" ? feedback.down : 0;
+  const net = up - down;
+  if (net === 0)
+    return 0;
+  const raw = FEEDBACK_BUMP_SCALE * Math.sign(net) * Math.log(1 + Math.abs(net));
+  if (raw > FEEDBACK_BUMP_MAX)
+    return FEEDBACK_BUMP_MAX;
+  if (raw < -FEEDBACK_BUMP_MAX)
+    return -FEEDBACK_BUMP_MAX;
+  return raw;
+}
+function effectiveImportance(entity) {
+  const base = baseImportance(entity.importance, entity.type);
+  const bump = usageBump(entity.access_count) + feedbackBump(entity.metadata?.feedback);
+  let v = base + bump;
   if (v < 1)
     v = 1;
   if (v > 10)
@@ -2397,7 +2529,7 @@ function rescore(entities, options = {}) {
   const scored = entities.map((entity) => {
     const relevance = clamp01(relevanceMap.get(entity.id ?? "") ?? 0.5);
     const recency = recencyDecay(entity.last_accessed_at, entity.created_at, entity.type, now);
-    const importance = importanceNorm(entity.importance, entity.type);
+    const importance = effectiveImportance(entity);
     const score = w.relevance * relevance + w.recency * recency + w.importance * importance;
     return { entity, relevance, recency, importance, score };
   });
@@ -2410,6 +2542,11 @@ function rescore(entities, options = {}) {
   });
   return scored;
 }
+function filterByMinConfidence(entities, minConfidence) {
+  if (typeof minConfidence !== "number")
+    return entities;
+  return entities.filter((e) => typeof e.confidence === "number" && e.confidence >= minConfidence);
+}
 function relevanceFromRank(ranked, decay = 10) {
   const out = new Map;
   ranked.forEach((entity, rank) => {
@@ -2442,6 +2579,82 @@ function fitToBudget(scored, budgetTokens) {
   }
   return out;
 }
+function mergeFeedback(existing, vote) {
+  const up = typeof existing?.up === "number" && existing.up > 0 ? existing.up : 0;
+  const down = typeof existing?.down === "number" && existing.down > 0 ? existing.down : 0;
+  return vote === "up" ? { up: up + 1, down } : { up, down: down + 1 };
+}
+
+// src/memory-provenance.ts
+function buildOrigin(input) {
+  const origin = { source: input.source };
+  if (input.source_card_id)
+    origin.source_card_id = input.source_card_id;
+  if (input.source_session_id)
+    origin.source_session_id = input.source_session_id;
+  if (input.author)
+    origin.author = input.author;
+  if (input.source_trust)
+    origin.source_trust = input.source_trust;
+  return origin;
+}
+function defaultConfidenceForSource(input) {
+  if (input.source_trust === "document")
+    return 0.9;
+  if (input.source_trust === "manual")
+    return 0.9;
+  switch (input.source) {
+    case "manual":
+      return 0.9;
+    case "assistant":
+      return 0.8;
+    case "agent-run":
+      return 0.6;
+    case "import":
+      return 0.6;
+    default:
+      return 0.7;
+  }
+}
+var TYPE_IMPORTANCE_DEFAULT2 = {
+  preference: 9,
+  lesson: 8,
+  decision: 8,
+  pattern: 7,
+  solution: 7,
+  procedure: 7,
+  error: 5,
+  context: 5,
+  task: 5,
+  agent: 5,
+  relationship: 6,
+  commitment: 7,
+  project: 6,
+  handoff: 6
+};
+var FILE_PATH = /(?:[\w.-]+\/){1,}[\w.-]+\.[a-z]{1,4}\b|(?:[\w-]+\/){2,}[\w-]+/i;
+var GUIDANCE_SECTION = /\b(why|how to apply|how to use|takeaway|root cause)\b/i;
+var PROPER_NOUN = /`[^`]+`|\b[A-Z][a-z0-9]+[A-Z][A-Za-z0-9]*\b|\b[a-z]+_[a-z][\w]*\b/;
+function signalDensity(content) {
+  let n = 0;
+  if (FILE_PATH.test(content))
+    n += 1;
+  if (GUIDANCE_SECTION.test(content))
+    n += 1;
+  if (PROPER_NOUN.test(content))
+    n += 1;
+  return n;
+}
+function importanceWithSignalBump(type, content) {
+  const base = TYPE_IMPORTANCE_DEFAULT2[type] ?? 5;
+  const bump = Math.min(2, signalDensity(content));
+  const v = base + bump;
+  if (v < 1)
+    return 1;
+  if (v > 10)
+    return 10;
+  return v;
+}
 
 // src/memory-session.ts
 var SESSION_SCOPE_PREFIX = "session:";
@@ -2462,6 +2675,49 @@ function sessionScopeFor(agentSessionId) {
   return `${SESSION_SCOPE_PREFIX}${agentSessionId}`;
 }
 
+// src/memory-tags.ts
+var CARD_REF = /^card[\s:#-]+(\d+)$/;
+function normalizeTag(tag) {
+  const cleaned = tag.trim().toLowerCase().replace(/\s+/g, " ");
+  const cardMatch = cleaned.match(CARD_REF);
+  if (cardMatch) {
+    return `card:${cardMatch[1]}`;
+  }
+  return cleaned;
+}
+function normalizeTags(tags) {
+  const seen = new Set;
+  const out = [];
+  for (const raw of tags) {
+    const norm = normalizeTag(raw);
+    if (!norm || seen.has(norm))
+      continue;
+    seen.add(norm);
+    out.push(norm);
+  }
+  return out;
+}
+function lintTags(tags) {
+  const suggestions = [];
+  for (const tag of tags) {
+    const norm = normalizeTag(tag);
+    if (norm === tag)
+      continue;
+    let reason;
+    if (CARD_REF.test(tag.trim().toLowerCase()) && norm.startsWith("card:")) {
+      reason = "non-canonical card ref; use 'card:<n>'";
+    } else if (tag !== tag.trim() || /\s{2,}/.test(tag)) {
+      reason = "whitespace; trim and collapse";
+    } else if (tag !== tag.toLowerCase()) {
+      reason = "case variant; use lowercase";
+    } else {
+      reason = "normalize to canonical form";
+    }
+    suggestions.push({ tag, suggestion: norm, reason });
+  }
+  return suggestions;
+}
+
 // src/onboard.ts
 async function onboardNewUser(params) {
   const {
@@ -3679,6 +3935,10 @@ var TOOLS = {
         projectId: {
           type: "string",
           description: "Project ID (optional, required if scope is 'project')"
+        },
+        supersedeId: {
+          type: "string",
+          description: "Optional. ID of an existing memory entity to soft-supersede with " + "this new one (sets its superseded_by/superseded_at). Use after a " + "previous harmony_remember returned a `similar` candidate you want " + "to replace. Reversible; never deletes or merges content. The new " + "entity is always created regardless."
         }
       },
       required: ["title", "content"]
@@ -3852,6 +4112,49 @@ var TOOLS = {
       required: ["sourceId", "targetId", "relationType"]
     }
   },
+  harmony_suggest_relations: {
+    description: "Suggest existing memory entities that look related to a given entity, using the same hybrid vector+FTS similarity as recall (card #281). Read-only: it NEVER creates relations — it only proposes candidates for a caller (human/agent) to relate explicitly via harmony_relate. Use to surface 'these look related — link?' candidates that would activate graph-walk retrieval.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        entityId: {
+          type: "string",
+          description: "The entity UUID to find related candidates for"
+        },
+        limit: {
+          type: "number",
+          description: "Max suggestions to return (default: 5)"
+        },
+        workspaceId: {
+          type: "string",
+          description: "Workspace ID (optional if context set)"
+        },
+        projectId: {
+          type: "string",
+          description: "Project ID (optional)"
+        }
+      },
+      required: ["entityId"]
+    }
+  },
+  harmony_recall_feedback: {
+    description: "Record a \uD83D\uDC4D/\uD83D\uDC4E on a recalled memory so future recalls can rank it better or worse. Non-destructive: stores a counter at metadata.feedback={up,down} and only affects ranking — it never deletes, hides, or supersedes the memory. Call after a recall when a memory proved useful (vote 'up') or misleading/irrelevant (vote 'down').",
+    inputSchema: {
+      type: "object",
+      properties: {
+        entityId: {
+          type: "string",
+          description: "Memory entity UUID that was recalled"
+        },
+        vote: {
+          type: "string",
+          enum: ["up", "down"],
+          description: "'up' if the memory was useful, 'down' if it was misleading or irrelevant"
+        }
+      },
+      required: ["entityId", "vote"]
+    }
+  },
   harmony_memory_search: {
     description: "Full-text and semantic search across the knowledge base. Uses hybrid vector+FTS search (when embeddings are available) for best results. Returns entities ranked by relevance.",
     inputSchema: {
@@ -4929,7 +5232,9 @@ async function handleToolCall(name, args, deps) {
         throw new Error("No workspace specified. Use harmony_set_workspace_context or provide workspaceId.");
       }
       const entityType = args.type || "context";
-      const entityTags = args.tags || [];
+      const rawTags = args.tags || [];
+      const entityTags = normalizeTags(rawTags);
+      const tagSuggestions = lintTags(rawTags);
       const activeMemSession = getActiveMemorySession();
       const entityScope = resolveSessionScope(args.scope, activeMemSession?.agentSessionId) || "project";
       const floorRejection = validateMemoryQuality({
@@ -4943,24 +5248,59 @@ async function handleToolCall(name, args, deps) {
       if (floorRejection) {
         throw new Error(`Memory rejected by Utility Floor [${floorRejection.rule}]: ${floorRejection.message}`);
       }
-      const callerImportance = args.importance !== undefined ? z.number().int().min(1).max(10).parse(args.importance) : undefined;
+      const sourceTrust = args.source_trust;
+      const source = activeMemSession ? activeMemSession.agentIdentifier === "assistant" ? "assistant" : "agent-run" : "manual";
+      const origin = buildOrigin({
+        source,
+        source_card_id: activeMemSession?.cardId,
+        source_session_id: activeMemSession?.agentSessionId,
+        author: activeMemSession?.agentIdentifier ?? "user",
+        source_trust: sourceTrust
+      });
+      const callerMetadata = args.metadata;
+      const metadataWithOrigin = {
+        ...callerMetadata ?? {},
+        origin
+      };
+      const confidence = args.confidence !== undefined ? z.number().min(0).max(1).parse(args.confidence) : defaultConfidenceForSource({ source, source_trust: sourceTrust });
+      const importance = args.importance !== undefined ? z.number().int().min(1).max(10).parse(args.importance) : importanceWithSignalBump(entityType, content);
+      const projectIdForWrite = args.projectId || deps.getActiveProjectId() || undefined;
+      let similar = [];
+      if (!isSessionScope(entityScope)) {
+        similar = await findSupersedeCandidates(client3, title, content, entityType, workspaceId, { projectId: projectIdForWrite, scope: entityScope });
+      }
       const result = await client3.createMemoryEntity({
         workspace_id: workspaceId,
-        project_id: args.projectId || deps.getActiveProjectId() || undefined,
+        project_id: projectIdForWrite,
         type: entityType,
         scope: entityScope,
         memory_tier: args.tier || undefined,
         title,
         content,
-        metadata: args.metadata,
-        confidence: args.confidence !== undefined ? z.number().min(0).max(1).parse(args.confidence) : undefined,
-        importance: callerImportance,
+        metadata: metadataWithOrigin,
+        confidence,
+        importance,
         tags: entityTags.length > 0 ? entityTags : undefined,
         agent_identifier: activeMemSession?.agentIdentifier || undefined
       });
+      const supersedeId = args.supersedeId;
+      const newEntityId = result.entity?.id;
+      let superseded;
+      if (supersedeId && newEntityId) {
+        try {
+          await client3.updateMemoryEntity(supersedeId, {
+            superseded_by: newEntityId,
+            superseded_at: new Date().toISOString()
+          });
+          superseded = supersedeId;
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          console.debug(`[harmony_remember] supersede ${supersedeId} failed: ${msg}`);
+        }
+      }
       const newEntityIdForGraph = result.entity?.id;
       if (newEntityIdForGraph) {
-        autoExpandGraph(client3, newEntityIdForGraph, title, content, entityTags, workspaceId, args.projectId || deps.getActiveProjectId() || undefined).catch(() => {});
+        autoExpandGraph(client3, newEntityIdForGraph, title, content, entityTags, workspaceId, projectIdForWrite).catch(() => {});
       }
       if (activeMemSession) {
         appendMemoryAction(activeMemSession.cardId, `Stored memory: ${title}`);
@@ -4968,7 +5308,10 @@ async function handleToolCall(name, args, deps) {
       }
       return {
         success: true,
-        ...result
+        ...result,
+        ...similar.length > 0 ? { similar } : {},
+        ...superseded ? { superseded } : {},
+        ...tagSuggestions.length > 0 ? { tagSuggestions } : {}
       };
     }
     case "harmony_recall": {
@@ -4990,26 +5333,22 @@ async function handleToolCall(name, args, deps) {
       let entities;
       let relevanceMap;
       if (queryText) {
+        const requestedTags = args.tags;
         const searchResult = await client3.searchMemoryEntities(workspaceId, queryText, {
           project_id: projectId,
           type: args.type,
-          limit: fetchLimit
+          limit: fetchLimit,
+          tags: requestedTags && requestedTags.length > 0 ? requestedTags : undefined,
+          include_superseded: includeSuperseded
         });
         entities = searchResult.entities ?? [];
-        const requestedTags = args.tags;
         const minConfidence = args.minConfidence;
         if (userScopeFilter) {
           entities = entities.filter((e) => e?.scope === userScopeFilter);
         } else if (excludeSessionFromLongTerm) {
           entities = entities.filter((e) => !isSessionScope(e?.scope));
         }
-        if (requestedTags && requestedTags.length > 0) {
-          const wanted = new Set(requestedTags);
-          entities = entities.filter((e) => (e?.tags ?? []).some((t) => wanted.has(t)));
-        }
-        if (typeof minConfidence === "number") {
-          entities = entities.filter((e) => typeof e?.confidence === "number" && e.confidence >= minConfidence);
-        }
+        entities = filterByMinConfidence(entities, minConfidence);
         if (!includeSuperseded) {
           entities = entities.filter((e) => !e?.superseded_at);
         }
@@ -5040,16 +5379,10 @@ async function handleToolCall(name, args, deps) {
         trimmed = fitToBudget(trimmed, budgetTokens);
       }
       if (trimmed.length > 0) {
-        Promise.all(trimmed.map(async ({ entity }) => {
-          try {
-            await client3.updateMemoryEntity(entity.id, {
-              metadata: {
-                ...entity.metadata || {},
-                _last_recall: new Date().toISOString()
-              }
-            });
-          } catch (_) {}
-        })).catch(() => {});
+        const touchIds = trimmed.map(({ entity }) => entity?.id).filter((id) => typeof id === "string");
+        if (touchIds.length > 0) {
+          client3.batchTouchMemoryEntities(touchIds).catch(() => {});
+        }
       }
       let sessionEntities = [];
       if (excludeSessionFromLongTerm && recallMemSession?.agentSessionId) {
@@ -5116,8 +5449,12 @@ async function handleToolCall(name, args, deps) {
         updates.type = args.type;
       if (args.scope !== undefined)
         updates.scope = args.scope;
-      if (args.tags !== undefined)
-        updates.tags = args.tags;
+      let updateTagSuggestions = [];
+      if (args.tags !== undefined) {
+        const updateRawTags = args.tags;
+        updates.tags = normalizeTags(updateRawTags);
+        updateTagSuggestions = lintTags(updateRawTags);
+      }
       if (args.confidence !== undefined)
         updates.confidence = z.number().min(0).max(1).parse(args.confidence);
       if (args.metadata !== undefined)
@@ -5129,7 +5466,11 @@ async function handleToolCall(name, args, deps) {
         appendMemoryAction(updateMemSession.cardId, `Updated memory: ${updateTitle}`);
         flushMemoryActions(client3, updateMemSession.cardId).catch(() => {});
       }
-      return { success: true, ...result };
+      return {
+        success: true,
+        ...result,
+        ...updateTagSuggestions.length > 0 ? { tagSuggestions: updateTagSuggestions } : {}
+      };
     }
     case "harmony_forget": {
       const entityId = z.string().uuid().parse(args.entityId);
@@ -5174,6 +5515,64 @@ async function handleToolCall(name, args, deps) {
       }
       return { success: true, ...result };
     }
+    case "harmony_suggest_relations": {
+      const entityId = z.string().uuid().parse(args.entityId);
+      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 limit = args.limit ?? 5;
+      const { entity } = await client3.getMemoryEntity(entityId);
+      const src = entity;
+      if (!src) {
+        throw new Error(`Entity not found: ${entityId}`);
+      }
+      const related = await client3.getRelatedEntities(entityId);
+      const excludeIds = new Set([entityId]);
+      for (const raw of [
+        ...related.outgoing || [],
+        ...related.incoming || []
+      ]) {
+        const rel = raw;
+        const target = rel.target;
+        const source = rel.source;
+        const otherId = target?.id ?? rel.target_id ?? source?.id ?? rel.source_id;
+        if (otherId)
+          excludeIds.add(otherId);
+      }
+      const suggestions = await findSimilarEntities(client3, src.title ?? "", src.content ?? "", workspaceId, {
+        projectId,
+        limit: limit + excludeIds.size,
+        excludeIds: [...excludeIds]
+      });
+      return {
+        success: true,
+        suggestions: suggestions.slice(0, limit).map((s) => ({
+          id: s.id,
+          title: s.title,
+          type: s.type,
+          rrf_score: s.rrf_score
+        }))
+      };
+    }
+    case "harmony_recall_feedback": {
+      const entityId = z.string().uuid().parse(args.entityId);
+      const vote = z.enum(["up", "down"]).parse(args.vote);
+      const { entity } = await client3.getMemoryEntity(entityId);
+      const existingMeta = entity?.metadata ?? {};
+      const existingFeedback = existingMeta.feedback;
+      const feedback = mergeFeedback(existingFeedback, vote);
+      const result = await client3.updateMemoryEntity(entityId, {
+        metadata: { ...existingMeta, feedback }
+      });
+      const fbMemSession = getActiveMemorySession();
+      if (fbMemSession) {
+        appendMemoryAction(fbMemSession.cardId, `Memory feedback: ${vote === "up" ? "\uD83D\uDC4D" : "\uD83D\uDC4E"} ${entityId.slice(0, 8)}`);
+        flushMemoryActions(client3, fbMemSession.cardId).catch(() => {});
+      }
+      return { success: true, feedback, ...result };
+    }
     case "harmony_memory_search": {
       const query = z.string().min(1).max(500).parse(args.query);
       const workspaceId = args.workspaceId || deps.getActiveWorkspaceId();