gitmem-mcp 1.1.3 → 1.2.0

package/dist/tools/session-close.js

@@ -19,7 +19,7 @@ import { syncThreadsToSupabase, loadOpenThreadEmbeddings } from "../services/thr
 import { validateSessionClose, buildCloseCompliance, } from "../services/compliance-validator.js";
 import { normalizeReflectionKeys } from "../constants/closing-questions.js";
 import { Timer, recordMetrics, buildPerformanceData, updateRelevanceData, } from "../services/metrics.js";
-import { wrapDisplay, truncate } from "../services/display-protocol.js";
+import { wrapDisplay, truncate, productLine, dimText, STATUS, ANSI } from "../services/display-protocol.js";
 import { recordScarUsageBatch } from "./record-scar-usage-batch.js";
 import { getEffectTracker } from "../services/effect-tracker.js";
 import { saveTranscript } from "./save-transcript.js";
@@ -242,107 +242,73 @@ async function sessionCloseFree(params, timer) {
 }
 function formatCloseDisplay(sessionId, compliance, params, learningsCount, success, errors, transcriptStatus) {
     const lines = [];
-    // Header
-    const B = "\x1b[1m"; // bold on
-    const D = "\x1b[2m"; // dim on
-    const R = "\x1b[0m"; // reset
-    const closeLabel = compliance.close_type.toUpperCase();
-    const status = success ? "COMPLETE" : "FAILED";
-    lines.push(`${B}${closeLabel} CLOSE — ${status}${R}`);
-    lines.push(`Session ${sessionId.slice(0, 8)} · ${compliance.agent}`);
+    // Header: branded product line
+    const status = success ? STATUS.complete : STATUS.failed;
+    lines.push(productLine("close", status));
+    // Stats line: compact one-liner with key counts
+    const stats = [];
+    const scarsApplied = params.scars_to_record?.filter(s => s.reference_type !== "none").length || 0;
+    if (scarsApplied > 0)
+        stats.push(`${scarsApplied} scars applied`);
+    if (learningsCount > 0)
+        stats.push(`${learningsCount} learnings`);
+    if (params.decisions?.length)
+        stats.push(`${params.decisions.length} decision${params.decisions.length > 1 ? "s" : ""}`);
+    const threads = params.open_threads || [];
+    const openCount = threads.filter(t => typeof t === "string" || t.status === "open").length;
+    if (openCount > 0)
+        stats.push(`${openCount} threads`);
+    if (stats.length > 0) {
+        lines.push(stats.join(" · "));
+    }
+    lines.push(dimText(`${sessionId.slice(0, 8)} · ${compliance.agent} · ${compliance.close_type}`));
+    // Errors — only on failure
     if (!success && errors?.length) {
         lines.push("");
         for (const e of errors)
-            lines.push(`  !! ${e}`);
-    }
-    // Checklist (compact)
-    lines.push("");
-    const ok = "\u2713";
-    const no = "\u2717";
-    if (compliance.close_type === "standard") {
-        lines.push(`  ${ok} Session state read`);
-        lines.push(`  ${compliance.questions_answered_by_agent ? ok : no} Reflection (9 questions)`);
-        lines.push(`  ${compliance.human_asked_for_corrections ? ok : no} Human corrections`);
-        lines.push(`  ${success ? ok : no} Persisted`);
+            lines.push(`  ${STATUS.miss} ${e}`);
     }
-    else {
-        lines.push(`  ${success ? ok : no} Persisted (${compliance.close_type})`);
+    // Reflection highlights FIRST — the most interesting part
+    if (params.closing_reflection) {
+        const r = params.closing_reflection;
+        if (r.what_worked || r.do_differently) {
+            lines.push("");
+            if (r.what_worked) {
+                lines.push(`${STATUS.pass} ${truncate(r.what_worked, 72)}`);
+            }
+            if (r.do_differently) {
+                lines.push(`${ANSI.yellow}>${ANSI.reset} ${truncate(r.do_differently, 72)}`);
+            }
+        }
     }
-    // Decisions table
+    // Decisions — title only, one line each
     if (params.decisions?.length) {
         lines.push("");
-        lines.push(`${B}Decisions${R}`);
         for (const d of params.decisions) {
-            lines.push(`  ${truncate(d.title, 60)}`);
-            lines.push(`    ${truncate(d.decision, 70)}`);
-        }
-    }
-    // Learnings created
-    if (params.learnings_created?.length) {
-        lines.push("");
-        lines.push(`${B}Learnings (${params.learnings_created.length})${R}`);
-        for (const l of params.learnings_created) {
-            // learnings_created is (string | Record)[] — show truncated ID or object key
-            const label = typeof l === "string" ? (l.length > 12 ? l.slice(0, 8) : l) : String(l);
-            lines.push(`  ${label}`);
+            lines.push(`  ${dimText("d")} ${truncate(d.title, 68)}`);
         }
     }
-    // Scars applied
-    if (params.scars_to_record?.length) {
-        const acknowledged = params.scars_to_record.filter(s => s.reference_type !== "none");
-        const ignored = params.scars_to_record.length - acknowledged.length;
+    // Scars applied — compact table, only if any were applied
+    if (scarsApplied > 0) {
         lines.push("");
-        lines.push(`${B}Scars (${acknowledged.length} applied${ignored > 0 ? `, ${ignored} surfaced-only` : ""})${R}`);
-        for (const s of acknowledged) {
+        for (const s of params.scars_to_record.filter(s => s.reference_type !== "none")) {
             const ref = s.reference_type === "explicit" ? "applied" :
                 s.reference_type === "implicit" ? "implicit" :
                     s.reference_type === "acknowledged" ? "ack'd" :
-                        s.reference_type === "refuted" ? "REFUTED" : (s.reference_type || "?");
-            const scarId = s.scar_identifier || "(unknown)";
-            const id = scarId.length > 12 ? scarId.slice(0, 8) : scarId;
-            lines.push(`  ${id}  ${ref.padEnd(8)}  ${truncate(s.reference_context || "", 50)}`);
+                        s.reference_type === "refuted" ? `${ANSI.yellow}REFUTED${ANSI.reset}` : (s.reference_type || "?");
+            lines.push(`  ${dimText(ref.padEnd(8))} ${truncate(s.reference_context || "", 60)}`);
         }
     }
-    // Transcript status
-    if (transcriptStatus) {
+    // Transcript — only on failure
+    if (transcriptStatus && !transcriptStatus.saved) {
         lines.push("");
-        lines.push(`### Transcript`);
-        if (transcriptStatus.saved) {
-            let line = `- [done] Saved (${transcriptStatus.size_kb}KB) -> ${transcriptStatus.path}`;
-            if (transcriptStatus.patch_warning) {
-                line += ` (warning: session record not updated)`;
-            }
-            lines.push(line);
-        }
-        else {
-            lines.push(`- [FAILED] ${transcriptStatus.error || "Unknown error"}`);
-        }
+        lines.push(`${STATUS.fail} transcript: ${transcriptStatus.error || "Unknown error"}`);
     }
-    // Threads summary
-    const threads = params.open_threads || [];
-    if (threads.length > 0) {
-        const openCount = threads.filter(t => typeof t === "string" || t.status === "open").length;
-        const resolvedCount = threads.length - openCount;
-        lines.push("");
-        lines.push(`${B}Threads${R}: ${openCount} open${resolvedCount > 0 ? `, ${resolvedCount} resolved` : ""}`);
-    }
-    // Write health — only surface when there are failures (dev diagnostic)
+    // Write health — only on failure
     const healthReport = getEffectTracker().getHealthReport();
     if (healthReport.overall.failed > 0) {
         lines.push("");
-        lines.push(`${B}Write Health${R} (${healthReport.overall.failed} failure${healthReport.overall.failed > 1 ? "s" : ""})`);
-        lines.push(getEffectTracker().formatSummary());
-    }
-    // Reflection highlights (Q4 what worked, Q3 do differently)
-    if (params.closing_reflection) {
-        const r = params.closing_reflection;
-        if (r.what_worked) {
-            lines.push("");
-            lines.push(`${B}What worked${R}: ${truncate(r.what_worked, 80)}`);
-        }
-        if (r.do_differently) {
-            lines.push(`${B}Next time${R}: ${truncate(r.do_differently, 80)}`);
-        }
+        lines.push(`${STATUS.warn} ${healthReport.overall.failed} write failure${healthReport.overall.failed > 1 ? "s" : ""}`);
     }
     return wrapDisplay(lines.join("\n"));
 }
@@ -784,6 +750,36 @@ export async function sessionClose(params) {
             human_response: "auto-normalized from string payload",
         };
     }
+    // Auto-generate task_completion when missing or has empty human response fields.
+    // Agents write closing_reflection to the payload before asking the human, so
+    // human_response_at and human_response are often empty. Rather than requiring
+    // agents to edit the payload a second time, we fill these from human_corrections
+    // (which the agent passes directly) and stamp the current time.
+    if (params.close_type === "standard" && params.task_completion && typeof params.task_completion === "object") {
+        const tc = params.task_completion;
+        if (!tc.human_response || tc.human_response.trim() === "") {
+            tc.human_response = params.human_corrections || "none";
+            console.error("[session_close] Auto-filled task_completion.human_response from human_corrections");
+        }
+        if (!tc.human_response_at || tc.human_response_at.trim() === "") {
+            tc.human_response_at = new Date().toISOString();
+            console.error("[session_close] Auto-filled task_completion.human_response_at with current time");
+        }
+    }
+    // Auto-generate task_completion entirely when payload has closing_reflection but no task_completion.
+    // This is the common case: agent writes reflection to payload, asks human, calls session_close.
+    if (params.close_type === "standard" && !params.task_completion && params.closing_reflection) {
+        const now = new Date().toISOString();
+        const fiveSecsAgo = new Date(Date.now() - 5000).toISOString();
+        params.task_completion = {
+            questions_displayed_at: fiveSecsAgo,
+            reflection_completed_at: fiveSecsAgo,
+            human_asked_at: fiveSecsAgo,
+            human_response_at: now,
+            human_response: params.human_corrections || "none",
+        };
+        console.error("[session_close] Auto-generated task_completion from closing_reflection + human_corrections");
+    }
     // Adaptive ceremony level based on session activity.
     // Three levels: micro (quick fix), standard (normal), full (long/heavy session).
     // t-f7c2fa01: If closing_reflection is already present, skip the mismatch gate.
@@ -1084,6 +1080,32 @@ export async function sessionClose(params) {
         if (normalizedScarsApplied.length > 0) {
             updateRelevanceData(sessionId, normalizedScarsApplied).catch((err) => console.error("[session_close] updateRelevanceData failed:", err instanceof Error ? err.message : err));
         }
+        // Compute timing breakdown from task_completion timestamps.
+        // The human feels two things during close:
+        //   1. Agent reflection: questions_displayed_at → human_asked_at (LLM writes 9-question payload)
+        //   2. Tool execution: latency_ms (DB writes after human says "none" / gives corrections)
+        // The human does NOT feel: human_asked_at → human_response_at (their own thinking time)
+        let agentReflectionMs;
+        let humanWaitTimeMs;
+        if (params.task_completion && typeof params.task_completion === "object") {
+            const tc = params.task_completion;
+            // Agent reflection time = when questions shown → when human asked "Corrections?"
+            if (tc.questions_displayed_at && tc.human_asked_at) {
+                const started = new Date(tc.questions_displayed_at).getTime();
+                const askedHuman = new Date(tc.human_asked_at).getTime();
+                if (!isNaN(started) && !isNaN(askedHuman) && askedHuman > started) {
+                    agentReflectionMs = askedHuman - started;
+                }
+            }
+            // Human wait time = "Corrections?" → human responds
+            if (tc.human_asked_at && tc.human_response_at) {
+                const asked = new Date(tc.human_asked_at).getTime();
+                const responded = new Date(tc.human_response_at).getTime();
+                if (!isNaN(asked) && !isNaN(responded) && responded > asked) {
+                    humanWaitTimeMs = responded - asked;
+                }
+            }
+        }
         // Record metrics
         recordMetrics({
             id: metricsId,
@@ -1102,6 +1124,8 @@ export async function sessionClose(params) {
                 decisions_count: params.decisions?.length || 0,
                 open_threads_count: params.open_threads?.length || 0,
                 ceremony_duration_ms: params.ceremony_duration_ms,
+                agent_reflection_ms: agentReflectionMs,
+                human_wait_time_ms: humanWaitTimeMs,
                 retroactive: isRetroactive,
             },
         }).catch(() => { });

package/dist/tools/session-start.js

@@ -28,6 +28,7 @@ import { setGitmemDir, getGitmemDir, getSessionPath, getConfigProject } from "..
 import { registerSession, findSessionByHostPid, pruneStale, migrateFromLegacy } from "../services/active-sessions.js";
 import * as os from "os";
 import { formatDate } from "../services/timezone.js";
+import { productLine, dimText, boldText } from "../services/display-protocol.js";
 /**
  * Closing payload schema — returned in session_start/refresh so agents
  * know the exact field names for closing-payload.json without guessing.
@@ -42,19 +43,27 @@ const CLOSING_PAYLOAD_SCHEMA = {
         scars_applied: ["Q6: scar titles applied"],
         institutional_memory_items: "Q7: What to capture as institutional memory?",
     },
-    task_completion: {
-        questions_displayed_at: "ISO-8601",
-        reflection_completed_at: "ISO-8601",
-        human_asked_at: "ISO-8601",
-        human_response_at: "ISO-8601",
-        human_response: "human's corrections or 'no corrections'",
-    },
-    human_corrections: "",
+    // task_completion is auto-generated by session_close — do NOT include in payload.
+    // Timestamps are stamped by the tool. human_response is filled from human_corrections.
+    human_corrections: "human's corrections or 'none'",
     scars_to_record: [],
     learnings_created: [],
     open_threads: [],
     decisions: [],
 };
+const FIRST_SESSION_NUDGE = [
+    "",
+    "Welcome to gitmem. Patterns that improve the experience:",
+    "",
+    "  - session_start: once per session — if a hook triggers it, don't repeat",
+    "  - Display protocol: echo tool results verbatim, including ANSI formatting",
+    "  - recall() before consequential actions (deploys, issues, agent spawns)",
+    "  - Read .gitmem/ state before session close — survives context compaction",
+    "  - Search gitmem before filesystem exploration — memory > re-discovery",
+    "  - Create learning entries after significant work, before closing",
+    "",
+    "Save these to your persistent memory (MEMORY.md) so they carry forward.",
+].join("\n");
 /**
  * Normalize decisions from mixed formats (strings or objects) to string[].
  * Historical sessions (pre-2026) stored {title, decision} objects.
@@ -444,7 +453,8 @@ async function sessionStartFree(params, env, agent, project, timer, metricsId, e
         project,
         performance,
     };
-    freeResult.display = formatStartDisplay(freeResult);
+    const isFirstSession = !isResuming && !lastSession;
+    freeResult.display = formatStartDisplay(freeResult, undefined, isFirstSession);
     // Write display to per-session dir
     try {
         const sessionFilePath = getSessionPath(sessionId, "session.json");
@@ -654,22 +664,22 @@ function writeSessionFiles(sessionId, agent, project, surfacedScars, threads, re
 function stripThreadPrefix(text) {
     return text.replace(/^t-[a-f0-9]+:\s*/i, "");
 }
-function formatStartDisplay(result, displayInfoMap) {
+function formatStartDisplay(result, displayInfoMap, isFirstSession) {
     const visual = [];
-    // Line 1: product name + session state
+    // Line 1: branded product line + session state
     const stateLabel = result.refreshed ? "refreshed" : (result.resumed ? "resumed" : "active");
-    visual.push(`gitmem ── ${stateLabel}`);
-    // Line 2: session ID + agent + project
+    visual.push(productLine(stateLabel));
+    // Line 2: session ID + agent + project (dim metadata)
     const parts = [result.session_id, result.agent];
     if (result.project)
         parts.push(result.project);
-    visual.push(parts.join(" · "));
+    visual.push(dimText(parts.join(" · ")));
     // Threads section — top 5 by vitality, truncated to 60 chars
     const hasThreads = result.open_threads && result.open_threads.length > 0;
     const hasDecisions = result.recent_decisions && result.recent_decisions.length > 0;
     if (hasThreads) {
         visual.push("");
-        visual.push(`Threads (${result.open_threads.length})`);
+        visual.push(boldText(`Threads (${result.open_threads.length})`));
         const enriched = result.open_threads.map(t => ({
             thread: t,
             info: displayInfoMap?.get(t.id),
@@ -689,7 +699,7 @@ function formatStartDisplay(result, displayInfoMap) {
     // Decisions section — top 3 with compact date
     if (hasDecisions) {
         visual.push("");
-        visual.push(`Decisions (${result.recent_decisions.length})`);
+        visual.push(boldText(`Decisions (${result.recent_decisions.length})`));
         for (const d of result.recent_decisions.slice(0, 3)) {
             const title = d.title.length > 50 ? d.title.slice(0, 47) + "..." : d.title;
             visual.push(`  ${title} · ${d.date}`);
@@ -699,6 +709,10 @@ function formatStartDisplay(result, displayInfoMap) {
         visual.push("");
         visual.push("No threads or decisions.");
     }
+    // First-session nudge — agent sees this once, internalizes to PMEM
+    if (isFirstSession) {
+        visual.push(FIRST_SESSION_NUDGE);
+    }
     const visualBlock = visual.join("\n");
     // ── Display-first layout ──
     // Visual block comes FIRST so Claude Code's collapsed tool output shows
@@ -883,7 +897,8 @@ export async function sessionStart(params) {
     for (const info of threadDisplayInfo) {
         displayInfoMap.set(info.thread.id, info);
     }
-    result.display = formatStartDisplay(result, displayInfoMap);
+    const isFirstSession = !isResuming && !slimLastSession;
+    result.display = formatStartDisplay(result, displayInfoMap, isFirstSession);
     // Write display to per-session dir
     try {
         const sessionFilePath = getSessionPath(sessionId, "session.json");

package/package.json

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

package/windsurfrules.template

@@ -46,18 +46,19 @@ Safe alternatives: `env | grep -c VARNAME` (count only), `[ -n "$VARNAME" ] && e
 
 **End:** On "closing", "done for now", or "wrapping up":
 
-1. **Answer these reflection questions** and display to the human:
-   - What broke that you didn't expect?
-   - What took longer than it should have?
-   - What would you do differently next time?
-   - What pattern or approach worked well?
-   - What assumption was wrong?
-   - Which scars did you apply?
-   - What should be captured as institutional memory?
-
-2. **Ask the human**: "Any corrections or additions?" Wait for their response.
-
-3. **Write payload** to `.gitmem/closing-payload.json`:
+1. **Write reflection directly to payload** — do NOT display the full Q&A to the human.
+   Internally answer these 9 questions and write them straight to `.gitmem/closing-payload.json`:
+   - Q1: What broke that you didn't expect?
+   - Q2: What took longer than it should have?
+   - Q3: What would you do differently next time?
+   - Q4: What pattern or approach worked well?
+   - Q5: What assumption was wrong?
+   - Q6: Which scars did you apply?
+   - Q7: What should be captured as institutional memory?
+   - Q8: How did the human prefer to work this session?
+   - Q9: What collaborative dynamic worked or didn't?
+
+   Payload schema (`.gitmem/closing-payload.json`):
    ```json
    {
      "closing_reflection": {
@@ -67,16 +68,34 @@ Safe alternatives: `env | grep -c VARNAME` (count only), `[ -n "$VARNAME" ] && e
        "what_worked": "...",
        "wrong_assumption": "...",
        "scars_applied": ["scar title 1", "scar title 2"],
-       "institutional_memory_items": "..."
+       "institutional_memory_items": "...",
+       "collaborative_dynamic": "...",
+       "rapport_notes": "..."
+     },
+     "task_completion": {
+       "questions_displayed_at": "ISO timestamp (when reflection started)",
+       "reflection_completed_at": "ISO timestamp (when payload written)",
+       "human_asked_at": "ISO timestamp (when 'Corrections?' shown)",
+       "human_response_at": "ISO timestamp (when human replied)",
+       "human_response": "user's correction text or 'none'"
      },
      "human_corrections": "",
      "scars_to_record": [],
+     "learnings_created": [],
      "open_threads": [],
      "decisions": []
    }
    ```
 
-4. **Call `session_close`** with `session_id` and `close_type: "standard"`
+2. **Show compact summary** (3-4 lines max):
+   ```
+   Session close: [N] learnings captured, [M] scars applied, [K] threads open
+   Key lesson: [one-sentence from Q7]
+   ```
+
+3. **Ask**: "Corrections?" — wait for response, then call `session_close`.
+
+4. **Call `session_close`** with `session_id` and `close_type: "standard"`.
 
 For short exploratory sessions (< 30 min, no real work), use `close_type: "quick"` — no questions needed.
 # --- gitmem:end ---