@gethmy/mcp 2.8.4 → 2.8.5

package/src/memory-tags.ts

@@ -0,0 +1,88 @@
+/**
+ * Memory tag normalization + lint (card #274).
+ *
+ * Memory tags were inconsistent and broke tag-based recall: card references
+ * appeared as both `card:259` (colon) and `card-175` / `card 229` (dash/space),
+ * so `harmony_recall({tags:["card:259"]})` missed the variants.
+ *
+ * Canonical card-ref form is `card:<n>` (colon) — this aligns with the active
+ * programmatic write path: the agent daemon's `episode-writer.ts` already tags
+ * episodes with `` `card:${short_id}` ``. We normalize toward that, not away.
+ *
+ * Rules are intentionally small and deterministic (no LLM, no taxonomy):
+ *   - trim surrounding whitespace
+ *   - lowercase
+ *   - collapse internal whitespace runs to a single space
+ *   - canonicalize card refs: `card-<n>` / `card <n>` / `card#<n>` → `card:<n>`
+ */
+
+/** Matches a card ref written with any common separator, e.g. `card-12`,
+ *  `card 12`, `card#12`, `card:12`. Captures the numeric short id. */
+const CARD_REF = /^card[\s:#-]+(\d+)$/;
+
+/**
+ * Normalize a single tag to its canonical form.
+ * Pure: trims, lowercases, collapses internal whitespace, canonicalizes card refs.
+ */
+export function normalizeTag(tag: string): string {
+  const cleaned = tag.trim().toLowerCase().replace(/\s+/g, " ");
+  const cardMatch = cleaned.match(CARD_REF);
+  if (cardMatch) {
+    return `card:${cardMatch[1]}`;
+  }
+  return cleaned;
+}
+
+/**
+ * Normalize a list of tags: map each through {@link normalizeTag}, drop empties,
+ * and dedupe while preserving first-seen order.
+ */
+export function normalizeTags(tags: string[]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const raw of tags) {
+    const norm = normalizeTag(raw);
+    if (!norm || seen.has(norm)) continue;
+    seen.add(norm);
+    out.push(norm);
+  }
+  return out;
+}
+
+/** A single advisory tag-lint suggestion. Non-fatal. */
+export interface TagSuggestion {
+  /** The original tag as written by the caller. */
+  tag: string;
+  /** The canonical form we'd prefer. */
+  suggestion: string;
+  /** Short human-readable reason. */
+  reason: string;
+}
+
+/**
+ * Advisory tag lint (card #274). Returns non-fatal suggestions for tags that
+ * differ from their canonical form (case variants, dash/space/hash card refs,
+ * surrounding/internal whitespace). NEVER rejects — purely informational.
+ *
+ * Clean tags (already canonical) produce no suggestions, so a fully-normalized
+ * input list returns `[]`.
+ */
+export function lintTags(tags: string[]): TagSuggestion[] {
+  const suggestions: TagSuggestion[] = [];
+  for (const tag of tags) {
+    const norm = normalizeTag(tag);
+    if (norm === tag) continue;
+    let reason: string;
+    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;
+}

package/src/server.ts

@@ -34,19 +34,34 @@ import {
   setActiveProject,
   setActiveWorkspace,
 } from "./config.js";
-import { autoExpandGraph } from "./graph-expansion.js";
+import {
+  autoExpandGraph,
+  findSimilarEntities,
+  findSupersedeCandidates,
+  type SupersedeCandidate,
+} from "./graph-expansion.js";
 import { validateMemoryQuality } from "./memory-floor.js";
 import {
+  filterByMinConfidence,
   fitToBudget,
+  type MemoryFeedback,
+  mergeFeedback,
   type ParkInput,
   relevanceFromRank,
   rescore,
 } from "./memory-park.js";
+import {
+  buildOrigin,
+  defaultConfidenceForSource,
+  importanceWithSignalBump,
+  type MemorySource,
+} from "./memory-provenance.js";
 import {
   isSessionScope,
   resolveSessionScope,
   sessionScopeFor,
 } from "./memory-session.js";
+import { lintTags, normalizeTags } from "./memory-tags.js";
 import { onboardNewUser } from "./onboard.js";
 import { stripSkillPreamble } from "./skills.js";
 
@@ -1101,6 +1116,15 @@ export const TOOLS = {
           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"],
     },
@@ -1282,6 +1306,52 @@ export const 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 👍/👎 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.",
@@ -2773,7 +2843,13 @@ async function handleToolCall(
         );
       }
       const entityType = (args.type as string) || "context";
-      const entityTags = (args.tags as string[]) || [];
+      const rawTags = (args.tags as string[]) || [];
+      // Tag taxonomy normalization (#274): canonicalize before any downstream
+      // use so the Floor, the write, and graph expansion all see the same
+      // canonical card refs / casing. Lint is advisory — surfaced in the
+      // response, never rejecting.
+      const entityTags = normalizeTags(rawTags);
+      const tagSuggestions = lintTags(rawTags);
 
       // Working-memory binding (plan §12 Phase 1, §13.1 D3). The caller may
       // pass `scope: 'session'` as an alias; resolve it to the active
@@ -2804,35 +2880,116 @@ async function handleToolCall(
         );
       }
 
-      // Importance: caller-provided > per-type default (plan §7.1).
-      // auto_score_importance is documented as an LLM-rating opt-in but the
-      // actual LLM call is deferred to a follow-up commit; currently it falls
-      // through to the type default, same as omission.
-      const callerImportance =
+      // Provenance (#273, task 2). Infer the source from context: an active
+      // memory session means the write came from an agent run (or the board
+      // assistant proxying for the user). With no session it's a manual,
+      // human-curated capture. The origin record rides inside metadata.origin
+      // — there is no dedicated provenance column.
+      const sourceTrust = args.source_trust as string | undefined;
+      const source: MemorySource = 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 as
+        | Record<string, unknown>
+        | undefined;
+      const metadataWithOrigin: Record<string, unknown> = {
+        ...(callerMetadata ?? {}),
+        origin,
+      };
+
+      // Confidence (#273, task 5). An explicit confidence always wins. When
+      // omitted, derive a non-uniform default from source/trust so
+      // minConfidence filtering on recall actually bites: manual/curated stays
+      // high, agent auto-extract / low-trust starts moderate. (Was: edge fn
+      // defaulted everything to 1.0, making the whole vault uniform.)
+      const confidence =
+        args.confidence !== undefined
+          ? z.number().min(0).max(1).parse(args.confidence)
+          : defaultConfidenceForSource({ source, source_trust: sourceTrust });
+
+      // Importance (#273, task 6). Caller-provided wins; auto_score_importance
+      // (LLM rating) stays deferred per the 2026-05-08 decision (the AGP
+      // auto-scorer was reverted in 43782a4 for poisoning the corpus). When
+      // omitted, use the per-type default plus a bounded, deterministic
+      // signal-density bump so the Park rescore has a non-flat importance term.
+      const importance =
         args.importance !== undefined
           ? z.number().int().min(1).max(10).parse(args.importance)
-          : undefined;
+          : importanceWithSignalBump(entityType, content);
+
+      const projectIdForWrite =
+        (args.projectId as string) || deps.getActiveProjectId() || undefined;
+
+      // Write-time semantic dedup probe (card #275). BEFORE inserting, look for
+      // existing non-superseded entities of the same type + scope that look
+      // like near-duplicates, reusing the hybrid-search path (no new embedding
+      // pipeline). This NEVER blocks the write — the result is surfaced in the
+      // `similar` response field so the caller can choose to supersede later
+      // via the `supersedeId` param. Session-scoped (ephemeral) writes skip the
+      // probe entirely: working memory is short-lived by design.
+      let similar: SupersedeCandidate[] = [];
+      if (!isSessionScope(entityScope)) {
+        similar = await findSupersedeCandidates(
+          client,
+          title,
+          content,
+          entityType,
+          workspaceId,
+          { projectId: projectIdForWrite, scope: entityScope },
+        );
+      }
 
-      // Use session's agent identifier if available, otherwise null
       const result = await client.createMemoryEntity({
         workspace_id: workspaceId,
-        project_id:
-          (args.projectId as string) || deps.getActiveProjectId() || undefined,
+        project_id: projectIdForWrite,
         type: entityType,
         scope: entityScope,
         memory_tier: (args.tier as string) || undefined,
         title,
         content,
-        metadata: args.metadata as Record<string, unknown> | undefined,
-        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,
       });
 
+      // Explicit supersede branch (card #275). When the caller passes
+      // `supersedeId`, soft-tombstone that existing entity by pointing its
+      // superseded_by at the row we just created. This is the ONLY mutation of
+      // an existing memory and it is always caller-driven — never automatic.
+      // Soft + reversible (clearing superseded_by restores it); no hard delete,
+      // no content merge. The AGP auto-consolidation layer was reverted
+      // (43782a4) for autonomously merging — this keeps the decision explicit.
+      const supersedeId = args.supersedeId as string | undefined;
+      const newEntityId = (result.entity as { id?: string } | null)?.id;
+      let superseded: string | undefined;
+      if (supersedeId && newEntityId) {
+        try {
+          await client.updateMemoryEntity(supersedeId, {
+            superseded_by: newEntityId,
+            superseded_at: new Date().toISOString(),
+          });
+          superseded = supersedeId;
+        } catch (err) {
+          // A failed supersede must not fail the write — the new entity already
+          // exists. Surface the failure in logs; caller can retry the tombstone.
+          const msg = err instanceof Error ? err.message : String(err);
+          console.debug(
+            `[harmony_remember] supersede ${supersedeId} failed: ${msg}`,
+          );
+        }
+      }
+
       // Fire-and-forget graph expansion: link new entity to semantically similar ones
       const newEntityIdForGraph = (result.entity as any)?.id;
       if (newEntityIdForGraph) {
@@ -2843,7 +3000,7 @@ async function handleToolCall(
           content,
           entityTags,
           workspaceId,
-          (args.projectId as string) || deps.getActiveProjectId() || undefined,
+          projectIdForWrite,
         ).catch(() => {});
       }
 
@@ -2859,6 +3016,15 @@ async function handleToolCall(
       return {
         success: true,
         ...result,
+        // Near-duplicate existing entities (same type + scope) above threshold.
+        // Always present; empty when nothing similar was found. Non-breaking:
+        // existing callers ignore it. Callers may re-call harmony_remember with
+        // `supersedeId` set to one of these ids to tombstone the older row.
+        ...(similar.length > 0 ? { similar } : {}),
+        ...(superseded ? { superseded } : {}),
+        // Advisory tag-lint hints (#274). Present only when the caller's tags
+        // were non-canonical; the tags were still normalized and written.
+        ...(tagSuggestions.length > 0 ? { tagSuggestions } : {}),
       };
     }
 
@@ -2943,13 +3109,7 @@ async function handleToolCall(
             (e?.tags ?? []).some((t: string) => 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);
         }
@@ -2992,23 +3152,20 @@ async function handleToolCall(
         trimmed = fitToBudget(trimmed, budgetTokens);
       }
 
-      // Touch access timestamps for the entities we returned (basic Park
-      // recency trail). Non-blocking.
+      // Touch access counters for the entities we returned (#273, task 4).
+      // Previously this wrote `metadata._last_recall` via updateMemoryEntity,
+      // which left `access_count` at 0 forever and never updated
+      // `last_accessed_at` — the column the Park recency term actually reads.
+      // Route through batch-touch, which calls the atomic
+      // `batch_touch_knowledge_entities` RPC (access_count += 1, last_accessed_at
+      // = now) in a single round-trip. Non-blocking; best-effort.
       if (trimmed.length > 0) {
-        Promise.all(
-          trimmed.map(async ({ entity }: { entity: any }) => {
-            try {
-              await client.updateMemoryEntity(entity.id, {
-                metadata: {
-                  ...(entity.metadata || {}),
-                  _last_recall: new Date().toISOString(),
-                },
-              });
-            } catch (_) {
-              // Non-critical
-            }
-          }),
-        ).catch(() => {});
+        const touchIds = trimmed
+          .map(({ entity }: { entity: any }) => entity?.id)
+          .filter((id: unknown): id is string => typeof id === "string");
+        if (touchIds.length > 0) {
+          client.batchTouchMemoryEntities(touchIds).catch(() => {});
+        }
       }
 
       // Working-memory prepend (plan §12 Phase 1). When a session is active
@@ -3086,7 +3243,15 @@ async function handleToolCall(
         updates.content = z.string().max(50000).parse(args.content);
       if (args.type !== undefined) updates.type = args.type;
       if (args.scope !== undefined) updates.scope = args.scope;
-      if (args.tags !== undefined) updates.tags = args.tags;
+      // Tag taxonomy normalization (#274): same canonicalization + advisory
+      // lint as harmony_remember. Normalized tags are persisted; suggestions
+      // are non-fatal and surfaced in the response.
+      let updateTagSuggestions: ReturnType<typeof lintTags> = [];
+      if (args.tags !== undefined) {
+        const updateRawTags = args.tags as string[];
+        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) updates.metadata = args.metadata;
@@ -3103,7 +3268,13 @@ async function handleToolCall(
         flushMemoryActions(client, updateMemSession.cardId).catch(() => {});
       }
 
-      return { success: true, ...result };
+      return {
+        success: true,
+        ...result,
+        ...(updateTagSuggestions.length > 0
+          ? { tagSuggestions: updateTagSuggestions }
+          : {}),
+      };
     }
 
     case "harmony_forget": {
@@ -3173,6 +3344,112 @@ async function handleToolCall(
       return { success: true, ...result };
     }
 
+    case "harmony_suggest_relations": {
+      // Relation suggestions (card #281, task 3). Read-only: reuses the
+      // existing hybrid similarity helper (findSimilarEntities, card #275) to
+      // propose candidates the caller may explicitly relate via harmony_relate.
+      // It NEVER writes a relation — surfacing only. Already-related entities
+      // and the entity itself are excluded so suggestions are net-new edges.
+      const entityId = z.string().uuid().parse(args.entityId);
+      const workspaceId =
+        (args.workspaceId as string) || deps.getActiveWorkspaceId();
+      if (!workspaceId) {
+        throw new Error(
+          "No workspace specified. Use harmony_set_workspace_context or provide workspaceId.",
+        );
+      }
+      const projectId =
+        (args.projectId as string) || deps.getActiveProjectId() || undefined;
+      const limit = (args.limit as number | undefined) ?? 5;
+
+      const { entity } = await client.getMemoryEntity(entityId);
+      const src = entity as {
+        title?: string;
+        content?: string;
+      } | null;
+      if (!src) {
+        throw new Error(`Entity not found: ${entityId}`);
+      }
+
+      // Exclude the entity itself plus anything it is already related to, so
+      // suggestions only ever propose new edges.
+      const related = await client.getRelatedEntities(entityId);
+      const excludeIds = new Set<string>([entityId]);
+      for (const raw of [
+        ...(related.outgoing || []),
+        ...(related.incoming || []),
+      ]) {
+        const rel = raw as Record<string, unknown>;
+        const target = rel.target as Record<string, unknown> | undefined;
+        const source = rel.source as Record<string, unknown> | undefined;
+        const otherId =
+          (target?.id as string) ??
+          (rel.target_id as string) ??
+          (source?.id as string) ??
+          (rel.source_id as string);
+        if (otherId) excludeIds.add(otherId);
+      }
+
+      const suggestions = await findSimilarEntities(
+        client,
+        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": {
+      // Record-success feedback loop (card #279, task 3). Non-destructive:
+      // increments a counter in metadata.feedback and writes it back via the
+      // standard metadata-merge update path. Affects RANKING ONLY (the Park
+      // rescore reads metadata.feedback into effective importance); the memory
+      // is never deleted, hidden, or superseded.
+      const entityId = z.string().uuid().parse(args.entityId);
+      const vote = z.enum(["up", "down"]).parse(args.vote);
+
+      const { entity } = await client.getMemoryEntity(entityId);
+      const existingMeta =
+        (entity as { metadata?: Record<string, unknown> } | null)?.metadata ??
+        {};
+      const existingFeedback = (existingMeta as { feedback?: MemoryFeedback })
+        .feedback;
+      const feedback = mergeFeedback(existingFeedback, vote);
+
+      // The harmony-api update REPLACES the metadata column (no server-side
+      // merge), so we must send the full object: existing metadata (incl.
+      // metadata.origin provenance from #273) plus the updated feedback delta.
+      // Sending only { feedback } would wipe provenance and everything else.
+      const result = await client.updateMemoryEntity(entityId, {
+        metadata: { ...existingMeta, feedback },
+      });
+
+      const fbMemSession = getActiveMemorySession();
+      if (fbMemSession) {
+        appendMemoryAction(
+          fbMemSession.cardId,
+          `Memory feedback: ${vote === "up" ? "👍" : "👎"} ${entityId.slice(0, 8)}`,
+        );
+        flushMemoryActions(client, 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 =