gitmem-mcp 1.6.1 → 1.6.3

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.6.3] - 2026-06-11
+
+### Fixed
+- **Stale npx cache**: All MCP server configs now use `gitmem-mcp@latest` instead of `gitmem-mcp`. Without `@latest`, npx can serve a cached older version indefinitely — the `-y` flag only auto-confirms prompts, it does not force a registry check. Affects: init wizard, configure command, README, docs, and distribution configs.
+
+## [1.6.2] - 2026-06-11
+
+### Fixed
+- **`archive_learning` short-ID resolution**: Accepts 8-character ID prefixes (e.g., `6edd41e6`) in addition to full UUIDs, matching the short IDs shown by `recall` and `search`.
+
+### Added
+- **Write-path health check**: New startup diagnostic detects two silent failure classes — (1) Supabase credentials present but tier resolved to FREE (writes go to local files instead of Supabase), and (2) pro/dev tier but resolved tables don't exist (prefix mismatch). Logs a loud warning at startup instead of failing silently on the first write.
+- **`GITMEM_TABLE_PREFIX` documentation**: Pro setup guide now documents custom table prefix configuration, mismatch symptoms, and troubleshooting steps.
+
 ## [1.6.1] - 2026-05-25
 
 ### Fixed

package/README.md

@@ -101,7 +101,7 @@ Add this to your MCP client's config file:
   "mcpServers": {
     "gitmem": {
       "command": "npx",
-      "args": ["-y", "gitmem-mcp"]
+      "args": ["-y", "gitmem-mcp@latest"]
     }
   }
 }

package/bin/gitmem.js

@@ -313,7 +313,7 @@ function cmdConfigure() {
       mcpServers: {
         gitmem: {
           command: "npx",
-          args: ["-y", "gitmem-mcp"],
+          args: ["-y", "gitmem-mcp@latest"],
         },
       },
     };
@@ -332,7 +332,7 @@ function cmdConfigure() {
       mcpServers: {
         gitmem: {
           command: "npx",
-          args: ["-y", "gitmem-mcp"],
+          args: ["-y", "gitmem-mcp@latest"],
           env: {
             SUPABASE_URL: "https://YOUR_PROJECT.supabase.co",
             SUPABASE_SERVICE_ROLE_KEY: "eyJ...",

package/bin/init-wizard.js

@@ -253,11 +253,11 @@ function log(icon, main, detail) {
 function buildMcpConfig() {
   const supabaseUrl = process.env.SUPABASE_URL;
   if (!supabaseUrl) {
-    return { command: "npx", args: ["-y", "gitmem-mcp"] };
+    return { command: "npx", args: ["-y", "gitmem-mcp@latest"] };
   }
   return {
     command: "npx",
-    args: ["-y", "gitmem-mcp"],
+    args: ["-y", "gitmem-mcp@latest"],
     env: {
       SUPABASE_URL: supabaseUrl,
       SUPABASE_SERVICE_ROLE_KEY:

package/dist/schemas/archive-learning.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Zod schema for archive_learning tool parameters
+ */
+import { z } from "zod";
+/**
+ * Archive learning parameters schema
+ *
+ * Accepts full UUIDs or short hex prefixes (4-32 chars).
+ * Short prefixes are resolved to full UUIDs at runtime.
+ */
+export declare const ArchiveLearningParamsSchema: z.ZodObject<{
+    id: z.ZodString;
+    reason: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    reason?: string | undefined;
+}, {
+    id: string;
+    reason?: string | undefined;
+}>;
+export type ArchiveLearningParams = z.infer<typeof ArchiveLearningParamsSchema>;
+//# sourceMappingURL=archive-learning.d.ts.map

package/dist/schemas/archive-learning.js

@@ -0,0 +1,15 @@
+/**
+ * Zod schema for archive_learning tool parameters
+ */
+import { z } from "zod";
+/**
+ * Archive learning parameters schema
+ *
+ * Accepts full UUIDs or short hex prefixes (4-32 chars).
+ * Short prefixes are resolved to full UUIDs at runtime.
+ */
+export const ArchiveLearningParamsSchema = z.object({
+    id: z.string().min(4, "ID must be at least 4 characters (short hex prefix or full UUID)").max(36),
+    reason: z.string().max(500).optional(),
+});
+//# sourceMappingURL=archive-learning.js.map

package/dist/schemas/index.d.ts

@@ -20,4 +20,5 @@ export * from "./get-transcript.js";
 export * from "./prepare-context.js";
 export * from "./absorb-observations.js";
 export * from "./active-sessions.js";
+export * from "./archive-learning.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/schemas/index.js

@@ -20,4 +20,5 @@ export * from "./get-transcript.js";
 export * from "./prepare-context.js";
 export * from "./absorb-observations.js";
 export * from "./active-sessions.js";
+export * from "./archive-learning.js";
 //# sourceMappingURL=index.js.map

package/dist/schemas/registry.js

@@ -22,6 +22,7 @@ import { PrepareContextParamsSchema } from "./prepare-context.js";
 import { AbsorbObservationsParamsSchema } from "./absorb-observations.js";
 import { ListThreadsParamsSchema, ResolveThreadParamsSchema } from "./thread.js";
 import { ContributeFeedbackParamsSchema } from "./contribute-feedback.js";
+import { ArchiveLearningParamsSchema } from "./archive-learning.js";
 /**
  * Map of canonical tool names → Zod schemas.
  * Aliases (gitmem-r, gm-open, etc.) are resolved to canonical names before lookup.
@@ -45,6 +46,7 @@ const TOOL_SCHEMAS = {
     list_threads: ListThreadsParamsSchema,
     resolve_thread: ResolveThreadParamsSchema,
     contribute_feedback: ContributeFeedbackParamsSchema,
+    archive_learning: ArchiveLearningParamsSchema,
 };
 /**
  * Map of alias → canonical name for all tool aliases.
@@ -113,7 +115,7 @@ const ALIAS_MAP = {
     // cleanup_threads — no schema yet
     "gitmem-cleanup": "cleanup_threads",
     "gm-cleanup": "cleanup_threads",
-    // archive_learning — no schema yet
+    // archive_learning
     "gitmem-al": "archive_learning",
     "gm-archive": "archive_learning",
     // contribute_feedback

package/dist/server.js

@@ -39,6 +39,7 @@ import { contributeFeedback } from "./tools/contribute-feedback.js";
 import { indexDocs } from "./tools/index-docs.js";
 import { searchDocsHandler } from "./tools/search-docs.js";
 import { getCacheStatus, checkCacheHealth, flushCache, startBackgroundInit, } from "./services/startup.js";
+import { checkWritePath } from "./services/write-health.js";
 import { getEffectTracker } from "./services/effect-tracker.js";
 import { RIPPLE, ANSI } from "./services/display-protocol.js";
 import { getProject } from "./services/session-state.js";
@@ -414,10 +415,18 @@ export async function runServer() {
             else {
                 console.error(`[gitmem:license] Validated: ${result.tier} tier`);
             }
+            // Verify the write path with the FINAL tier (post-validation): catches an
+            // invalid license silently downgrading writes to local files.
+            void checkWritePath();
         }).catch((err) => {
             console.error(`[gitmem:license] Validation error: ${err}`);
         });
     }
+    else {
+        // No license key to validate — verify the write path with the detected tier
+        // (catches a GITMEM_TABLE_PREFIX / schema mismatch on the backward-compat path).
+        void checkWritePath();
+    }
     if (hasSupabase()) {
         // Pro/Dev: Initialize local vector search in background (non-blocking)
         // This loads scars with embeddings directly from Supabase REST API

package/dist/services/write-health.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Write-path health check.
+ *
+ * Verifies that (a) the resolved storage tier matches the presence of Supabase
+ * credentials and (b) the tables the WRITE path resolves to actually exist on
+ * the configured backend. Surfaces two silent-failure classes loudly at
+ * startup instead of on the first failed write:
+ *
+ *   1. free_with_credentials — Supabase creds are present but the tier resolved
+ *      to FREE (e.g. an invalid/expired/placeholder GITMEM_API_KEY). Writes go
+ *      to local .gitmem/ files instead of Supabase, while reads (recall,
+ *      cache-health) can still reach Supabase and mask the problem.
+ *   2. missing_tables — pro/dev tier, but the prefixed tables don't exist (e.g.
+ *      a GITMEM_TABLE_PREFIX mismatch, or the schema was never applied).
+ *      create_learning / create_decision 404 (PGRST205) on the first write.
+ *
+ * Fire-and-forget: never throws (whole body is guarded), never blocks startup.
+ * Logs a loud warning to stderr when misconfigured, a one-line confirmation
+ * otherwise.
+ */
+export type WritePathMode = "local" | "free_with_credentials" | "missing_tables" | "supabase" | "skipped";
+export interface WritePathResult {
+    ok: boolean;
+    mode: WritePathMode;
+    missing?: string[];
+}
+export declare function checkWritePath(): Promise<WritePathResult>;
+//# sourceMappingURL=write-health.d.ts.map

package/dist/services/write-health.js

@@ -0,0 +1,79 @@
+/**
+ * Write-path health check.
+ *
+ * Verifies that (a) the resolved storage tier matches the presence of Supabase
+ * credentials and (b) the tables the WRITE path resolves to actually exist on
+ * the configured backend. Surfaces two silent-failure classes loudly at
+ * startup instead of on the first failed write:
+ *
+ *   1. free_with_credentials — Supabase creds are present but the tier resolved
+ *      to FREE (e.g. an invalid/expired/placeholder GITMEM_API_KEY). Writes go
+ *      to local .gitmem/ files instead of Supabase, while reads (recall,
+ *      cache-health) can still reach Supabase and mask the problem.
+ *   2. missing_tables — pro/dev tier, but the prefixed tables don't exist (e.g.
+ *      a GITMEM_TABLE_PREFIX mismatch, or the schema was never applied).
+ *      create_learning / create_decision 404 (PGRST205) on the first write.
+ *
+ * Fire-and-forget: never throws (whole body is guarded), never blocks startup.
+ * Logs a loud warning to stderr when misconfigured, a one-line confirmation
+ * otherwise.
+ */
+import { getTier, hasSupabase, getTablePrefix, getTableName } from "./tier.js";
+import { isConfigured, directQuery } from "./supabase-client.js";
+/** Error messages that indicate a resolved table is absent on the backend. */
+const SCHEMA_MISS = /PGRST205|schema cache|does not exist|Could not find the table/i;
+export async function checkWritePath() {
+    try {
+        // No Supabase credentials → legitimate free tier; local writes are intended.
+        if (!isConfigured()) {
+            return { ok: true, mode: "local" };
+        }
+        // Credentials present but tier resolved to free. With SUPABASE_URL set, the
+        // only path to free tier is a missing/invalid license — so create_learning /
+        // create_decision are writing to local files instead of Supabase.
+        if (!hasSupabase()) {
+            console.error("\n\u26a0\ufe0f  [gitmem] WRITE PATH: Supabase is configured but the tier resolved to FREE.\n" +
+                "   create_learning / create_decision are writing to local .gitmem/ files, NOT Supabase.\n" +
+                "   Likely cause: a missing or invalid GITMEM_API_KEY \u2014 it must be a real gitmem_pro_... key,\n" +
+                "   present in the SAME environment as this server. Check the startup 'Tier:' line and the\n" +
+                "   device limit (3). Reads (recall, cache-health) can still reach Supabase, masking this.\n");
+            return { ok: false, mode: "free_with_credentials" };
+        }
+        // Pro/dev: probe the tables the write path actually resolves to. learnings
+        // and decisions hard-fail on a prefix/schema mismatch (threads fall back to
+        // local), so probing those two is sufficient and avoids column assumptions.
+        const prefix = getTablePrefix();
+        const prefixSource = process.env.GITMEM_TABLE_PREFIX ? "GITMEM_TABLE_PREFIX" : "default";
+        const missing = [];
+        for (const base of ["learnings", "decisions"]) {
+            const table = getTableName(base);
+            try {
+                await directQuery(table, { select: "id", limit: 1 });
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                if (SCHEMA_MISS.test(msg))
+                    missing.push(table);
+                // Transient network/auth errors are out of scope for this check.
+            }
+        }
+        if (missing.length > 0) {
+            console.error("\n\u26a0\ufe0f  [gitmem] WRITE PATH: these resolved tables do not exist on the Supabase backend:\n" +
+                `      ${missing.join(", ")}\n` +
+                `   Resolved table prefix: "${prefix}" (from ${prefixSource}).\n` +
+                "   create_learning / create_decision WILL FAIL until this is fixed:\n" +
+                "     - Pointing at an existing schema (e.g. orchestra_)? Set GITMEM_TABLE_PREFIX to match.\n" +
+                "     - Fresh project? Run `npx gitmem-mcp setup` (or set DATABASE_URL and re-activate) to create tables.\n");
+            return { ok: false, mode: "missing_tables", missing };
+        }
+        console.error(`[gitmem] Write-path OK (tier ${getTier()}, prefix "${prefix}", learnings/decisions present).`);
+        return { ok: true, mode: "supabase" };
+    }
+    catch (err) {
+        // The health check must never break startup. On any unexpected error, stay
+        // silent (don't false-alarm) rather than throw from a floated promise.
+        console.error(`[gitmem] Write-path check skipped: ${err instanceof Error ? err.message : String(err)}`);
+        return { ok: true, mode: "skipped" };
+    }
+}
+//# sourceMappingURL=write-health.js.map

package/dist/tools/archive-learning.d.ts

@@ -9,7 +9,7 @@
  * removed from in-memory search results.
  */
 export interface ArchiveLearningParams {
-    /** UUID of the learning to archive */
+    /** UUID or short ID prefix of the learning to archive */
     id: string;
     /** Optional reason for archiving */
     reason?: string;

package/dist/tools/archive-learning.js

@@ -8,16 +8,64 @@
  * Also triggers a local cache flush so the archived scar is immediately
  * removed from in-memory search results.
  */
-import { directPatch, isConfigured } from "../services/supabase-client.js";
+import { directPatch, directQuery, isConfigured } from "../services/supabase-client.js";
 import { hasSupabase, getTableName } from "../services/tier.js";
 import { getStorage } from "../services/storage.js";
 import { flushCache } from "../services/startup.js";
 import { Timer } from "../services/metrics.js";
 import { wrapDisplay } from "../services/display-protocol.js";
+const FULL_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const HEX_PREFIX_RE = /^[0-9a-f]{4,32}$/i;
+/**
+ * Resolve a short hex ID prefix to a full UUID.
+ * Git-style prefix resolution: accepts 4-32 char hex prefixes.
+ * Full UUIDs pass through unchanged.
+ */
+async function resolveIdPrefix(input) {
+    // Full UUID — pass through
+    if (FULL_UUID_RE.test(input)) {
+        return { id: input };
+    }
+    // Validate hex prefix format
+    if (!HEX_PREFIX_RE.test(input)) {
+        return { error: `Invalid ID format: "${input}". Provide a full UUID or a 4-32 char hex prefix.` };
+    }
+    const prefix = input.toLowerCase();
+    if (hasSupabase() && isConfigured()) {
+        // Supabase: use PostgREST like filter
+        const matches = await directQuery(getTableName("learnings"), {
+            select: "id",
+            filters: { id: `like.${prefix}%` },
+            limit: 2,
+        });
+        if (matches.length === 0) {
+            return { error: `No learning found with ID prefix "${prefix}"` };
+        }
+        if (matches.length > 1) {
+            const ids = matches.map(m => m.id.slice(0, 12) + "…").join(", ");
+            return { error: `Ambiguous prefix "${prefix}" — matches multiple learnings: ${ids}` };
+        }
+        return { id: matches[0].id };
+    }
+    else {
+        // Local storage: scan and filter
+        const storage = getStorage();
+        const all = await storage.query("learnings", {});
+        const matches = all.filter(r => r.id.toLowerCase().startsWith(prefix));
+        if (matches.length === 0) {
+            return { error: `No learning found with ID prefix "${prefix}"` };
+        }
+        if (matches.length > 1) {
+            const ids = matches.map(m => m.id.slice(0, 12) + "…").join(", ");
+            return { error: `Ambiguous prefix "${prefix}" — matches multiple learnings: ${ids}` };
+        }
+        return { id: matches[0].id };
+    }
+}
 export async function archiveLearning(params) {
     const timer = new Timer();
     if (!params.id || typeof params.id !== "string") {
-        const msg = "Missing required parameter: id (UUID of the learning to archive)";
+        const msg = "Missing required parameter: id (UUID or short ID prefix of the learning to archive)";
         return {
             success: false,
             id: "",
@@ -27,12 +75,25 @@ export async function archiveLearning(params) {
             performance_ms: timer.stop(),
         };
     }
+    // Resolve short prefix to full UUID
+    const resolved = await resolveIdPrefix(params.id);
+    if ("error" in resolved) {
+        return {
+            success: false,
+            id: params.id,
+            cache_flushed: false,
+            display: wrapDisplay(resolved.error),
+            error: resolved.error,
+            performance_ms: timer.stop(),
+        };
+    }
+    const resolvedId = resolved.id;
     try {
         const archivedAt = new Date().toISOString();
         let cacheFlushed = false;
         if (hasSupabase() && isConfigured()) {
             // Pro/dev: patch in Supabase
-            await directPatch(getTableName("learnings"), { id: `eq.${params.id}` }, {
+            await directPatch(getTableName("learnings"), { id: `eq.${resolvedId}` }, {
                 is_active: false,
                 archived_at: archivedAt,
             });
@@ -47,12 +108,12 @@ export async function archiveLearning(params) {
         else {
             // Free tier: update in local JSON
             const storage = getStorage();
-            const existing = await storage.get("learnings", params.id);
+            const existing = await storage.get("learnings", resolvedId);
             if (!existing) {
-                const msg = `Learning ${params.id} not found in local storage`;
+                const msg = `Learning ${resolvedId} not found in local storage`;
                 return {
                     success: false,
-                    id: params.id,
+                    id: resolvedId,
                     cache_flushed: false,
                     display: wrapDisplay(msg),
                     error: msg,
@@ -61,17 +122,21 @@ export async function archiveLearning(params) {
             }
             await storage.upsert("learnings", {
                 ...existing,
-                id: params.id,
+                id: resolvedId,
                 is_active: false,
                 archived_at: archivedAt,
             });
         }
         const latencyMs = timer.stop();
         const reasonText = params.reason ? ` Reason: ${params.reason}` : "";
-        const display = `Archived learning ${params.id}.${reasonText}\n(${latencyMs}ms)`;
+        // Show resolution when input differed from resolved ID
+        const idDisplay = params.id !== resolvedId
+            ? `${params.id} → ${resolvedId}`
+            : resolvedId;
+        const display = `Archived learning ${idDisplay}.${reasonText}\n(${latencyMs}ms)`;
         return {
             success: true,
-            id: params.id,
+            id: resolvedId,
             archived_at: archivedAt,
             reason: params.reason,
             cache_flushed: cacheFlushed,
@@ -84,7 +149,7 @@ export async function archiveLearning(params) {
         const latencyMs = timer.stop();
         return {
             success: false,
-            id: params.id,
+            id: resolvedId,
             cache_flushed: false,
             display: wrapDisplay(`Failed to archive learning: ${message}`),
             error: message,

package/dist/tools/definitions.js

@@ -2072,7 +2072,7 @@ export const TOOLS = [
             properties: {
                 id: {
                     type: "string",
-                    description: "UUID of the learning to archive",
+                    description: "UUID or short ID prefix of the learning to archive (e.g., the 8-char prefix shown by recall/search)",
                 },
                 reason: {
                     type: "string",
@@ -2090,7 +2090,7 @@ export const TOOLS = [
             properties: {
                 id: {
                     type: "string",
-                    description: "UUID of the learning to archive",
+                    description: "UUID or short ID prefix of the learning to archive (e.g., the 8-char prefix shown by recall/search)",
                 },
                 reason: {
                     type: "string",
@@ -2108,7 +2108,7 @@ export const TOOLS = [
             properties: {
                 id: {
                     type: "string",
-                    description: "UUID of the learning to archive",
+                    description: "UUID or short ID prefix of the learning to archive (e.g., the 8-char prefix shown by recall/search)",
                 },
                 reason: {
                     type: "string",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitmem-mcp",
-  "version": "1.6.1",
+  "version": "1.6.3",
   "mcpName": "io.github.gitmem-dev/gitmem",
   "description": "Persistent learning memory for AI coding agents. Memory that compounds.",
   "type": "module",