gitmem-mcp 1.1.2 → 1.1.3

package/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.1.3] - 2026-02-19
+
+### Fixed
+- **Thread display output**: `list_threads` and `cleanup_threads` replaced ASCII box-drawing tables with markdown tables. Thread text truncation increased from 40-48 to 60 characters. Output now renders cleanly in all MCP clients instead of clipping on narrow terminals.
+
 ## [1.1.2] - 2026-02-17
 
 ### Changed

package/README.md

@@ -21,7 +21,9 @@
 
 GitMem is an [MCP server](https://modelcontextprotocol.io/) that gives your AI coding agent **persistent memory across sessions**. It remembers mistakes (scars), successes (wins), and decisions — so your agent learns from experience instead of starting from scratch every time.
 
-Works with **Claude Code**, **Claude Desktop**, **Cursor**, and any MCP-compatible client.
+> **What's MCP?** [Model Context Protocol](https://modelcontextprotocol.io/) is how AI coding tools connect to external capabilities. GitMem is an MCP server — install it once and your agent gains persistent memory.
+
+Works with **Claude Code**, **Cursor**, **VS Code (Copilot)**, **Windsurf**, and any MCP-compatible client.
 
 ## Quick Start
 
@@ -29,19 +31,19 @@ Works with **Claude Code**, **Claude Desktop**, **Cursor**, and any MCP-compatib
 npx gitmem-mcp init
 ```
 
-One command. The wizard sets up everything:
-- `.gitmem/` directory with 3 starter scars
-- `.mcp.json` with gitmem server entry
-- `CLAUDE.md` with memory protocol instructions
-- `.claude/settings.json` with tool permissions
-- Lifecycle hooks for automatic session management
+One command. The wizard auto-detects your IDE and sets up everything:
+- `.gitmem/` directory with starter scars
+- MCP server config (`.mcp.json`, `.vscode/mcp.json`, `.cursor/mcp.json`, etc.)
+- Instructions file (`CLAUDE.md`, `.cursorrules`, `.windsurfrules`, `.github/copilot-instructions.md`)
+- Lifecycle hooks (where supported)
 - `.gitignore` updated
 
 Already have existing config? The wizard merges without destroying anything. Re-running is safe.
 
 ```bash
-npx gitmem-mcp init --yes       # Non-interactive
-npx gitmem-mcp init --dry-run   # Preview changes
+npx gitmem-mcp init --yes                # Non-interactive
+npx gitmem-mcp init --dry-run            # Preview changes
+npx gitmem-mcp init --client vscode      # Force specific client
 ```
 
 ## How It Works
@@ -78,16 +80,22 @@ Every scar includes **counter-arguments** — reasons why someone might reasonab
 
 ## Supported Clients
 
-| Client | Setup |
-|--------|-------|
-| **Claude Code** | `npx gitmem-mcp init` (auto-detected) |
-| **Claude Desktop** | `npx gitmem-mcp init` or add to `claude_desktop_config.json` |
-| **Cursor** | `npx gitmem-mcp init` or add to `.cursor/mcp.json` |
-| **Any MCP client** | Add `npx -y gitmem-mcp` as an MCP server |
+| Client | Setup | Hooks |
+|--------|-------|-------|
+| **Claude Code** | `npx gitmem-mcp init` | Full (session, recall, credential guard) |
+| **Cursor** | `npx gitmem-mcp init --client cursor` | Partial (session, recall) |
+| **VS Code (Copilot)** | `npx gitmem-mcp init --client vscode` | Instructions-based |
+| **Windsurf** | `npx gitmem-mcp init --client windsurf` | Instructions-based |
+| **Claude Desktop** | Add to `claude_desktop_config.json` | Manual |
+| **Any MCP client** | `npx gitmem-mcp init --client generic` | Instructions-based |
+
+The wizard auto-detects your IDE. Use `--client` to override.
 
 <details>
 <summary><strong>Manual MCP configuration</strong></summary>
 
+Add this to your MCP client's config file:
+
 ```json
 {
   "mcpServers": {
@@ -99,13 +107,21 @@ Every scar includes **counter-arguments** — reasons why someone might reasonab
 }
 ```
 
+| Client | Config file |
+|--------|-------------|
+| Claude Code | `.mcp.json` |
+| Cursor | `.cursor/mcp.json` |
+| VS Code | `.vscode/mcp.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+
 </details>
 
 ## CLI Commands
 
 | Command | Description |
 |---------|-------------|
-| `npx gitmem-mcp init` | Interactive setup wizard |
+| `npx gitmem-mcp init` | Interactive setup wizard (auto-detects IDE) |
+| `npx gitmem-mcp init --client <name>` | Setup for specific client (`claude`, `cursor`, `vscode`, `windsurf`, `generic`) |
 | `npx gitmem-mcp init --yes` | Non-interactive setup |
 | `npx gitmem-mcp init --dry-run` | Preview changes |
 | `npx gitmem-mcp uninstall` | Clean removal (preserves `.gitmem/` data) |

package/bin/init-wizard.js

@@ -6,7 +6,7 @@
  * Interactive setup that detects existing config, prompts, and merges.
  * Supports Claude Code and Cursor IDE.
  *
- * Usage: npx gitmem-mcp init [--yes] [--dry-run] [--project <name>] [--client <claude|cursor>]
+ * Usage: npx gitmem-mcp init [--yes] [--dry-run] [--project <name>] [--client <claude|cursor|vscode|windsurf|generic>]
  */
 
 import {
@@ -35,11 +35,15 @@ const clientFlag = clientIdx !== -1 ? args[clientIdx + 1]?.toLowerCase() : null;
 
 // ── Client Configuration ──
 
+// Resolve user home directory for clients that use user-level config
+const homeDir = process.env.HOME || process.env.USERPROFILE || "~";
+
 const CLIENT_CONFIGS = {
   claude: {
     name: "Claude Code",
     mcpConfigPath: join(cwd, ".mcp.json"),
     mcpConfigName: ".mcp.json",
+    mcpConfigScope: "project",
     instructionsFile: join(cwd, "CLAUDE.md"),
     instructionsName: "CLAUDE.md",
     templateFile: join(__dirname, "..", "CLAUDE.md.template"),
@@ -50,12 +54,14 @@ const CLIENT_CONFIGS = {
     settingsLocalFile: join(cwd, ".claude", "settings.local.json"),
     hasPermissions: true,
     hooksInSettings: true,
+    hasHooks: true,
     completionMsg: "Setup complete! Start Claude Code \u2014 memory is active.",
   },
   cursor: {
     name: "Cursor",
     mcpConfigPath: join(cwd, ".cursor", "mcp.json"),
     mcpConfigName: ".cursor/mcp.json",
+    mcpConfigScope: "project",
     instructionsFile: join(cwd, ".cursorrules"),
     instructionsName: ".cursorrules",
     templateFile: join(__dirname, "..", "cursorrules.template"),
@@ -66,10 +72,66 @@ const CLIENT_CONFIGS = {
     settingsLocalFile: null,
     hasPermissions: false,
     hooksInSettings: false,
+    hasHooks: true,
     hooksFile: join(cwd, ".cursor", "hooks.json"),
     hooksFileName: ".cursor/hooks.json",
     completionMsg: "Setup complete! Open Cursor (Agent mode) \u2014 memory is active.",
   },
+  vscode: {
+    name: "VS Code (Copilot)",
+    mcpConfigPath: join(cwd, ".vscode", "mcp.json"),
+    mcpConfigName: ".vscode/mcp.json",
+    mcpConfigScope: "project",
+    instructionsFile: join(cwd, ".github", "copilot-instructions.md"),
+    instructionsName: ".github/copilot-instructions.md",
+    templateFile: join(__dirname, "..", "copilot-instructions.template"),
+    startMarker: "<!-- gitmem:start -->",
+    endMarker: "<!-- gitmem:end -->",
+    configDir: join(cwd, ".vscode"),
+    settingsFile: null,
+    settingsLocalFile: null,
+    hasPermissions: false,
+    hooksInSettings: false,
+    hasHooks: false,
+    completionMsg: "Setup complete! Open VS Code \u2014 memory is active via Copilot.",
+  },
+  windsurf: {
+    name: "Windsurf",
+    mcpConfigPath: join(homeDir, ".codeium", "windsurf", "mcp_config.json"),
+    mcpConfigName: "~/.codeium/windsurf/mcp_config.json",
+    mcpConfigScope: "user",
+    instructionsFile: join(cwd, ".windsurfrules"),
+    instructionsName: ".windsurfrules",
+    templateFile: join(__dirname, "..", "windsurfrules.template"),
+    startMarker: "# --- gitmem:start ---",
+    endMarker: "# --- gitmem:end ---",
+    configDir: null,
+    settingsFile: null,
+    settingsLocalFile: null,
+    hasPermissions: false,
+    hooksInSettings: false,
+    hasHooks: false,
+    completionMsg: "Setup complete! Open Windsurf \u2014 memory is active.",
+  },
+  generic: {
+    name: "Generic MCP Client",
+    mcpConfigPath: join(cwd, ".mcp.json"),
+    mcpConfigName: ".mcp.json",
+    mcpConfigScope: "project",
+    instructionsFile: join(cwd, "CLAUDE.md"),
+    instructionsName: "CLAUDE.md",
+    templateFile: join(__dirname, "..", "CLAUDE.md.template"),
+    startMarker: "<!-- gitmem:start -->",
+    endMarker: "<!-- gitmem:end -->",
+    configDir: null,
+    settingsFile: null,
+    settingsLocalFile: null,
+    hasPermissions: false,
+    hooksInSettings: false,
+    hasHooks: false,
+    completionMsg:
+      "Setup complete! Configure your MCP client to use the gitmem server from .mcp.json.",
+  },
 };
 
 // Shared paths (client-agnostic)
@@ -84,33 +146,49 @@ let cc; // shorthand for CLIENT_CONFIGS[client]
 
 // ── Client Detection ──
 
+const VALID_CLIENTS = Object.keys(CLIENT_CONFIGS);
+
 function detectClient() {
   // Explicit flag takes priority
   if (clientFlag) {
-    if (clientFlag !== "claude" && clientFlag !== "cursor") {
-      console.error(`  Error: Unknown client "${clientFlag}". Use --client claude or --client cursor.`);
+    if (!VALID_CLIENTS.includes(clientFlag)) {
+      console.error(`  Error: Unknown client "${clientFlag}". Use --client ${VALID_CLIENTS.join("|")}.`);
       process.exit(1);
     }
     return clientFlag;
   }
 
-  // Auto-detect based on directory presence
+  // Auto-detect based on directory/file presence
   const hasCursorDir = existsSync(join(cwd, ".cursor"));
   const hasClaudeDir = existsSync(join(cwd, ".claude"));
   const hasMcpJson = existsSync(join(cwd, ".mcp.json"));
   const hasClaudeMd = existsSync(join(cwd, "CLAUDE.md"));
   const hasCursorRules = existsSync(join(cwd, ".cursorrules"));
   const hasCursorMcp = existsSync(join(cwd, ".cursor", "mcp.json"));
+  const hasVscodeDir = existsSync(join(cwd, ".vscode"));
+  const hasVscodeMcp = existsSync(join(cwd, ".vscode", "mcp.json"));
+  const hasCopilotInstructions = existsSync(join(cwd, ".github", "copilot-instructions.md"));
+  const hasWindsurfRules = existsSync(join(cwd, ".windsurfrules"));
+  const hasWindsurfMcp = existsSync(
+    join(homeDir, ".codeium", "windsurf", "mcp_config.json")
+  );
 
   // Strong Cursor signals
   if (hasCursorDir && !hasClaudeDir && !hasMcpJson && !hasClaudeMd) return "cursor";
-  if (hasCursorRules && !hasClaudeMd) return "cursor";
-  if (hasCursorMcp && !hasMcpJson) return "cursor";
+  if (hasCursorRules && !hasClaudeMd && !hasCopilotInstructions) return "cursor";
+  if (hasCursorMcp && !hasMcpJson && !hasVscodeMcp) return "cursor";
 
   // Strong Claude signals
-  if (hasClaudeDir && !hasCursorDir) return "claude";
-  if (hasMcpJson && !hasCursorMcp) return "claude";
-  if (hasClaudeMd && !hasCursorRules) return "claude";
+  if (hasClaudeDir && !hasCursorDir && !hasVscodeDir) return "claude";
+  if (hasMcpJson && !hasCursorMcp && !hasVscodeMcp) return "claude";
+  if (hasClaudeMd && !hasCursorRules && !hasCopilotInstructions) return "claude";
+
+  // VS Code signals
+  if (hasVscodeMcp && !hasMcpJson && !hasCursorMcp) return "vscode";
+  if (hasCopilotInstructions && !hasClaudeMd && !hasCursorRules) return "vscode";
+
+  // Windsurf signals
+  if (hasWindsurfRules && !hasClaudeMd && !hasCursorRules && !hasCopilotInstructions) return "windsurf";
 
   // Default to Claude Code (most common)
   return "claude";
@@ -428,6 +506,36 @@ async function stepMemoryStore() {
     }
   }
 
+  // Closing payload template — agents read this before writing closing-payload.json
+  const templatePath = join(gitmemDir, "closing-payload-template.json");
+  if (!existsSync(templatePath)) {
+    writeJson(templatePath, {
+      closing_reflection: {
+        what_broke: "",
+        what_took_longer: "",
+        do_differently: "",
+        what_worked: "",
+        wrong_assumption: "",
+        scars_applied: [],
+        institutional_memory_items: "",
+        collaborative_dynamic: "",
+        rapport_notes: ""
+      },
+      task_completion: {
+        questions_displayed_at: "ISO-8601 timestamp",
+        reflection_completed_at: "ISO-8601 timestamp",
+        human_asked_at: "ISO-8601 timestamp",
+        human_response_at: "ISO-8601 timestamp",
+        human_response: "no corrections | actual corrections text"
+      },
+      human_corrections: "",
+      scars_to_record: [],
+      learnings_created: [],
+      open_threads: [],
+      decisions: []
+    });
+  }
+
   console.log(
     `  Created .gitmem/ with ${starterScars.length} starter scars` +
       (added < starterScars.length
@@ -439,6 +547,7 @@ async function stepMemoryStore() {
 async function stepMcpServer() {
   const mcpPath = cc.mcpConfigPath;
   const mcpName = cc.mcpConfigName;
+  const isUserLevel = cc.mcpConfigScope === "user";
 
   const existing = readJson(mcpPath);
   const hasGitmem =
@@ -453,9 +562,10 @@ async function stepMcpServer() {
     ? Object.keys(existing.mcpServers).length
     : 0;
   const tierLabel = process.env.SUPABASE_URL ? "pro" : "free";
+  const scopeNote = isUserLevel ? " (user-level config)" : "";
   const prompt = existing
-    ? `Add gitmem to ${mcpName}? (${serverCount} existing server${serverCount !== 1 ? "s" : ""} preserved)`
-    : `Create ${mcpName} with gitmem server?`;
+    ? `Add gitmem to ${mcpName}?${scopeNote} (${serverCount} existing server${serverCount !== 1 ? "s" : ""} preserved)`
+    : `Create ${mcpName} with gitmem server?${scopeNote}`;
 
   if (!(await confirm(prompt))) {
     console.log("  Skipped.");
@@ -463,11 +573,11 @@ async function stepMcpServer() {
   }
 
   if (dryRun) {
-    console.log(`  [dry-run] Would add gitmem entry to ${mcpName} (${tierLabel} tier)`);
+    console.log(`  [dry-run] Would add gitmem entry to ${mcpName} (${tierLabel} tier${scopeNote})`);
     return;
   }
 
-  // Ensure parent directory exists (for .cursor/mcp.json)
+  // Ensure parent directory exists (for .cursor/mcp.json, .vscode/mcp.json, ~/.codeium/windsurf/)
   const parentDir = dirname(mcpPath);
   if (!existsSync(parentDir)) {
     mkdirSync(parentDir, { recursive: true });
@@ -481,7 +591,8 @@ async function stepMcpServer() {
   console.log(
     `  Added gitmem entry to ${mcpName} (${tierLabel} tier` +
       (process.env.SUPABASE_URL ? " \u2014 Supabase detected" : " \u2014 local storage") +
-      ")"
+      ")" +
+      (isUserLevel ? " [user-level]" : "")
   );
 }
 
@@ -525,6 +636,12 @@ async function stepInstructions() {
     block = `${cc.startMarker}\n${block}\n${cc.endMarker}`;
   }
 
+  // Ensure parent directory exists (for .github/copilot-instructions.md)
+  const instrParentDir = dirname(instrPath);
+  if (!existsSync(instrParentDir)) {
+    mkdirSync(instrParentDir, { recursive: true });
+  }
+
   if (exists) {
     content = content.trimEnd() + "\n\n" + block + "\n";
   } else {
@@ -598,6 +715,11 @@ function copyHookScripts() {
 }
 
 async function stepHooks() {
+  if (!cc.hasHooks) {
+    console.log(`  ${cc.name} does not support lifecycle hooks. Skipping.`);
+    console.log("  Enforcement relies on system prompt instructions instead.");
+    return;
+  }
   if (cc.hooksInSettings) {
     return stepHooksClaude();
   }
@@ -821,7 +943,7 @@ async function main() {
     );
   }
 
-  if (!cc.hooksInSettings && cc.hooksFile && existsSync(cc.hooksFile)) {
+  if (!cc.hooksInSettings && cc.hasHooks && cc.hooksFile && existsSync(cc.hooksFile)) {
     const hooks = readJson(cc.hooksFile);
     const hookCount = hooks?.hooks
       ? Object.values(hooks.hooks).flat().length
@@ -850,8 +972,10 @@ async function main() {
   );
   console.log("");
 
-  // Run steps — step count depends on client
-  const stepCount = cc.hasPermissions ? 6 : 5;
+  // Run steps — step count depends on client capabilities
+  let stepCount = 4; // memory store + mcp server + instructions + gitignore
+  if (cc.hasPermissions) stepCount++;
+  if (cc.hasHooks) stepCount++;
   let step = 1;
 
   console.log(`  Step ${step}/${stepCount} \u2014 Memory Store`);
@@ -876,10 +1000,12 @@ async function main() {
     step++;
   }
 
-  console.log(`  Step ${step}/${stepCount} \u2014 Lifecycle Hooks`);
-  await stepHooks();
-  console.log("");
-  step++;
+  if (cc.hasHooks) {
+    console.log(`  Step ${step}/${stepCount} \u2014 Lifecycle Hooks`);
+    await stepHooks();
+    console.log("");
+    step++;
+  }
 
   console.log(`  Step ${step}/${stepCount} \u2014 Gitignore`);
   await stepGitignore();

package/copilot-instructions.template

@@ -0,0 +1,82 @@
+<!-- gitmem:start -->
+# GitMem — Persistent Memory
+
+You have a persistent memory layer called gitmem. Every session starts from
+zero — but gitmem carries forward lessons, mistakes, wins, decisions, and
+open threads across sessions and projects. Search it. Test it. You might be
+amazed at what's already there. If convinced, make it your own.
+
+## Red Lines
+
+### Credential Protection
+
+Credential exposure in conversation history is permanent and irreversible.
+
+1. **NEVER read credential files in full.** Files like `mcp-config.json`, `.env`, `.credentials.json`, `.netrc`, `.npmrc`, SSH keys, or `.pem`/`.key` files must not be read or dumped.
+2. **NEVER print environment variable values that contain secrets.** Commands like `env | grep KEY`, `echo $API_KEY`, or `printenv TOKEN` expose credentials in output.
+3. **NEVER display API keys, tokens, or secrets in conversation output.**
+
+Safe alternatives: `env | grep -c VARNAME` (count only), `[ -n "$VARNAME" ] && echo "set"` (existence check), `grep -c '"key"' config.json` (structure check).
+
+### Recall Before Consequential Actions
+
+1. **NEVER parallelize `recall()` with actions that expose, modify, or transmit sensitive data.** Recall must complete first.
+2. **Confirm scars before acting.** Each recalled scar requires APPLYING (past-tense evidence), N_A (explanation), or REFUTED (risk acknowledgment).
+3. **Parallel recall is only safe with benign reads** — source code, docs, non-sensitive config.
+
+## Tools
+
+| Tool | When to use |
+|------|-------------|
+| `recall` | Before any task — surfaces relevant warnings from past experience |
+| `confirm_scars` | After recall — acknowledge each scar as APPLYING, N_A, or REFUTED |
+| `search` | Explore institutional knowledge by topic |
+| `log` | Browse recent learnings chronologically |
+| `session_start` | Beginning of session — loads last session context and open threads |
+| `session_close` | End of session — persists what you learned |
+| `create_learning` | Capture a mistake (scar), success (win), or pattern |
+| `create_decision` | Log an architectural or operational decision with rationale |
+| `list_threads` | See unresolved work carrying over between sessions |
+| `create_thread` | Track something that needs follow-up in a future session |
+| `help` | Show all available commands |
+
+## Session Lifecycle
+
+**Start:** Call `session_start()` at the beginning of every session.
+
+**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`:
+   ```json
+   {
+     "closing_reflection": {
+       "what_broke": "...",
+       "what_took_longer": "...",
+       "do_differently": "...",
+       "what_worked": "...",
+       "wrong_assumption": "...",
+       "scars_applied": ["scar title 1", "scar title 2"],
+       "institutional_memory_items": "..."
+     },
+     "human_corrections": "",
+     "scars_to_record": [],
+     "open_threads": [],
+     "decisions": []
+   }
+   ```
+
+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 -->

package/dist/schemas/session-close.d.ts

@@ -279,16 +279,6 @@ export declare const SessionCloseParamsSchema: z.ZodObject<{
     }[] | undefined;
     transcript_path?: string | undefined;
     linear_issue?: string | undefined;
-    open_threads?: (string | {
-        id: string;
-        created_at: string;
-        status: "open" | "resolved";
-        text: string;
-        resolved_at?: string | undefined;
-        resolution_note?: string | undefined;
-        source_session?: string | undefined;
-        resolved_by_session?: string | undefined;
-    })[] | undefined;
     closing_reflection?: {
         what_broke: string;
         what_took_longer: string;
@@ -300,7 +290,6 @@ export declare const SessionCloseParamsSchema: z.ZodObject<{
         collaborative_dynamic?: string | undefined;
         rapport_notes?: string | undefined;
     } | undefined;
-    project_state?: string | undefined;
     task_completion?: {
         questions_displayed_at: string;
         reflection_completed_at: string;
@@ -309,8 +298,6 @@ export declare const SessionCloseParamsSchema: z.ZodObject<{
         human_response: string;
     } | undefined;
     human_corrections?: string | undefined;
-    learnings_created?: (string | Record<string, unknown>)[] | undefined;
-    ceremony_duration_ms?: number | undefined;
     scars_to_record?: {
         surfaced_at: string;
         reference_type: "explicit" | "implicit" | "acknowledged" | "refuted" | "none";
@@ -324,6 +311,19 @@ export declare const SessionCloseParamsSchema: z.ZodObject<{
         execution_successful?: boolean | undefined;
         variant_id?: string | undefined;
     }[] | undefined;
+    learnings_created?: (string | Record<string, unknown>)[] | undefined;
+    open_threads?: (string | {
+        id: string;
+        created_at: string;
+        status: "open" | "resolved";
+        text: string;
+        resolved_at?: string | undefined;
+        resolution_note?: string | undefined;
+        source_session?: string | undefined;
+        resolved_by_session?: string | undefined;
+    })[] | undefined;
+    project_state?: string | undefined;
+    ceremony_duration_ms?: number | undefined;
     capture_transcript?: boolean | undefined;
 }, {
     session_id: string;
@@ -336,16 +336,6 @@ export declare const SessionCloseParamsSchema: z.ZodObject<{
     }[] | undefined;
     transcript_path?: string | undefined;
     linear_issue?: string | undefined;
-    open_threads?: (string | {
-        id: string;
-        created_at: string;
-        status: "open" | "resolved";
-        text: string;
-        resolved_at?: string | undefined;
-        resolution_note?: string | undefined;
-        source_session?: string | undefined;
-        resolved_by_session?: string | undefined;
-    })[] | undefined;
     closing_reflection?: {
         what_broke: string;
         what_took_longer: string;
@@ -357,7 +347,6 @@ export declare const SessionCloseParamsSchema: z.ZodObject<{
         collaborative_dynamic?: string | undefined;
         rapport_notes?: string | undefined;
     } | undefined;
-    project_state?: string | undefined;
     task_completion?: {
         questions_displayed_at: string;
         reflection_completed_at: string;
@@ -366,8 +355,6 @@ export declare const SessionCloseParamsSchema: z.ZodObject<{
         human_response: string;
     } | undefined;
     human_corrections?: string | undefined;
-    learnings_created?: (string | Record<string, unknown>)[] | undefined;
-    ceremony_duration_ms?: number | undefined;
     scars_to_record?: {
         surfaced_at: string;
         reference_type: "explicit" | "implicit" | "acknowledged" | "refuted" | "none";
@@ -381,6 +368,19 @@ export declare const SessionCloseParamsSchema: z.ZodObject<{
         execution_successful?: boolean | undefined;
         variant_id?: string | undefined;
     }[] | undefined;
+    learnings_created?: (string | Record<string, unknown>)[] | undefined;
+    open_threads?: (string | {
+        id: string;
+        created_at: string;
+        status: "open" | "resolved";
+        text: string;
+        resolved_at?: string | undefined;
+        resolution_note?: string | undefined;
+        source_session?: string | undefined;
+        resolved_by_session?: string | undefined;
+    })[] | undefined;
+    project_state?: string | undefined;
+    ceremony_duration_ms?: number | undefined;
     capture_transcript?: boolean | undefined;
 }>;
 export type SessionCloseParams = z.infer<typeof SessionCloseParamsSchema>;

package/dist/server.js

@@ -4,6 +4,9 @@
  * Registers all tools and handles MCP protocol communication.
  * Tool definitions are in ./tools/definitions.ts
  */
+import { createRequire } from "module";
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json");
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
@@ -34,6 +37,7 @@ import { archiveLearning } from "./tools/archive-learning.js";
 import { getCacheStatus, checkCacheHealth, flushCache, startBackgroundInit, } from "./services/startup.js";
 import { getEffectTracker } from "./services/effect-tracker.js";
 import { getProject } from "./services/session-state.js";
+import { checkEnforcement } from "./services/enforcement.js";
 import { getTier, hasSupabase, hasCacheManagement, hasBatchOperations, hasTranscripts, } from "./services/tier.js";
 import { getRegisteredTools } from "./tools/definitions.js";
 import { validateToolArgs } from "./schemas/registry.js";
@@ -43,7 +47,7 @@ import { validateToolArgs } from "./schemas/registry.js";
 export function createServer() {
     const server = new Server({
         name: "gitmem-mcp",
-        version: "1.0.3",
+        version: pkg.version,
     }, {
         capabilities: {
             tools: {},
@@ -84,6 +88,8 @@ export function createServer() {
                 isError: true,
             };
         }
+        // Server-side enforcement: advisory warnings for protocol violations
+        const enforcement = checkEnforcement(name);
         try {
             let result;
             switch (name) {
@@ -240,7 +246,7 @@ export function createServer() {
                     // Build command table for display
                     const cmdLines = visibleCommands.map(c => `  ${c.alias.padEnd(22)} ${c.description}`).join("\n");
                     const display = [
-                        `gitmem v1.0.3 · ${tier} · ${registeredTools.length} tools · ${hasSupabase() ? "supabase" : "local (.gitmem/)"}`,
+                        `gitmem v${pkg.version} · ${tier} · ${registeredTools.length} tools · ${hasSupabase() ? "supabase" : "local (.gitmem/)"}`,
                         "Memory that compounds.",
                         "",
                         cmdLines,
@@ -252,7 +258,7 @@ export function createServer() {
                         "Tool results are collapsed in the CLI — the user cannot see them unless you echo them.",
                     ].join("\n");
                     result = {
-                        version: "1.0.3",
+                        version: pkg.version,
                         tier,
                         tools_registered: registeredTools.length,
                         storage: hasSupabase() ? "supabase" : "local (.gitmem/)",
@@ -313,6 +319,10 @@ export function createServer() {
             else {
                 responseText = JSON.stringify(result, null, 2);
             }
+            // Prepend enforcement warning if present (advisory, non-blocking)
+            if (enforcement.warning) {
+                responseText = enforcement.warning + "\n\n" + responseText;
+            }
             return {
                 content: [
                     {

package/dist/services/analytics.js

@@ -365,7 +365,7 @@ export function formatSummary(data) {
     const lines = [
         `## ${period.days}-Day Summary (${period.start} to ${period.end})`,
         ``,
-        `**Sessions:** ${total_sessions} | **Decisions:** ${total_decisions} | **Open Threads:** ${total_open_threads}`,
+        `**Sessions:** ${total_sessions} | **Decisions:** ${total_decisions} | **Threads Referenced:** ${total_open_threads}`,
         `**With Reflections:** ${sessions_with_reflections} | **With Issues:** ${sessions_with_issues}`,
         ``,
         `### Agents`,

package/dist/services/enforcement.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Server-Side Enforcement Layer
+ *
+ * Advisory warnings that surface in tool responses when the agent
+ * hasn't followed the recall → confirm → act protocol.
+ *
+ * Design principles:
+ * - Advisory, not blocking: warnings append to responses, never prevent execution
+ * - Zero overhead on compliant calls: only fires when state is missing
+ * - Universal: works in ALL MCP clients, no IDE hooks needed
+ * - Lightweight: pure in-memory checks, no I/O
+ */
+export interface EnforcementResult {
+    /** Warning text to prepend to tool response (null = clean, no warning) */
+    warning: string | null;
+}
+/**
+ * Run pre-dispatch enforcement checks for a tool call.
+ *
+ * Returns a warning string to prepend to the response, or null if clean.
+ * Never blocks execution — always advisory.
+ */
+export declare function checkEnforcement(toolName: string): EnforcementResult;
+//# sourceMappingURL=enforcement.d.ts.map

package/dist/services/enforcement.js

@@ -0,0 +1,126 @@
+/**
+ * Server-Side Enforcement Layer
+ *
+ * Advisory warnings that surface in tool responses when the agent
+ * hasn't followed the recall → confirm → act protocol.
+ *
+ * Design principles:
+ * - Advisory, not blocking: warnings append to responses, never prevent execution
+ * - Zero overhead on compliant calls: only fires when state is missing
+ * - Universal: works in ALL MCP clients, no IDE hooks needed
+ * - Lightweight: pure in-memory checks, no I/O
+ */
+import { getCurrentSession, hasUnconfirmedScars, getSurfacedScars } from "./session-state.js";
+/**
+ * Tools that require an active session to function properly.
+ * Read-only/administrative tools are excluded.
+ */
+const SESSION_REQUIRED_TOOLS = new Set([
+    "recall", "gitmem-r",
+    "confirm_scars", "gitmem-cs", "gm-confirm",
+    "session_close", "gitmem-sc", "gm-close",
+    "session_refresh", "gitmem-sr", "gm-refresh",
+    "create_learning", "gitmem-cl", "gm-scar",
+    "create_decision", "gitmem-cd",
+    "record_scar_usage", "gitmem-rs",
+    "record_scar_usage_batch", "gitmem-rsb",
+    "prepare_context", "gitmem-pc", "gm-pc",
+    "absorb_observations", "gitmem-ao", "gm-absorb",
+    "create_thread", "gitmem-ct", "gm-thread-new",
+    "resolve_thread", "gitmem-rt", "gm-resolve",
+    "save_transcript", "gitmem-st",
+]);
+/**
+ * Tools that represent "consequential actions" — the agent is creating
+ * or modifying state. These should ideally happen after recall + confirm.
+ */
+const CONSEQUENTIAL_TOOLS = new Set([
+    "create_learning", "gitmem-cl", "gm-scar",
+    "create_decision", "gitmem-cd",
+    "create_thread", "gitmem-ct", "gm-thread-new",
+    "session_close", "gitmem-sc", "gm-close",
+]);
+/**
+ * Tools that are always safe — no enforcement checks needed.
+ * Includes session_start (which creates the session), read-only tools,
+ * and administrative tools.
+ */
+const EXEMPT_TOOLS = new Set([
+    "session_start", "gitmem-ss", "gm-open",
+    "search", "gitmem-search", "gm-search",
+    "log", "gitmem-log", "gm-log",
+    "analyze", "gitmem-analyze", "gm-analyze",
+    "graph_traverse", "gitmem-graph", "gm-graph",
+    "list_threads", "gitmem-lt", "gm-threads",
+    "cleanup_threads", "gitmem-cleanup", "gm-cleanup",
+    "promote_suggestion", "gitmem-ps", "gm-promote",
+    "dismiss_suggestion", "gitmem-ds", "gm-dismiss",
+    "archive_learning", "gitmem-al", "gm-archive",
+    "get_transcript", "gitmem-gt",
+    "search_transcripts", "gitmem-stx", "gm-stx",
+    "gitmem-help",
+    "health", "gitmem-health", "gm-health",
+    "gitmem-cache-status", "gm-cache-s",
+    "gitmem-cache-health", "gm-cache-h",
+    "gitmem-cache-flush", "gm-cache-f",
+]);
+/**
+ * Run pre-dispatch enforcement checks for a tool call.
+ *
+ * Returns a warning string to prepend to the response, or null if clean.
+ * Never blocks execution — always advisory.
+ */
+export function checkEnforcement(toolName) {
+    // Exempt tools skip all checks
+    if (EXEMPT_TOOLS.has(toolName)) {
+        return { warning: null };
+    }
+    const session = getCurrentSession();
+    // Check 1: No active session
+    if (!session && SESSION_REQUIRED_TOOLS.has(toolName)) {
+        return {
+            warning: [
+                "--- gitmem enforcement ---",
+                "No active session. Call session_start() first to initialize memory context.",
+                "Without a session, scars won't be tracked and the closing ceremony can't run.",
+                "---",
+            ].join("\n"),
+        };
+    }
+    // If no session and not session-required, skip remaining checks
+    if (!session) {
+        return { warning: null };
+    }
+    // Check 2: Unconfirmed scars before consequential action
+    if (CONSEQUENTIAL_TOOLS.has(toolName) && hasUnconfirmedScars()) {
+        const recallScars = getSurfacedScars().filter(s => s.source === "recall");
+        const confirmedCount = session.confirmations?.length || 0;
+        const pendingCount = recallScars.length - confirmedCount;
+        return {
+            warning: [
+                "--- gitmem enforcement ---",
+                `${pendingCount} recalled scar(s) await confirmation.`,
+                "Call confirm_scars() with APPLYING/N_A/REFUTED for each before proceeding.",
+                "Unconfirmed scars may contain warnings relevant to what you're about to do.",
+                "---",
+            ].join("\n"),
+        };
+    }
+    // Check 3: No recall before consequential action
+    if (CONSEQUENTIAL_TOOLS.has(toolName)) {
+        const recallScars = getSurfacedScars().filter(s => s.source === "recall");
+        if (recallScars.length === 0) {
+            return {
+                warning: [
+                    "--- gitmem enforcement ---",
+                    "No recall() was run this session before this action.",
+                    "Consider calling recall() first to check for relevant institutional memory.",
+                    "Past mistakes and patterns may prevent repeating known issues.",
+                    "---",
+                ].join("\n"),
+            };
+        }
+    }
+    return { warning: null };
+}
+//# sourceMappingURL=enforcement.js.map

package/dist/tools/cleanup-threads.js

@@ -44,12 +44,16 @@ function buildCleanupDisplay(summary, groups, archivedCount) {
     for (const [label, items] of sections) {
         if (items.length === 0)
             continue;
-        lines.push(`${label} (${items.length}):`);
+        lines.push(`**${label}** (${items.length}):`);
+        lines.push("");
+        lines.push("| ID | Thread | Last Touch |");
+        lines.push("|----|--------|------------|");
         for (const t of items) {
-            const text = truncate(t.text, 48);
+            const text = truncate(t.text, 60);
             const time = formatDaysAgo(t.days_since_touch);
-            lines.push(`  ${t.thread_id}  ${text.padEnd(50)} ${time.padStart(8)}`);
+            lines.push(`| ${t.thread_id} | ${text} | ${time} |`);
         }
+        lines.push("");
     }
     lines.push("");
     lines.push(`Archived: ${archivedCount}`);

package/dist/tools/definitions.js

@@ -158,7 +158,7 @@ export const TOOLS = [
     },
     {
         name: "create_learning",
-        description: "Create scar, win, or pattern entry in institutional memory",
+        description: "Create scar, win, or pattern entry in institutional memory. Frame as 'what we now know' — lead with the factual/architectural discovery, not what went wrong. Good: 'Fine-grained PATs are scoped to one resource owner'. Bad: 'Should have checked PAT type first'.",
         inputSchema: {
             type: "object",
             properties: {
@@ -169,11 +169,11 @@ export const TOOLS = [
                 },
                 title: {
                     type: "string",
-                    description: "Learning title",
+                    description: "Frame as a knowledge discovery — what we now know. Lead with the factual insight, not self-criticism.",
                 },
                 description: {
                     type: "string",
-                    description: "Detailed description",
+                    description: "Detailed description. Include the architectural/behavioral fact that makes this retrievable by domain.",
                 },
                 severity: {
                     type: "string",
@@ -849,7 +849,7 @@ export const TOOLS = [
     },
     {
         name: "gitmem-cl",
-        description: "gitmem-cl (create_learning) - Create scar/win/pattern in institutional memory",
+        description: "gitmem-cl (create_learning) - Create scar/win/pattern. Frame as 'what we now know' — factual discovery, not self-criticism.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1496,7 +1496,7 @@ export const TOOLS = [
     },
     {
         name: "gm-scar",
-        description: "gm-scar (create_learning) - Create a scar/win/pattern in institutional memory",
+        description: "gm-scar (create_learning) - Create a scar/win/pattern. Frame as 'what we now know' — factual discovery, not self-criticism.",
         inputSchema: {
             type: "object",
             properties: {

package/dist/tools/list-threads.js

@@ -39,24 +39,16 @@ 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));
-    const NUM_W = 3;
-    const ID_W = 12;
-    const TEXT_W = 40;
-    const DATE_W = 8;
-    const hr = (l, j, r) => `${l}${"─".repeat(NUM_W + 2)}${j}${"─".repeat(ID_W + 2)}${j}${"─".repeat(TEXT_W + 2)}${j}${"─".repeat(DATE_W + 2)}${r}`;
-    const hdr = (l, j, r) => `${l}${"═".repeat(NUM_W + 2)}${j}${"═".repeat(ID_W + 2)}${j}${"═".repeat(TEXT_W + 2)}${j}${"═".repeat(DATE_W + 2)}${r}`;
-    const row = (n, id, t, d) => `│ ${n.padEnd(NUM_W)} │ ${id.padEnd(ID_W)} │ ${t.padEnd(TEXT_W)} │ ${d.padStart(DATE_W)} │`;
-    lines.push(hr("┌", "┬", "┐"));
-    lines.push(row("#", "ID", "Thread", "Active"));
-    lines.push(hdr("╞", "╪", "╡"));
+    // Markdown table — renders cleanly in all MCP clients
+    lines.push("| # | ID | Thread | Active |");
+    lines.push("|---|-----|--------|--------|");
     for (let i = 0; i < sorted.length; i++) {
         const t = sorted[i];
-        const shortId = truncate(t.id, ID_W);
-        const text = truncate(t.text, TEXT_W);
+        const shortId = t.id;
+        const text = truncate(t.text, 60);
         const date = shortDate(t.last_touched_at || t.created_at);
-        lines.push(row(`${i + 1}.`, shortId, text, date));
+        lines.push(`| ${i + 1} | ${shortId} | ${text} | ${date} |`);
     }
-    lines.push(hr("└", "┴", "┘"));
     return wrapDisplay(lines.join("\n"));
 }
 export async function listThreads(params) {

package/dist/tools/log.js

@@ -20,7 +20,7 @@ import { wrapDisplay, relativeTime, truncate, SEV, TYPE } from "../services/disp
 // --- Display Formatting ---
 function buildLogDisplay(entries, total, filters) {
     const lines = [];
-    lines.push(`gitmem log · ${total} entries · ${filters.project}`);
+    lines.push(`gitmem log · ${total} most recent learnings · ${filters.project}`);
     const fp = [];
     if (filters.learning_type)
         fp.push(`type=${filters.learning_type}`);

package/dist/tools/record-scar-usage-batch.js

@@ -5,6 +5,8 @@
 import { v4 as uuidv4 } from "uuid";
 import * as supabase from "../services/supabase-client.js";
 import { hasSupabase, getTableName } from "../services/tier.js";
+import { detectAgent } from "../services/agent-detection.js";
+import { getCurrentSession } from "../services/session-state.js";
 import { Timer, recordMetrics, buildPerformanceData } from "../services/metrics.js";
 const TARGET_LATENCY_MS = 2000; // Target for batch operation
 /**
@@ -84,6 +86,9 @@ export async function recordScarUsageBatch(params) {
             return { entry, scarId };
         });
         const resolvedScars = await Promise.all(resolutionPromises);
+        // Auto-detect agent and session as fallbacks for entries missing them
+        const fallbackAgent = detectAgent().agent || null;
+        const fallbackSessionId = getCurrentSession()?.sessionId || null;
         // Build usage records for all successfully resolved scars
         const usageRecords = resolvedScars
             .filter(({ scarId }) => scarId !== null)
@@ -94,8 +99,8 @@ export async function recordScarUsageBatch(params) {
                 scar_id: scarId,
                 issue_id: entry.issue_id || null,
                 issue_identifier: entry.issue_identifier || null,
-                session_id: entry.session_id || null, // Session tracking
-                agent: entry.agent || null, // Agent identity
+                session_id: entry.session_id || fallbackSessionId,
+                agent: entry.agent || fallbackAgent,
                 surfaced_at: entry.surfaced_at,
                 acknowledged_at: entry.acknowledged_at || null,
                 referenced: entry.reference_type !== "none",

package/dist/tools/record-scar-usage.js

@@ -11,6 +11,8 @@ import { wrapDisplay } from "../services/display-protocol.js";
 import * as supabase from "../services/supabase-client.js";
 import { hasSupabase } from "../services/tier.js";
 import { getStorage } from "../services/storage.js";
+import { detectAgent } from "../services/agent-detection.js";
+import { getCurrentSession } from "../services/session-state.js";
 import { Timer, recordMetrics, buildPerformanceData, } from "../services/metrics.js";
 /**
  * Execute record_scar_usage tool
@@ -19,13 +21,16 @@ export async function recordScarUsage(params) {
     const timer = new Timer();
     const metricsId = uuidv4();
     const usageId = uuidv4();
+    // Auto-detect agent and session if not provided by caller
+    const resolvedAgent = params.agent || detectAgent().agent || null;
+    const resolvedSessionId = params.session_id || getCurrentSession()?.sessionId || null;
     const usageData = {
         id: usageId,
         scar_id: params.scar_id,
         issue_id: params.issue_id || null,
         issue_identifier: params.issue_identifier || null,
-        session_id: params.session_id || null, // Session tracking
-        agent: params.agent || null, // Agent identity
+        session_id: resolvedSessionId,
+        agent: resolvedAgent,
         surfaced_at: params.surfaced_at,
         acknowledged_at: params.acknowledged_at || null,
         referenced: params.reference_type !== "none",

package/dist/tools/session-start.js

@@ -28,6 +28,33 @@ 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";
+/**
+ * Closing payload schema — returned in session_start/refresh so agents
+ * know the exact field names for closing-payload.json without guessing.
+ */
+const CLOSING_PAYLOAD_SCHEMA = {
+    closing_reflection: {
+        what_broke: "Q1: What broke that you didn't expect?",
+        what_took_longer: "Q2: What took longer than it should have?",
+        do_differently: "Q3: What would you do differently next time?",
+        what_worked: "Q4: What pattern or approach worked well?",
+        wrong_assumption: "Q5: What assumption was wrong?",
+        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: "",
+    scars_to_record: [],
+    learnings_created: [],
+    open_threads: [],
+    decisions: [],
+};
 /**
  * Normalize decisions from mixed formats (strings or objects) to string[].
  * Historical sessions (pre-2026) stored {title, decision} objects.
@@ -413,6 +440,7 @@ async function sessionStartFree(params, env, agent, project, timer, metricsId, e
         ...(freeMergedThreads.length > 0 && { open_threads: freeMergedThreads }),
         recent_decisions: decisions,
         gitmem_dir: getGitmemDir(),
+        closing_payload_schema: CLOSING_PAYLOAD_SCHEMA,
         project,
         performance,
     };
@@ -573,13 +601,27 @@ function writeSessionFiles(sessionId, agent, project, surfacedScars, threads, re
     const existingFileThreads = loadThreadsFile();
     let merged;
     if (supabaseAuthoritative) {
-        // Supabase is source of truth — use its threads, but preserve any local-only threads
-        // (threads in the file that don't exist in the Supabase set, e.g. created via create_thread
-        // mid-session but not yet synced to Supabase by session_close).
+        // Supabase is source of truth — use its threads, but preserve local-only threads
+        // that were created recently (within 24h) and have a valid ID. These are likely
+        // mid-session threads not yet synced by session_close. Older local-only threads
+        // are stale — they were resolved/archived in Supabase but linger in the file
+        // because the NOT-IN query excludes them, making them look "local-only".
         const supabaseIds = new Set(threads.map(t => t.id));
-        const localOnlyThreads = existingFileThreads.filter(t => !supabaseIds.has(t.id));
+        const cutoff = Date.now() - 24 * 60 * 60 * 1000;
+        const localOnlyThreads = existingFileThreads.filter(t => {
+            if (supabaseIds.has(t.id))
+                return false; // exists in Supabase active set
+            if (!t.id)
+                return false; // no ID = malformed, drop
+            const created = t.created_at ? new Date(t.created_at).getTime() : 0;
+            return created > cutoff; // only keep if created within last 24h
+        });
+        const dropped = existingFileThreads.filter(t => !supabaseIds.has(t.id)).length - localOnlyThreads.length;
         if (localOnlyThreads.length > 0) {
-            console.error(`[session_start] Preserving ${localOnlyThreads.length} local-only threads not yet in Supabase`);
+            console.error(`[session_start] Preserving ${localOnlyThreads.length} recent local-only threads not yet in Supabase`);
+        }
+        if (dropped > 0) {
+            console.error(`[session_start] Dropped ${dropped} stale local-only threads (resolved/archived in Supabase)`);
         }
         merged = deduplicateThreadList([...threads, ...localOnlyThreads]);
     }
@@ -809,6 +851,7 @@ export async function sessionStart(params) {
         recent_decisions: decisions,
         ...(recordingPath && { recording_path: recordingPath }),
         gitmem_dir: getGitmemDir(),
+        closing_payload_schema: CLOSING_PAYLOAD_SCHEMA,
         project,
         performance,
     };
@@ -931,6 +974,7 @@ export async function sessionRefresh(params) {
         recent_decisions: decisions,
         // Rapport disabled — not injected into session context
         ...(recordingPath && { recording_path: recordingPath }),
+        closing_payload_schema: CLOSING_PAYLOAD_SCHEMA,
         project,
         performance,
     };

package/dist/types/index.d.ts

@@ -163,6 +163,8 @@ export interface SessionStartResult {
     recording_path?: string;
     /** Resolved .gitmem directory path — use for closing-payload.json writes */
     gitmem_dir?: string;
+    /** Closing payload schema — exact field names for closing-payload.json */
+    closing_payload_schema?: Record<string, unknown>;
     /** Project namespace for this session */
     project?: string;
     /** Pre-formatted display string for consistent CLI output */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitmem-mcp",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "Institutional memory for AI coding agents. Memory that compounds.",
   "type": "module",
   "main": "dist/index.js",
@@ -40,7 +40,7 @@
     "@types/uuid": "^9.0.0",
     "pg": "^8.11.0",
     "typescript": "^5.0.0",
-    "vitest": "^1.0.0"
+    "vitest": "^4.0.18"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -55,16 +55,26 @@
     "schema",
     "CLAUDE.md.template",
     "cursorrules.template",
+    "copilot-instructions.template",
+    "windsurfrules.template",
     "README.md",
     "CHANGELOG.md"
   ],
   "keywords": [
     "mcp",
+    "mcp-server",
     "gitmem",
     "claude",
+    "claude-code",
     "cursor",
-    "institutional-memory",
+    "vscode",
+    "copilot",
+    "windsurf",
+    "openclaw",
+    "ai-memory",
+    "ai-agent",
     "ai-coding",
+    "institutional-memory",
     "scars",
     "semantic-search"
   ],

package/windsurfrules.template

@@ -0,0 +1,82 @@
+# --- gitmem:start ---
+# GitMem — Persistent Memory
+
+You have a persistent memory layer called gitmem. Every session starts from
+zero — but gitmem carries forward lessons, mistakes, wins, decisions, and
+open threads across sessions and projects. Search it. Test it. You might be
+amazed at what's already there. If convinced, make it your own.
+
+## Red Lines
+
+### Credential Protection
+
+Credential exposure in conversation history is permanent and irreversible.
+
+1. **NEVER read credential files in full.** Files like `mcp-config.json`, `.env`, `.credentials.json`, `.netrc`, `.npmrc`, SSH keys, or `.pem`/`.key` files must not be read or dumped.
+2. **NEVER print environment variable values that contain secrets.** Commands like `env | grep KEY`, `echo $API_KEY`, or `printenv TOKEN` expose credentials in output.
+3. **NEVER display API keys, tokens, or secrets in conversation output.**
+
+Safe alternatives: `env | grep -c VARNAME` (count only), `[ -n "$VARNAME" ] && echo "set"` (existence check), `grep -c '"key"' config.json` (structure check).
+
+### Recall Before Consequential Actions
+
+1. **NEVER parallelize `recall()` with actions that expose, modify, or transmit sensitive data.** Recall must complete first.
+2. **Confirm scars before acting.** Each recalled scar requires APPLYING (past-tense evidence), N_A (explanation), or REFUTED (risk acknowledgment).
+3. **Parallel recall is only safe with benign reads** — source code, docs, non-sensitive config.
+
+## Tools
+
+| Tool | When to use |
+|------|-------------|
+| `recall` | Before any task — surfaces relevant warnings from past experience |
+| `confirm_scars` | After recall — acknowledge each scar as APPLYING, N_A, or REFUTED |
+| `search` | Explore institutional knowledge by topic |
+| `log` | Browse recent learnings chronologically |
+| `session_start` | Beginning of session — loads last session context and open threads |
+| `session_close` | End of session — persists what you learned |
+| `create_learning` | Capture a mistake (scar), success (win), or pattern |
+| `create_decision` | Log an architectural or operational decision with rationale |
+| `list_threads` | See unresolved work carrying over between sessions |
+| `create_thread` | Track something that needs follow-up in a future session |
+| `help` | Show all available commands |
+
+## Session Lifecycle
+
+**Start:** Call `session_start()` at the beginning of every session.
+
+**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`:
+   ```json
+   {
+     "closing_reflection": {
+       "what_broke": "...",
+       "what_took_longer": "...",
+       "do_differently": "...",
+       "what_worked": "...",
+       "wrong_assumption": "...",
+       "scars_applied": ["scar title 1", "scar title 2"],
+       "institutional_memory_items": "..."
+     },
+     "human_corrections": "",
+     "scars_to_record": [],
+     "open_threads": [],
+     "decisions": []
+   }
+   ```
+
+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 ---