gitmem-mcp 1.0.14 → 1.1.0

package/dist/services/thread-dedup.d.ts

@@ -1,14 +1,16 @@
 /**
  * Thread Deduplication Service (Phase 3)
  *
- * Pure functions for detecting duplicate threads by embedding similarity
- * or normalized text equality. Zero I/O — all Supabase and embedding
- * calls live in the caller (create-thread.ts).
+ * Pure functions for detecting duplicate threads by embedding similarity,
+ * token overlap, or normalized text equality. Zero I/O — all Supabase
+ * and embedding calls live in the caller (create-thread.ts).
  *
  * Strategy:
  *   1. If embedding available: cosine similarity > 0.85 → duplicate
- *   2. If embedding unavailable: normalized text equality → duplicate
- *   3. If no existing threads: skip check
+ *   2. Token overlap coefficient > 0.6 → duplicate (no API key needed)
+ *      - Lowered to 0.4 when both threads share an issue prefix (e.g., OD-692:)
+ *   3. Normalized text equality → duplicate
+ *   4. If no existing threads: skip check
  */
 import type { ThreadObject } from "../types/index.js";
 export interface ThreadWithEmbedding {
@@ -21,9 +23,11 @@ export interface DedupResult {
     matched_thread_id: string | null;
     matched_text: string | null;
     similarity: number | null;
-    method: "embedding" | "text_normalization" | "skipped";
+    method: "embedding" | "token_overlap" | "text_normalization" | "skipped";
 }
 export declare const DEDUP_SIMILARITY_THRESHOLD = 0.85;
+export declare const TOKEN_OVERLAP_THRESHOLD = 0.6;
+export declare const TOKEN_OVERLAP_ISSUE_PREFIX_THRESHOLD = 0.4;
 /**
  * Check if new thread text is a semantic duplicate of any existing open thread.
  *
@@ -43,7 +47,23 @@ export declare function cosineSimilarity(a: number[], b: number[]): number;
  */
 export declare function normalizeText(text: string): string;
 /**
- * Deduplicate a thread list by both ID and normalized text.
+ * Tokenize text into content words for overlap comparison.
+ * Lowercase, split on non-alphanumeric boundaries, remove stop words.
+ */
+export declare function tokenize(text: string): Set<string>;
+/**
+ * Overlap coefficient: |intersection| / min(|A|, |B|).
+ * Handles the common case where one thread is a shorter variant of another.
+ * Returns 0 if either set is empty.
+ */
+export declare function tokenOverlap(a: Set<string>, b: Set<string>): number;
+/**
+ * Extract issue prefix like "OD-692" or "PROJ-123" from thread text.
+ * Returns null if no prefix found.
+ */
+export declare function extractIssuePrefix(text: string): string | null;
+/**
+ * Deduplicate a thread list by ID, normalized text, and token overlap.
  * First-seen wins. Skips empty-text threads. Does not mutate input.
  *
  * Applied at every thread loading/merging exit point to guarantee

package/dist/services/thread-dedup.js

@@ -1,17 +1,28 @@
 /**
  * Thread Deduplication Service (Phase 3)
  *
- * Pure functions for detecting duplicate threads by embedding similarity
- * or normalized text equality. Zero I/O — all Supabase and embedding
- * calls live in the caller (create-thread.ts).
+ * Pure functions for detecting duplicate threads by embedding similarity,
+ * token overlap, or normalized text equality. Zero I/O — all Supabase
+ * and embedding calls live in the caller (create-thread.ts).
  *
  * Strategy:
  *   1. If embedding available: cosine similarity > 0.85 → duplicate
- *   2. If embedding unavailable: normalized text equality → duplicate
- *   3. If no existing threads: skip check
+ *   2. Token overlap coefficient > 0.6 → duplicate (no API key needed)
+ *      - Lowered to 0.4 when both threads share an issue prefix (e.g., OD-692:)
+ *   3. Normalized text equality → duplicate
+ *   4. If no existing threads: skip check
  */
 // ---------- Constants ----------
 export const DEDUP_SIMILARITY_THRESHOLD = 0.85;
+export const TOKEN_OVERLAP_THRESHOLD = 0.6;
+export const TOKEN_OVERLAP_ISSUE_PREFIX_THRESHOLD = 0.4;
+const STOP_WORDS = new Set([
+    "a", "an", "the", "and", "or", "but", "in", "on", "at", "to", "for",
+    "of", "with", "by", "from", "is", "it", "be", "as", "was", "are",
+    "been", "being", "have", "has", "had", "do", "does", "did", "will",
+    "that", "this", "not", "no", "so", "if", "its", "also", "into",
+    "than", "then", "can", "just", "about", "up", "out", "still",
+]);
 // ---------- Core ----------
 /**
  * Check if new thread text is a semantic duplicate of any existing open thread.
@@ -60,6 +71,36 @@ export function checkDuplicate(newText, newEmbedding, existingThreads) {
             method: "embedding",
         };
     }
+    // Token overlap check (works without any API key)
+    const newTokens = tokenize(newText);
+    const newPrefix = extractIssuePrefix(newText);
+    if (newTokens.size > 0) {
+        let bestOverlap = -1;
+        let bestThread = null;
+        for (const thread of existingThreads) {
+            const existingTokens = tokenize(thread.text);
+            if (existingTokens.size === 0)
+                continue;
+            const overlap = tokenOverlap(newTokens, existingTokens);
+            const existingPrefix = extractIssuePrefix(thread.text);
+            const threshold = newPrefix && existingPrefix && newPrefix === existingPrefix
+                ? TOKEN_OVERLAP_ISSUE_PREFIX_THRESHOLD
+                : TOKEN_OVERLAP_THRESHOLD;
+            if (overlap > threshold && overlap > bestOverlap) {
+                bestOverlap = overlap;
+                bestThread = thread;
+            }
+        }
+        if (bestThread && bestOverlap > 0) {
+            return {
+                is_duplicate: true,
+                matched_thread_id: bestThread.thread_id,
+                matched_text: bestThread.text,
+                similarity: round(bestOverlap, 4),
+                method: "token_overlap",
+            };
+        }
+    }
     // Text normalization fallback (conservative: exact match only)
     const normalizedNew = normalizeText(newText);
     for (const thread of existingThreads) {
@@ -106,13 +147,49 @@ export function normalizeText(text) {
         .trim()
         .replace(/[.!?;:]+$/, "");
 }
+/**
+ * Tokenize text into content words for overlap comparison.
+ * Lowercase, split on non-alphanumeric boundaries, remove stop words.
+ */
+export function tokenize(text) {
+    const words = text
+        .toLowerCase()
+        .split(/[^a-z0-9-]+/)
+        .filter((w) => w.length > 1 && !STOP_WORDS.has(w));
+    return new Set(words);
+}
+/**
+ * Overlap coefficient: |intersection| / min(|A|, |B|).
+ * Handles the common case where one thread is a shorter variant of another.
+ * Returns 0 if either set is empty.
+ */
+export function tokenOverlap(a, b) {
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    let intersection = 0;
+    const smaller = a.size <= b.size ? a : b;
+    const larger = a.size <= b.size ? b : a;
+    for (const word of smaller) {
+        if (larger.has(word))
+            intersection++;
+    }
+    return intersection / Math.min(a.size, b.size);
+}
+/**
+ * Extract issue prefix like "OD-692" or "PROJ-123" from thread text.
+ * Returns null if no prefix found.
+ */
+export function extractIssuePrefix(text) {
+    const match = text.match(/^([A-Z]+-\d+)/i);
+    return match ? match[1].toUpperCase() : null;
+}
 function round(value, decimals) {
     const factor = 10 ** decimals;
     return Math.round(value * factor) / factor;
 }
 // ---------- List Deduplication ----------
 /**
- * Deduplicate a thread list by both ID and normalized text.
+ * Deduplicate a thread list by ID, normalized text, and token overlap.
  * First-seen wins. Skips empty-text threads. Does not mutate input.
  *
  * Applied at every thread loading/merging exit point to guarantee
@@ -120,19 +197,44 @@ function round(value, decimals) {
  */
 export function deduplicateThreadList(threads) {
     const seenIds = new Set();
-    const seenText = new Set();
     const result = [];
+    // Track accepted threads with their tokens for overlap comparison
+    const accepted = [];
     for (const thread of threads) {
         const text = thread.text || "";
         const key = normalizeText(text);
         // Skip empty-text threads
         if (!key)
             continue;
-        // Skip if we've seen this ID or this normalized text
-        if (seenIds.has(thread.id) || seenText.has(key))
+        // Skip if we've seen this ID
+        if (seenIds.has(thread.id))
+            continue;
+        // Check exact text match against accepted threads
+        const tokens = tokenize(text);
+        const prefix = extractIssuePrefix(text);
+        let isDuplicate = false;
+        for (const prev of accepted) {
+            // Exact normalized text match
+            if (normalizeText(prev.text) === key) {
+                isDuplicate = true;
+                break;
+            }
+            // Token overlap match
+            if (tokens.size > 0 && prev.tokens.size > 0) {
+                const overlap = tokenOverlap(tokens, prev.tokens);
+                const threshold = prefix && prev.prefix && prefix === prev.prefix
+                    ? TOKEN_OVERLAP_ISSUE_PREFIX_THRESHOLD
+                    : TOKEN_OVERLAP_THRESHOLD;
+                if (overlap > threshold) {
+                    isDuplicate = true;
+                    break;
+                }
+            }
+        }
+        if (isDuplicate)
             continue;
         seenIds.add(thread.id);
-        seenText.add(key);
+        accepted.push({ text, tokens, prefix });
         result.push(thread);
     }
     return result;

package/dist/services/thread-manager.js

@@ -56,8 +56,10 @@ export function normalizeThreads(raw, sourceSession) {
                             id: parsed.id,
                             text: parsed.note,
                             status: parsed.status,
+                            // Preserve existing created_at — only default to now() for genuinely new threads
                             created_at: parsed.created_at || new Date().toISOString(),
-                            ...(sourceSession && { source_session: sourceSession }),
+                            ...(sourceSession && !parsed.source_session && { source_session: sourceSession }),
+                            ...(parsed.source_session && { source_session: parsed.source_session }),
                             ...(parsed.resolved_at && { resolved_at: parsed.resolved_at }),
                         };
                     }
@@ -88,8 +90,9 @@ export function normalizeThreads(raw, sourceSession) {
                         id: inner.id,
                         text: inner.text || inner.note,
                         status: inner.status || item.status,
+                        // Preserve the earliest available created_at — never overwrite with now()
                         created_at: inner.created_at || item.created_at || new Date().toISOString(),
-                        ...(sourceSession && { source_session: sourceSession }),
+                        ...(sourceSession && !item.source_session && { source_session: sourceSession }),
                         ...(inner.resolved_at && { resolved_at: inner.resolved_at }),
                     };
                 }

package/dist/tools/confirm-scars.js

@@ -15,7 +15,7 @@
  *   N_A       — Scar doesn't apply, scenario comparison required
  *   REFUTED   — Overriding scar, risk acknowledgment required
  */
-import { getCurrentSession, getSurfacedScars, addConfirmations, } from "../services/session-state.js";
+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";
@@ -23,7 +23,8 @@ import * as fs from "fs";
 // Minimum evidence length per decision type
 const MIN_EVIDENCE_LENGTH = 50;
 // Future-tense patterns — APPLYING must use past tense
-const FUTURE_PATTERNS = /\b(will|going to|plan to|intend to|I'll|we'll|shall|about to|aim to|expect to)\b/i;
+// Only catch first-person forward-looking language, not third-person "will"
+const FUTURE_PATTERNS = /\b(I will|I'll|we will|we'll|I'm going to|we're going to|I plan to|I intend to|I shall|I aim to|I expect to)\b/i;
 /**
  * Validate a single confirmation against its surfaced scar.
  * Returns null if valid, or an error string if invalid.
@@ -192,9 +193,11 @@ export async function confirmScars(params) {
         }
     }
     // Check for missing scars (all recall scars must be addressed)
+    // Credit scars already confirmed in a previous call this session
+    const previouslyConfirmedIds = new Set(getConfirmations().map(c => c.scar_id));
     const missingScars = [];
     for (const scar of recallScars) {
-        if (!confirmedIds.has(scar.scar_id)) {
+        if (!confirmedIds.has(scar.scar_id) && !previouslyConfirmedIds.has(scar.scar_id)) {
             missingScars.push(scar.scar_title);
         }
     }

package/dist/tools/create-thread.d.ts

@@ -33,7 +33,7 @@ export interface CreateThreadResult {
     deduplicated?: boolean;
     /** Phase 3: dedup gate details */
     dedup?: {
-        method: "embedding" | "text_normalization" | "skipped";
+        method: "embedding" | "token_overlap" | "text_normalization" | "skipped";
         similarity: number | null;
         matched_thread_id: string | null;
     };

package/dist/tools/recall.js

@@ -172,7 +172,9 @@ export async function recall(params) {
     const matchCount = params.match_count || 3;
     const issueId = params.issue_id; // For variant assignment
     // Similarity threshold — suppress weak matches
-    const defaultThreshold = hasSupabase() ? 0.35 : 0.4;
+    // Pro tier: 0.45 calibrated from UX audit (66% N_A rate at 0.35, APPLYING avg 0.55, N_A avg 0.51)
+    // Free tier: 0.4 (BM25 scores are relative — top result always 1.0)
+    const defaultThreshold = hasSupabase() ? 0.45 : 0.4;
     const similarityThreshold = params.similarity_threshold ?? defaultThreshold;
     // Free tier: use local keyword search
     if (!hasSupabase()) {

package/hooks/scripts/recall-check.sh

@@ -1,21 +1,23 @@
 #!/bin/bash
 # GitMem Hooks Plugin — PreToolUse Hook (Recall Check + Confirmation Gate)
 #
-# Two enforcement mechanisms for consequential actions:
+# Two enforcement mechanisms with different trigger scopes:
 #
-# 1. CONFIRMATION GATE (hard block):
+# 1. CONFIRMATION GATE (hard block, consequential actions only):
 #    If recall() surfaced scars but confirm_scars() hasn't been called → BLOCK.
 #    Uses JSON "decision: block" pattern (same as session-close-check.sh).
 #    Only blocks on recall-source scars; session_start scars don't require confirmation.
+#    Consequential = git push, npm publish, deploy, .sql, .env files.
 #
-# 2. RECALL NAG (soft reminder):
-#    If recall hasn't been called recently → nudge (additionalContext, never blocks).
-#    - If recall never called AND >3 tool calls → nag
-#    - Cooldown: no more than once per 60 seconds
+# 2. RECALL NAG (soft reminder, ALL Bash/Write/Edit actions):
+#    If recall hasn't been called AND agent has made 10+ tool calls → nudge.
+#    Never blocks — just injects additionalContext.
+#    Cooldown: no more than once per 90 seconds.
+#    NOTE: hooks.json matchers already limit this to Bash/Write/Edit.
 #
-# Filter layer: Only triggers on consequential actions:
-#   - Bash: git push, git tag, npm publish, deploy commands
-#   - Write/Edit: .sql migrations, .env files
+# UX audit finding: 12 sessions >30min with zero recalls because the nag was
+# gated behind the consequential filter — agents writing .ts files, running
+# tests, etc. were never nudged. Now the nag fires for all code changes.
 #
 # Input: JSON via stdin with tool_name and tool_input
 # Output: JSON with decision:block OR additionalContext OR empty (exit 0)
@@ -88,7 +90,35 @@ read_session_count() {
 TOOL_NAME=$(parse_json "$HOOK_INPUT" ".tool_name")
 
 # ============================================================================
-# Filter layer: Is this a consequential action?
+# Read session state (shared by both gate and nag)
+# ============================================================================
+
+RECALL_SCAR_COUNT=$(read_session_count \
+    '[.surfaced_scars // [] | .[] | select(.source == "recall")] | length' \
+    "const fs=require('fs');try{const s=JSON.parse(fs.readFileSync('$SESSION_FILE','utf8'));const c=(s.surfaced_scars||[]).filter(x=>x.source==='recall');process.stdout.write(String(c.length))}catch(e){process.stdout.write('0')}")
+
+CONFIRMATION_COUNT=$(read_session_count \
+    '[.confirmations // [] | .[]] | length' \
+    "const fs=require('fs');try{const s=JSON.parse(fs.readFileSync('$SESSION_FILE','utf8'));process.stdout.write(String((s.confirmations||[]).length))}catch(e){process.stdout.write('0')}")
+
+# ============================================================================
+# Session state tracking (for nag logic — runs for ALL matched tool calls)
+# ============================================================================
+
+SESSION_ID="${CLAUDE_SESSION_ID:-$$}"
+STATE_DIR="/tmp/gitmem-hooks-${SESSION_ID}"
+mkdir -p "$STATE_DIR"
+
+# Increment tool call count (counts all Bash/Write/Edit, not just consequential)
+TOOL_COUNT=0
+if [ -f "$STATE_DIR/tool_call_count" ]; then
+    TOOL_COUNT=$(cat "$STATE_DIR/tool_call_count")
+fi
+TOOL_COUNT=$((TOOL_COUNT + 1))
+echo "$TOOL_COUNT" > "$STATE_DIR/tool_call_count"
+
+# ============================================================================
+# Filter layer: Is this a consequential action? (used for gate only)
 # ============================================================================
 
 IS_CONSEQUENTIAL=false
@@ -111,26 +141,13 @@ case "$TOOL_NAME" in
         ;;
 esac
 
-# Not consequential → pass through silently
-if [ "$IS_CONSEQUENTIAL" != "true" ]; then
-    exit 0
-fi
-
 # ============================================================================
-# CONFIRMATION GATE (runs first — hard block takes priority over soft nag)
+# CONFIRMATION GATE (hard block — consequential actions only)
 # ============================================================================
 # Block if recall() surfaced scars but confirm_scars() hasn't been called.
 # Only blocks on recall-source scars; session_start scars don't require confirmation.
 
-RECALL_SCAR_COUNT=$(read_session_count \
-    '[.surfaced_scars // [] | .[] | select(.source == "recall")] | length' \
-    "const fs=require('fs');try{const s=JSON.parse(fs.readFileSync('$SESSION_FILE','utf8'));const c=(s.surfaced_scars||[]).filter(x=>x.source==='recall');process.stdout.write(String(c.length))}catch(e){process.stdout.write('0')}")
-
-CONFIRMATION_COUNT=$(read_session_count \
-    '[.confirmations // [] | .[]] | length' \
-    "const fs=require('fs');try{const s=JSON.parse(fs.readFileSync('$SESSION_FILE','utf8'));process.stdout.write(String((s.confirmations||[]).length))}catch(e){process.stdout.write('0')}")
-
-if [ "$RECALL_SCAR_COUNT" -gt 0 ] 2>/dev/null && [ "$CONFIRMATION_COUNT" -eq 0 ] 2>/dev/null; then
+if [ "$IS_CONSEQUENTIAL" = "true" ] && [ "$RECALL_SCAR_COUNT" -gt 0 ] 2>/dev/null && [ "$CONFIRMATION_COUNT" -eq 0 ] 2>/dev/null; then
     # Get scar titles for the error message
     if command -v jq &>/dev/null; then
         SCAR_TITLES=$(jq -r '[.surfaced_scars // [] | .[] | select(.source == "recall") | .scar_title] | join(", ")' "$SESSION_FILE" 2>/dev/null || echo "(unknown)")
@@ -152,24 +169,11 @@ HOOKJSON
 fi
 
 # ============================================================================
-# Session state tracking (for nag logic)
-# ============================================================================
-
-SESSION_ID="${CLAUDE_SESSION_ID:-$$}"
-STATE_DIR="/tmp/gitmem-hooks-${SESSION_ID}"
-mkdir -p "$STATE_DIR"
-
-# Increment tool call count
-TOOL_COUNT=0
-if [ -f "$STATE_DIR/tool_call_count" ]; then
-    TOOL_COUNT=$(cat "$STATE_DIR/tool_call_count")
-fi
-TOOL_COUNT=$((TOOL_COUNT + 1))
-echo "$TOOL_COUNT" > "$STATE_DIR/tool_call_count"
-
-# ============================================================================
-# Cooldown check: don't nag more than once per 60 seconds
+# RECALL NAG (soft reminder — ALL Bash/Write/Edit, not just consequential)
 # ============================================================================
+# UX audit: 12 sessions >30min with zero recalls because nag was gated behind
+# consequential filter. Now fires for any code change after 10+ tool calls.
+# Cooldown: 90s between nags. Never blocks — additionalContext only.
 
 NOW=$(date +%s)
 LAST_NAG=0
@@ -178,21 +182,16 @@ if [ -f "$STATE_DIR/last_nag_time" ]; then
 fi
 
 ELAPSED_SINCE_NAG=$((NOW - LAST_NAG))
-if [ "$ELAPSED_SINCE_NAG" -lt 60 ]; then
+if [ "$ELAPSED_SINCE_NAG" -lt 90 ]; then
     exit 0
 fi
 
-# ============================================================================
-# RECALL NAG: Nudge if recall hasn't been called
-# ============================================================================
-# Check if any recall-source scars exist. If RECALL_SCAR_COUNT is 0 and
-# we've had >3 tool calls, the agent hasn't called recall at all → nag.
-
 SHOULD_NAG=false
 
 if [ "$RECALL_SCAR_COUNT" -eq 0 ] 2>/dev/null; then
-    # No recall scars found — recall probably wasn't called
-    if [ "$TOOL_COUNT" -gt 3 ]; then
+    # No recall scars found — recall hasn't been called this session
+    # Threshold: 10 tool calls to avoid nagging during initial exploration
+    if [ "$TOOL_COUNT" -gt 10 ]; then
         SHOULD_NAG=true
     fi
 fi
@@ -205,7 +204,7 @@ if [ "$SHOULD_NAG" = "true" ]; then
     echo "$NOW" > "$STATE_DIR/last_nag_time"
     cat <<'HOOKJSON'
 {
-  "additionalContext": "GITMEM RECALL REMINDER: You're about to take a consequential action but haven't checked institutional memory recently. Consider calling `recall` (or `gitmem-r`) with your plan before proceeding. This surfaces relevant scars that may prevent repeating past mistakes."
+  "additionalContext": "GITMEM RECALL REMINDER: You've been working for a while without checking institutional memory. Consider calling `recall` (or `gitmem-r`) with your current plan — it surfaces relevant lessons from past sessions that may save time or prevent mistakes. Example: recall({ plan: \"what I'm about to do\" })"
 }
 HOOKJSON
 fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitmem-mcp",
-  "version": "1.0.14",
+  "version": "1.1.0",
   "description": "Institutional memory for AI coding agents. Memory that compounds.",
   "type": "module",
   "main": "dist/index.js",
@@ -55,6 +55,7 @@
     "!hooks/tests",
     "schema",
     "CLAUDE.md.template",
+    "cursorrules.template",
     "README.md",
     "CHANGELOG.md"
   ],