gitmem-mcp 1.1.2 → 1.2.0

package/CHANGELOG.md

@@ -7,6 +7,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-02-20
+
+### Added
+- **Telemetry CLI**: `npx gitmem-mcp telemetry` command for viewing scar effectiveness metrics and recall statistics.
+- **Confirm-scars prefix matching**: `confirm_scars` now accepts 8-character ID prefixes instead of requiring full UUIDs — faster agent workflows.
+- **Session-close timing**: `session_close` now tracks and reports ceremony duration for performance visibility.
+
+### Fixed
+- **Test assertion alignment**: Updated smoke and E2E test assertions to match current CLI output format (branded `((●))` display, lowercase identifiers).
+- **No-console-log allowlist**: CLI commands correctly excluded from console.log lint rule.
+
+## [1.1.4] - 2026-02-20
+
+### Changed
+- **Recall default switched to c-review**: Production nudge header changed from "INSTITUTIONAL MEMORY ACTIVATED" to "N scars to review". Nudge-bench testing (54 runs × 3 models) showed 89% scar reference rate vs 44% — a 2x improvement across Opus, Sonnet, and Haiku.
+
+### Fixed
+- **Thread display cleanup**: Removed internal thread IDs from `list_threads` output. Threads now show `# | Thread | Active` — IDs were implementation detail with no user value.
+
+## [1.1.3] - 2026-02-19
+
+### Added
+- **Multi-client init wizard**: `npx gitmem-mcp init` now supports VS Code, Windsurf, and generic MCP clients in addition to Claude Code and Cursor.
+- **Server-side enforcement layer**: Universal compliance enforcement that works across all MCP clients — recall before consequential actions, scar confirmation gates.
+- **Scar framing guidance**: `create_learning` tool now guides agents to frame scars as "what we now know" (factual discovery) rather than "what I did wrong" (self-criticism).
+- **Auto-detect agent and session**: Scar usage tracking automatically detects the current agent identity and session context.
+- **Closing payload schema**: Session close payload schema now ships with `init` and `session_start` for client reference.
+- **npm discoverability keywords**: Added `mcp-server`, `claude-code`, `ai-memory`, `ai-agent` keywords for npm search.
+- **Documentation site**:
+  - Restored Fumadocs source for gitmem.ai/docs with emerald theme.
+  - Redesigned docs landing page with improved messaging and branding.
+  - Added FAQ page with 11 questions.
+  - Added MCP one-liner explainer for new users.
+  - Added 3 docs examples (scar stories): credential leak, phantom deploy, and first scar.
+  - Inline mailing list signup form in docs pages.
+  - Rich installation page with multi-client instructions.
+
+### 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.
+- **Version reporting**: Server now reads version from `package.json` instead of hardcoded `1.0.3`.
+- **Log header clarity**: `gitmem log` header now says "most recent learnings" instead of ambiguous label.
+- **Analyze output**: Relabeled misleading "Open Threads" to "Threads Referenced" in analyze output.
+- **Stale thread cleanup**: Drop stale local-only threads on `session_start` when Supabase is authoritative source.
+- **Package name in docs**: Corrected to `npx gitmem-mcp init` (was `npx gitmem init`).
+- **Docs fixes**: Removed duplicate h1 headers, fixed sidebar nav duplicate entry, corrected GitHub URLs after org migration.
+
 ## [1.1.2] - 2026-02-17
 
 ### Changed

package/CLAUDE.md.template

@@ -51,18 +51,19 @@ A PreToolUse hook blocks consequential actions until all recalled scars are conf
 
 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": {
@@ -73,15 +74,15 @@ On "closing", "done for now", or "wrapping up":
        "wrong_assumption": "...",
        "scars_applied": ["scar title 1", "scar title 2"],
        "institutional_memory_items": "...",
-       "collaborative_dynamic": "Q8: How human preferred to work",
-       "rapport_notes": "Q9: What collaborative dynamic worked"
+       "collaborative_dynamic": "...",
+       "rapport_notes": "..."
      },
      "task_completion": {
-       "questions_displayed_at": "ISO timestamp",
-       "reflection_completed_at": "ISO timestamp",
-       "human_asked_at": "ISO timestamp",
-       "human_response_at": "ISO timestamp",
-       "human_response": "human's correction text or 'Looks good'"
+       "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": [],
@@ -91,7 +92,15 @@ On "closing", "done for now", or "wrapping up":
    }
    ```
 
-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 -->

package/README.md

@@ -3,11 +3,11 @@
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/gitmem-mcp"><img src="https://img.shields.io/npm/v/gitmem-mcp?style=flat-square&color=ed1e25&label=npm" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/gitmem-mcp"><img src="https://img.shields.io/npm/v/gitmem-mcp?style=flat-square&color=c41920&label=npm" alt="npm version" /></a>
   <a href="https://www.npmjs.com/package/gitmem-mcp"><img src="https://img.shields.io/npm/dm/gitmem-mcp?style=flat-square&color=333333&label=downloads" alt="npm downloads" /></a>
-  <a href="https://github.com/gitmem-dev/gitmem/blob/main/LICENSE"><img src="https://img.shields.io/github/license/gitmem-dev/gitmem?style=flat-square&color=ed1e25" alt="MIT License" /></a>
+  <a href="https://github.com/gitmem-dev/gitmem/blob/main/LICENSE"><img src="https://img.shields.io/github/license/gitmem-dev/gitmem?style=flat-square&color=c41920" alt="MIT License" /></a>
   <a href="https://github.com/gitmem-dev/gitmem/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/gitmem-dev/gitmem/ci.yml?style=flat-square&color=333333&label=build" alt="Build" /></a>
-  <img src="https://img.shields.io/badge/node-%3E%3D22-ed1e25?style=flat-square" alt="Node.js >= 22" />
+  <img src="https://img.shields.io/badge/node-%3E%3D18-c41920?style=flat-square" alt="Node.js >= 18" />
 </p>
 
 <p align="center">
@@ -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) |
@@ -120,7 +136,7 @@ Every scar includes **counter-arguments** — reasons why someone might reasonab
 | **Session analytics** | Spot patterns in what keeps going wrong |
 | **Sub-agent briefing** | Hand institutional context to sub-agents automatically |
 | **Cloud persistence** | Memory survives machine changes, shareable across team |
-| **A/B testing** | Optimize scar phrasing based on what actually changes behavior |
+| **A/B testing analytics** | Measure which scar phrasings actually change agent behavior (free tier includes `GITMEM_NUDGE_VARIANT` for manual testing) |
 
 The free tier gives you everything for solo projects. Pro makes recall smarter and memory portable.
 

package/bin/gitmem.js

@@ -51,6 +51,9 @@ Other commands:
   npx gitmem-mcp check --full      Full diagnostic with benchmarks
   npx gitmem-mcp install-hooks     Install hooks (standalone)
   npx gitmem-mcp uninstall-hooks   Remove hooks (standalone)
+  npx gitmem-mcp telemetry status  Check telemetry settings
+  npx gitmem-mcp telemetry enable  Enable anonymous usage tracking (opt-in)
+  npx gitmem-mcp telemetry disable Disable usage tracking
   npx gitmem-mcp server            Start MCP server (default)
   npx gitmem-mcp help              Show this help message
 
@@ -200,6 +203,10 @@ async function cmdInit() {
     console.log("Add .gitmem/ to your .gitignore:");
     console.log("  echo '.gitmem/' >> .gitignore");
     console.log("");
+
+    // Prompt for telemetry (optional, non-blocking)
+    promptTelemetryOptIn();
+
     console.log("To upgrade to Pro tier (semantic search + Supabase persistence):");
     console.log("  Set SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY, then run init again.");
     return;
@@ -686,6 +693,29 @@ function cmdInstallHooks() {
   console.log("  npx gitmem-mcp install-hooks --force");
 }
 
+/**
+ * Prompt user to opt-in to telemetry (non-blocking, async)
+ */
+function promptTelemetryOptIn() {
+  console.log("─────────────────────────────────────────────");
+  console.log("");
+  console.log("Help improve GitMem? (Optional)");
+  console.log("");
+  console.log("Send anonymous usage data to help us understand:");
+  console.log("  • Which features are most useful");
+  console.log("  • Where errors occur");
+  console.log("  • Performance patterns");
+  console.log("");
+  console.log("✓ No queries, scars, or project content");
+  console.log("✓ Randomized ID (not linked to you)");
+  console.log("✓ View all data before it's sent");
+  console.log("✓ Disable anytime");
+  console.log("");
+  console.log("To enable: npx gitmem-mcp telemetry enable");
+  console.log("Privacy policy: https://gitmem.ai/privacy");
+  console.log("");
+}
+
 /**
  * Uninstall gitmem hooks.
  *
@@ -858,6 +888,9 @@ switch (command) {
   case "check":
     import("../dist/commands/check.js").then((m) => m.main(process.argv.slice(3)));
     break;
+  case "telemetry":
+    import("../dist/commands/telemetry.js").then((m) => m.main(process.argv.slice(3)));
+    break;
   case "install-hooks":
     cmdInstallHooks();
     break;

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();