stackmem 1.0.25 → 1.0.27

package/dist/config-file.js

@@ -0,0 +1,72 @@
+import fs from "node:fs";
+import path from "node:path";
+export const STACKMEM_CONFIG_FILENAME = ".stackmem.json";
+export const DEFAULT_STACKMEM_CONFIG = {
+    ignore: [],
+    tokenBudget: 2000,
+    decayLambda: 0.05,
+    captureTypes: ["decision", "constraint", "discovery", "rejection"],
+    minQualityScore: 0.3,
+};
+function isStringArray(value) {
+    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) {
+    const raw = (parsed && typeof parsed === "object" ? parsed : {});
+    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 = process.cwd()) {
+    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() {
+    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, pattern) {
+    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, config) {
+    return config.ignore.some((pattern) => matchesIgnorePattern(filePath, pattern));
+}

package/dist/index.js

@@ -4,7 +4,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { analyzeCodebase, getFileSummary, findDependencies } from "./ast-index.js";
 import { getDeviceId } from "./device.js";
-import { applyContextBudget, buildSummaryContent, clusterMemories, computeDecayScore, computeMemoryLinks, decideSaveAction, estimateTokens, indicatesFailedApproach, isAuthRelatedFile, isCodeFile, isQualityMessage, } from "./scoring.js";
+import { applyContextBudget, buildSummaryContent, clusterMemories, computeDecayScore, computeMemoryLinks, decideSaveAction, estimateTokens, indicatesFailedApproach, isAuthRelatedFile, isCodeFile, isQualityMessage, parseUtcDate, redactSecrets, } from "./scoring.js";
 import { supabase } from "./storage.js";
 const CONTEXT_BUDGET_TOKENS = 2000;
 const COMPRESSION_THRESHOLD = 20;
@@ -24,7 +24,8 @@ server.registerTool("session_start", {
         .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}`);
     }
@@ -32,7 +33,7 @@ server.registerTool("session_start", {
     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);
     const budgetedMemories = applyContextBudget(scoredMemories, CONTEXT_BUDGET_TOKENS);
@@ -112,7 +113,8 @@ async function compressMemories(project) {
         .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}`);
     }
@@ -162,6 +164,7 @@ server.registerTool("save_memory", {
         content: z.string().describe("The memory content to save"),
     },
 }, async ({ project, type, content }) => {
+    content = redactSecrets(content);
     const { data: existingRows, error: existingError } = await supabase
         .from("memories")
         .select("id, content")
@@ -193,7 +196,7 @@ server.registerTool("save_memory", {
     }
     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();
     if (error || !inserted) {

package/dist/scoring.js

@@ -65,7 +65,9 @@ function trigramSet(text) {
 // similarity (typos, partial substrings, shared phrasing) that word-based
 // containment misses entirely, since containment only ever compares whole
 // extracted entities.
-function ngramOverlap(a, b) {
+// Exported for direct unit testing (src/tests/scoring.test.ts) — hybridScore
+// is the only production caller.
+export function ngramOverlap(a, b) {
     const trigramsA = trigramSet(a);
     const trigramsB = trigramSet(b);
     const union = new Set([...trigramsA, ...trigramsB]);
@@ -114,7 +116,9 @@ const NEGATION_WORDS = [
     "switched", "removed", "replaced", "no longer", "instead",
     "deprecated", "reverted", "changed",
 ];
-function containsNegationWord(text) {
+// Exported for direct unit testing (src/tests/scoring.test.ts) — decideSaveAction
+// is the only production caller.
+export function containsNegationWord(text) {
     const lower = text.toLowerCase();
     return NEGATION_WORDS.some((word) => lower.includes(word));
 }
@@ -159,13 +163,32 @@ export function decideSaveAction(newContent, existingMemories) {
     return { action: "created" };
 }
 // --- 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) {
+    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, accessCount) {
+// but every memory still fades over time regardless of access count —
+// unless pinned.
+export function computeDecayScore(createdAt, accessCount, pinned = false, lambda = DEFAULT_DECAY_LAMBDA) {
+    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 ------------------------------------------------------
 // Rough token estimate: ~4 characters per token.
@@ -401,4 +424,26 @@ export function scoreMemoryRelevance(memoryContent, task) {
     const wordOverlapRatio = taskWords.length === 0 ? 0 : shared / taskWords.length;
     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) {
+    const tokens = new Set();
+    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, b) {
+    for (const token of a) {
+        if (b.has(token))
+            return true;
+    }
+    return false;
+}
 // TODO: optimize the clustering algorithm

package/dist/storage.js

@@ -25,13 +25,91 @@
 import { createClient } from "@supabase/supabase-js";
 import { SUPABASE_ANON_KEY, SUPABASE_URL } from "./config.js";
 import { getDeviceId } from "./device.js";
-export const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY, {
+const rawSupabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY, {
     global: {
         headers: {
             "x-device-id": getDeviceId(),
         },
     },
 });
+function sleep(ms) {
+    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(fn, maxAttempts = 3, baseDelayMs = 500) {
+    let lastError;
+    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) {
+    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(target) {
+    if (target === null || typeof target !== "object")
+        return target;
+    return new Proxy(target, {
+        get(obj, prop, receiver) {
+            if (prop === "then") {
+                return (onFulfilled, onRejected) => {
+                    const attempt = () => new Promise((resolve, reject) => {
+                        obj.then((result) => {
+                            if (result && result.error && isRetryableStatus(result.status)) {
+                                const err = new Error(`Supabase request failed (status ${result.status}): ${result.error.message}`);
+                                err.status = result.status;
+                                err.supabaseError = result.error;
+                                reject(err);
+                            }
+                            else {
+                                resolve(result);
+                            }
+                        }, (err) => reject(err));
+                    });
+                    return withRetry(attempt).then(onFulfilled, onRejected);
+                };
+            }
+            const value = Reflect.get(obj, prop, receiver);
+            if (typeof value === "function") {
+                return (...args) => wrapWithRetry(value.apply(obj, args));
+            }
+            return value;
+        },
+    });
+}
+export const supabase = new Proxy(rawSupabase, {
+    get(obj, prop, receiver) {
+        if (prop === "from") {
+            return (...args) => wrapWithRetry(obj.from(...args));
+        }
+        return Reflect.get(obj, prop, receiver);
+    },
+});
 // 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/dist/tests/crud.test.js

@@ -0,0 +1,93 @@
+// 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) {
+    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) => 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);
+});