gitmem-mcp 1.2.0 → 1.2.2

package/dist/tools/definitions.js

@@ -77,6 +77,39 @@ export const TOOLS = [
             required: ["confirmations"],
         },
     },
+    {
+        name: "reflect_scars",
+        description: "End-of-session scar reflection — the closing counterpart to confirm_scars. Mirrors CODA-1's [Scar Reflection] protocol. Call BEFORE session_close to provide evidence of how each surfaced scar was handled. OBEYED: concrete evidence of compliance (min 15 chars). REFUTED: why it didn't apply + what was done instead (min 30 chars). Session close uses reflections to set execution_successful accurately.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                reflections: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            scar_id: {
+                                type: "string",
+                                description: "UUID of the surfaced scar (from recall or session_start)",
+                            },
+                            outcome: {
+                                type: "string",
+                                enum: ["OBEYED", "REFUTED"],
+                                description: "OBEYED: followed the scar with evidence. REFUTED: scar didn't apply, explain why.",
+                            },
+                            evidence: {
+                                type: "string",
+                                description: "Concrete evidence of compliance (OBEYED, min 15 chars) or explanation of why scar didn't apply (REFUTED, min 30 chars).",
+                            },
+                        },
+                        required: ["scar_id", "outcome", "evidence"],
+                    },
+                    description: "One reflection per surfaced scar.",
+                },
+            },
+            required: ["reflections"],
+        },
+    },
     {
         name: "session_start",
         description: "Initialize session, detect agent, load institutional context (last session, recent decisions, open threads). Scars surface on-demand via recall(). DISPLAY: The result includes a pre-formatted 'display' field visible in the tool result. Output the display field verbatim as your response — tool results are collapsed in the CLI.",
@@ -768,6 +801,29 @@ export const TOOLS = [
             required: ["confirmations"],
         },
     },
+    {
+        name: "gitmem-rf",
+        description: "gitmem-rf (reflect_scars) - End-of-session scar reflection (OBEYED/REFUTED with evidence)",
+        inputSchema: {
+            type: "object",
+            properties: {
+                reflections: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            scar_id: { type: "string", description: "UUID of the surfaced scar" },
+                            outcome: { type: "string", enum: ["OBEYED", "REFUTED"], description: "Reflection outcome" },
+                            evidence: { type: "string", description: "Evidence (OBEYED min 15 chars, REFUTED min 30 chars)" },
+                        },
+                        required: ["scar_id", "outcome", "evidence"],
+                    },
+                    description: "One reflection per surfaced scar",
+                },
+            },
+            required: ["reflections"],
+        },
+    },
     {
         name: "gitmem-ss",
         description: "gitmem-ss (session_start) - Initialize session with institutional context. DISPLAY: The result includes a pre-formatted 'display' field. Output the display field verbatim as your response — tool results are collapsed in the CLI.",
@@ -1454,6 +1510,29 @@ export const TOOLS = [
             required: ["confirmations"],
         },
     },
+    {
+        name: "gm-reflect",
+        description: "gm-reflect (reflect_scars) - End-of-session scar reflection",
+        inputSchema: {
+            type: "object",
+            properties: {
+                reflections: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            scar_id: { type: "string", description: "UUID of the surfaced scar" },
+                            outcome: { type: "string", enum: ["OBEYED", "REFUTED"] },
+                            evidence: { type: "string", description: "Evidence of compliance or refutation" },
+                        },
+                        required: ["scar_id", "outcome", "evidence"],
+                    },
+                    description: "One reflection per surfaced scar",
+                },
+            },
+            required: ["reflections"],
+        },
+    },
     {
         name: "gm-refresh",
         description: "gm-refresh (session_refresh) - Refresh context for the active session without creating a new one. DISPLAY: The result includes a pre-formatted 'display' field. Output the display field verbatim as your response — tool results are collapsed in the CLI.",
@@ -2117,7 +2196,7 @@ export const TOOLS = [
  */
 export const ALIAS_TOOL_NAMES = new Set([
     // gitmem-* aliases
-    "gitmem-r", "gitmem-cs", "gitmem-ss", "gitmem-sr", "gitmem-sc",
+    "gitmem-r", "gitmem-cs", "gitmem-rf", "gitmem-ss", "gitmem-sr", "gitmem-sc",
     "gitmem-cl", "gitmem-cd", "gitmem-rs", "gitmem-rsb",
     "gitmem-st", "gitmem-gt", "gitmem-stx",
     "gitmem-search", "gitmem-log", "gitmem-analyze",
@@ -2125,7 +2204,7 @@ export const ALIAS_TOOL_NAMES = new Set([
     "gitmem-lt", "gitmem-rt", "gitmem-ct", "gitmem-ps", "gitmem-ds",
     "gitmem-cleanup", "gitmem-health", "gitmem-al", "gitmem-graph",
     // gm-* aliases
-    "gm-open", "gm-confirm", "gm-refresh", "gm-close",
+    "gm-open", "gm-confirm", "gm-reflect", "gm-refresh", "gm-close",
     "gm-scar", "gm-search", "gm-log", "gm-analyze",
     "gm-pc", "gm-absorb",
     "gm-threads", "gm-resolve", "gm-thread-new", "gm-promote", "gm-dismiss",

package/dist/tools/reflect-scars.d.ts

@@ -0,0 +1,20 @@
+/**
+ * reflect_scars Tool
+ *
+ * End-of-session scar reflection — the closing counterpart to confirm_scars.
+ * Mirrors CODA-1's [Scar Reflection] protocol for CLI/DAC/Brain agents.
+ *
+ * Flow:
+ *   recall → confirm_scars (START: "I will...") → work
+ *     → reflect_scars (END: "I did...") → session_close uses reflections
+ *
+ * Each scar surfaced during the session should be reflected upon with:
+ *   OBEYED  — Followed the scar, with concrete evidence (min 15 chars)
+ *   REFUTED — Scar didn't apply or was overridden (min 30 chars)
+ */
+import type { ReflectScarsParams, ReflectScarsResult } from "../types/index.js";
+/**
+ * Main tool implementation: reflect_scars
+ */
+export declare function reflectScars(params: ReflectScarsParams): Promise<ReflectScarsResult>;
+//# sourceMappingURL=reflect-scars.d.ts.map

package/dist/tools/reflect-scars.js

@@ -0,0 +1,219 @@
+/**
+ * reflect_scars Tool
+ *
+ * End-of-session scar reflection — the closing counterpart to confirm_scars.
+ * Mirrors CODA-1's [Scar Reflection] protocol for CLI/DAC/Brain agents.
+ *
+ * Flow:
+ *   recall → confirm_scars (START: "I will...") → work
+ *     → reflect_scars (END: "I did...") → session_close uses reflections
+ *
+ * Each scar surfaced during the session should be reflected upon with:
+ *   OBEYED  — Followed the scar, with concrete evidence (min 15 chars)
+ *   REFUTED — Scar didn't apply or was overridden (min 30 chars)
+ */
+import { getCurrentSession, getSurfacedScars, addReflections, getReflections, } from "../services/session-state.js";
+import { Timer, buildPerformanceData } from "../services/metrics.js";
+import { getSessionPath } from "../services/gitmem-dir.js";
+import { wrapDisplay, STATUS, ANSI } from "../services/display-protocol.js";
+import * as fs from "fs";
+// Minimum evidence lengths (matching CODA-1's refute-or-obey.test.js)
+const MIN_OBEYED_LENGTH = 15;
+const MIN_REFUTED_LENGTH = 30;
+/**
+ * Validate a single reflection.
+ * Returns null if valid, or an error string if invalid.
+ */
+function validateReflection(reflection, scar) {
+    const { outcome, evidence } = reflection;
+    if (!evidence || evidence.trim().length === 0) {
+        return `${scar.scar_title}: Evidence is required for ${outcome}.`;
+    }
+    switch (outcome) {
+        case "OBEYED":
+            if (evidence.trim().length < MIN_OBEYED_LENGTH) {
+                return `${scar.scar_title}: OBEYED evidence too short (${evidence.trim().length} chars, minimum ${MIN_OBEYED_LENGTH}). Provide concrete evidence of compliance.`;
+            }
+            break;
+        case "REFUTED":
+            if (evidence.trim().length < MIN_REFUTED_LENGTH) {
+                return `${scar.scar_title}: REFUTED evidence too short (${evidence.trim().length} chars, minimum ${MIN_REFUTED_LENGTH}). Explain why the scar didn't apply and what was done instead.`;
+            }
+            break;
+        default:
+            return `${scar.scar_title}: Invalid outcome "${outcome}". Must be OBEYED or REFUTED.`;
+    }
+    return null;
+}
+/**
+ * Format the reflection result as markdown.
+ */
+function formatResponse(valid, reflections, errors, missingScars) {
+    const lines = [];
+    if (valid) {
+        lines.push(`${STATUS.ok} SCAR REFLECTIONS ACCEPTED`);
+        lines.push("");
+        for (const ref of reflections) {
+            const indicator = ref.outcome === "OBEYED" ? STATUS.pass : `${ANSI.yellow}!${ANSI.reset}`;
+            lines.push(`${indicator} **${ref.scar_title}** → ${ref.outcome}`);
+        }
+        lines.push("");
+        lines.push("All surfaced scars reflected upon. Session close will use these for execution_successful.");
+    }
+    else {
+        lines.push(`${STATUS.rejected} SCAR REFLECTIONS REJECTED`);
+        lines.push("");
+        if (errors.length > 0) {
+            lines.push("**Validation errors:**");
+            for (const err of errors) {
+                lines.push(`- ${err}`);
+            }
+            lines.push("");
+        }
+        if (missingScars.length > 0) {
+            lines.push("**Unreflected scars (must reflect on all surfaced scars):**");
+            for (const title of missingScars) {
+                lines.push(`- ${title}`);
+            }
+            lines.push("");
+        }
+        lines.push("Fix the errors above and call reflect_scars again.");
+    }
+    return lines.join("\n");
+}
+/**
+ * Persist reflections to the per-session file.
+ */
+function persistReflectionsToFile(reflections) {
+    try {
+        const session = getCurrentSession();
+        if (!session)
+            return;
+        const sessionFilePath = getSessionPath(session.sessionId, "session.json");
+        if (!fs.existsSync(sessionFilePath))
+            return;
+        const data = JSON.parse(fs.readFileSync(sessionFilePath, "utf8"));
+        data.reflections = reflections;
+        fs.writeFileSync(sessionFilePath, JSON.stringify(data, null, 2));
+        console.error(`[reflect_scars] Reflections persisted to ${sessionFilePath}`);
+    }
+    catch (error) {
+        console.warn("[reflect_scars] Failed to persist reflections to file:", error);
+    }
+}
+/**
+ * Main tool implementation: reflect_scars
+ */
+export async function reflectScars(params) {
+    const timer = new Timer();
+    // Validate session exists
+    const session = getCurrentSession();
+    if (!session) {
+        const performance = buildPerformanceData("reflect_scars", timer.elapsed(), 0);
+        const noSessionMsg = `${STATUS.rejected} No active session. Call session_start before reflect_scars.`;
+        return {
+            valid: false,
+            errors: ["No active session. Call session_start first."],
+            reflections: [],
+            missing_scars: [],
+            formatted_response: noSessionMsg,
+            display: wrapDisplay(noSessionMsg),
+            performance,
+        };
+    }
+    // Get ALL surfaced scars (both session_start and recall — reflections cover the whole session)
+    const allSurfacedScars = getSurfacedScars();
+    if (allSurfacedScars.length === 0) {
+        const performance = buildPerformanceData("reflect_scars", timer.elapsed(), 0);
+        const noScarsMsg = `${STATUS.ok} No surfaced scars to reflect upon. Proceed to session close.`;
+        return {
+            valid: true,
+            errors: [],
+            reflections: [],
+            missing_scars: [],
+            formatted_response: noScarsMsg,
+            display: wrapDisplay(noScarsMsg),
+            performance,
+        };
+    }
+    // Build scar lookup by ID
+    const scarById = new Map();
+    for (const scar of allSurfacedScars) {
+        scarById.set(scar.scar_id, scar);
+    }
+    // Validate each reflection
+    const errors = [];
+    const validReflections = [];
+    const reflectedIds = new Set();
+    if (!params.reflections || params.reflections.length === 0) {
+        errors.push("No reflections provided. Each surfaced scar should be reflected upon.");
+    }
+    else {
+        for (const ref of params.reflections) {
+            // Check scar exists (try exact match first)
+            let scar = scarById.get(ref.scar_id);
+            // 8-char prefix match (same as confirm_scars)
+            if (!scar && /^[0-9a-f]{8}$/i.test(ref.scar_id)) {
+                let matchedId = null;
+                for (const [fullId, scarData] of scarById.entries()) {
+                    if (fullId.startsWith(ref.scar_id)) {
+                        if (matchedId) {
+                            errors.push(`Ambiguous scar_id prefix "${ref.scar_id}" matches multiple scars. Use full UUID.`);
+                            scar = undefined;
+                            break;
+                        }
+                        matchedId = fullId;
+                        scar = scarData;
+                    }
+                }
+            }
+            if (!scar) {
+                errors.push(`Unknown scar_id "${ref.scar_id}". Only reflect on scars surfaced during this session.`);
+                continue;
+            }
+            // Validate the reflection
+            const error = validateReflection(ref, scar);
+            if (error) {
+                errors.push(error);
+            }
+            else {
+                validReflections.push({
+                    scar_id: scar.scar_id,
+                    scar_title: scar.scar_title,
+                    outcome: ref.outcome,
+                    evidence: ref.evidence.trim(),
+                    reflected_at: new Date().toISOString(),
+                });
+                reflectedIds.add(scar.scar_id);
+            }
+        }
+    }
+    // Check for unreflected scars — advisory, not blocking
+    // (Unlike confirm_scars which requires all recall scars, reflect_scars
+    // is softer — missing scars are noted but don't invalidate the call)
+    const previouslyReflectedIds = new Set(getReflections().map(r => r.scar_id));
+    const missingScars = [];
+    for (const scar of allSurfacedScars) {
+        if (!reflectedIds.has(scar.scar_id) && !previouslyReflectedIds.has(scar.scar_id)) {
+            missingScars.push(scar.scar_title);
+        }
+    }
+    const valid = errors.length === 0;
+    // If valid, persist to session state and file
+    if (valid && validReflections.length > 0) {
+        addReflections(validReflections);
+        persistReflectionsToFile([...getReflections()]);
+    }
+    const performance = buildPerformanceData("reflect_scars", timer.elapsed(), validReflections.length);
+    const formatted_response = formatResponse(valid, validReflections, errors, missingScars);
+    return {
+        valid,
+        errors,
+        reflections: validReflections,
+        missing_scars: missingScars,
+        formatted_response,
+        display: wrapDisplay(formatted_response),
+        performance,
+    };
+}
+//# sourceMappingURL=reflect-scars.js.map

package/dist/tools/session-close.js

@@ -12,7 +12,7 @@ import * as supabase from "../services/supabase-client.js";
 import { embed, isEmbeddingAvailable } from "../services/embedding.js";
 import { hasSupabase, getTableName } from "../services/tier.js";
 import { getStorage } from "../services/storage.js";
-import { clearCurrentSession, getSurfacedScars, getConfirmations, getObservations, getChildren, getThreads, getSessionActivity } from "../services/session-state.js";
+import { clearCurrentSession, getSurfacedScars, getConfirmations, getReflections, getObservations, getChildren, getThreads, getSessionActivity } from "../services/session-state.js";
 import { normalizeThreads, mergeThreadStates, migrateStringThread, saveThreadsFile } from "../services/thread-manager.js"; // 
 import { deduplicateThreadList } from "../services/thread-dedup.js";
 import { syncThreadsToSupabase, loadOpenThreadEmbeddings } from "../services/thread-supabase.js";
@@ -573,24 +573,47 @@ function bridgeScarsToUsageRecords(normalizedScarsApplied, sessionId, agentIdent
         }
         const autoBridgedScars = [];
         const matchedScarIds = new Set();
-        // Load structured confirmations from confirm_scars (preferred source)
+        // Load structured confirmations from confirm_scars (start-of-task)
         const confirmations = getConfirmations();
         const confirmationMap = new Map();
         for (const conf of confirmations) {
             confirmationMap.set(conf.scar_id, conf);
         }
+        // Load end-of-session reflections from reflect_scars (end-of-task)
+        // Reflections provide the most accurate execution_successful signal
+        const reflections = getReflections();
+        const reflectionMap = new Map();
+        for (const ref of reflections) {
+            reflectionMap.set(ref.scar_id, { outcome: ref.outcome, evidence: ref.evidence });
+        }
         // First pass: match surfaced scars against structured confirmations
         for (const scar of surfacedScars) {
             const confirmation = confirmationMap.get(scar.scar_id);
             if (confirmation) {
                 matchedScarIds.add(scar.scar_id);
+                // Prefer reflect_scars outcome over confirmation default
+                // reflect_scars gives actual end-of-session evidence; confirm_scars is intent
+                const reflection = reflectionMap.get(scar.scar_id);
+                let executionSuccessful;
+                let context;
+                if (reflection) {
+                    // Reflection provides definitive signal
+                    executionSuccessful = reflection.outcome === "OBEYED" ? true : false;
+                    context = `Confirmed: ${confirmation.decision} → Reflected: ${reflection.outcome} — ${reflection.evidence.slice(0, 80)}`;
+                }
+                else {
+                    // Fall back to confirmation-based default (Option A)
+                    executionSuccessful = confirmation.decision === "APPLYING" ? true : undefined;
+                    context = `Confirmed via confirm_scars: ${confirmation.decision} — ${confirmation.evidence.slice(0, 100)}`;
+                }
                 autoBridgedScars.push({
                     scar_identifier: scar.scar_id,
                     session_id: sessionId,
                     agent: agentIdentity,
                     surfaced_at: scar.surfaced_at,
                     reference_type: decisionToRefType(confirmation.decision),
-                    reference_context: `Confirmed via confirm_scars: ${confirmation.decision} — ${confirmation.evidence.slice(0, 100)}`,
+                    reference_context: context,
+                    execution_successful: executionSuccessful,
                     variant_id: scar.variant_id,
                 });
             }
@@ -619,6 +642,7 @@ function bridgeScarsToUsageRecords(normalizedScarsApplied, sessionId, agentIdent
             }
         }
         // For surfaced scars NOT matched by either method, record as "none"
+        // execution_successful = false — scar was surfaced but ignored entirely
         for (const scar of surfacedScars) {
             if (!matchedScarIds.has(scar.scar_id)) {
                 autoBridgedScars.push({
@@ -628,6 +652,7 @@ function bridgeScarsToUsageRecords(normalizedScarsApplied, sessionId, agentIdent
                     surfaced_at: scar.surfaced_at,
                     reference_type: "none",
                     reference_context: `Surfaced during ${scar.source} but not mentioned in closing reflection`,
+                    execution_successful: false,
                     variant_id: scar.variant_id,
                 });
             }

package/dist/types/index.d.ts

@@ -330,6 +330,30 @@ export interface ConfirmScarsResult {
     display?: string;
     performance: PerformanceData;
 }
+export type ReflectionOutcome = "OBEYED" | "REFUTED";
+export interface ScarReflection {
+    scar_id: string;
+    scar_title: string;
+    outcome: ReflectionOutcome;
+    evidence: string;
+    reflected_at: string;
+}
+export interface ReflectScarsParams {
+    reflections: Array<{
+        scar_id: string;
+        outcome: ReflectionOutcome;
+        evidence: string;
+    }>;
+}
+export interface ReflectScarsResult {
+    valid: boolean;
+    errors: string[];
+    reflections: ScarReflection[];
+    missing_scars: string[];
+    formatted_response: string;
+    display?: string;
+    performance: PerformanceData;
+}
 export type ReferenceType = "explicit" | "implicit" | "acknowledged" | "refuted" | "none";
 export interface RecordScarUsageParams {
     scar_id: string;

package/hooks/scripts/auto-retrieve-hook.sh

@@ -65,6 +65,37 @@ PROMPT_LEN=${#PROMPT}
 
 RETRIEVAL_LEVEL=""
 
+# Priority 0: Knowledge-retrieval queries — route through gitmem, don't inject scars
+# These are queries where the user wants to ACCESS institutional memory, not just
+# have scars passively injected. Output a routing instruction instead of scars.
+IS_KNOWLEDGE_QUERY=false
+
+# Explicit recall/remember commands
+if echo "$PROMPT_LOWER" | grep -qE '\b(recall|remember)\b.*(doc|process|tree|structure|how|what|where|our)'; then
+    IS_KNOWLEDGE_QUERY=true
+# Process/documentation queries ("what's our process for X", "how do we usually Y")
+elif echo "$PROMPT_LOWER" | grep -qE "(what('s| is) our (process|approach|pattern|method)|how do we (usually|typically|normally)|remind me (how|what|about)|what('s| is) the (process|protocol|procedure) for)"; then
+    IS_KNOWLEDGE_QUERY=true
+# Documentation discovery ("show me the docs", "where are the scars")
+elif echo "$PROMPT_LOWER" | grep -qE '\b(show me|find|where (is|are|do)).*(doc(s|umentation)?|process(es)?|pattern(s)?|decision(s)?|scar(s)?|learning(s)?)\b'; then
+    IS_KNOWLEDGE_QUERY=true
+# Institutional knowledge queries ("what did we decide about", "what scars exist")
+elif echo "$PROMPT_LOWER" | grep -qE '\b(what did we (decide|learn|document)|what scars|what learnings|past decisions about|institutional (memory|knowledge))\b'; then
+    IS_KNOWLEDGE_QUERY=true
+# Direct "recall" as a verb/command at start of prompt
+elif echo "$PROMPT_LOWER" | grep -qE '^\s*recall\b'; then
+    IS_KNOWLEDGE_QUERY=true
+fi
+
+if [ "$IS_KNOWLEDGE_QUERY" = "true" ]; then
+    cat <<HOOKJSON
+{
+  "additionalContext": "KNOWLEDGE RETRIEVAL DETECTED. Route through GitMem FIRST:\n\n1. gitmem search (query relevant to the question) OR gitmem recall (if action-oriented)\n2. gitmem log (if browsing recent learnings)\n3. ONLY THEN fall back to filesystem reads if gitmem doesn't have the answer\n\nDo NOT start with Read/Glob/Grep on local files. Institutional memory exists precisely so we don't re-explore the filesystem every time."
+}
+HOOKJSON
+    exit 0
+fi
+
 # Priority 1: Trivial — skip retrieval entirely
 if echo "$PROMPT_LOWER" | grep -qE '^(yes|no|ok|k|y|n|sure|thanks|thank you|continue|go ahead|proceed|correct|right|exactly|got it|sounds good|lgtm|looks good|done|nope|yep|yup|agreed)$'; then
     exit 0

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "gitmem-mcp",
-  "version": "1.2.0",
+  "version": "1.2.2",
+  "mcpName": "io.github.gitmem-dev/gitmem",
   "description": "Institutional memory for AI coding agents. Memory that compounds.",
   "type": "module",
   "main": "dist/index.js",