stackmem 1.0.21 → 1.0.22

package/README.md

@@ -1,8 +1,10 @@
 # stackmem
 
-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.
+Persistent memory for AI coding agents. Zero config. Installs in 60 seconds.
 
-stackmem 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.
+## The problem
+
+Every session with an AI coding agent starts from zero. You re-explain the same stack, the same constraints, the same "we tried that and it didn't work" — and the agent repeats mistakes it already made last week, because nothing it learned last session survived the chat closing.
 
 ## Install
 
@@ -10,196 +12,116 @@ stackmem is a CLI and an MCP server that stores that context in Supabase and han
 npm install -g stackmem
 ```
 
-Then in any git repo:
-
-```
-cm init <project> .
-```
-
-`cm init <project> .` does three things automatically:
-
-1. Installs a git post-commit hook
-2. Registers the stackmem MCP server with Claude Code
-3. Writes a CLAUDE.md to the project
-
-After that, memories load automatically when you open Claude Code and save automatically on every commit. No further setup needed.
-
-## 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
+## Setup
 
 ```
-$ cm analyze myapp .
-Indexed 7 file(s):
-  functions: 24
-  classes:   0
+cd myproject
+cm init myapp .
 ```
 
-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
+✓ .gitignore created
+✓ Git hook installed
+✓ MCP server registered
+✓ CLAUDE.md written
+✓ .cursorrules written
+✓ .windsurfrules written
+✓ Seeded 2 memories from project scan
+✓ Backend connection verified
 
-Past Fixes (1)
-  Problem:  tsc failed with Node16 module resolution error
-  Solution: switched moduleResolution to Node16
+stackmem is live. Open Claude Code and ask "what do you know about this project?" to verify.
 ```
 
-### cm resolve / cm delete
+That's it. Open Claude Code and ask "what do you know about this project?" to verify.
 
-```
-$ cm resolve myapp 294fba3a-aef3-472a-933f-b6bfd41c7cfa
-Resolved memory [294fba3a-aef3-472a-933f-b6bfd41c7cfa]
+## How it works
 
-$ cm delete myapp 793a0053-83b6-463a-9e6d-df8b7c2fbed8
-Deleted memory [793a0053-83b6-463a-9e6d-df8b7c2fbed8]
-```
+Four layers, each feeding the next:
 
-`delete` also removes any memory_links pointing at that id.
+- **Capture** — a git post-commit hook saves memories automatically on every commit: removed dependencies, new config files, auth-related files, TODOs, schema changes, and the commit message itself when it's substantive. No manual annotation. **97.9% automation rate** across stackmem's own real development history.
+- **Semantic organization** — hybrid containment-trigram scoring deduplicates new memories against existing ones, links related memories bidirectionally, and resolves contradictions ("we switched from X to Y") automatically.
+- **Temporal ranking** — an exponential decay score ranks memories by recency and access frequency, then a 2000-token budget decides what actually gets injected.
+- **Delivery** — an MCP server, an 18-command CLI, and the Memory Vault web dashboard all read from the same store and deliver it back into every new session.
 
-### cm context
+## Claude Code (automatic)
 
-```
-$ cm context myapp "fix the module resolution error in the build"
-## Project Context: myapp
-### Task: fix the module resolution error in the build
+`cm init` registers the stackmem MCP server in `~/.claude.json`. Memories load automatically at the start of every session — nothing to configure, nothing to remember to run.
 
-**Constraints**
-- Service role key must never be exposed to a client
+## Cursor and Windsurf (automatic)
 
-**Discoveries**
-- schema change: migrations/003_add_access_count.sql
+`cm init` writes `.cursorrules` and `.windsurfrules` directly from your project's live memories, and the git hook keeps them current — `cm sync` regenerates and commits both files automatically after every push. You never have to remember to refresh them by hand.
 
-*(41/2000 tokens used)*
 ```
+# stackmem — project memory (auto-updated)
+## Project: myapp
 
-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.
+### Constraints
+- required env vars: DATABASE_URL, API_KEY
 
-### cm compress
+### Discoveries
+- tech stack: express
 
-```
-$ cm compress myapp
-Compressed 4 memories into 1 summary
-Compressed 3 memories into 1 summary
-Compression complete. 2 clusters compressed.
+---
+*Last updated: 10/13/2026, 5:37:45 PM*
+*Run `cm start` for full details with decay scores*
 ```
 
-Needs 20+ unresolved memories. Also runs automatically once a project crosses that count.
+## CLI commands (all 18)
 
-### cm init
+| Command | Description |
+|---|---|
+| `cm start [project]` | Load all unresolved memories, decay-ranked and budget-capped, grouped by type with linked memory ids. |
+| `cm save [project] <type> <content>` | Save a new memory (`decision`, `constraint`, `discovery`, or `rejection`). Links to related memories automatically; prompts on contradiction unless `--force`. |
+| `cm fix [project] <problem> <solution>` | Record a problem and its solution for future reference. |
+| `cm analyze [project] <path>` | Build a Tree-Sitter AST index (files, functions, classes) for the codebase. |
+| `cm search [--project <name>] <query>` | Search memories and past fixes for a project matching a query. |
+| `cm resolve [project] <memory-id>` | Mark a memory as resolved. |
+| `cm delete [project] <memory-id>` | Delete a memory and any links referencing it. |
+| `cm inspect [project] <memory-id>` | Show a single memory's full detail: type, content, decay score, access count, linked memories, and related fixes. |
+| `cm compress [project]` | Cluster related memories (needs 20+) and collapse clusters of 3+ into a summary memory. |
+| `cm init <project> <path>` | Install the git hook, register the MCP server, seed memories from the project scan, and write `.gitignore`, `CLAUDE.md`, `.cursorrules`, and `.windsurfrules`. |
+| `cm sync` | Regenerate `.cursorrules` and `.windsurfrules` from current memories and recent fixes. |
+| `cm context [--project <name>] <task>` | Return the top 5 memories most relevant to a specific task, capped at 2000 tokens. |
+| `cm session-end [project]` | Capture what happened in a session and extract memories, errors, and rejected approaches. |
+| `cm doctor` | Check every integration point — backend, MCP registration, `.stackmem`, git hook, memory count — and report what's broken. |
+| `cm undo [project]` | Delete the most recently saved unresolved memory. |
+| `cm export [filename]` | Export all unresolved memories, fixes, and links to a JSON file. |
+| `cm import [project] <filename>` | Import memories and fixes from a file produced by `cm export`. |
+| `cm help` | Show the full help message. |
 
-```
-$ cm init myapp .
-coding-memory hook installed for project myapp at .
-```
+## The Memory Vault
 
-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.
+`stackmem-vault.vercel.app`
 
-### cm help
+Sign in with GitHub. View every project you track, each with its memory count and last activity. Four tabs per project: **Memories** (typed, with decay scores and resolve/delete actions), **Fixes** (problem/solution pairs), **Graph** (a D3.js force-directed view of your actual knowledge network — nodes are memories, edges are semantic links), and **Timeline** (every memory chronologically, including resolved ones). A global search bar queries memories and fixes across every project at once.
 
-```
-$ cm help
-cm — coding memory CLI
+## How memory works
 
-  cm start <project>
-      Load all unresolved memories for a project, sorted by decay
-      score and capped at a 2000 token context budget.
+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 error doesn't cost another 20 minutes next month.
 
-  cm save <project> <type> <content> [--force]
-      Save a new memory. Prompts before overwriting a contradiction
-      unless --force is passed.
+Every save checks new content against existing memories with a **hybrid score**: 0.7 × entity containment (shared terms over the size of the smaller set) + 0.3 × character-trigram Jaccard overlap. The trigram component catches lexical near-misses that containment alone can't — e.g. `"removed dependency: node:path"` vs `"removed dependency: node:url"`, which share identical entity sets but diverge in the actual package name. 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.
 
-  ...
-```
-
-## How it works
+`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.
 
-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.
+New memories are also compared against everything else and linked above a lower threshold of 0.15, using the same hybrid score. `cm start` and `cm context` show those links without any manual tagging.
 
-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.
+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 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.
+`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.
 
-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.
+Past 20 unresolved memories, `cm compress` clusters related memories by hybrid score above 0.2 using union-find. Clusters of 3 or more collapse into a single summary memory.
 
-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.
+## Benchmark results
 
-`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.
+Measured against stackmem's own real production data — not synthetic fixtures.
 
-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.
+| Metric | Result |
+|---|---|
+| Token reduction vs. full codebase dump | 99.4% (36,579 → 226 tokens) |
+| Duplicate detection F1 | 0.974 (P=1.00, R=0.95) |
+| Contradiction detection F1 | 0.947 (P=1.00, R=0.90) |
+| Semantic linking SNR | 7.8x (linked: 0.69, random: 0.09) |
+| Automation rate | 97.9% (47/48 memories auto-captured) |
 
 ## Research
 
@@ -210,3 +132,7 @@ Ideas taken from a few papers, not implementations of them.
 - 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)
+
+## Paper
+
+[stackmem: MCP, Tree-Sitter AST Graphs, Hybrid Containment-Trigram Scoring, and Temporal Decay for Persistent AI Coding Agent Memory](https://github.com/arushlagudu/coding-memory/blob/main/docs/paper.pdf)