@gethmy/mcp 2.8.4 → 2.8.6

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 } : {}),
       };
     }
 
@@ -2914,6 +3080,12 @@ async function handleToolCall(
       let relevanceMap: Map<string, number>;
 
       if (queryText) {
+        const requestedTags = args.tags as string[] | undefined;
+        // Tag + superseded filtering is now authoritative in the hybrid_search
+        // RPC (#298/#299): tags match the canonical `tags_normalized` column at
+        // the DB level (no client-side fetch-then-filter completeness gap), and
+        // tombstoned rows are excluded unless include_superseded is set. Tags
+        // are normalized server-side; we pass them through verbatim.
         const searchResult = await client.searchMemoryEntities(
           workspaceId,
           queryText,
@@ -2921,14 +3093,18 @@ async function handleToolCall(
             project_id: projectId,
             type: args.type as string | undefined,
             limit: fetchLimit,
+            tags:
+              requestedTags && requestedTags.length > 0
+                ? requestedTags
+                : undefined,
+            include_superseded: includeSuperseded,
           },
         );
         entities = (searchResult.entities ?? []) as any[];
 
-        // Post-filter the rest of the params client-side. Hybrid search RPC
-        // exposes only project_id + type; tags / scope / minConfidence /
-        // include_superseded are applied here on the rank-ordered set.
-        const requestedTags = args.tags as string[] | undefined;
+        // Post-filter the params the RPC does not handle. Scope + minConfidence
+        // are applied here on the rank-ordered set. (Tags + include_superseded
+        // are handled server-side above.)
         const minConfidence = args.minConfidence as number | undefined;
         if (userScopeFilter) {
           entities = entities.filter((e) => e?.scope === userScopeFilter);
@@ -2937,19 +3113,9 @@ async function handleToolCall(
           // out of the long-term mix so the same row never shows twice.
           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: string) => wanted.has(t)),
-          );
-        }
-        if (typeof minConfidence === "number") {
-          entities = entities.filter(
-            (e) =>
-              typeof e?.confidence === "number" &&
-              e.confidence >= minConfidence,
-          );
-        }
+        entities = filterByMinConfidence(entities, minConfidence);
+        // Belt-and-suspenders: the RPC already excludes tombstoned rows; this
+        // also drops any if a stale/FTS path slipped one through.
         if (!includeSuperseded) {
           entities = entities.filter((e) => !e?.superseded_at);
         }
@@ -2992,23 +3158,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 +3249,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 +3274,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 +3350,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 =