gitmem-mcp 1.1.3 → 1.2.1

package/dist/services/nudge-variants.js

@@ -0,0 +1,71 @@
+/**
+ * Nudge Variant Support
+ *
+ * Reads GITMEM_NUDGE_VARIANT env var to select alternative header
+ * framings for recall/prepare-context output. Used by nudge-bench
+ * to A/B test how different wording affects agent compliance.
+ *
+ * When no env var is set, returns the production default.
+ *
+ * Variant IDs match nudge-bench/variants/n001-header.ts
+ */
+const VARIANTS = {
+    // Production default
+    "n001-a-institutional": {
+        icon: "🧠",
+        text: (n) => `INSTITUTIONAL MEMORY ACTIVATED\n\nFound ${n} relevant scar${n === 1 ? "" : "s"} for your plan:`,
+    },
+    // Informational/passive
+    "n001-b-recalled": {
+        icon: "\x1b[38;5;37m⬢\x1b[0m",
+        text: (n) => `gitmem ── ${n} learnings recalled`,
+    },
+    // Obligation
+    "n001-c-review": {
+        icon: "\x1b[38;5;37m⬢\x1b[0m",
+        text: (n) => `gitmem ── ${n} scar${n === 1 ? "" : "s"} to review`,
+    },
+    // Directive
+    "n001-d-directive": {
+        icon: "\x1b[38;5;37m⬢\x1b[0m",
+        text: (n) => `gitmem ── review ${n} learning${n === 1 ? "" : "s"} before proceeding`,
+    },
+    // Procedural — ties to confirm_scars
+    "n001-e-confirm": {
+        icon: "\x1b[38;5;37m⬢\x1b[0m",
+        text: (n) => `gitmem ── ${n} scar${n === 1 ? "" : "s"} found — confirm before acting`,
+    },
+    // Reasoning — explains WHY (Karpathy: reasoning > command)
+    "n001-f-reasoning": {
+        icon: "\x1b[38;5;37m⬢\x1b[0m",
+        text: (n) => `gitmem ── ${n} past mistake${n === 1 ? "" : "s"} detected that may repeat here — review to avoid the same outcome`,
+    },
+};
+const DEFAULT_VARIANT = "n001-c-review";
+/**
+ * Get the active nudge header based on GITMEM_NUDGE_VARIANT env var.
+ * Falls back to production default if unset or invalid.
+ */
+export function getNudgeHeader() {
+    const variantId = process.env.GITMEM_NUDGE_VARIANT;
+    if (!variantId)
+        return VARIANTS[DEFAULT_VARIANT];
+    return VARIANTS[variantId] || VARIANTS[DEFAULT_VARIANT];
+}
+/**
+ * Format the recall header line using the active nudge variant.
+ */
+export function formatNudgeHeader(scarCount) {
+    const header = getNudgeHeader();
+    return `${header.icon} ${header.text(scarCount)}`;
+}
+/**
+ * Get the active variant ID (for logging/metrics).
+ */
+export function getActiveVariantId() {
+    const variantId = process.env.GITMEM_NUDGE_VARIANT;
+    if (variantId && VARIANTS[variantId])
+        return variantId;
+    return DEFAULT_VARIANT;
+}
+//# sourceMappingURL=nudge-variants.js.map

package/dist/tools/cleanup-threads.js

@@ -14,7 +14,7 @@ import { computeLifecycleStatus } from "../services/thread-vitality.js";
 import { archiveDormantThreads } from "../services/thread-supabase.js";
 import { loadThreadsFile } from "../services/thread-manager.js";
 import { Timer, recordMetrics, buildPerformanceData, } from "../services/metrics.js";
-import { wrapDisplay, truncate } from "../services/display-protocol.js";
+import { wrapDisplay, truncate, productLine, boldText } from "../services/display-protocol.js";
 // --- Display Formatting ---
 function formatDaysAgo(days) {
     if (days < 1)
@@ -28,7 +28,7 @@ function formatDaysAgo(days) {
 }
 function buildCleanupDisplay(summary, groups, archivedCount) {
     const lines = [];
-    lines.push(`gitmem cleanup · ${summary.total_open} open · ${summary.active} active · ${summary.cooling} cooling · ${summary.dormant} dormant`);
+    lines.push(productLine("cleanup", `${summary.total_open} open · ${summary.active} active · ${summary.cooling} cooling · ${summary.dormant} dormant`));
     lines.push("");
     const totalItems = summary.total_open;
     if (totalItems === 0 && archivedCount === 0) {
@@ -44,7 +44,7 @@ function buildCleanupDisplay(summary, groups, archivedCount) {
     for (const [label, items] of sections) {
         if (items.length === 0)
             continue;
-        lines.push(`**${label}** (${items.length}):`);
+        lines.push(`${boldText(label)} (${items.length}):`);
         lines.push("");
         lines.push("| ID | Thread | Last Touch |");
         lines.push("|----|--------|------------|");

package/dist/tools/confirm-scars.js

@@ -18,7 +18,7 @@
 import { getCurrentSession, getSurfacedScars, addConfirmations, getConfirmations, } from "../services/session-state.js";
 import { Timer, buildPerformanceData } from "../services/metrics.js";
 import { getSessionPath } from "../services/gitmem-dir.js";
-import { wrapDisplay } from "../services/display-protocol.js";
+import { wrapDisplay, STATUS, ANSI } from "../services/display-protocol.js";
 import * as fs from "fs";
 // Minimum evidence length per decision type
 const MIN_EVIDENCE_LENGTH = 50;
@@ -65,17 +65,17 @@ function validateConfirmation(confirmation, scar) {
 function formatResponse(valid, confirmations, errors, missingScars) {
     const lines = [];
     if (valid) {
-        lines.push("✅ SCAR CONFIRMATIONS ACCEPTED");
+        lines.push(`${STATUS.ok} SCAR CONFIRMATIONS ACCEPTED`);
         lines.push("");
         for (const conf of confirmations) {
-            const emoji = conf.decision === "APPLYING" ? "🟢" : conf.decision === "N_A" ? "⚪" : "🟠";
-            lines.push(`${emoji} **${conf.scar_title}** → ${conf.decision}`);
+            const indicator = conf.decision === "APPLYING" ? STATUS.pass : conf.decision === "N_A" ? `${ANSI.dim}-${ANSI.reset}` : `${ANSI.yellow}!${ANSI.reset}`;
+            lines.push(`${indicator} **${conf.scar_title}** → ${conf.decision}`);
         }
         lines.push("");
         lines.push("All recalled scars addressed. Consequential actions are now unblocked.");
     }
     else {
-        lines.push("⛔ SCAR CONFIRMATIONS REJECTED");
+        lines.push(`${STATUS.rejected} SCAR CONFIRMATIONS REJECTED`);
         lines.push("");
         if (errors.length > 0) {
             lines.push("**Validation errors:**");
@@ -124,7 +124,7 @@ export async function confirmScars(params) {
     const session = getCurrentSession();
     if (!session) {
         const performance = buildPerformanceData("confirm_scars", timer.elapsed(), 0);
-        const noSessionMsg = "⛔ No active session. Call session_start before confirm_scars.";
+        const noSessionMsg = `${STATUS.rejected} No active session. Call session_start before confirm_scars.`;
         return {
             valid: false,
             errors: ["No active session. Call session_start first."],
@@ -140,7 +140,7 @@ export async function confirmScars(params) {
     const recallScars = allSurfacedScars.filter(s => s.source === "recall");
     if (recallScars.length === 0) {
         const performance = buildPerformanceData("confirm_scars", timer.elapsed(), 0);
-        const noScarsMsg = "✅ No recall-surfaced scars to confirm. Proceed freely.";
+        const noScarsMsg = `${STATUS.ok} No recall-surfaced scars to confirm. Proceed freely.`;
         return {
             valid: true,
             errors: [],
@@ -165,8 +165,25 @@ export async function confirmScars(params) {
     }
     else {
         for (const conf of params.confirmations) {
-            // Check scar exists in recalled set
-            const scar = scarById.get(conf.scar_id);
+            // Check scar exists in recalled set (try exact match first)
+            let scar = scarById.get(conf.scar_id);
+            // If not found and looks like 8-char prefix, try prefix match
+            // This allows agents to copy IDs from recall display (which shows truncated IDs)
+            if (!scar && /^[0-9a-f]{8}$/i.test(conf.scar_id)) {
+                let matchedId = null;
+                for (const [fullId, scarData] of scarById.entries()) {
+                    if (fullId.startsWith(conf.scar_id)) {
+                        if (matchedId) {
+                            // Ambiguous prefix - multiple matches
+                            errors.push(`Ambiguous scar_id prefix "${conf.scar_id}" matches multiple scars. Use full UUID.`);
+                            scar = undefined;
+                            break;
+                        }
+                        matchedId = fullId;
+                        scar = scarData;
+                    }
+                }
+            }
             if (!scar) {
                 errors.push(`Unknown scar_id "${conf.scar_id}". Only confirm scars returned by recall().`);
                 continue;
@@ -181,14 +198,14 @@ export async function confirmScars(params) {
                 const relevance = conf.relevance ??
                     (conf.decision === "APPLYING" ? "high" : conf.decision === "N_A" ? "low" : "low");
                 validConfirmations.push({
-                    scar_id: conf.scar_id,
+                    scar_id: scar.scar_id, // Use full UUID from matched scar, not potentially truncated input
                     scar_title: scar.scar_title,
                     decision: conf.decision,
                     evidence: conf.evidence.trim(),
                     confirmed_at: new Date().toISOString(),
                     relevance,
                 });
-                confirmedIds.add(conf.scar_id);
+                confirmedIds.add(scar.scar_id); // Track by full UUID
             }
         }
     }

package/dist/tools/definitions.js

@@ -131,7 +131,7 @@ export const TOOLS = [
     },
     {
         name: "session_close",
-        description: "Persist session with compliance validation. IMPORTANT: Before calling this tool, write all heavy payload data (closing_reflection, task_completion, human_corrections, scars_to_record, open_threads, decisions, learnings_created) to {gitmem_dir}/closing-payload.json using your file write tool — the gitmem_dir path is returned by session_start (also shown in session start display as 'Payload path'). Then call this tool with ONLY session_id and close_type. The tool reads the payload file automatically and deletes it after processing. DISPLAY: The result includes a pre-formatted 'display' field. Output the display field verbatim as your response — tool results are collapsed in the CLI.",
+        description: "Persist session with compliance validation. IMPORTANT: Before calling this tool, write all heavy payload data (closing_reflection, human_corrections, scars_to_record, open_threads, decisions, learnings_created) to {gitmem_dir}/closing-payload.json using your file write tool — the gitmem_dir path is returned by session_start (also shown in session start display as 'Payload path'). Then call this tool with ONLY session_id and close_type. The tool reads the payload file automatically and deletes it after processing. task_completion is auto-generated from closing_reflection timestamps and human_corrections — do NOT write it to the payload. DISPLAY: The result includes a pre-formatted 'display' field. Output the display field verbatim as your response — tool results are collapsed in the CLI.",
         inputSchema: {
             type: "object",
             properties: {
@@ -595,7 +595,7 @@ export const TOOLS = [
     // --- Thread Lifecycle Tools () ---
     {
         name: "list_threads",
-        description: "List open threads across recent sessions. Shows unresolved work items that carry over between sessions, with IDs for resolution. Use resolve_thread to mark threads as done.",
+        description: "List open threads across recent sessions. Shows unresolved work items that carry over between sessions. Use resolve_thread to mark threads as done.",
         inputSchema: {
             type: "object",
             properties: {

package/dist/tools/list-threads.d.ts

@@ -2,7 +2,7 @@
  * list_threads Tool
  *
  * List open threads across recent sessions. Shows unresolved work items
- * that carry over between sessions, with IDs for resolution.
+ * that carry over between sessions.
  *
  * Primary read from Supabase (source of truth).
  * Falls back to session-based aggregation (same as session_start),

package/dist/tools/list-threads.js

@@ -2,7 +2,7 @@
  * list_threads Tool
  *
  * List open threads across recent sessions. Shows unresolved work items
- * that carry over between sessions, with IDs for resolution.
+ * that carry over between sessions.
  *
  * Primary read from Supabase (source of truth).
  * Falls back to session-based aggregation (same as session_start),
@@ -19,7 +19,7 @@ import { listThreadsFromSupabase } from "../services/thread-supabase.js";
 import * as supabase from "../services/supabase-client.js";
 import { Timer, recordMetrics, buildPerformanceData, } from "../services/metrics.js";
 import { formatThreadForDisplay } from "../services/timezone.js";
-import { wrapDisplay, truncate } from "../services/display-protocol.js";
+import { wrapDisplay, truncate, productLine } from "../services/display-protocol.js";
 // --- Display Formatting ---
 /** Format date as short absolute string: "Feb 13" or "Jan 5" */
 function shortDate(date) {
@@ -31,7 +31,7 @@ function shortDate(date) {
 }
 function buildThreadsDisplay(threads, totalOpen, totalResolved) {
     const lines = [];
-    lines.push(`gitmem threads · ${totalOpen} open · ${totalResolved} resolved`);
+    lines.push(productLine("threads", `${totalOpen} open · ${totalResolved} resolved`));
     lines.push("");
     if (threads.length === 0) {
         lines.push("No threads found.");
@@ -40,14 +40,13 @@ function buildThreadsDisplay(threads, totalOpen, totalResolved) {
     // Deterministic sort: oldest first by created_at
     const sorted = [...threads].sort((a, b) => a.created_at.localeCompare(b.created_at));
     // Markdown table — renders cleanly in all MCP clients
-    lines.push("| # | ID | Thread | Active |");
-    lines.push("|---|-----|--------|--------|");
+    lines.push("| # | Thread | Active |");
+    lines.push("|---|--------|--------|");
     for (let i = 0; i < sorted.length; i++) {
         const t = sorted[i];
-        const shortId = t.id;
         const text = truncate(t.text, 60);
         const date = shortDate(t.last_touched_at || t.created_at);
-        lines.push(`| ${i + 1} | ${shortId} | ${text} | ${date} |`);
+        lines.push(`| ${i + 1} | ${text} | ${date} |`);
     }
     return wrapDisplay(lines.join("\n"));
 }

package/dist/tools/log.js

@@ -16,11 +16,11 @@ import { getStorage } from "../services/storage.js";
 import { Timer, recordMetrics, buildPerformanceData, buildComponentPerformance, } from "../services/metrics.js";
 import { v4 as uuidv4 } from "uuid";
 import { formatTimestamp } from "../services/timezone.js";
-import { wrapDisplay, relativeTime, truncate, SEV, TYPE } from "../services/display-protocol.js";
+import { wrapDisplay, relativeTime, truncate, SEV, TYPE, productLine } from "../services/display-protocol.js";
 // --- Display Formatting ---
 function buildLogDisplay(entries, total, filters) {
     const lines = [];
-    lines.push(`gitmem log · ${total} most recent learnings · ${filters.project}`);
+    lines.push(productLine("log", `${total} most recent · ${filters.project}`));
     const fp = [];
     if (filters.learning_type)
         fp.push(`type=${filters.learning_type}`);
@@ -37,7 +37,7 @@ function buildLogDisplay(entries, total, filters) {
     }
     for (const e of entries) {
         const te = TYPE[e.learning_type] || "·";
-        const se = e.learning_type === "decision" ? "\u{1F4CB}" : (SEV[e.severity] || "\u{26AA}");
+        const se = e.learning_type === "decision" ? "[d]" : (SEV[e.severity] || "[?]");
         const t = truncate(e.title, 50);
         const time = relativeTime(e.created_at);
         const issue = e.source_linear_issue ? `  ${e.source_linear_issue}` : "";

package/dist/tools/prepare-context.js

@@ -22,7 +22,8 @@ import { hasSupabase, getTableName } from "../services/tier.js";
 import { getStorage } from "../services/storage.js";
 import { Timer, recordMetrics, buildPerformanceData, buildComponentPerformance, } from "../services/metrics.js";
 import { v4 as uuidv4 } from "uuid";
-import { wrapDisplay } from "../services/display-protocol.js";
+import { wrapDisplay, productLine } from "../services/display-protocol.js";
+import { formatNudgeHeader } from "../services/nudge-variants.js";
 import { estimateTokens, formatCompact, formatGate, SEVERITY_EMOJI, } from "../hooks/format-utils.js";
 /**
  * Format scars in full mode.
@@ -36,17 +37,13 @@ function formatFull(scars, plan) {
 Proceed with caution — this may be new territory without documented lessons.`;
     }
     const lines = [
-        "🧠 INSTITUTIONAL MEMORY ACTIVATED",
-        "",
-        `Found ${scars.length} relevant scar${scars.length === 1 ? "" : "s"} for your plan:`,
+        formatNudgeHeader(scars.length),
         "",
     ];
     // Blocking verification requirements first
     const blockingScars = scars.filter((s) => s.required_verification?.blocking);
     if (blockingScars.length > 0) {
-        lines.push("═══════════════════════════════════════════════════════════════");
-        lines.push("🚨 **VERIFICATION REQUIRED BEFORE PROCEEDING**");
-        lines.push("═══════════════════════════════════════════════════════════════");
+        lines.push("[!!] VERIFICATION REQUIRED BEFORE PROCEEDING");
         lines.push("");
         for (const scar of blockingScars) {
             const rv = scar.required_verification;
@@ -63,11 +60,11 @@ Proceed with caution — this may be new territory without documented lessons.`;
             lines.push(`**MUST SHOW:** ${rv.must_show}`);
             lines.push("");
         }
-        lines.push("═══════════════════════════════════════════════════════════════");
+        lines.push("---");
         lines.push("");
     }
     for (const scar of scars) {
-        const emoji = SEVERITY_EMOJI[scar.severity] || "⚪";
+        const emoji = SEVERITY_EMOJI[scar.severity] || "[?]";
         lines.push(`${emoji} **${scar.title}** (${scar.severity}, score: ${(scar.similarity || 0).toFixed(2)})`);
         lines.push(scar.description);
         if (scar.counter_arguments && scar.counter_arguments.length > 0) {
@@ -167,7 +164,7 @@ function buildResult(scars, plan, format, maxTokens, timer, metricsId, project,
             blocking_scars,
         },
     }).catch(() => { });
-    const display = wrapDisplay(`prepare_context \u00b7 ${format} \u00b7 ${scars_included} scars (${blocking_scars} blocking) \u00b7 ~${token_estimate} tokens\n\n${memory_payload}`);
+    const display = wrapDisplay(`${productLine("prepare_context", `${format} · ${scars_included} scars (${blocking_scars} blocking) · ~${token_estimate} tokens`)}\n\n${memory_payload}`);
     return {
         memory_payload,
         display,

package/dist/tools/recall.js

@@ -24,7 +24,8 @@ import { getAgentIdentity } from "../services/agent-detection.js";
 import { v4 as uuidv4 } from "uuid";
 import * as fs from "fs";
 import { getSessionPath } from "../services/gitmem-dir.js";
-import { wrapDisplay } from "../services/display-protocol.js";
+import { wrapDisplay, SEV, dimText, ANSI } from "../services/display-protocol.js";
+import { formatNudgeHeader } from "../services/nudge-variants.js";
 import { fetchDismissalCounts } from "../services/behavioral-decay.js";
 /**
  * Format scars into a readable response for Claude
@@ -38,16 +39,12 @@ No past lessons match this plan closely enough. Scars accumulate as you work —
     // Check if any scars have required_verification (blocking gates)
     const scarsWithVerification = scars.filter((s) => s.required_verification?.blocking);
     const lines = [
-        "🧠 INSTITUTIONAL MEMORY ACTIVATED",
-        "",
-        `Found ${scars.length} relevant scar${scars.length === 1 ? "" : "s"} for your plan:`,
+        formatNudgeHeader(scars.length),
         "",
     ];
     // Display blocking verification requirements FIRST and prominently
     if (scarsWithVerification.length > 0) {
-        lines.push("═══════════════════════════════════════════════════════════════");
-        lines.push("🚨 **VERIFICATION REQUIRED BEFORE PROCEEDING**");
-        lines.push("═══════════════════════════════════════════════════════════════");
+        lines.push(`${ANSI.yellow}VERIFICATION REQUIRED${ANSI.reset}`);
         lines.push("");
         for (const scar of scarsWithVerification) {
             const rv = scar.required_verification;
@@ -63,20 +60,13 @@ No past lessons match this plan closely enough. Scars accumulate as you work —
             lines.push("");
             lines.push(`**MUST SHOW:** ${rv.must_show}`);
             lines.push("");
-            lines.push("⛔ DO NOT write SQL until verification output is shown above.");
+            lines.push(`${ANSI.red}Do not proceed until verification output is shown.${ANSI.reset}`);
             lines.push("");
         }
-        lines.push("═══════════════════════════════════════════════════════════════");
-        lines.push("");
     }
     for (const scar of scars) {
-        const severityEmoji = {
-            critical: "🔴",
-            high: "🟠",
-            medium: "🟡",
-            low: "🟢",
-        }[scar.severity] || "⚪";
-        lines.push(`${severityEmoji} **${scar.title}** (${scar.severity}, score: ${scar.similarity.toFixed(2)}) · id: ${scar.id}`);
+        const sev = SEV[scar.severity] || "[?]";
+        lines.push(`${sev} **${scar.title}** (${scar.severity}, ${scar.similarity.toFixed(2)}) ${dimText(`id:${scar.id.slice(0, 8)}`)}`);
         // Inline archival hint: scars with high dismiss rates get annotated
         if (dismissals) {
             const counts = dismissals.get(scar.id);

package/dist/tools/search.js

@@ -17,11 +17,11 @@ import { getProject } from "../services/session-state.js";
 import { getStorage } from "../services/storage.js";
 import { Timer, recordMetrics, buildPerformanceData, buildComponentPerformance, } from "../services/metrics.js";
 import { v4 as uuidv4 } from "uuid";
-import { wrapDisplay, truncate, SEV, TYPE } from "../services/display-protocol.js";
+import { wrapDisplay, truncate, SEV, TYPE, productLine } from "../services/display-protocol.js";
 // --- Display Formatting ---
 function buildSearchDisplay(results, total_found, query, filters) {
     const lines = [];
-    lines.push(`gitmem search · ${total_found} results · "${truncate(query, 60)}"`);
+    lines.push(productLine("search", `${total_found} results · "${truncate(query, 60)}"`));
     const fp = [];
     if (filters.severity)
         fp.push(`severity=${filters.severity}`);
@@ -36,7 +36,7 @@ function buildSearchDisplay(results, total_found, query, filters) {
     }
     for (const r of results) {
         const te = TYPE[r.learning_type] || "·";
-        const se = SEV[r.severity] || "⚪";
+        const se = SEV[r.severity] || "[?]";
         const t = truncate(r.title, 50);
         const sim = `(${r.similarity.toFixed(2)})`;
         const issue = r.source_linear_issue ? `  ${r.source_linear_issue}` : "";