stackmem 1.0.0

package/README.md

@@ -0,0 +1,223 @@
+# coding-memory
+
+AI agents forget everything between sessions. Every new chat re-derives decisions, re-breaks constraints that were already settled, and re-debugs errors that were already fixed last week.
+
+coding-memory is a CLI and an MCP server that stores that context in Supabase and hands it back at the start of the next session. A git post-commit hook captures most of it automatically.
+
+## Install
+
+```
+git clone https://github.com/arushlagudu/coding-memory.git
+cd coding-memory
+npm install
+```
+
+Create `.env`:
+
+```
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
+```
+
+Build and link:
+
+```
+npm run build
+sudo npm link
+sudo npm install -g tsx
+```
+
+`cm` is now on your PATH. Install the hook in a project:
+
+```
+$ cd your-project-directory
+$ cm init myapp .
+coding-memory hook installed for project myapp at .
+```
+
+## Usage
+
+```
+cm start <project>
+cm save <project> <type> <content> [--force]
+cm fix <project> <problem> <solution>
+cm analyze <project> <path>
+cm search <project> <query>
+cm resolve <project> <memory-id>
+cm delete <project> <memory-id>
+cm context <project> <task>
+cm compress <project>
+cm init <project> <path>
+cm help
+```
+
+### cm start
+
+```
+$ cm start myapp
+Loaded 2 memory(ies) for "myapp".
+
+Decisions (1)
+-------------
+  [294fba3a-aef3-472a-933f-b6bfd41c7cfa] Use Supabase for persistence layer
+      linked: 793a0053-83b6-463a-9e6d-df8b7c2fbed8
+
+Constraints (1)
+---------------
+  [793a0053-83b6-463a-9e6d-df8b7c2fbed8] Service role key must never be exposed to a client
+      linked: 294fba3a-aef3-472a-933f-b6bfd41c7cfa
+```
+
+### cm save
+
+`type` is one of `decision`, `rejection`, `constraint`, `discovery`.
+
+```
+$ cm save myapp decision "Use ilike search across memories and execution_log"
+Saved decision [294fba3a-aef3-472a-933f-b6bfd41c7cfa] for "myapp".
+```
+
+If the new content contradicts something already stored, it asks first.
+
+```
+$ cm save myapp decision "We switched from Supabase to Postgres directly"
+Conflict detected:
+  Old: Use Supabase for persistence layer
+  New: We switched from Supabase to Postgres directly
+
+Keep old or replace? (k/r): r
+Replaced with new memory [b1a2c3d4-5678-90ab-cdef-1234567890ab].
+```
+
+`--force` skips the prompt and always replaces. Use it from scripts.
+
+```
+$ cm save myapp decision "We switched from Supabase to Postgres directly" --force
+Replaced with new memory [b1a2c3d4-5678-90ab-cdef-1234567890ab].
+Saved decision [b1a2c3d4-5678-90ab-cdef-1234567890ab] for "myapp".
+```
+
+### cm fix
+
+```
+$ cm fix myapp "tsc failed with Node16 module resolution error" "switched moduleResolution to Node16"
+Fix recorded for "myapp".
+```
+
+### cm analyze
+
+```
+$ cm analyze myapp .
+Indexed 7 file(s):
+  functions: 24
+  classes:   0
+```
+
+Runs tree-sitter over the project and writes an AST index to `.coding-memory/ast-index.db`.
+
+### cm search
+
+Checks memories and past fixes in the same query.
+
+```
+$ cm search myapp "module resolution"
+Memories (0)
+No results found
+
+Past Fixes (1)
+  Problem:  tsc failed with Node16 module resolution error
+  Solution: switched moduleResolution to Node16
+```
+
+### cm resolve / cm delete
+
+```
+$ cm resolve myapp 294fba3a-aef3-472a-933f-b6bfd41c7cfa
+Resolved memory [294fba3a-aef3-472a-933f-b6bfd41c7cfa]
+
+$ cm delete myapp 793a0053-83b6-463a-9e6d-df8b7c2fbed8
+Deleted memory [793a0053-83b6-463a-9e6d-df8b7c2fbed8]
+```
+
+`delete` also removes any memory_links pointing at that id.
+
+### cm context
+
+```
+$ cm context myapp "fix the module resolution error in the build"
+## Project Context: myapp
+### Task: fix the module resolution error in the build
+
+**Constraints**
+- Service role key must never be exposed to a client
+
+**Discoveries**
+- schema change: migrations/003_add_access_count.sql
+
+*(41/2000 tokens used)*
+```
+
+Top 5 memories relevant to a task, ranked by relevance and decay, capped at 2000 tokens. Feed this to an agent instead of the whole project's memory.
+
+### cm compress
+
+```
+$ cm compress myapp
+Compressed 4 memories into 1 summary
+Compressed 3 memories into 1 summary
+Compression complete. 2 clusters compressed.
+```
+
+Needs 20+ unresolved memories. Also runs automatically once a project crosses that count.
+
+### cm init
+
+```
+$ cm init myapp .
+coding-memory hook installed for project myapp at .
+```
+
+Installs a post-commit hook that calls `dist/cli.js save` after every commit with the commit message, plus whatever the diff turns up: removed imports, new env vars, new auth files, package.json changes, new config files, schema files, TODOs.
+
+### cm help
+
+```
+$ cm help
+cm — coding memory CLI
+
+  cm start <project>
+      Load all unresolved memories for a project, sorted by decay
+      score and capped at a 2000 token context budget.
+
+  cm save <project> <type> <content> [--force]
+      Save a new memory. Prompts before overwriting a contradiction
+      unless --force is passed.
+
+  ...
+```
+
+## How it works
+
+Memories are decisions, constraints, discoveries, and rejections, scoped to a project. Fixes are stored separately as a problem string and the solution that closed it, so the same tsc error doesn't cost another 20 minutes next month.
+
+Every save checks new content against existing memories with a containment score: shared terms over the size of the smaller set. Above 0.85 with no negation word, it's a duplicate and gets skipped. With a negation word like "switched" or "no longer" and a score above 0.4, it's a contradiction.
+
+cm save stops and asks whether to keep the old memory or replace it, unless `--force` is passed. The MCP `save_memory` tool always replaces automatically, since nothing is watching stdin on that path.
+
+New memories are also compared against everything else and linked above a lower threshold of 0.15. `cm start` and `cm context` show those links without any manual tagging.
+
+Relevance decays over time: `score = (1 + ln(1 + accessCount)) * exp(-0.05 * daysSinceCreated)`. Frequently accessed memories decay slower, but nothing survives forever. The 0.05 constant works out to roughly a 14-day half life.
+
+`cm start` and `cm context` cap output at 2000 tokens. They fill from the highest-ranked memory down until the next one would push past that limit.
+
+Past 20 unresolved memories, `cm compress` clusters related memories by containment score above 0.2 using union-find. Clusters of 3 or more collapse into a single summary memory.
+
+## Research
+
+Ideas taken from a few papers, not implementations of them.
+
+- Codebase-Memory: Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP (arXiv:2603.27277)
+- Feedback-Normalized Developer Memory for Reinforcement-Learning Coding Agents (arXiv:2605.01567)
+- A-MEM: Agentic Memory for LLM Agents (arXiv:2502.12110, NeurIPS 2025)
+- SWE-MeM: Learning Adaptive Memory Management for Long-Horizon Coding Agents (arXiv:2606.28434)
+- AtomMem: Learnable Dynamic Agentic Memory with Atomic Memory Operation (arXiv:2601.08323)

package/dist/ast-index.js

@@ -0,0 +1,272 @@
+import fs from "node:fs";
+import path from "node:path";
+import Database from "better-sqlite3";
+import Parser from "tree-sitter";
+import TreeSitterTypeScript from "tree-sitter-typescript";
+import TreeSitterJavaScript from "tree-sitter-javascript";
+const TypeScript = TreeSitterTypeScript.typescript;
+const SKIP_DIRS = new Set([
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    "out",
+    ".next",
+    ".turbo",
+    "coverage",
+    ".coding-memory",
+]);
+const FUNCTION_NODE_TYPES = new Set([
+    "function_declaration",
+    "function_expression",
+    "generator_function_declaration",
+    "generator_function",
+    "method_definition",
+]);
+function getDbPath(projectPath) {
+    return path.join(projectPath, ".coding-memory", "ast-index.db");
+}
+function openDb(projectPath) {
+    const dbDir = path.join(projectPath, ".coding-memory");
+    fs.mkdirSync(dbDir, { recursive: true });
+    const db = new Database(getDbPath(projectPath));
+    db.pragma("journal_mode = WAL");
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS files (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      file_path TEXT NOT NULL UNIQUE,
+      file_name TEXT NOT NULL,
+      indexed_at TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS functions (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      file_id INTEGER NOT NULL REFERENCES files(id) ON DELETE CASCADE,
+      name TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS classes (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      file_id INTEGER NOT NULL REFERENCES files(id) ON DELETE CASCADE,
+      name TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS imports (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      file_id INTEGER NOT NULL REFERENCES files(id) ON DELETE CASCADE,
+      source TEXT NOT NULL
+    );
+  `);
+    return db;
+}
+function walkProjectFiles(projectPath) {
+    const results = [];
+    function walk(dir) {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                if (SKIP_DIRS.has(entry.name))
+                    continue;
+                walk(path.join(dir, entry.name));
+            }
+            else if (entry.isFile()) {
+                if (/\.(ts|js)$/.test(entry.name) && !entry.name.endsWith(".d.ts")) {
+                    results.push(path.join(dir, entry.name));
+                }
+            }
+        }
+    }
+    walk(projectPath);
+    return results;
+}
+function nameOfNode(node) {
+    if (!node)
+        return null;
+    return node.text;
+}
+function extractIdentifierFromLhs(node) {
+    // For `const foo = () => {}` / `const foo = function () {}`, the
+    // enclosing variable_declarator's `name` field holds the identifier.
+    if (node.type === "identifier")
+        return node.text;
+    return null;
+}
+function extractFromSource(sourceCode, language) {
+    const parser = new Parser();
+    parser.setLanguage(language);
+    const tree = parser.parse(sourceCode);
+    const functions = [];
+    const classes = [];
+    const imports = [];
+    function visit(node) {
+        switch (node.type) {
+            case "function_declaration":
+            case "generator_function_declaration": {
+                const name = nameOfNode(node.childForFieldName("name"));
+                if (name)
+                    functions.push(name);
+                break;
+            }
+            case "method_definition": {
+                const name = nameOfNode(node.childForFieldName("name"));
+                if (name)
+                    functions.push(name);
+                break;
+            }
+            case "function_expression":
+            case "generator_function":
+            case "arrow_function": {
+                const declaredName = nameOfNode(node.childForFieldName("name"));
+                if (declaredName) {
+                    functions.push(declaredName);
+                }
+                else if (node.parent?.type === "variable_declarator") {
+                    const lhs = extractIdentifierFromLhs(node.parent.childForFieldName("name"));
+                    if (lhs)
+                        functions.push(lhs);
+                }
+                break;
+            }
+            case "class_declaration":
+            case "class": {
+                const name = nameOfNode(node.childForFieldName("name"));
+                if (name) {
+                    classes.push(name);
+                }
+                else if (node.parent?.type === "variable_declarator") {
+                    const lhs = extractIdentifierFromLhs(node.parent.childForFieldName("name"));
+                    if (lhs)
+                        classes.push(lhs);
+                }
+                break;
+            }
+            case "import_statement": {
+                const source = node.childForFieldName("source");
+                if (source)
+                    imports.push(source.text.replace(/^['"]|['"]$/g, ""));
+                break;
+            }
+            case "call_expression": {
+                const fn = node.childForFieldName("function");
+                if (fn?.type === "identifier" && fn.text === "require") {
+                    const args = node.childForFieldName("arguments");
+                    const firstArg = args?.namedChild(0);
+                    if (firstArg?.type === "string") {
+                        imports.push(firstArg.text.replace(/^['"]|['"]$/g, ""));
+                    }
+                }
+                break;
+            }
+        }
+        for (const child of node.namedChildren) {
+            visit(child);
+        }
+    }
+    visit(tree.rootNode);
+    return { functions, classes, imports };
+}
+function extractFile(filePath, projectPath) {
+    const sourceCode = fs.readFileSync(filePath, "utf-8");
+    const language = filePath.endsWith(".ts") ? TypeScript : TreeSitterJavaScript;
+    const { functions, classes, imports } = extractFromSource(sourceCode, language);
+    return {
+        relativePath: path.relative(projectPath, filePath),
+        functions,
+        classes,
+        imports,
+    };
+}
+export function analyzeCodebase(projectPath) {
+    const resolvedProjectPath = path.resolve(projectPath);
+    const db = openDb(resolvedProjectPath);
+    const insertFile = db.prepare("INSERT INTO files (file_path, file_name, indexed_at) VALUES (?, ?, ?) ON CONFLICT(file_path) DO UPDATE SET indexed_at = excluded.indexed_at RETURNING id");
+    const deleteChildren = db.prepare("DELETE FROM functions WHERE file_id = ?");
+    const deleteClasses = db.prepare("DELETE FROM classes WHERE file_id = ?");
+    const deleteImports = db.prepare("DELETE FROM imports WHERE file_id = ?");
+    const insertFunction = db.prepare("INSERT INTO functions (file_id, name) VALUES (?, ?)");
+    const insertClass = db.prepare("INSERT INTO classes (file_id, name) VALUES (?, ?)");
+    const insertImport = db.prepare("INSERT INTO imports (file_id, source) VALUES (?, ?)");
+    const files = walkProjectFiles(resolvedProjectPath);
+    let totalFunctions = 0;
+    let totalClasses = 0;
+    const runAll = db.transaction((filePaths) => {
+        for (const filePath of filePaths) {
+            const extraction = extractFile(filePath, resolvedProjectPath);
+            const row = insertFile.get(extraction.relativePath, path.basename(extraction.relativePath), new Date().toISOString());
+            const fileId = row.id;
+            deleteChildren.run(fileId);
+            deleteClasses.run(fileId);
+            deleteImports.run(fileId);
+            for (const name of extraction.functions) {
+                insertFunction.run(fileId, name);
+                totalFunctions++;
+            }
+            for (const name of extraction.classes) {
+                insertClass.run(fileId, name);
+                totalClasses++;
+            }
+            for (const source of extraction.imports) {
+                insertImport.run(fileId, source);
+            }
+        }
+    });
+    runAll(files);
+    db.close();
+    return {
+        files_indexed: files.length,
+        functions: totalFunctions,
+        classes: totalClasses,
+    };
+}
+function findFileRow(db, fileName) {
+    const exact = db
+        .prepare("SELECT id, file_path, file_name FROM files WHERE file_path = ?")
+        .get(fileName);
+    if (exact)
+        return exact;
+    return db
+        .prepare("SELECT id, file_path, file_name FROM files WHERE file_name = ?")
+        .get(path.basename(fileName));
+}
+export function getFileSummary(projectPath, fileName) {
+    const resolvedProjectPath = path.resolve(projectPath);
+    const dbPath = getDbPath(resolvedProjectPath);
+    if (!fs.existsSync(dbPath)) {
+        throw new Error(`No AST index found at ${dbPath}. Run analyze_codebase on this project first.`);
+    }
+    const db = new Database(dbPath, { readonly: true });
+    try {
+        const fileRow = findFileRow(db, fileName);
+        if (!fileRow) {
+            throw new Error(`File "${fileName}" not found in the AST index for ${resolvedProjectPath}.`);
+        }
+        const functions = db.prepare("SELECT name FROM functions WHERE file_id = ?").all(fileRow.id).map((r) => r.name);
+        const classes = db.prepare("SELECT name FROM classes WHERE file_id = ?").all(fileRow.id).map((r) => r.name);
+        return { file_path: fileRow.file_path, functions, classes };
+    }
+    finally {
+        db.close();
+    }
+}
+export function findDependencies(projectPath, fileName) {
+    const resolvedProjectPath = path.resolve(projectPath);
+    const dbPath = getDbPath(resolvedProjectPath);
+    if (!fs.existsSync(dbPath)) {
+        throw new Error(`No AST index found at ${dbPath}. Run analyze_codebase on this project first.`);
+    }
+    const db = new Database(dbPath, { readonly: true });
+    try {
+        const fileRow = findFileRow(db, fileName);
+        if (!fileRow) {
+            throw new Error(`File "${fileName}" not found in the AST index for ${resolvedProjectPath}.`);
+        }
+        const imports = db.prepare("SELECT source FROM imports WHERE file_id = ?").all(fileRow.id).map((r) => r.source);
+        return { file_path: fileRow.file_path, imports };
+    }
+    finally {
+        db.close();
+    }
+}