@stackmemoryai/stackmemory 0.5.64 → 0.5.66

package/README.md

@@ -1,6 +1,11 @@
 # StackMemory
 
-**Lossless, project-scoped memory for AI tools** • v0.5.59
+[![Test Shared Context](https://github.com/stackmemoryai/stackmemory/actions/workflows/test-shared-context.yml/badge.svg?branch=main)](https://github.com/stackmemoryai/stackmemory/actions/workflows/test-shared-context.yml)
+[![Publish to NPM](https://github.com/stackmemoryai/stackmemory/actions/workflows/npm-publish.yml/badge.svg?branch=main)](https://github.com/stackmemoryai/stackmemory/actions/workflows/npm-publish.yml)
+[![Coverage](https://codecov.io/gh/stackmemoryai/stackmemory/branch/main/graph/badge.svg)](https://codecov.io/gh/stackmemoryai/stackmemory)
+[![npm version](https://img.shields.io/npm/v/@stackmemoryai/stackmemory)](https://www.npmjs.com/package/@stackmemoryai/stackmemory)
+
+Lossless, project-scoped memory for AI tools
 
 StackMemory is a **production-ready memory runtime** for AI coding tools that preserves full project context across sessions:
 
@@ -19,124 +24,46 @@ Instead of a linear chat log, StackMemory organizes memory as a **call stack** o
 
 ## Why StackMemory exists
 
-Development tools lose context between sessions:
-
-- Previous decisions aren't tracked
-- Constraints get forgotten
-- Changes lack history
-- Tool execution isn't recorded
+Tools forget decisions and constraints between sessions. StackMemory makes context durable and actionable.
 
-StackMemory solves this by:
-
-- Storing all events, tool calls, and decisions
-- Smart retrieval of relevant context
-- Call stack organization for nested context
-- Configurable importance scoring
-- Team collaboration through shared stacks
+- Records: events, tool calls, decisions, and anchors
+- Retrieves: high-signal context tailored to the current task
+- Organizes: nested frames with importance scoring and shared stacks
 
 ---
 
-## Features
-
-StackMemory includes powerful features to enhance your AI coding workflow. Enable/disable with `claude-sm config setup`.
-
-### Predictive Edit
-
-Anticipates your next edit and displays suggestions as a status bar overlay. Powered by llama-server and Claude Code's PostToolUse hooks.
-
-```bash
-claude-sm --sweep          # Enable (default: on)
-claude-sm --no-sweep       # Disable
-```
-
-- **How it works**: Analyzes tool outputs and predicts likely follow-up edits
-- **Interface**: Tab to accept, Esc to dismiss
-- **Requirement**: Installs `node-pty` on first use
-
-### Code Review
-
-AI-powered code review using Greptile's codebase-aware analysis. Automatically registers the Greptile MCP server for deep repository understanding.
-
-```bash
-claude-sm --greptile       # Enable (default: on)
-claude-sm --no-greptile    # Disable
-```
-
-- **Tools provided**: `index_repository`, `query_repository`, `get_repository_info`
-- **Requirement**: `GREPTILE_API_KEY` in `.env`
-
-### Prompt Forge
-
-Genetic Eval-driven Prompt Algorithm (GEPA) for automatic system prompt optimization. Evolves your `CLAUDE.md` through mutation, evaluation, and selection.
-
-```bash
-claude-sm --gepa           # Enable
-claude-sm --no-gepa        # Disable (default)
-```
-
-- **Auto-optimize**: Watches `CLAUDE.md` and runs optimization on changes
-- **Strategies**: rephrase, add_examples, remove_redundancy, restructure, add_constraints, simplify
-- **Output**: Before/after comparison with metrics (lines, tokens, rules)
-
-### Model Switcher
-
-Dynamic model routing based on task complexity. Automatically selects the optimal model (Haiku/Sonnet/Opus) for each request.
-
-```bash
-claude-sm --model-routing  # Enable
-claude-sm --no-model-routing  # Disable (default)
-```
-
-- **Cost optimization**: Uses cheaper models for simple tasks
-- **Quality preservation**: Routes complex tasks to more capable models
-
-### Safe Branch
-
-Git worktree isolation for experimental changes. Each session operates in an isolated branch, preventing accidental commits to main.
-
-```bash
-claude-sm --worktree       # Enable
-claude-sm --no-worktree    # Disable (default)
-```
-
-- **Isolation**: Changes happen in a separate worktree
-- **Safety**: Main branch remains untouched until explicit merge
+## Features (at a glance)
 
-### Mobile Sync
+- MCP tools for Claude Code: 26+ tools; context on every request
+- Safe branches: worktree isolation with `--worktree` or `-w`
+- Persistent context: frames, anchors, decisions, retrieval
+- Optional boosts: model routing, prompt optimization (GEPA)
+- Integrations: Linear, Greptile, DiffMem, Browser MCP
 
-WhatsApp notifications for session updates and task completion. Stay informed even when away from your terminal.
+See the docs directory for deeper feature guides.
 
-```bash
-claude-sm --whatsapp       # Enable
-claude-sm --no-whatsapp    # Disable (default)
-```
-
-- **Notifications**: Session start, task completion, errors
-- **Interactive**: Reply to trigger actions remotely
+---
 
-### Session Insights
+## Quick Start
 
-Detailed tracing of session activity for debugging and optimization. Tracks tool calls, timing, and decision paths.
+Requirements: Node >= 20
 
 ```bash
-claude-sm --tracing        # Enable
-claude-sm --no-tracing     # Disable (default)
-```
-
-- **Visibility**: Full execution trace
-- **Analytics**: Performance metrics and patterns
+# Install globally
+npm install -g @stackmemoryai/stackmemory
 
-### Task Alert
+# Initialize in your project (zero-config, just works)
+cd your-project
+stackmemory init
 
-Desktop/terminal notifications when long-running tasks complete. Never miss a completed build or test run.
+# Configure Claude Code integration
+stackmemory setup-mcp
 
-```bash
-claude-sm --notify-on-done # Enable (default: on)
-claude-sm --no-notify-on-done  # Disable
+# Minimal usage
+stackmemory init && stackmemory setup-mcp && stackmemory doctor
 ```
 
-- **Platforms**: macOS notifications, terminal bell
-- **Smart**: Only notifies for tasks taking >10 seconds
+Restart Claude Code and StackMemory MCP tools will be available.
 
 ---
 
@@ -161,72 +88,52 @@ Frames can span:
 
 ## Hosted vs Open Source
 
-### Hosted (default)
-
-- Cloud-backed memory runtime
-- Fast indexing + retrieval
-- Durable storage
-- Per-project pricing
-- Works out-of-the-box
-
-### Open-source local mirror
-
-- SQLite-based
-- Fully inspectable
-- Offline / air-gapped
-- Intentionally **N versions behind**
-- No sync, no org features
-
-> OSS is for trust and inspection.
-> Hosted is for scale, performance, and teams.
+- Hosted: cloud-backed, fast retrieval, durable, team features — works out of the box.
+- OSS local: SQLite, offline, inspectable — intentionally behind; no sync/org features.
 
 ---
 
 ## How it integrates
 
-StackMemory integrates as an **MCP tool** and is invoked on **every interaction** in:
+Runs as an MCP server. Editors (e.g., Claude Code) call StackMemory on each interaction to fetch a compiled context bundle; editors don’t store memory themselves.
 
-- Claude Code
-- compatible editors
-- future MCP-enabled tools
+### MCP Quick Usage
 
-The editor never manages memory directly; it asks StackMemory for the **context bundle**.
+Use these JSON snippets with Claude Code’s MCP “tools/call”. Responses are returned as a single text item containing JSON.
 
----
+- Plan only (no code):
+  ```json
+  {"method":"tools/call","params":{"name":"plan_only","arguments":{"task":"Refactor config loader","plannerModel":"claude-3-5-sonnet-latest"}}}
+  ```
 
-## Product Health Metrics
+- Approval‑gated plan (phase 1):
+  ```json
+  {"method":"tools/call","params":{"name":"plan_gate","arguments":{"task":"Refactor config loader","compact":true}}}
+  ```
 
-### Current Status (v0.5.47)
+- Approve + execute (phase 2):
+  ```json
+  {"method":"tools/call","params":{"name":"approve_plan","arguments":{"approvalId":"<copy from plan_gate>","implementer":"codex","execute":true,"recordFrame":true,"compact":true}}}
+  ```
 
-| Metric | Current | Target | Status |
-|--------|---------|--------|--------|
-| **Test Coverage** | 85% | 90% | In Progress |
-| **Tests Passing** | 490 | 500+ | On Track |
-| **Documentation** | 80% | 100% | In Progress |
-| **Active Issues** | 3 high | 0 high | In Progress |
+- Manage approvals:
+  ```json
+  {"method":"tools/call","params":{"name":"pending_list","arguments":{}}}
+  {"method":"tools/call","params":{"name":"pending_show","arguments":{"approvalId":"<id>","compact":true}}}
+  {"method":"tools/call","params":{"name":"pending_clear","arguments":{"approvalId":"<id>"}}}
+  ```
 
----
-
-# QuickStart
+Env defaults (optional):
+- `STACKMEMORY_MM_PLANNER_MODEL` (e.g., `claude-3-5-sonnet-latest` or `claude-3-opus-latest`)
+- `STACKMEMORY_MM_REVIEWER_MODEL` (defaults to planner if unset)
+- `STACKMEMORY_MM_IMPLEMENTER` (`codex` or `claude`)
+- `STACKMEMORY_MM_MAX_ITERS` (e.g., `2`)
 
-## 1. Install & Initialize (30 seconds)
-
-```bash
-# Install globally
-npm install -g @stackmemoryai/stackmemory
+---
 
-# Initialize in your project (zero-config, just works)
-cd your-project
-stackmemory init
+## Quick Start
 
-# Configure Claude Code integration
-stackmemory setup-mcp
-
-# Verify everything works
-stackmemory doctor
-```
-
-That's it! Restart Claude Code and StackMemory MCP tools are available.
+See above for install and minimal usage. For advanced options, see Setup.
 
 ---
 
@@ -277,77 +184,7 @@ Checks project initialization, database integrity, MCP config, and suggests fixe
 
 ## 3. Advanced Setup
 
-<details>
-<summary>Manual MCP configuration</summary>
-
-Create MCP configuration:
-
-```bash
-mkdir -p ~/.claude
-cat > ~/.claude/stackmemory-mcp.json << 'EOF'
-{
-  "mcpServers": {
-    "stackmemory": {
-      "command": "stackmemory",
-      "args": ["mcp-server"],
-      "env": { "NODE_ENV": "production" }
-    }
-  }
-}
-EOF
-```
-
-Update Claude config.json:
-
-```json
-{
-  "mcp": {
-    "configFiles": ["~/.claude/stackmemory-mcp.json"]
-  }
-}
-```
-
-</details>
-
-<details>
-<summary>Hosted mode (cloud storage)</summary>
-
-```bash
-stackmemory onboard
-# Select "Hosted" when prompted
-# Or set DATABASE_URL environment variable
-```
-
-</details>
-
-<details>
-<summary>ChromaDB for semantic search</summary>
-
-```bash
-stackmemory init --chromadb
-# Prompts for ChromaDB API key
-```
-
-</details>
-
-Claude Code sessions automatically capture tool calls, maintain context across sessions, and sync with Linear when configured.
-
-Available MCP tools in Claude Code:
-
-| Tool                 | Description                                |
-| -------------------- | ------------------------------------------ |
-| `get_context`        | Retrieve relevant context for current work |
-| `add_decision`       | Record a decision with rationale           |
-| `start_frame`        | Begin a new context frame                  |
-| `close_frame`        | Close current frame with summary           |
-| `create_task`        | Create a new task                          |
-| `update_task_status` | Update task status                         |
-| `get_active_tasks`   | List active tasks (with filters)           |
-| `get_task_metrics`   | Get task analytics                         |
-| `linear_sync`        | Sync with Linear                           |
-| `linear_update_task` | Update Linear issue                        |
-| `linear_get_tasks`   | Get tasks from Linear                      |
-
+See https://github.com/stackmemoryai/stackmemory/blob/main/docs/setup.md for advanced options (hosted mode, ChromaDB, manual MCP config, and available tools).
 
 ---
 
@@ -379,7 +216,7 @@ This creates `.stackmemory/` with SQLite storage.
   "mcpServers": {
     "stackmemory": {
       "command": "node",
-      "args": ["dist/integrations/mcp/server.js"]
+      "args": ["dist/src/integrations/mcp/server.js"]
     }
   }
 }
@@ -540,140 +377,25 @@ stackmemory skills rlm "Build, test, and publish version 2.0.0"
 
 ## CLI Commands
 
-```bash
-# Setup & Diagnostics
-stackmemory init                          # Initialize project (zero-config)
-stackmemory init --interactive            # Interactive setup with options
-stackmemory setup-mcp                     # Configure Claude Code MCP
-stackmemory doctor                        # Diagnose issues and suggest fixes
-
-# Status
-stackmemory status                        # Current status
-stackmemory progress                      # Recent activity
-
-# Tasks
-stackmemory tasks list [--status pending] # List tasks
-stackmemory task add "title" --priority high
-stackmemory task done <id>
-
-# Search & Logs
-stackmemory search "query" [--tasks|--context]
-stackmemory log [--follow] [--type task]
-```
-
-```bash
-# Context
-stackmemory context show [--verbose]
-stackmemory context push "name" --type task
-stackmemory context add decision "text"
-stackmemory context pop [--all]
-
-# Linear Integration
-stackmemory linear setup                  # OAuth setup
-stackmemory linear sync [--direction from_linear]
-stackmemory linear auto-sync --start
-stackmemory linear update ENG-123 --status done
-
-# Storage Management
-stackmemory storage status               # Show tier distribution
-stackmemory storage migrate [--tier young] # Trigger migration
-stackmemory storage cleanup --force      # Clean old data
-stackmemory storage config --show        # Show configuration
-
-# Analytics & Server
-stackmemory analytics [--view|--port 3000]
-stackmemory mcp-server [--port 3001]
-```
+See https://github.com/stackmemoryai/stackmemory/blob/main/docs/cli.md for the full command reference and examples.
 
 ---
 
 ## Status
 
-- Hosted: **Private beta**
-- OSS mirror: **Production ready**
-- MCP integration: **Stable**
-- CLI: **v0.5.51** - Zero-config setup, diagnostics, full task/context/Linear management
-- Two-tier storage: **Complete**
-- Test Suite: **480 tests passing**
+See https://github.com/stackmemoryai/stackmemory/blob/main/docs/status.md for current status.
 
 ---
 
 ## Changelog
 
-### v0.5.51 (2026-01-28)
-- **Interactive feature setup**: `claude-sm config setup` wizard to toggle features and install deps on demand
-  - Checkbox prompt for all features (Sweep, Greptile, Model Routing, Worktree, WhatsApp, Tracing)
-  - Auto-installs `node-pty` when Sweep is enabled
-  - Prompts for `GREPTILE_API_KEY` and registers MCP server when Greptile is enabled
-- **Sweep next-edit predictions**: PTY wrapper displays predicted edits as a status bar in Claude Code sessions. Tab to accept, Esc to dismiss. Powered by llama-server via PostToolUse hooks.
-  - `claude-sm --sweep` (default: on) or `stackmemory sweep wrap`
-  - `node-pty` installed on demand via setup (no longer in optionalDependencies)
-- **Greptile AI code review**: Auto-registers Greptile MCP server for codebase-aware code review.
-  - `claude-sm --greptile` (default: on)
-  - Requires `GREPTILE_API_KEY` in `.env`
-  - Tools: `index_repository`, `query_repository`, `get_repository_info`
-- **Feature flags**: Added `greptile` feature flag to `feature-flags.ts`
-
-### v0.5.47 (2026-01-27)
-- **Graceful database failures**: Handles native module version mismatches
-- **Suppress dotenv logs**: Cleaner terminal output
-- **TTY preservation**: Fixes interactive mode for claude-sm/claude-smd
-- **Silent Linear auth**: No spam when API key not configured
-
-### v0.5.40 (2026-01-27)
-- **Zero-config onboarding**: `stackmemory init` now works without any prompts
-- **New `setup-mcp` command**: Auto-configures Claude Code MCP integration
-- **New `doctor` command**: Diagnoses issues and suggests fixes
-- **Interactive postinstall**: Asks for consent before modifying ~/.claude
-- **Better error messages**: Shows reason + fix + next step
-
-### v0.5.39 (2026-01-27)
-- **AsyncMutex**: Thread-safe Linear sync with stale lock detection
-- **Action timeout**: 60s timeout for SMS action execution
-- **Persistent rate limiting**: Survives server restarts
-- **Atomic file writes**: Prevents corruption on crash
-
-### v0.5.30 (2026-01-26)
-- Standardized error handling with `IntegrationError`, `DatabaseError`, `ValidationError`
-- Adopted error classes across Linear integration (12 files)
-- Adopted error classes across database layer (6 files)
-- WhatsApp notifications with session ID and interactive options
-
-### v0.5.28 (2026-01-25)
-- WhatsApp flag for claude-sm automatic notifications
-- Incoming request queue for WhatsApp triggers
-- SMS webhook /send endpoint for outgoing notifications
-
-### v0.5.26 (2026-01-24)
-- OpenCode wrapper (opencode-sm) with context integration
-- Discovery CLI and MCP tools
-- Real LLM provider and retrieval audit system
-- Linear issue management and task picker
-
-### v0.5.21 (2026-01-23)
-- Claude-sm remote mode and configurable defaults
-- Context loading command improvements
-- Session summary features
-
-### v0.3.16 (2026-01-15)
-- Fixed critical error handling - getFrame() returns undefined instead of throwing
-- Improved test coverage and fixed StackMemoryError constructor usage
-- Removed dangerous secret-cleaning scripts from repository
-- All tests passing, lint clean, build successful
-
-### v0.3.15 (2026-01-14)
-- Two-tier storage system implementation complete
-- Smart compression with LZ4/ZSTD support
-- Background migration with configurable triggers
-- Improved Linear integration with bidirectional sync
+See https://github.com/stackmemoryai/stackmemory/blob/main/docs/changelog.md for detailed release notes.
 
 ---
 
 ## Roadmap
 
-**Phase 4 (Completed):** Two-tier storage system with local tiers and infinite remote storage
-**Phase 5 (Current):** PostgreSQL production adapter, enhanced team collaboration, advanced analytics
-**Phase 6 (Next):** Enterprise features, multi-org support, cost optimization
+See https://github.com/stackmemoryai/stackmemory/blob/main/docs/roadmap.md for our current roadmap.
 
 ---
 
@@ -696,5 +418,6 @@ stackmemory mcp-server [--port 3001]
 - [Product Requirements](./PRD.md) - Detailed product specifications
 - [Technical Architecture](./TECHNICAL_ARCHITECTURE.md) - System design and database schemas
 - [Beads Integration](./BEADS_INTEGRATION.md) - Git-native memory patterns from Beads ecosystem
+ - [MCP: plan_and_code](https://github.com/stackmemoryai/stackmemory/blob/main/docs/mcp.md) - Trigger planning + coding via MCP with JSON results
 
 ---

package/bin/claude-sm

@@ -3,4 +3,4 @@
  * Claude-SM CLI Launcher (ESM)
  * Delegates to built CLI in dist without requiring tsx.
  */
-import('../dist/cli/claude-sm.js');
+import('../dist/src/cli/claude-sm.js');

package/bin/claude-smd

@@ -3,4 +3,4 @@
  * Claude-SM-Danger CLI Launcher (ESM)
  * Delegates to built CLI in dist without requiring tsx.
  */
-import('../dist/cli/claude-sm-danger.js');
+import('../dist/src/cli/claude-sm-danger.js');

package/bin/codex-smd

@@ -3,4 +3,4 @@
  * Codex-SM-Danger CLI Launcher (ESM)
  * Delegates to built CLI in dist without requiring tsx.
  */
-import('../dist/cli/codex-sm-danger.js');
+import('../dist/src/cli/codex-sm-danger.js');

package/dist/src/cli/commands/skills.js

@@ -23,6 +23,7 @@ import {
   DatabaseError,
   ErrorCode
 } from "../../core/errors/index.js";
+import { version as VERSION } from "../../version.js";
 function getEnv(key, defaultValue) {
   const value = process.env[key];
   if (value === void 0) {
@@ -270,6 +271,109 @@ function createSkillsCommand() {
       process.exit(1);
     }
   });
+  skillsCmd.command("spike").description(
+    "Run multi-agent spike (planner: Claude, implementer: Codex/Claude, critic: Claude)"
+  ).option("-t, --task <desc>", "Task description", "Spike harness").option(
+    "--planner-model <name>",
+    "Claude model for planning",
+    "claude-3-5-sonnet-latest"
+  ).option(
+    "--reviewer-model <name>",
+    "Claude model for review",
+    "claude-3-5-sonnet-latest"
+  ).option("--implementer <name>", "codex|claude", "codex").option("--max-iters <n>", "Retry loop iterations", "2").option(
+    "--execute",
+    "Execute implementer (codex-sm) instead of dry-run",
+    false
+  ).option("--audit-dir <path>", "Persist spike results to directory").option("--record-frame", "Record as real frame with anchors", false).option(
+    "--record",
+    "Record plan & critique into StackMemory context",
+    false
+  ).option("--json", "Emit single JSON result (UI-friendly)", false).option("--quiet", "Minimal output (default)", true).option("--verbose", "Verbose sectioned output", false).action(async (options) => {
+    const spinner = ora("Planning with Claude...").start();
+    try {
+      const { runSpike } = await import("../../orchestrators/multimodal/harness.js");
+      const result = await runSpike(
+        {
+          task: options.task,
+          repoPath: process.cwd()
+        },
+        {
+          plannerModel: options.plannerModel,
+          reviewerModel: options.reviewerModel,
+          implementer: options.implementer,
+          maxIters: parseInt(options.maxIters),
+          dryRun: !options.execute,
+          auditDir: options.auditDir,
+          recordFrame: Boolean(options.recordFrame),
+          record: Boolean(options.record)
+        }
+      );
+      spinner.stop();
+      if (options.json) {
+        console.log(JSON.stringify(result));
+      } else if (options.verbose) {
+        console.log(chalk.gray(`StackMemory v${VERSION}`));
+        console.log(chalk.cyan("\n=== Plan ==="));
+        console.log(JSON.stringify(result.plan, null, 2));
+        console.log(chalk.cyan("\n=== Iterations ==="));
+        (result.iterations || []).forEach((it, idx) => {
+          console.log(chalk.gray(`
+-- Attempt ${idx + 1} --`));
+          console.log(`Command: ${it.command}`);
+          console.log(`OK: ${it.ok}`);
+          console.log("Critique:", JSON.stringify(it.critique));
+        });
+        console.log(chalk.cyan("\n=== Final ==="));
+        console.log(JSON.stringify(result.implementation, null, 2));
+        console.log(chalk.cyan("\n=== Critique ==="));
+        console.log(JSON.stringify(result.critique, null, 2));
+      } else if (!options.quiet) {
+        console.log(
+          `Plan steps: ${result.plan.steps.length}, Approved: ${result.critique.approved}`
+        );
+      }
+      if (!result.implementation.success) process.exitCode = 1;
+    } catch (error) {
+      spinner.stop();
+      console.error(chalk.red("Spike failed:"), error?.message || error);
+      process.exit(1);
+    }
+  });
+  skillsCmd.command("plan <task>").description("Generate an implementation plan (no code execution)").option(
+    "--planner-model <name>",
+    "Claude model for planning",
+    "claude-3-5-sonnet-latest"
+  ).option("--json", "Emit JSON (default)", true).option("--pretty", "Pretty-print JSON", false).option(
+    "--compact",
+    "Compact output (summary + step titles + criteria)",
+    false
+  ).action(async (task, options) => {
+    const spinner = ora("Planning with Claude...").start();
+    try {
+      const { runPlanOnly } = await import("../../orchestrators/multimodal/harness.js");
+      const plan = await runPlanOnly(
+        { task, repoPath: process.cwd() },
+        { plannerModel: options.plannerModel }
+      );
+      spinner.stop();
+      const compacted = options.compact ? {
+        summary: plan?.summary,
+        steps: Array.isArray(plan?.steps) ? plan.steps.map((s) => ({
+          id: s.id,
+          title: s.title,
+          acceptanceCriteria: s.acceptanceCriteria
+        })) : [],
+        risks: plan?.risks
+      } : plan;
+      const payload = JSON.stringify(compacted, null, options.pretty ? 2 : 0);
+      console.log(payload);
+    } catch (error) {
+      spinner.stop();
+      console.error(chalk.red("Plan failed:"), error?.message || error);
+      process.exit(1);
+    }
+  });
   skillsCmd.command("dig <query>").description("Deep historical context retrieval").option(
     "-d, --depth <depth>",
     "Search depth (e.g., 30days, 6months, all)",