stackmem 1.0.25 → 1.0.27

package/src/config-file.ts

@@ -0,0 +1,98 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export const STACKMEM_CONFIG_FILENAME = ".stackmem.json";
+
+export interface StackmemConfig {
+  ignore: string[];
+  tokenBudget: number;
+  decayLambda: number;
+  captureTypes: string[];
+  minQualityScore: number;
+}
+
+export const DEFAULT_STACKMEM_CONFIG: StackmemConfig = {
+  ignore: [],
+  tokenBudget: 2000,
+  decayLambda: 0.05,
+  captureTypes: ["decision", "constraint", "discovery", "rejection"],
+  minQualityScore: 0.3,
+};
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+// Every field is independently optional — a partial or malformed
+// .stackmem.json falls back to the default for whichever fields it got
+// wrong, rather than failing the whole read.
+function mergeWithDefaults(parsed: unknown): StackmemConfig {
+  const raw = (parsed && typeof parsed === "object" ? parsed : {}) as Record<string, unknown>;
+
+  return {
+    ignore: isStringArray(raw.ignore) ? raw.ignore : DEFAULT_STACKMEM_CONFIG.ignore,
+    tokenBudget:
+      typeof raw.tokenBudget === "number" && raw.tokenBudget > 0
+        ? raw.tokenBudget
+        : DEFAULT_STACKMEM_CONFIG.tokenBudget,
+    decayLambda:
+      typeof raw.decayLambda === "number" && raw.decayLambda > 0
+        ? raw.decayLambda
+        : DEFAULT_STACKMEM_CONFIG.decayLambda,
+    captureTypes: isStringArray(raw.captureTypes) ? raw.captureTypes : DEFAULT_STACKMEM_CONFIG.captureTypes,
+    minQualityScore:
+      typeof raw.minQualityScore === "number"
+        ? raw.minQualityScore
+        : DEFAULT_STACKMEM_CONFIG.minQualityScore,
+  };
+}
+
+// Reads .stackmem.json from `projectRoot` (defaulting to cwd). Missing
+// file, unreadable file, or invalid JSON all fall back to defaults
+// silently — a config file is an optimization, never a hard requirement.
+export function readStackmemConfig(projectRoot: string = process.cwd()): StackmemConfig {
+  const configPath = path.join(projectRoot, STACKMEM_CONFIG_FILENAME);
+
+  if (!fs.existsSync(configPath)) {
+    return { ...DEFAULT_STACKMEM_CONFIG };
+  }
+
+  try {
+    const parsed = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    return mergeWithDefaults(parsed);
+  } catch {
+    return { ...DEFAULT_STACKMEM_CONFIG };
+  }
+}
+
+export function defaultConfigFileContents(): string {
+  return JSON.stringify(DEFAULT_STACKMEM_CONFIG, null, 2) + "\n";
+}
+
+// Minimal glob support for the `ignore` list: a trailing "/" matches a
+// directory name anywhere in the path (like "dist/" already does
+// elsewhere in the hook's own skip list); "*" matches any run of
+// characters. Everything else is an exact match against the basename or
+// full path. Deliberately not a real glob engine — just enough for the
+// documented ignore patterns ("dist/", "migrations/", "*.generated.*").
+export function matchesIgnorePattern(filePath: string, pattern: string): boolean {
+  const baseName = filePath.split("/").pop() ?? filePath;
+
+  if (pattern.endsWith("/")) {
+    const dirName = pattern.slice(0, -1);
+    return filePath.split("/").includes(dirName);
+  }
+
+  if (pattern.includes("*")) {
+    const regex = new RegExp(
+      "^" + pattern.split("*").map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*") + "$"
+    );
+    return regex.test(baseName) || regex.test(filePath);
+  }
+
+  return filePath === pattern || baseName === pattern;
+}
+
+export function isIgnoredByConfig(filePath: string, config: StackmemConfig): boolean {
+  return config.ignore.some((pattern) => matchesIgnorePattern(filePath, pattern));
+}

package/src/index.ts

@@ -16,6 +16,8 @@ import {
   isAuthRelatedFile,
   isCodeFile,
   isQualityMessage,
+  parseUtcDate,
+  redactSecrets,
 } from "./scoring.js";
 import { supabase } from "./storage.js";
 
@@ -43,7 +45,8 @@ server.registerTool(
       .from("memories")
       .select("*")
       .eq("project", project)
-      .eq("resolved", false);
+      .eq("resolved", false)
+      .eq("suggested", false);
 
     if (error) {
       throw new Error(`Failed to load memories: ${error.message}`);
@@ -54,7 +57,7 @@ server.registerTool(
     const scoredMemories = memories
       .map((memory) => ({
         ...memory,
-        decay_score: computeDecayScore(new Date(memory.created_at), memory.access_count ?? 0),
+        decay_score: computeDecayScore(parseUtcDate(memory.created_at), memory.access_count ?? 0, memory.pinned ?? false),
       }))
       .sort((a, b) => b.decay_score - a.decay_score);
 
@@ -158,7 +161,8 @@ async function compressMemories(
     .from("memories")
     .select("*")
     .eq("project", project)
-    .eq("resolved", false);
+    .eq("resolved", false)
+    .eq("suggested", false);
 
   if (error) {
     throw new Error(`Failed to load memories for compression: ${error.message}`);
@@ -224,6 +228,8 @@ server.registerTool(
     },
   },
   async ({ project, type, content }) => {
+    content = redactSecrets(content);
+
     const { data: existingRows, error: existingError } = await supabase
       .from("memories")
       .select("id, content")
@@ -261,7 +267,7 @@ server.registerTool(
 
     const { data: inserted, error } = await supabase
       .from("memories")
-      .insert({ project, type, content, device_id: getDeviceId() })
+      .insert({ project, type, content, device_id: getDeviceId(), source: "mcp" })
       .select("id")
       .single();
 

package/src/scoring.ts

@@ -73,7 +73,9 @@ function trigramSet(text: string): Set<string> {
 // similarity (typos, partial substrings, shared phrasing) that word-based
 // containment misses entirely, since containment only ever compares whole
 // extracted entities.
-function ngramOverlap(a: string, b: string): number {
+// Exported for direct unit testing (src/tests/scoring.test.ts) — hybridScore
+// is the only production caller.
+export function ngramOverlap(a: string, b: string): number {
   const trigramsA = trigramSet(a);
   const trigramsB = trigramSet(b);
   const union = new Set([...trigramsA, ...trigramsB]);
@@ -145,7 +147,9 @@ const NEGATION_WORDS = [
   "deprecated", "reverted", "changed",
 ];
 
-function containsNegationWord(text: string): boolean {
+// Exported for direct unit testing (src/tests/scoring.test.ts) — decideSaveAction
+// is the only production caller.
+export function containsNegationWord(text: string): boolean {
   const lower = text.toLowerCase();
   return NEGATION_WORDS.some((word) => lower.includes(word));
 }
@@ -201,14 +205,40 @@ export function decideSaveAction(
 
 // --- memory decay --------------------------------------------------------
 
+// Supabase/PostgREST sometimes returns a timestamptz column without an
+// explicit UTC suffix (e.g. "2026-10-26T00:36:16.36535" — no "Z" or
+// offset — even though the underlying value is UTC). The bare `new
+// Date(...)` constructor then parses that as LOCAL time, silently
+// shifting every timestamp by the machine's UTC offset — several hours
+// of error on every decay score, and a negative "N seconds ago" for
+// anything created in roughly the last half-day. Normalize first.
+export function parseUtcDate(dateString: string): Date {
+  const hasTimezone = /[Zz]$|[+-]\d{2}:?\d{2}$/.test(dateString);
+  return new Date(hasTimezone ? dateString : `${dateString}Z`);
+}
+
 // Decay constant tuned for a ~14-day half-life: exp(-0.05 * 14) ≈ 0.5.
-const DECAY_LAMBDA = 0.05;
+// Overridable per-project via .stackmem.json's decayLambda (src/config-file.ts).
+export const DEFAULT_DECAY_LAMBDA = 0.05;
+
+// A pinned memory always sorts first and never decays — 999 is well above
+// any value the exponential formula below can produce, so ranking by this
+// score alone puts every pinned memory ahead of every unpinned one.
+const PINNED_SCORE = 999;
 
 // Recency-weighted relevance: frequently-accessed memories decay slower,
-// but every memory still fades over time regardless of access count.
-export function computeDecayScore(createdAt: Date, accessCount: number): number {
+// but every memory still fades over time regardless of access count —
+// unless pinned.
+export function computeDecayScore(
+  createdAt: Date,
+  accessCount: number,
+  pinned = false,
+  lambda = DEFAULT_DECAY_LAMBDA
+): number {
+  if (pinned) return PINNED_SCORE;
+
   const daysSinceCreated = (Date.now() - createdAt.getTime()) / (1000 * 60 * 60 * 24);
-  return (1 + Math.log(1 + accessCount)) * Math.exp(-DECAY_LAMBDA * daysSinceCreated);
+  return (1 + Math.log(1 + accessCount)) * Math.exp(-lambda * daysSinceCreated);
 }
 
 // --- context budget ------------------------------------------------------
@@ -485,4 +515,30 @@ export function scoreMemoryRelevance(memoryContent: string, task: string): numbe
 
   return structuralScore * 0.7 + wordOverlapRatio * 0.3;
 }
+
+// --- task-aware ranking signals (branch name / PR title overlap) -----------
+
+const TOKEN_SPLIT_RE = /[^a-zA-Z0-9]+/;
+const MIN_TOKEN_LENGTH = 3;
+
+// Branch names and PR titles use "/", "-", "_" as word separators (e.g.
+// "feature/stripe-webhook-retry"), unlike prose content — splitWords above
+// only splits on whitespace, so it can't tokenize these the same way.
+export function tokenize(text: string): Set<string> {
+  const tokens = new Set<string>();
+  for (const word of text.toLowerCase().split(TOKEN_SPLIT_RE)) {
+    if (word.length >= MIN_TOKEN_LENGTH && !STOP_WORDS.has(word)) {
+      tokens.add(word);
+    }
+  }
+  return tokens;
+}
+
+export function hasTokenOverlap(a: Set<string>, b: Set<string>): boolean {
+  for (const token of a) {
+    if (b.has(token)) return true;
+  }
+  return false;
+}
+
 // TODO: optimize the clustering algorithm

package/src/storage.ts

@@ -27,7 +27,7 @@ import { createClient, type SupabaseClient } from "@supabase/supabase-js";
 import { SUPABASE_ANON_KEY, SUPABASE_URL } from "./config.js";
 import { getDeviceId } from "./device.js";
 
-export const supabase: SupabaseClient = createClient(SUPABASE_URL, SUPABASE_ANON_KEY, {
+const rawSupabase: SupabaseClient = createClient(SUPABASE_URL, SUPABASE_ANON_KEY, {
   global: {
     headers: {
       "x-device-id": getDeviceId(),
@@ -35,6 +35,106 @@ export const supabase: SupabaseClient = createClient(SUPABASE_URL, SUPABASE_ANON
   },
 });
 
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// maxAttempts counts RETRIES, not total tries — the default (3 retries,
+// 500ms base) produces exactly the 500ms / 1000ms / 2000ms backoff
+// sequence across 4 total tries (1 initial + 3 retries).
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  maxAttempts = 3,
+  baseDelayMs = 500
+): Promise<T> {
+  let lastError: unknown;
+
+  for (let attempt = 0; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      if (attempt === maxAttempts) break;
+
+      const delayMs = baseDelayMs * 2 ** attempt;
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(
+        `Supabase request failed (retry ${attempt + 1}/${maxAttempts} in ${delayMs}ms): ${message}`
+      );
+      await sleep(delayMs);
+    }
+  }
+
+  throw lastError;
+}
+
+// A 4xx response (bad request, not found, RLS denial) is a logic error —
+// retrying it wastes time and can't succeed. status 0 (the fetch itself
+// failed: DNS, connection refused, timeout) and 5xx (transient server
+// errors) are the cases retrying can actually help with.
+function isRetryableStatus(status: number): boolean {
+  return status === 0 || status >= 500;
+}
+
+// Supabase/postgrest query results RESOLVE with { data, error, status }
+// even on failure — they don't reject — so a plain try/catch around the
+// call never sees a 5xx or network failure to retry. This wraps every
+// query builder returned from `.from(...)` so that a retryable result
+// is converted into a throw (for withRetry's catch to see), while a
+// success or a non-retryable 4xx result still resolves normally, exactly
+// as every existing `const { data, error } = await supabase.from(...)...`
+// call site already expects — no call site elsewhere needs to change.
+function wrapWithRetry<T>(target: T): T {
+  if (target === null || typeof target !== "object") return target;
+
+  return new Proxy(target as object, {
+    get(obj: any, prop, receiver) {
+      if (prop === "then") {
+        return (onFulfilled?: unknown, onRejected?: unknown) => {
+          const attempt = () =>
+            new Promise((resolve, reject) => {
+              obj.then(
+                (result: any) => {
+                  if (result && result.error && isRetryableStatus(result.status)) {
+                    const err = new Error(
+                      `Supabase request failed (status ${result.status}): ${result.error.message}`
+                    );
+                    (err as any).status = result.status;
+                    (err as any).supabaseError = result.error;
+                    reject(err);
+                  } else {
+                    resolve(result);
+                  }
+                },
+                (err: unknown) => reject(err)
+              );
+            });
+
+          return withRetry(attempt).then(
+            onFulfilled as ((value: unknown) => unknown) | undefined,
+            onRejected as ((reason: unknown) => unknown) | undefined
+          );
+        };
+      }
+
+      const value = Reflect.get(obj, prop, receiver);
+      if (typeof value === "function") {
+        return (...args: unknown[]) => wrapWithRetry(value.apply(obj, args));
+      }
+      return value;
+    },
+  }) as T;
+}
+
+export const supabase: SupabaseClient = new Proxy(rawSupabase, {
+  get(obj, prop, receiver) {
+    if (prop === "from") {
+      return (...args: unknown[]) => wrapWithRetry((obj.from as (...a: unknown[]) => unknown)(...args));
+    }
+    return Reflect.get(obj, prop, receiver);
+  },
+}) as SupabaseClient;
+
 // Run this migration in the Supabase SQL editor to add the access_count
 // column used by the memory decay scoring in src/scoring.ts (computeDecayScore)
 // and consumed by cm start / session_start in src/cli.ts and src/index.ts.

package/src/tests/crud.test.ts

@@ -0,0 +1,110 @@
+// CRUD-behavior tests. Tests 1-3 are pure (decideSaveAction, no network).
+// Tests 4-6 exercise the real Supabase backend via the compiled CLI,
+// matching src/tests/regression.test.ts's convention — using a dedicated
+// throwaway project cleaned up in `after()` regardless of pass/fail.
+import { test, after } from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+
+import { decideSaveAction } from "../scoring.js";
+import { supabase } from "../storage.js";
+
+const CLI_PATH = path.join(import.meta.dirname, "..", "..", "dist", "cli.js");
+const CRUD_TEST_PROJECT = "crud-test-temp";
+
+function runCli(args: string[]): string {
+  return execFileSync(process.execPath, [CLI_PATH, ...args], { encoding: "utf-8" });
+}
+
+// 1. decideSaveAction returns "duplicate" ("skip", in the task's wording)
+// for near-identical content.
+test('decideSaveAction returns "duplicate" for near-identical content', () => {
+  const existing = [{ id: "mem-1", content: "add stripe webhook signature verification" }];
+  const decision = decideSaveAction("add stripe webhook signature verification", existing);
+  assert.equal(decision.action, "duplicate");
+});
+
+// 2. decideSaveAction returns "superseded" ("replace", in the task's
+// wording) for contradicting content.
+test('decideSaveAction returns "superseded" for contradicting content', () => {
+  const existing = [{ id: "mem-1", content: "use redis for session storage" }];
+  const decision = decideSaveAction("we switched from redis to postgres for session storage", existing);
+  assert.equal(decision.action, "superseded");
+});
+
+// 3. decideSaveAction returns "created" ("create", in the task's wording)
+// for genuinely new content.
+test('decideSaveAction returns "created" for genuinely new content', () => {
+  const existing = [{ id: "mem-1", content: "use redis for session storage" }];
+  const decision = decideSaveAction("add rate limiting to the public api gateway", existing);
+  assert.equal(decision.action, "created");
+});
+
+after(async () => {
+  const { data: mem } = await supabase.from("memories").select("id").eq("project", CRUD_TEST_PROJECT);
+  const ids = (mem ?? []).map((m: { id: string }) => m.id);
+  if (ids.length > 0) {
+    const idList = ids.join(",");
+    await supabase.from("memory_links").delete().or(`source_id.in.(${idList}),target_id.in.(${idList})`);
+  }
+  await supabase.from("memories").delete().eq("project", CRUD_TEST_PROJECT);
+});
+
+// 4. A duplicate commit_sha is recognized by the check-commit guard
+// (src/cli.ts cmdCheckCommit) rather than producing a second memory for
+// the same commit — this is the actual mechanism behind "saving a memory
+// with a duplicate commit_sha doesn't create a new one": the hook calls
+// `cm check-commit` once per invocation and skips its entire capture
+// pass if it reports the commit_sha already has a memory, rather than
+// cmdSave de-duplicating per individual save. Exit code is inverted:
+// 0 = not seen yet (proceed), 1 = already has a memory (duplicate, skip).
+test("check-commit: fresh sha allowed, then blocked once a memory exists for it", () => {
+  const sha = `test-sha-${Date.now()}-fresh`;
+
+  // No memory for this sha yet — check-commit should exit 0 (allowed).
+  runCli(["check-commit", CRUD_TEST_PROJECT, sha]);
+
+  // Save a memory tagged with that sha.
+  runCli(["save", CRUD_TEST_PROJECT, "decision", "duplicate commit_sha guard test", "--force", "--commit-sha", sha]);
+
+  // Now the same sha must be blocked (non-zero exit = duplicate).
+  assert.throws(() => runCli(["check-commit", CRUD_TEST_PROJECT, sha]));
+});
+
+// 5. cm pin sets pinned=true.
+test("cm pin sets pinned=true on the target memory", async () => {
+  runCli(["save", CRUD_TEST_PROJECT, "decision", "memory to be pinned in crud test", "--force"]);
+  const { data } = await supabase
+    .from("memories")
+    .select("id")
+    .eq("project", CRUD_TEST_PROJECT)
+    .eq("content", "memory to be pinned in crud test")
+    .single();
+  assert.ok(data);
+
+  runCli(["pin", CRUD_TEST_PROJECT, data.id]);
+
+  const { data: after_ } = await supabase.from("memories").select("pinned").eq("id", data.id).single();
+  assert.ok(after_);
+  assert.equal(after_.pinned, true);
+});
+
+// 6. cm unpin sets pinned=false.
+test("cm unpin sets pinned=false on the target memory", async () => {
+  runCli(["save", CRUD_TEST_PROJECT, "decision", "memory to be unpinned in crud test", "--force"]);
+  const { data } = await supabase
+    .from("memories")
+    .select("id")
+    .eq("project", CRUD_TEST_PROJECT)
+    .eq("content", "memory to be unpinned in crud test")
+    .single();
+  assert.ok(data);
+
+  runCli(["pin", CRUD_TEST_PROJECT, data.id]);
+  runCli(["unpin", CRUD_TEST_PROJECT, data.id]);
+
+  const { data: after_ } = await supabase.from("memories").select("pinned").eq("id", data.id).single();
+  assert.ok(after_);
+  assert.equal(after_.pinned, false);
+});