@gethmy/mcp 2.8.3 → 2.8.5

package/src/memory-provenance.ts

@@ -0,0 +1,177 @@
+/**
+ * Write-time provenance + signal-derived confidence/importance.
+ *
+ * Card #273: "Set meaningful confidence, importance & provenance at write
+ * time". Three deterministic, rule-based concerns live here (NO LLM rating —
+ * LLM-rated importance was reverted in 43782a4 for poisoning the corpus and
+ * stays deferred):
+ *
+ *   1. `MemoryOrigin` — provenance stamped into `metadata.origin`. There is no
+ *      dedicated provenance column; it rides inside the existing metadata jsonb.
+ *   2. `defaultConfidenceForSource` — source/trust-derived confidence default
+ *      used only when the caller did NOT pass an explicit confidence.
+ *   3. `importanceWithSignalBump` — per-type importance default plus a bounded
+ *      bump for signal density (file paths, "Why"/"How to apply" sections,
+ *      proper nouns). Pairs with the Park rescore so ranking differentiates.
+ *
+ * Pure and side-effect free — safe to unit test without network/DB.
+ */
+
+// ---------------------------------------------------------------------------
+// Provenance shape (task 1)
+// ---------------------------------------------------------------------------
+
+/** Where a memory came from. */
+export type MemorySource = "manual" | "assistant" | "agent-run" | "import";
+
+/**
+ * Provenance record stored at `metadata.origin`. Input for provenance badges
+ * (companion UI card) and auto-vs-curated hygiene filtering. All fields except
+ * `source` are optional so partial context still round-trips.
+ */
+export interface MemoryOrigin {
+  source: MemorySource;
+  /** Card the write originated from (uuid or short id as string). */
+  source_card_id?: string;
+  /** Agent/working-memory session that produced the write. */
+  source_session_id?: string;
+  /** Human or agent identifier that authored the memory. */
+  author?: string;
+  /**
+   * Trust hint carried through from the write call (e.g. 'document',
+   * 'manual', 'agent'). Persisted so downstream hygiene can reason about it —
+   * previously `source_trust` only reached the Floor and was dropped.
+   */
+  source_trust?: string;
+}
+
+/**
+ * Build a `MemoryOrigin`, dropping undefined fields so the stored jsonb stays
+ * compact. `source` is always present.
+ */
+export function buildOrigin(input: {
+  source: MemorySource;
+  source_card_id?: string | null;
+  source_session_id?: string | null;
+  author?: string | null;
+  source_trust?: string | null;
+}): MemoryOrigin {
+  const origin: MemoryOrigin = { 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;
+}
+
+// ---------------------------------------------------------------------------
+// Source-derived confidence default (task 5)
+// ---------------------------------------------------------------------------
+
+/**
+ * Default confidence by source/trust, applied ONLY when the caller omits an
+ * explicit confidence. An explicit value always wins (handled by the caller).
+ *
+ * Rule (deterministic, documented):
+ *   - manual capture (human at the keyboard): high — 0.9
+ *   - `source_trust === 'document'` import: high — 0.9 (curated long-form)
+ *   - assistant-authored (board assistant on the user's behalf): 0.8
+ *   - agent-run auto-extract / low-trust import: moderate — 0.6
+ *
+ * The point is non-uniformity: most live entities sat at 1.0, which made
+ * `minConfidence` filtering inert. Auto-written memories should start lower so
+ * a curated pattern outranks a freshly auto-extracted episode at equal
+ * relevance/recency.
+ */
+export function defaultConfidenceForSource(input: {
+  source: MemorySource;
+  source_trust?: string;
+}): number {
+  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;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Importance signal-density bump (task 6)
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-type importance default. Mirrors the edge function `IMPORTANCE_DEFAULTS`
+ * and `memory-park.ts` `TYPE_IMPORTANCE_DEFAULT`; duplicated here so the write
+ * path doesn't import the rescorer. Values in [1,10].
+ */
+export const TYPE_IMPORTANCE_DEFAULT: Record<string, number> = {
+  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,
+};
+
+// A file path / module path, e.g. `src/foo/bar.ts`, `packages/x/y`.
+const FILE_PATH =
+  /(?:[\w.-]+\/){1,}[\w.-]+\.[a-z]{1,4}\b|(?:[\w-]+\/){2,}[\w-]+/i;
+// A "Why" or "How to apply" style guidance heading.
+const GUIDANCE_SECTION =
+  /\b(why|how to apply|how to use|takeaway|root cause)\b/i;
+// A proper noun / identifier in the body (PascalCase, camelCase, snake_case,
+// or a backtick-fenced symbol).
+const PROPER_NOUN =
+  /`[^`]+`|\b[A-Z][a-z0-9]+[A-Z][A-Za-z0-9]*\b|\b[a-z]+_[a-z][\w]*\b/;
+
+/**
+ * Count distinct signal-density cues present in the content. Bounded [0,3].
+ *   +1 — contains a file/module path
+ *   +1 — contains a "Why"/"How to apply"/"Takeaway"/"Root cause" section
+ *   +1 — contains a proper noun / code identifier
+ */
+export function signalDensity(content: string): number {
+  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;
+}
+
+/**
+ * Importance = per-type default + bounded signal-density bump, clamped to
+ * [1,10]. Deterministic and rule-based.
+ *
+ * The bump is +1 per cue, capped at +2 total, so a dense, file-path-bearing
+ * lesson edges out a thin one of the same type — giving the Park rescore a
+ * non-flat importance term to work with. A caller-provided importance always
+ * takes precedence and never enters this function.
+ */
+export function importanceWithSignalBump(
+  type: string,
+  content: string,
+): number {
+  const base = TYPE_IMPORTANCE_DEFAULT[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;
+}

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;
+}