gitmem-mcp 1.0.2 → 1.0.4

package/dist/server.js

@@ -43,7 +43,7 @@ import { validateToolArgs } from "./schemas/registry.js";
 export function createServer() {
     const server = new Server({
         name: "gitmem-mcp",
-        version: "0.1.0",
+        version: "1.0.3",
     }, {
         capabilities: {
             tools: {},
@@ -207,6 +207,7 @@ export function createServer() {
                         { alias: "gitmem-r", full: "recall", description: "Check scars before taking action" },
                         { alias: "gitmem-cs", full: "confirm_scars", description: "Confirm recalled scars (APPLYING/N_A/REFUTED)" },
                         { alias: "gitmem-ss", full: "session_start", description: "Initialize session with context" },
+                        { alias: "gitmem-sr", full: "session_refresh", description: "Refresh context for active session" },
                         { alias: "gitmem-sc", full: "session_close", description: "Close session with compliance validation" },
                         { alias: "gitmem-cl", full: "create_learning", description: "Create scar/win/pattern entry" },
                         { alias: "gitmem-cd", full: "create_decision", description: "Log architectural/operational decision" },
@@ -223,6 +224,7 @@ export function createServer() {
                         { alias: "gitmem-cleanup", full: "cleanup_threads", description: "Triage threads by lifecycle health" },
                         { alias: "gitmem-health", full: "health", description: "Show write health for fire-and-forget operations" },
                         { alias: "gitmem-al", full: "archive_learning", description: "Archive a scar/win/pattern (is_active=false)" },
+                        { alias: "gitmem-graph", full: "graph_traverse", description: "Traverse knowledge graph over institutional memory" },
                     ];
                     if (hasBatchOperations()) {
                         commands.push({ alias: "gitmem-rsb", full: "record_scar_usage_batch", description: "Track multiple scars (batch)" });
@@ -233,10 +235,12 @@ export function createServer() {
                     if (hasCacheManagement()) {
                         commands.push({ alias: "gitmem-cache-status", full: "cache_status", description: "Show cache status" }, { alias: "gitmem-cache-health", full: "cache_health", description: "Compare local vs remote" }, { alias: "gitmem-cache-flush", full: "cache_flush", description: "Force reload from Supabase" });
                     }
+                    // Filter to only show commands whose canonical tool is actually registered
+                    const visibleCommands = commands.filter(c => registeredToolNames.has(c.full));
                     // Build command table for display
-                    const cmdLines = commands.map(c => `  ${c.alias.padEnd(22)} ${c.description}`).join("\n");
+                    const cmdLines = visibleCommands.map(c => `  ${c.alias.padEnd(22)} ${c.description}`).join("\n");
                     const display = [
-                        `gitmem v0.1.0 · ${tier} · ${registeredTools.length} tools · ${hasSupabase() ? "supabase" : "local (.gitmem/)"}`,
+                        `gitmem v1.0.3 · ${tier} · ${registeredTools.length} tools · ${hasSupabase() ? "supabase" : "local (.gitmem/)"}`,
                         "Memory that compounds.",
                         "",
                         cmdLines,
@@ -248,11 +252,11 @@ export function createServer() {
                         "Tool results are collapsed in the CLI — the user cannot see them unless you echo them.",
                     ].join("\n");
                     result = {
-                        version: "0.1.0",
+                        version: "1.0.3",
                         tier,
                         tools_registered: registeredTools.length,
                         storage: hasSupabase() ? "supabase" : "local (.gitmem/)",
-                        commands,
+                        commands: visibleCommands,
                         display,
                     };
                     break;
@@ -277,7 +281,7 @@ export function createServer() {
                 case "gm-graph":
                     result = await graphTraverse(toolArgs);
                     break;
-                // Cache management tools (OD-473)
+                // Cache management tools
                 case "gitmem-cache-status":
                 case "gm-cache-s":
                     result = getCacheStatus(toolArgs.project || getProject() || "default");
@@ -319,12 +323,19 @@ export function createServer() {
             };
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
+            const rawMessage = error instanceof Error ? error.message : String(error);
+            // Redact internal details: file paths, SQL errors, stack traces
+            const safeMessage = rawMessage
+                .replace(/\/[^\s:]+/g, "[path]") // redact file paths
+                .replace(/\b\d{5}\b/g, "[code]") // redact PG error codes
+                .replace(/at\s+\S+\s+\(.+\)/g, "") // strip stack frames
+                .slice(0, 200); // cap length
+            console.error(`[server] Tool error:`, rawMessage);
             return {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify({ error: message }),
+                        text: JSON.stringify({ error: safeMessage }),
                     },
                 ],
                 isError: true,
@@ -336,8 +347,8 @@ export function createServer() {
 /**
  * Run the server with stdio transport
  *
- * OD-473: Initializes local vector search in background for fast startup.
- * OD-489: Uses direct Supabase queries to get embeddings for local cache.
+ * Initializes local vector search in background for fast startup.
+ * Uses direct Supabase queries to get embeddings for local cache.
  *
  * Server starts immediately; cache loads in background.
  * First few queries may use Supabase fallback until cache is ready.

package/dist/services/active-sessions.js

@@ -13,7 +13,7 @@
 import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
-import { getGitmemDir, getSessionPath } from "./gitmem-dir.js";
+import { getGitmemDir, getSessionPath, sanitizePathComponent } from "./gitmem-dir.js";
 import { ActiveSessionsRegistrySchema } from "../schemas/active-sessions.js";
 import { withLockSync } from "./file-lock.js";
 const REGISTRY_FILENAME = "active-sessions.json";
@@ -276,6 +276,7 @@ function pruneOrphanedDirs(gitmemDir, registry) {
  */
 function cleanupSessionDir(gitmemDir, sessionId) {
     try {
+        sanitizePathComponent(sessionId, "sessionId");
         const sessionDir = path.join(gitmemDir, "sessions", sessionId);
         if (fs.existsSync(sessionDir)) {
             fs.rmSync(sessionDir, { recursive: true, force: true });
@@ -328,7 +329,7 @@ export function migrateFromLegacy() {
             // 2. Create registry with single entry
             const entry = {
                 session_id: old.session_id,
-                agent: old.agent || "CLI",
+                agent: old.agent || "cli",
                 started_at: old.started_at || new Date().toISOString(),
                 hostname: old.hostname || os.hostname(),
                 pid: old.pid || process.pid,

package/dist/services/agent-briefing.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Agent Briefing Generator
+ *
+ * Generates `.gitmem/agent-briefing.md` at session close with a
+ * compact summary of memory state. Designed for inclusion in
+ * MEMORY.md to bridge PMEM <-> GitMem.
+ */
+/**
+ * Generate and write agent-briefing.md to .gitmem/
+ */
+export declare function writeAgentBriefing(newLearnings: number, newDecisions: number): Promise<void>;
+//# sourceMappingURL=agent-briefing.d.ts.map

package/dist/services/agent-briefing.js

@@ -0,0 +1,81 @@
+/**
+ * Agent Briefing Generator
+ *
+ * Generates `.gitmem/agent-briefing.md` at session close with a
+ * compact summary of memory state. Designed for inclusion in
+ * MEMORY.md to bridge PMEM <-> GitMem.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { getGitmemDir } from "./gitmem-dir.js";
+import { getStorage } from "./storage.js";
+/**
+ * Generate and write agent-briefing.md to .gitmem/
+ */
+export async function writeAgentBriefing(newLearnings, newDecisions) {
+    try {
+        const gitmemDir = getGitmemDir();
+        if (!gitmemDir || !fs.existsSync(gitmemDir))
+            return;
+        const storage = getStorage();
+        const sessions = await storage.query("sessions");
+        const learnings = await storage.query("learnings");
+        const threads = await storage.query("threads");
+        // Count by severity
+        const severityCounts = {};
+        const domainCounts = {};
+        for (const l of learnings) {
+            const sev = l.severity || "medium";
+            severityCounts[sev] = (severityCounts[sev] || 0) + 1;
+            const domains = l.domain || [];
+            for (const d of domains) {
+                domainCounts[d] = (domainCounts[d] || 0) + 1;
+            }
+        }
+        // Active threads
+        const activeThreads = threads.filter((t) => t.status === "open").length;
+        // Top domains (top 5)
+        const topDomains = Object.entries(domainCounts)
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, 5)
+            .map(([d]) => d);
+        // Severity breakdown
+        const sevParts = [];
+        if (severityCounts.critical)
+            sevParts.push(`${severityCounts.critical} critical`);
+        if (severityCounts.high)
+            sevParts.push(`${severityCounts.high} high`);
+        if (severityCounts.medium)
+            sevParts.push(`${severityCounts.medium} medium`);
+        if (severityCounts.low)
+            sevParts.push(`${severityCounts.low} low`);
+        // Recent activity
+        const recentParts = [];
+        if (newLearnings > 0)
+            recentParts.push(`+${newLearnings} scars`);
+        if (newDecisions > 0)
+            recentParts.push(`+${newDecisions} decisions`);
+        const today = new Date().toISOString().split("T")[0];
+        const lines = [
+            "<!-- Generated by GitMem at session close. Include in MEMORY.md for cross-session context. -->",
+            "## GitMem Status",
+            `- **Sessions:** ${sessions.length} total, last: ${today}`,
+            `- **Active threads:** ${activeThreads}`,
+            `- **Scars earned:** ${learnings.length}${sevParts.length > 0 ? ` (${sevParts.join(", ")})` : ""}`,
+        ];
+        if (recentParts.length > 0) {
+            lines.push(`- **Recent:** ${recentParts.join(", ")} this session`);
+        }
+        if (topDomains.length > 0) {
+            lines.push(`- **Top domains:** ${topDomains.join(", ")}`);
+        }
+        const briefingPath = path.join(gitmemDir, "agent-briefing.md");
+        fs.writeFileSync(briefingPath, lines.join("\n") + "\n");
+        console.error(`[agent-briefing] Written to ${briefingPath}`);
+    }
+    catch (error) {
+        // Non-fatal — don't break session close
+        console.warn("[agent-briefing] Failed to write:", error);
+    }
+}
+//# sourceMappingURL=agent-briefing.js.map

package/dist/services/agent-detection.d.ts

@@ -8,7 +8,7 @@
  * | ENTRYPOINT | Docker | Hostname | Identity |
  * |------------|--------|----------|----------|
  * | cli        | YES    | (any)    | CLI      |
- * | cli        | NO     | orchestra.nteg.com | CODA-1 |
+ * | cli        | NO     | (server hostname)  | CODA-1 |
  * | claude-desktop | NO | (any)    | DAC      |
  * | (empty)    | NO     | (local)  | Brain_Local |
  * | (empty)    | NO     | (no fs)  | Brain_Cloud |
@@ -18,6 +18,7 @@ import type { AgentIdentity, DetectedEnvironment } from "../types/index.js";
  * Detect the current agent identity based on environment
  */
 export declare function detectAgent(): DetectedEnvironment;
+export declare function normalizeAgent(input: string): AgentIdentity;
 /**
  * Get just the agent identity (convenience function)
  */

package/dist/services/agent-detection.js

@@ -8,7 +8,7 @@
  * | ENTRYPOINT | Docker | Hostname | Identity |
  * |------------|--------|----------|----------|
  * | cli        | YES    | (any)    | CLI      |
- * | cli        | NO     | orchestra.nteg.com | CODA-1 |
+ * | cli        | NO     | (server hostname)  | CODA-1 |
  * | claude-desktop | NO | (any)    | DAC      |
  * | (empty)    | NO     | (local)  | Brain_Local |
  * | (empty)    | NO     | (no fs)  | Brain_Cloud |
@@ -48,33 +48,27 @@ export function detectAgent() {
     let agent;
     if (entrypoint === "cli") {
         if (docker) {
-            // CLI in Docker container
-            agent = "CLI";
+            agent = "cli";
         }
-        else if (hostname === "orchestra.nteg.com" || hostname === "cyrus") {
-            // CLI on orchestra server = CODA-1
-            agent = "CODA-1";
+        else if (process.env.GITMEM_AGENT_HOSTNAME && (hostname === process.env.GITMEM_AGENT_HOSTNAME)) {
+            agent = "autonomous";
         }
         else {
-            // CLI elsewhere (fallback)
-            agent = "CLI";
+            agent = "cli";
         }
     }
     else if (entrypoint === "claude-desktop") {
-        // Desktop app code tab
-        agent = "DAC";
+        agent = "desktop";
     }
     else if (!entrypoint) {
-        // No entrypoint - could be Brain Local or Brain Cloud
         if (hasFilesystemAccess()) {
-            agent = "Brain_Local";
+            agent = "local";
         }
         else {
-            agent = "Brain_Cloud";
+            agent = "cloud";
         }
     }
     else {
-        // Unknown entrypoint
         agent = "Unknown";
     }
     return {
@@ -84,6 +78,21 @@ export function detectAgent() {
         agent,
     };
 }
+/**
+ * Normalize legacy agent names to new generic names.
+ * Accepts both old (CLI, DAC, CODA-1, Brain_Local, Brain_Cloud)
+ * and new (cli, desktop, autonomous, local, cloud) formats.
+ */
+const LEGACY_MAP = {
+    "CLI": "cli",
+    "DAC": "desktop",
+    "CODA-1": "autonomous",
+    "Brain_Local": "local",
+    "Brain_Cloud": "cloud",
+};
+export function normalizeAgent(input) {
+    return LEGACY_MAP[input] || input;
+}
 /**
  * Get just the agent identity (convenience function)
  */

package/dist/services/analytics.d.ts

@@ -1,5 +1,5 @@
 /**
- * Analytics Service (OD-567)
+ * Analytics Service
  *
  * Shared analytics engine for session insights. Powers both the
  * gitmem-analyze MCP tool (CLI) and the GitMem Console dashboard.

package/dist/services/analytics.js

@@ -1,12 +1,12 @@
 /**
- * Analytics Service (OD-567)
+ * Analytics Service
  *
  * Shared analytics engine for session insights. Powers both the
  * gitmem-analyze MCP tool (CLI) and the GitMem Console dashboard.
  *
  * Uses directQuery for raw Supabase REST access (no ww-mcp dependency).
  */
-import { directQuery, directQueryAll } from "./supabase-client.js";
+import { directQuery, directQueryAll, safeInFilter } from "./supabase-client.js";
 import { getCache } from "./cache.js";
 // --- Query Layer ---
 /**
@@ -97,7 +97,7 @@ export async function enrichScarUsageTitles(usages) {
     const learnings = await directQuery("orchestra_learnings", {
         select: "id,title,severity",
         filters: {
-            id: `in.(${ids.join(",")})`,
+            id: safeInFilter(ids),
         },
     });
     // Build lookup map

package/dist/services/behavioral-decay.js

@@ -10,7 +10,7 @@
  * 2. fetchDismissalCounts() — queries scar_usage for inline archival hints
  *    (called from recall to annotate frequently-dismissed scars)
  */
-import { isConfigured } from "./supabase-client.js";
+import { isConfigured, safeInFilter } from "./supabase-client.js";
 const SUPABASE_URL = process.env.SUPABASE_URL || "";
 const SUPABASE_KEY = process.env.SUPABASE_SERVICE_ROLE_KEY || process.env.SUPABASE_KEY || "";
 const SUPABASE_REST_URL = SUPABASE_URL ? `${SUPABASE_URL}/rest/v1` : "";
@@ -76,7 +76,7 @@ export async function fetchDismissalCounts(scarIds) {
         // Query scar_usage for the given scar IDs (last 90 days)
         const url = new URL(`${SUPABASE_REST_URL}/scar_usage`);
         url.searchParams.set("select", "scar_id,reference_type");
-        url.searchParams.set("scar_id", `in.(${scarIds.join(",")})`);
+        url.searchParams.set("scar_id", safeInFilter(scarIds));
         url.searchParams.set("surfaced_at", `gte.${new Date(Date.now() - 90 * 86400000).toISOString()}`);
         url.searchParams.set("limit", "1000");
         const response = await fetch(url.toString(), {

package/dist/services/cache.d.ts

@@ -5,7 +5,7 @@
  * Caches search results to avoid repeated ww-mcp calls.
  *
  * Design: docs/systems/gitmem-caching.md
- * Issue: OD-473
+ *
  */
 declare const TTL: {
     readonly SCAR_SEARCH: number;

package/dist/services/cache.js

@@ -5,7 +5,7 @@
  * Caches search results to avoid repeated ww-mcp calls.
  *
  * Design: docs/systems/gitmem-caching.md
- * Issue: OD-473
+ *
  */
 import { createHash } from "crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, unlinkSync, statSync } from "fs";

package/dist/services/compliance-validator.d.ts

@@ -3,7 +3,7 @@
  *
  * Validates session close compliance based on close type.
  *
- * Standard close requires (OD-491):
+ * Standard close requires:
  * - task_completion object with timestamps proving each step was done
  * - All 6 closing questions answered
  * - human_corrections field present (even if empty string)

package/dist/services/compliance-validator.js

@@ -3,7 +3,7 @@
  *
  * Validates session close compliance based on close type.
  *
- * Standard close requires (OD-491):
+ * Standard close requires:
  * - task_completion object with timestamps proving each step was done
  * - All 6 closing questions answered
  * - human_corrections field present (even if empty string)
@@ -17,7 +17,7 @@ import { CLOSING_QUESTIONS } from "../constants/closing-questions.js";
 /** Minimum time (ms) between asking human and receiving response */
 const MIN_HUMAN_RESPONSE_GAP_MS = 3000;
 /**
- * Validate task_completion timestamps (OD-491)
+ * Validate task_completion timestamps
  *
  * Ensures:
  * 1. All timestamps are valid ISO strings
@@ -83,14 +83,14 @@ function validateTaskCompletion(tc) {
 /**
  * Validate standard close parameters
  *
- * OD-491: Now requires task_completion with timestamps proving each step was done.
+ * Now requires task_completion with timestamps proving each step was done.
  */
 function validateStandardClose(params) {
     const errors = [];
     const warnings = [];
-    // OD-491: task_completion is REQUIRED for standard close
+    // task_completion is REQUIRED for standard close
     if (!params.task_completion) {
-        errors.push("Standard close requires task_completion object (OD-491). " +
+        errors.push("Standard close requires task_completion object. " +
             "You must complete each step: display questions → answer → ask human → wait for response");
     }
     else {

package/dist/services/config.d.ts

@@ -10,7 +10,7 @@
  * - GITMEM_STALE_CHECK: "true" | "false" - Check for stale data (default: "true")
  * - SUPABASE_URL: Supabase project URL
  *
- * Issue: OD-473
+ *
  */
 import type { GitMemTier } from "./tier.js";
 export type SearchMode = "local" | "remote" | "auto";

package/dist/services/config.js

@@ -10,7 +10,7 @@
  * - GITMEM_STALE_CHECK: "true" | "false" - Check for stale data (default: "true")
  * - SUPABASE_URL: Supabase project URL
  *
- * Issue: OD-473
+ *
  */
 import { getTier, hasSupabase, getTablePrefix } from "./tier.js";
 // Private IP patterns for on-prem detection

package/dist/services/file-lock.js

@@ -66,6 +66,18 @@ export function acquireLockSync(lockPath, timeoutMs = DEFAULT_TIMEOUT_MS, retryM
             if (error.code !== "EEXIST") {
                 throw new Error(`[file-lock] Failed to create lock file ${lockPath}: ${error.message}`);
             }
+            // Lock file exists — check if we already hold it (reentrance detection)
+            try {
+                const raw = fs.readFileSync(lockPath, "utf-8");
+                const holder = JSON.parse(raw);
+                if (holder.pid === process.pid && holder.hostname === os.hostname()) {
+                    // Same process already holds the lock — reentrant call, allow through
+                    return;
+                }
+            }
+            catch {
+                // Can't read lock — fall through to stale check
+            }
             // Lock file exists — check if stale
             if (isLockStale(lockPath)) {
                 try {

package/dist/services/gitmem-dir.d.ts

@@ -2,20 +2,33 @@
  * Resolved .gitmem directory path
  *
  * Solves: process.cwd() changes when agents cd into other repos (e.g., /workspace/gitmem),
- * but .gitmem/ was created in the project root (e.g., /workspace/orchestra/).
+ * but .gitmem/ was created in the project root.
  * The MCP server is long-running, so we resolve the path once and cache it.
  *
  * Resolution order:
- * 1. Cached path from session_start (most reliable — session_start created the directory)
- * 2. Walk up from process.cwd() looking for existing .gitmem/ sentinels
- * 3. Fall back to process.cwd()/.gitmem (original behavior)
+ * 1. GITMEM_DIR env var (explicit override)
+ * 2. Cached path from session_start (most reliable — session_start created the directory)
+ * 3. Walk up from process.cwd() looking for existing .gitmem/ sentinels (backward compat)
+ * 4. Fall back to ~/.gitmem (developer-scoped, survives across projects/containers)
  */
+/**
+ * Validate a string intended for use as a single path component (directory name or filename).
+ * Rejects path traversal sequences, directory separators, and null bytes.
+ * Throws on invalid input — callers should validate before reaching this layer.
+ */
+export declare function sanitizePathComponent(value: string, label: string): string;
 /**
  * Set the .gitmem directory path (called by session_start after creating it)
  */
 export declare function setGitmemDir(dir: string): void;
 /**
  * Get the resolved .gitmem directory path
+ *
+ * Resolution order:
+ * 1. GITMEM_DIR env var (explicit override)
+ * 2. Cached path from session_start (most reliable)
+ * 3. Walk up from CWD looking for existing .gitmem/ sentinels (backward compat)
+ * 4. Fall back to ~/.gitmem (developer-scoped, survives across projects/containers)
  */
 export declare function getGitmemDir(): string;
 /**

package/dist/services/gitmem-dir.js

@@ -2,16 +2,32 @@
  * Resolved .gitmem directory path
  *
  * Solves: process.cwd() changes when agents cd into other repos (e.g., /workspace/gitmem),
- * but .gitmem/ was created in the project root (e.g., /workspace/orchestra/).
+ * but .gitmem/ was created in the project root.
  * The MCP server is long-running, so we resolve the path once and cache it.
  *
  * Resolution order:
- * 1. Cached path from session_start (most reliable — session_start created the directory)
- * 2. Walk up from process.cwd() looking for existing .gitmem/ sentinels
- * 3. Fall back to process.cwd()/.gitmem (original behavior)
+ * 1. GITMEM_DIR env var (explicit override)
+ * 2. Cached path from session_start (most reliable — session_start created the directory)
+ * 3. Walk up from process.cwd() looking for existing .gitmem/ sentinels (backward compat)
+ * 4. Fall back to ~/.gitmem (developer-scoped, survives across projects/containers)
  */
 import * as path from "path";
 import * as fs from "fs";
+import * as os from "os";
+/**
+ * Validate a string intended for use as a single path component (directory name or filename).
+ * Rejects path traversal sequences, directory separators, and null bytes.
+ * Throws on invalid input — callers should validate before reaching this layer.
+ */
+export function sanitizePathComponent(value, label) {
+    if (!value || typeof value !== "string") {
+        throw new Error(`${label} must be a non-empty string`);
+    }
+    if (value.includes("..") || value.includes("/") || value.includes("\\") || value.includes("\0")) {
+        throw new Error(`${label} contains invalid characters (path traversal rejected)`);
+    }
+    return value;
+}
 let cachedGitmemDir = null;
 /**
  * Set the .gitmem directory path (called by session_start after creating it)
@@ -22,13 +38,29 @@ export function setGitmemDir(dir) {
 }
 /**
  * Get the resolved .gitmem directory path
+ *
+ * Resolution order:
+ * 1. GITMEM_DIR env var (explicit override)
+ * 2. Cached path from session_start (most reliable)
+ * 3. Walk up from CWD looking for existing .gitmem/ sentinels (backward compat)
+ * 4. Fall back to ~/.gitmem (developer-scoped, survives across projects/containers)
  */
 export function getGitmemDir() {
-    // 1. Use cached path from session_start
+    // 1. GITMEM_DIR env var (explicit override, highest priority)
+    const envDir = process.env.GITMEM_DIR;
+    if (envDir) {
+        if (!cachedGitmemDir || cachedGitmemDir !== envDir) {
+            cachedGitmemDir = envDir;
+            console.error(`[gitmem-dir] Using GITMEM_DIR env var: ${envDir}`);
+        }
+        return envDir;
+    }
+    // 2. Use cached path from session_start
     if (cachedGitmemDir && fs.existsSync(cachedGitmemDir)) {
         return cachedGitmemDir;
     }
-    // 2. Walk up from CWD looking for existing .gitmem directory
+    // 3. Walk up from CWD looking for existing .gitmem directory
+    //    Backward compat: finds project-scoped .gitmem/ from older installations.
     //    Sentinel files checked in priority order:
     //    - active-sessions.json  (multi-session registry, GIT-19)
     //    - config.json           (project-level gitmem config)
@@ -46,9 +78,9 @@ export function getGitmemDir() {
         }
         dir = path.dirname(dir);
     }
-    // 3. Fall back to CWD (original behavior)
-    const fallback = path.join(process.cwd(), ".gitmem");
-    console.error(`[gitmem-dir] Falling back to CWD: ${fallback}`);
+    // 4. Fall back to ~/.gitmem (developer-scoped — survives across projects and containers)
+    const fallback = path.join(os.homedir(), ".gitmem");
+    console.error(`[gitmem-dir] Falling back to home dir: ${fallback}`);
     return fallback;
 }
 /**
@@ -62,6 +94,7 @@ export function getGitmemPath(filename) {
  * Creates the directory if it doesn't exist.
  */
 export function getSessionDir(sessionId) {
+    sanitizePathComponent(sessionId, "sessionId");
     const sessionsDir = path.join(getGitmemDir(), "sessions", sessionId);
     if (!fs.existsSync(sessionsDir)) {
         fs.mkdirSync(sessionsDir, { recursive: true });
@@ -73,6 +106,7 @@ export function getSessionDir(sessionId) {
  * Get a file path within a per-session directory.
  */
 export function getSessionPath(sessionId, filename) {
+    sanitizePathComponent(filename, "filename");
     return path.join(getSessionDir(sessionId), filename);
 }
 /**

package/dist/services/local-file-storage.d.ts

@@ -2,7 +2,7 @@
  * Local File Storage — Free Tier Backend
  *
  * Stores scars, sessions, decisions, and scar usage as JSON files
- * in the .gitmem/ directory of the current project.
+ * in the .gitmem/ directory (defaults to ~/.gitmem, overridable via GITMEM_DIR).
  *
  * Provides keyword-based search (no embeddings needed).
  */