@gethmy/mcp 2.8.4 → 2.8.6

package/dist/lib/api-client.js

@@ -726,10 +726,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;
@@ -786,9 +790,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} ` : "";
@@ -1313,6 +1323,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) {

package/package.json

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

package/src/api-client.ts

@@ -1003,6 +1003,8 @@ export class HarmonyApiClient {
       project_id?: string;
       type?: string;
       limit?: number;
+      tags?: string[];
+      include_superseded?: boolean;
     },
   ): Promise<{ entities: unknown[]; count: number }> {
     const params = new URLSearchParams();
@@ -1012,6 +1014,10 @@ export class HarmonyApiClient {
     if (options?.type) params.set("type", options.type);
     if (options?.limit !== undefined)
       params.set("limit", String(options.limit));
+    // Repeated `tags` params — the search endpoint reads them via getAll and
+    // matches against the canonical `tags_normalized` column (#299).
+    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()}`);
   }
 

package/src/auto-session.ts

@@ -68,14 +68,18 @@ export function resolveAgentIdentity(info: ClientInfo | null): {
 /**
  * Tools that trigger auto-start of a session.
  *
- * Restricted to tools that signal real work on a card. Board-management ops
- * (move, label add/remove) are excluded — they're routinely used for triage
- * and would create false-positive sessions whose side effect (the auto-added
- * `agent` label on the card) confuses both UI and humans.
+ * Restricted to tools that signal real work on a card. Triage/board-management
+ * ops are excluded — they're routinely used for sorting and card creation, not
+ * implementation, and would create false-positive sessions whose side effect
+ * (the auto-added `agent` label on the card) confuses both UI and humans.
+ *
+ * `harmony_update_card` is deliberately NOT a trigger: editing a card's
+ * title/description/priority is metadata editing (used during `/hmy` create and
+ * triage), not work. Including it spawned phantom sessions on freshly-created
+ * cards (card #295), the same reason move/label ops are excluded.
  */
 export const AUTO_START_TRIGGERS = new Set([
   "harmony_generate_prompt",
-  "harmony_update_card",
   "harmony_create_subtask",
   "harmony_toggle_subtask",
   "harmony_update_subtask",
@@ -134,6 +138,15 @@ export async function trackActivity(
   const client = options?.client ?? clientGetter?.();
   if (!client) return;
 
+  // Resolve agent identity from the MCP `initialize` handshake. Never auto-start
+  // an anonymous session: if we can't say WHO is working, we don't fabricate a
+  // phantom "Unknown Agent" session (card #295). Identified clients only — this
+  // bail happens BEFORE ending other sessions so an unidentified call can't tear
+  // down a legitimate tracked session.
+  const info = clientInfoGetter?.() ?? null;
+  if (!info?.name) return;
+  const { agentIdentifier, agentName } = resolveAgentIdentity(info);
+
   // Collect auto-sessions on other cards to end (avoid mutating map during iteration)
   const toEnd: string[] = [];
   for (const [otherCardId, session] of activeSessions) {
@@ -145,10 +158,6 @@ export async function trackActivity(
     await autoEndSession(client, otherCardId, "completed");
   }
 
-  // Resolve agent identity from MCP client info
-  const info = clientInfoGetter?.() ?? null;
-  const { agentIdentifier, agentName } = resolveAgentIdentity(info);
-
   // Start a new auto-session
   try {
     await client.startAgentSession(cardId, {

package/src/graph-expansion.ts

@@ -138,6 +138,157 @@ export async function findSimilarEntities(
   }
 }
 
+// ============ WRITE-TIME SEMANTIC DEDUP (card #275) ============
+
+/**
+ * RRF-score floor for treating a hybrid-search hit as a *supersede candidate*
+ * at write time. The hybrid_search RPC fuses FTS + vector ranks via Reciprocal
+ * Rank Fusion: score = 1/(k+fts_rank) + 1/(k+semantic_rank), k=50. A row that
+ * ranks #1 in BOTH lists tops out near 2/51 ≈ 0.039; #1 in a single list is
+ * ≈ 0.0196. RRF rank is NOT cosine similarity, so this threshold alone is a
+ * weak signal — it is paired with a lexical title-overlap guard below so we
+ * only ever surface genuinely near-duplicate titles. Deliberately
+ * conservative: dedup must never produce false "this already exists" noise.
+ *
+ * Tuning note: the cross-type causal linker (linkCrossTypeNeighbors) uses
+ * minRrfScore 0.04 for a comparable "strongly related" bar; we sit just under
+ * it because dedup probes the SAME type and wants the top fused hit.
+ */
+export const SUPERSEDE_RRF_THRESHOLD = 0.029;
+
+/**
+ * Minimum Jaccard overlap of significant title tokens required, in addition to
+ * the RRF floor, before a hit counts as a supersede candidate. Guards against
+ * semantic-only matches (e.g. two different patterns about "BoardContext")
+ * being flagged as duplicates. 0.5 = at least half the significant tokens are
+ * shared.
+ */
+export const SUPERSEDE_TITLE_OVERLAP = 0.5;
+
+const TITLE_STOPWORDS = new Set([
+  "a",
+  "an",
+  "the",
+  "and",
+  "or",
+  "of",
+  "to",
+  "in",
+  "on",
+  "for",
+  "with",
+  "is",
+  "are",
+  "be",
+  "by",
+  "at",
+  "as",
+]);
+
+function significantTitleTokens(title: string): Set<string> {
+  return new Set(
+    title
+      .toLowerCase()
+      .replace(/[^a-z0-9\s]/g, " ")
+      .split(/\s+/)
+      .filter((t) => t.length > 2 && !TITLE_STOPWORDS.has(t)),
+  );
+}
+
+/** Jaccard similarity of two token sets. Returns 0 when either set is empty. */
+function jaccard(a: Set<string>, b: Set<string>): number {
+  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);
+}
+
+export interface SupersedeCandidate {
+  id: string;
+  title: string;
+  /** RRF score from the hybrid search (higher = more relevant). */
+  score: number;
+}
+
+/**
+ * Write-time dedup probe (card #275). BEFORE inserting a new memory, find
+ * existing, non-superseded entities of the SAME type + scope that look like
+ * near-duplicates of the candidate title+content.
+ *
+ * Reuses the existing hybrid-search path (searchMemoryEntities → the
+ * hybrid_search_knowledge_entities RPC) — no new embedding pipeline. A hit must
+ * clear BOTH the RRF floor AND a lexical title-overlap guard, so this is a
+ * conservative "these are probably the same memory" signal, never a silent
+ * merge.
+ *
+ * Non-fatal and non-blocking: any failure returns [] so the write still
+ * proceeds. The caller ALWAYS inserts; this only surfaces candidates for the
+ * caller (agent / assistant / human) to optionally supersede.
+ */
+export async function findSupersedeCandidates(
+  client: HarmonyApiClient,
+  title: string,
+  content: string,
+  type: string,
+  workspaceId: string,
+  options?: {
+    projectId?: string;
+    scope?: string;
+    limit?: number;
+    rrfThreshold?: number;
+    titleOverlap?: number;
+  },
+): Promise<SupersedeCandidate[]> {
+  const rrfThreshold = options?.rrfThreshold ?? SUPERSEDE_RRF_THRESHOLD;
+  const titleOverlap = options?.titleOverlap ?? SUPERSEDE_TITLE_OVERLAP;
+  const candidateTokens = significantTitleTokens(title);
+
+  try {
+    const hits = await findSimilarEntities(
+      client,
+      title,
+      content,
+      workspaceId,
+      {
+        projectId: options?.projectId,
+        // Filter to the same type server-side — dedup only applies within a type.
+        type,
+        limit: options?.limit ?? 10,
+        minRrfScore: rrfThreshold,
+      },
+    );
+
+    return hits
+      .filter((e) => {
+        // Same scope only — a project memory shouldn't supersede a global one.
+        if (options?.scope && (e as { scope?: string }).scope !== undefined) {
+          if ((e as { scope?: string }).scope !== options.scope) return false;
+        }
+        // Skip already-superseded rows. The hybrid-search RPC now both returns
+        // `superseded_at` and excludes tombstoned rows by default (#298), so
+        // retired rows no longer surface as candidates on the embedding path.
+        // Kept as belt-and-suspenders for the FTS fallback and any caller that
+        // opts into include_superseded.
+        if ((e as { superseded_at?: string | null }).superseded_at) {
+          return false;
+        }
+        // Lexical guard: require real title-token overlap on top of RRF.
+        return (
+          jaccard(candidateTokens, significantTitleTokens(e.title)) >=
+          titleOverlap
+        );
+      })
+      .map((e) => ({
+        id: e.id,
+        title: e.title,
+        score: e.rrf_score ?? 0,
+      }));
+  } catch {
+    // Never block a write because the dedup probe failed.
+    return [];
+  }
+}
+
 /**
  * Causal lookup table: maps an entity type to the target types it should
  * be linked to, along with the relation type and direction.

package/src/memory-park.ts

@@ -11,9 +11,18 @@
  *                      baseline so recency + importance still differentiate.
  *   recency_decay    — exp(-Δt_seconds / τ_type) clamped to [0, 1].
  *                      τ depends on memory type per plan §4.
- *   importance_norm  — importance / 10, clamped to [0, 1].
+ *   importance_norm  — effective_importance / 10, clamped to [0, 1], where
+ *                      effective_importance folds in two bounded, deterministic
+ *                      signals on top of the stored importance (card #279):
+ *                        + usage bump   — proven-useful memories (recalled
+ *                                         often) rank above never-recalled ones
+ *                        + feedback bump — 👍/👎 stored in metadata.feedback
+ *                      See `effectiveImportance` below. This is RANKING ONLY:
+ *                      nothing is stored, deleted, or mutated.
  *
- *   defaults: α=0.55, β=0.25, γ=0.20 (sum to 1.0).
+ *   defaults: α=0.55, β=0.25, γ=0.20 (sum to 1.0). Weights are NOT re-tuned by
+ *   #279 — usage + feedback fold into the existing γ·importance term so the
+ *   formula stays a stable 3-weight model.
  *
  * The function is pure. Hot-path-safe — no LLM calls, no DB reads.
  */
@@ -28,6 +37,37 @@ export const DEFAULT_WEIGHTS = {
   importance: 0.2,
 } as const;
 
+// ---------------------------------------------------------------------------
+// Usage + feedback bumps (card #279) — fold into effective importance.
+// ---------------------------------------------------------------------------
+
+/**
+ * Usage bump (card #279, task 2). A bounded, log-scaled lift to importance for
+ * memories that have actually been recalled. Proven-useful memories outrank
+ * never-recalled ones at equal relevance/recency; never-used ones get +0 and
+ * gently sink relative to their used peers.
+ *
+ *   bump = USAGE_BUMP_SCALE · ln(1 + access_count), capped at USAGE_BUMP_MAX
+ *
+ * Log scaling keeps the lift gentle and diminishing: the jump from 0→1 recall
+ * matters most, runaway counts can't dominate. Capped so usage never swamps the
+ * stored importance signal. Pure + deterministic — no LLM, no storage change.
+ */
+export const USAGE_BUMP_SCALE = 0.6;
+export const USAGE_BUMP_MAX = 2;
+
+/**
+ * Feedback bump (card #279, task 3). Net 👍/👎 stored non-destructively in
+ * `metadata.feedback = { up, down }` shifts importance up (positive net) or
+ * down (negative net), bounded and symmetric. Feedback affects RANKING ONLY —
+ * it never deletes or supersedes a memory.
+ *
+ *   bump = FEEDBACK_BUMP_SCALE · sign(net) · ln(1 + |net|),
+ *          clamped to ±FEEDBACK_BUMP_MAX
+ */
+export const FEEDBACK_BUMP_SCALE = 0.8;
+export const FEEDBACK_BUMP_MAX = 2;
+
 // Per-type recency time constant τ in seconds.
 // `Infinity` = never decays (preferences shouldn't fade with disuse).
 export const TYPE_TAU_SECONDS: Record<string, number> = {
@@ -71,17 +111,28 @@ export const TYPE_IMPORTANCE_DEFAULT: Record<string, number> = {
 // Types
 // ---------------------------------------------------------------------------
 
+/** 👍/👎 counters stored non-destructively at `metadata.feedback`. */
+export interface MemoryFeedback {
+  up?: number;
+  down?: number;
+}
+
 export interface ParkInput {
   type: string;
   importance?: number | null;
   last_accessed_at?: string | null;
   created_at?: string | null;
+  /** Recall counter maintained by batch_touch_knowledge_entities (#273). */
+  access_count?: number | null;
+  /** Carries `metadata.feedback` (#279). Other metadata keys are ignored. */
+  metadata?: { feedback?: MemoryFeedback | null } | null;
 }
 
 export interface ParkScored<T extends ParkInput> {
   entity: T;
   relevance: number;
   recency: number;
+  /** Effective importance term, normalised to [0,1] (post usage + feedback). */
   importance: number;
   score: number;
 }
@@ -124,10 +175,59 @@ function recencyDecay(
   return clamp01(Math.exp(-dtSec / tau));
 }
 
-function importanceNorm(raw: number | null | undefined, type: string): number {
+/** Resolve the stored (base) importance, clamped to [1,10]. */
+function baseImportance(raw: number | null | undefined, type: string): number {
   let v = typeof raw === "number" ? raw : (TYPE_IMPORTANCE_DEFAULT[type] ?? 5);
   if (v < 1) v = 1;
   if (v > 10) v = 10;
+  return v;
+}
+
+/**
+ * Bounded, log-scaled usage lift (card #279, task 2). +0 for never-recalled.
+ * Pure; reads only `access_count`.
+ */
+export function usageBump(accessCount: number | null | undefined): number {
+  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));
+}
+
+/**
+ * Bounded, symmetric feedback shift (card #279, task 3). Positive net 👍 lifts,
+ * negative net 👎 demotes. Pure; reads only `metadata.feedback`.
+ */
+export function feedbackBump(
+  feedback: MemoryFeedback | null | undefined,
+): number {
+  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;
+}
+
+/**
+ * Effective importance = base importance + usage bump + feedback bump, clamped
+ * to [1,10], then normalised to [0,1] (card #279, task 2 + 3).
+ *
+ * Folding usage + feedback into the existing γ·importance term — instead of
+ * adding new weights — keeps the Park formula a stable 3-weight model. This is
+ * a RANKING-ONLY transform: it reads `access_count` and `metadata.feedback`
+ * but never writes, deletes, or supersedes anything.
+ */
+export function effectiveImportance(entity: ParkInput): number {
+  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) v = 10;
   return v / 10;
 }
 
@@ -160,7 +260,7 @@ export function rescore<T extends ParkInput & { id?: string }>(
       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 };
@@ -176,6 +276,28 @@ export function rescore<T extends ParkInput & { id?: string }>(
   return scored;
 }
 
+// ---------------------------------------------------------------------------
+// minConfidence filter (#273)
+// ---------------------------------------------------------------------------
+
+/**
+ * Keep only entities whose confidence meets the threshold. Entities with a
+ * non-numeric confidence are dropped (we can't prove they clear the bar).
+ *
+ * Pure + exported so the recall path's `minConfidence` semantics are
+ * unit-testable. Once writes set non-uniform confidence (#273), a low
+ * threshold yields a strictly smaller set than passing no threshold.
+ */
+export function filterByMinConfidence<T extends { confidence?: number | null }>(
+  entities: T[],
+  minConfidence: number | undefined,
+): T[] {
+  if (typeof minConfidence !== "number") return entities;
+  return entities.filter(
+    (e) => typeof e.confidence === "number" && e.confidence >= minConfidence,
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Rank-to-relevance helper (Phase 1 hybrid retrieval bridge)
 // ---------------------------------------------------------------------------
@@ -250,3 +372,60 @@ export function fitToBudget<
   }
   return out;
 }
+
+// ---------------------------------------------------------------------------
+// Stale / never-recalled signal (card #279, task 4)
+// ---------------------------------------------------------------------------
+
+export interface StaleUnusedInput {
+  access_count?: number | null;
+  last_accessed_at?: string | null;
+  created_at?: string | null;
+}
+
+/**
+ * Returns true when a memory has NEVER been recalled (access_count 0/absent)
+ * AND has existed longer than `thresholdDays`. SIGNAL ONLY — card #280's
+ * prune-suggestion digest consumes this to surface candidates for human
+ * review. It deletes/modifies NOTHING; non-destructive by construction.
+ *
+ * Age is measured from `created_at` (a never-recalled memory has no meaningful
+ * `last_accessed_at`; #273 only stamps it on recall). A memory that has been
+ * recalled even once is never stale-unused, regardless of age.
+ */
+export function isStaleUnused(
+  entity: StaleUnusedInput,
+  now: Date,
+  thresholdDays: number,
+): boolean {
+  const recalled =
+    typeof entity.access_count === "number" && entity.access_count > 0;
+  if (recalled) return false;
+  const createdRaw = entity.created_at ?? null;
+  if (!createdRaw) return false; // Unknown age: don't flag.
+  const created = Date.parse(createdRaw);
+  if (Number.isNaN(created)) return false;
+  const ageDays = (now.getTime() - created) / (1000 * 60 * 60 * 24);
+  return ageDays > thresholdDays;
+}
+
+// ---------------------------------------------------------------------------
+// Feedback merge (card #279, task 3) — non-destructive counter increment
+// ---------------------------------------------------------------------------
+
+/**
+ * Merge a single 👍/👎 vote into an existing feedback counter, returning a NEW
+ * object (input is never mutated). Used by the recall-feedback record path to
+ * compute the `metadata.feedback` patch before persisting. Pure + bounded to
+ * non-negative integers.
+ */
+export function mergeFeedback(
+  existing: MemoryFeedback | null | undefined,
+  vote: "up" | "down",
+): MemoryFeedback {
+  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 };
+}