@stackmemoryai/stackmemory 1.2.4 → 1.2.7

package/README.md

@@ -5,19 +5,26 @@
 [![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 coding tools.
+Lossless, project-scoped memory for AI coding tools. **[Website](https://stackmemoryai.github.io/stackmemory/)** | **[MCP Tools](https://stackmemoryai.github.io/stackmemory/tools.html)** | **[Getting Started](./docs/GETTING_STARTED.md)**
+
+<p align="center">
+  <img src="site/demo.svg" alt="StackMemory setup demo" width="560">
+</p>
 
 StackMemory is a **production-ready memory runtime** for AI coding tools that preserves full project context across sessions:
 
 - **Zero-config setup** — `stackmemory init` just works
-- **25 MCP tools** for Claude Code integration
-- **Full Linear integration** with bidirectional sync
+- **32 MCP tools** for Claude Code integration (context, tasks, Linear, traces, discovery, cord, team)
+- **FTS5 full-text search** with BM25 scoring and hybrid retrieval
+- **Full Linear integration** with bidirectional sync and OAuth/API key support
 - **Context persistence** that survives `/clear` operations
 - **Hierarchical frame organization** (nested call stack model)
+- **Multi-wrapper support** — `claude-sm`, `codex-sm`, `opencode-sm` with auto context loading
 - **Skills system** with `/spec` and `/linear-run` for Claude Code
 - **Automatic hooks** for task tracking, Linear sync, and spec progress
 - **Memory monitor daemon** with automatic capture/clear on RAM pressure
-- **652 tests passing** with comprehensive coverage
+- **Auto-save service** for periodic context persistence
+- **Comprehensive test coverage** across all core modules
 
 Instead of a linear chat log, StackMemory organizes memory as a **call stack** of scoped work (frames), with intelligent LLM-driven retrieval and team collaboration features.
 
@@ -50,13 +57,14 @@ Tools forget decisions and constraints between sessions. StackMemory makes conte
 
 ## Features
 
-- **MCP tools** for Claude Code: 25 tools across context, tasks, Linear, traces, and discovery
+- **MCP tools** for Claude Code: 36 tools across context, tasks, Linear, traces, discovery, cord, and team
+- **FTS5 search**: full-text search with BM25 scoring, hybrid retrieval, and smart thresholds
 - **Skills**: `/spec` (iterative spec generation), `/linear-run` (task execution via RLM)
-- **Hooks**: automatic context save, task tracking, Linear sync, PROMPT_PLAN updates
+- **Hooks**: automatic context save, task tracking, Linear sync, PROMPT_PLAN updates, cord tracing
 - **Prompt Forge**: watches CLAUDE.md and AGENTS.md for prompt optimization (GEPA)
 - **Safe branches**: worktree isolation with `--worktree` or `-w`
 - **Persistent context**: frames, anchors, decisions, retrieval
-- **Integrations**: Linear, DiffMem, Browser MCP
+- **Integrations**: Linear (API key + OAuth), DiffMem, Browser MCP, log-mcp (log analysis)
 
 ---
 
@@ -347,6 +355,8 @@ See [docs/cli.md](https://github.com/stackmemoryai/stackmemory/blob/main/docs/cl
 
 ## Documentation
 
+- [Getting Started](./docs/GETTING_STARTED.md) — Quick start guide (5 minutes)
+- [MCP Tools Reference](https://stackmemoryai.github.io/stackmemory/tools.html) — All 32 MCP tools
 - [CLI Reference](./docs/cli.md) — Full command reference
 - [Setup Guide](./docs/SETUP.md) — Advanced setup options
 - [Development Guide](./docs/DEVELOPMENT.md) — Contributing and development

package/dist/src/cli/claude-sm.js

@@ -322,6 +322,28 @@ class ClaudeSM {
     } catch {
     }
   }
+  getTheoryContent() {
+    try {
+      let root;
+      try {
+        root = execSync("git rev-parse --show-toplevel", {
+          encoding: "utf-8",
+          timeout: 5e3
+        }).trim();
+      } catch {
+        root = process.cwd();
+      }
+      const theoryPath = path.join(root, "THEORY.MD");
+      if (fs.existsSync(theoryPath)) {
+        const content = fs.readFileSync(theoryPath, "utf8").trim();
+        if (content.length > 0) {
+          return content.length > 4e3 ? content.substring(0, 4e3) + "\n\n[...truncated]" : content;
+        }
+      }
+    } catch {
+    }
+    return null;
+  }
   getHandoffContent() {
     if (!this.config.contextEnabled) return null;
     try {
@@ -684,13 +706,20 @@ Session ended (exit ${exitCode ?? 0})`));
       this.startGEPAWatcher();
     }
     let initialInput = "";
-    const handoffContent = this.getHandoffContent();
-    if (handoffContent) {
-      const hasResume = claudeArgs.includes("--continue") || claudeArgs.some((a) => a === "--resume");
-      if (!hasResume) {
+    const hasResume = claudeArgs.includes("--continue") || claudeArgs.some((a) => a === "--resume");
+    if (!hasResume) {
+      const handoffContent = this.getHandoffContent();
+      if (handoffContent) {
         initialInput = handoffContent;
         console.log(chalk.gray("   Handoff context ready"));
       }
+      const theoryContent = this.getTheoryContent();
+      if (theoryContent) {
+        initialInput += (initialInput ? "\n\n---\n\n" : "") + `## Operating Theory (THEORY.MD)
+
+${theoryContent}`;
+        console.log(chalk.gray("   Theory context loaded"));
+      }
     }
     console.log();
     if (this.config.useSweep) {

package/dist/src/cli/codex-sm-danger.js

@@ -6,7 +6,10 @@ const __dirname = __pathDirname(__filename);
 import { spawn } from "child_process";
 import * as path from "path";
 const codexSmPath = path.join(__dirname, "codex-sm.js");
-const args = ["--dangerously-skip-permissions", ...process.argv.slice(2)];
+const args = [
+  "--dangerously-bypass-approvals-and-sandbox",
+  ...process.argv.slice(2)
+];
 const child = spawn("node", [codexSmPath, ...args], {
   stdio: "inherit",
   env: process.env

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

@@ -317,12 +317,12 @@ ${contextResponse.context}`;
     "Launch Oracle/Worker pattern swarm for cost-effective execution"
   ).argument("<project>", "Project description for Oracle planning").option(
     "--oracle <model>",
-    "Oracle model (default: claude-3-opus)",
-    "claude-3-opus-20240229"
+    "Oracle model (default: claude-sonnet-4-5)",
+    "claude-sonnet-4-5-20250929"
   ).option(
     "--workers <models>",
     "Comma-separated worker models",
-    "claude-3-5-haiku-20241022"
+    "claude-haiku-4-5-20251001"
   ).option("--budget <amount>", "Cost budget in USD", "10.0").option("--max-workers <count>", "Maximum worker agents", "5").option("--hints <hints>", "Comma-separated planning hints").action(async (project, options) => {
     return trace.command(
       "ralph-oracle-worker",

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

@@ -795,6 +795,89 @@ ${result.data.diffStat}`));
       process.exit(1);
     }
   });
+  const theoryCmd = skillsCmd.command("theory").description("Maintain a living THEORY.MD at repo root");
+  theoryCmd.command("show").description("Display current THEORY.MD content").action(async () => {
+    try {
+      const { context } = await initializeSkillContext();
+      const { TheorySkill } = await import("../../skills/theory-skill.js");
+      const skill = new TheorySkill(context);
+      const result = skill.show();
+      if (result.success) {
+        console.log(result.message);
+      } else {
+        console.log(chalk.red("\u2717"), result.message);
+      }
+      await context.database.disconnect();
+    } catch (error) {
+      console.error(chalk.red("Error:"), error.message);
+      process.exit(1);
+    }
+  });
+  theoryCmd.command("init <problem>").description("Create THEORY.MD with scaffold sections").action(async (problem) => {
+    try {
+      const { context } = await initializeSkillContext();
+      const { TheorySkill } = await import("../../skills/theory-skill.js");
+      const skill = new TheorySkill(context);
+      const result = skill.init(problem);
+      if (result.success) {
+        console.log(chalk.green("\u2713"), result.message);
+      } else {
+        console.log(chalk.red("\u2717"), result.message);
+      }
+      await context.database.disconnect();
+    } catch (error) {
+      console.error(chalk.red("Error:"), error.message);
+      process.exit(1);
+    }
+  });
+  theoryCmd.command("update <content>").description("Overwrite THEORY.MD with new content").action(async (content) => {
+    try {
+      const { context } = await initializeSkillContext();
+      const { TheorySkill } = await import("../../skills/theory-skill.js");
+      const skill = new TheorySkill(context);
+      const result = skill.update(content);
+      if (result.success) {
+        console.log(chalk.green("\u2713"), result.message);
+        if (result.data?.warnings?.length > 0) {
+          result.data.warnings.forEach((w) => {
+            console.log(chalk.yellow(`  \u26A0 ${w}`));
+          });
+        }
+      } else {
+        console.log(chalk.red("\u2717"), result.message);
+      }
+      await context.database.disconnect();
+    } catch (error) {
+      console.error(chalk.red("Error:"), error.message);
+      process.exit(1);
+    }
+  });
+  theoryCmd.command("status").description("Show THEORY.MD metadata").action(async () => {
+    try {
+      const { context } = await initializeSkillContext();
+      const { TheorySkill } = await import("../../skills/theory-skill.js");
+      const skill = new TheorySkill(context);
+      const result = skill.status();
+      if (result.success) {
+        console.log(chalk.cyan("THEORY.MD Status:"));
+        if (result.data?.exists) {
+          console.log(`  Lines: ${result.data.lineCount}`);
+          console.log(
+            `  Sections: ${result.data.sections?.length}/${result.data.totalSections}`
+          );
+          console.log(`  Last modified: ${result.data.lastModified}`);
+        } else {
+          console.log(chalk.gray("  Not found"));
+        }
+      } else {
+        console.log(chalk.red("\u2717"), result.message);
+      }
+      await context.database.disconnect();
+    } catch (error) {
+      console.error(chalk.red("Error:"), error.message);
+      process.exit(1);
+    }
+  });
   skillsCmd.command("help [skill]").description("Show help for a specific skill").action(async (skill) => {
     if (skill) {
       switch (skill) {
@@ -846,6 +929,27 @@ Examples:
 
 Apply patches:  git apply .stackmemory/patches/<file>.patch
 Review specs:   cd /tmp/sm-spec-* && git log --oneline
+`);
+          break;
+        case "theory":
+          console.log(`
+theory \u2014 Living Operating Theory Document
+
+Maintains a THEORY.MD at repo root: a narrative capturing your problem
+thesis, mental model, strategy, discoveries, and open questions.
+
+Subcommands:
+  show                     Display current THEORY.MD
+  init <problem>           Create THEORY.MD with scaffold sections
+  update <content>         Overwrite THEORY.MD (validates, warns on anti-patterns)
+  status                   Show metadata (lines, sections, last modified)
+
+Examples:
+  stackmemory skills theory init "Build context-aware memory for AI agents"
+  stackmemory skills theory show
+  stackmemory skills theory status
+
+Based on Theorist by @blader (MIT).
 `);
           break;
         default:
@@ -875,7 +979,10 @@ Review specs:   cd /tmp/sm-spec-* && git log --oneline
       );
       console.log("  linear-run - Execute Linear tasks via RLM orchestrator");
       console.log(
-        "  agent      - Spawn parallel agents (research, maintain, spec-run)\n"
+        "  agent      - Spawn parallel agents (research, maintain, spec-run)"
+      );
+      console.log(
+        "  theory     - Maintain a living THEORY.MD (show, init, update, status)\n"
       );
       console.log(
         chalk.yellow(

package/dist/src/core/extensions/provider-adapter.js

@@ -113,10 +113,11 @@ class ClaudeAdapter {
   }
   async listModels() {
     return [
-      "claude-opus-4-20250514",
+      "claude-opus-4-6",
+      "claude-sonnet-4-5-20250929",
+      "claude-haiku-4-5-20251001",
       "claude-sonnet-4-20250514",
-      "claude-3-5-haiku-20241022",
-      "claude-3-opus-20240229"
+      "claude-3-5-haiku-20241022"
     ];
   }
   buildRequestBody(messages, options) {
@@ -360,16 +361,7 @@ class GPTAdapter {
     }
   }
   async listModels() {
-    return [
-      "gpt-4o",
-      "gpt-4o-mini",
-      "gpt-4-turbo",
-      "gpt-4",
-      "gpt-3.5-turbo",
-      "o1",
-      "o1-mini",
-      "o1-preview"
-    ];
+    return ["gpt-4o", "gpt-4o-mini", "o3-mini", "o4-mini"];
   }
 }
 function createProvider(id, config) {

package/dist/src/core/models/model-router.js

@@ -22,16 +22,14 @@ const MODEL_TOKEN_LIMITS = {
   "claude-sonnet-4-5-20250929": 2e5,
   "claude-haiku-4-5-20251001": 2e5,
   "claude-sonnet-4-20250514": 2e5,
-  // Claude 3.x
+  // Claude 3.x (legacy, still functional)
   "claude-3-5-sonnet-20241022": 2e5,
   "claude-3-5-haiku-20241022": 2e5,
-  "claude-3-opus-20240229": 2e5,
   // OpenAI
   "gpt-4o": 128e3,
-  "gpt-4-turbo": 128e3,
-  "gpt-4": 8192,
-  o1: 2e5,
+  "gpt-4o-mini": 128e3,
   "o3-mini": 2e5,
+  "o4-mini": 2e5,
   // Qwen
   "qwen3-max-2025-01-23": 128e3,
   // Cerebras

package/dist/src/hooks/daemon.js

@@ -13,7 +13,6 @@ import {
 import { join, extname, relative } from "path";
 import { spawn } from "child_process";
 import { loadConfig } from "./config.js";
-import { GraphitiHooks } from "./graphiti-hooks.js";
 import {
   hookEmitter
 } from "./events.js";
@@ -143,13 +142,6 @@ function registerBuiltinHandlers() {
   hookEmitter.registerHandler("file_change", handleFileChange);
   hookEmitter.registerHandler("suggestion_ready", handleSuggestionReady);
   hookEmitter.registerHandler("error", handleError);
-  try {
-    if (process.env.GRAPHITI_ENDPOINT || process.env.GRAPHITI_ENABLED === "true") {
-      const graphiti = new GraphitiHooks();
-      graphiti.register(hookEmitter);
-    }
-  } catch {
-  }
   hookEmitter.on("*", () => {
     state.eventsProcessed++;
   });

package/dist/src/integrations/linear/webhook.js

@@ -22,7 +22,6 @@ function getOptionalEnv(key) {
 class LinearWebhookHandler {
   syncEngine;
   taskStore;
-  graphitiBridge;
   webhookSecret;
   constructor(webhookSecret) {
     this.webhookSecret = webhookSecret || process.env["LINEAR_WEBHOOK_SECRET"];
@@ -39,12 +38,6 @@ class LinearWebhookHandler {
   setTaskStore(taskStore) {
     this.taskStore = taskStore;
   }
-  /**
-   * Set the Graphiti bridge for knowledge graph sync
-   */
-  setGraphitiBridge(bridge) {
-    this.graphitiBridge = bridge;
-  }
   /**
    * Verify webhook signature
    */
@@ -111,15 +104,6 @@ class LinearWebhookHandler {
       default:
         logger.warn(`Unknown webhook action: ${payload.action}`);
     }
-    if (this.graphitiBridge) {
-      this.graphitiBridge.processWebhook(payload).catch((err) => {
-        logger.debug("Linear-Graphiti bridge error", {
-          action: payload.action,
-          identifier: payload.data.identifier,
-          error: err instanceof Error ? err.message : String(err)
-        });
-      });
-    }
   }
   /**
    * Handle issue created in Linear

package/dist/src/integrations/mcp/handlers/index.js

@@ -99,10 +99,6 @@ class MCPHandlerFactory {
         return this.taskHandlers.handleGetActiveTasks.bind(this.taskHandlers);
       case "get_task_metrics":
         return this.taskHandlers.handleGetTaskMetrics.bind(this.taskHandlers);
-      case "add_task_dependency":
-        return this.taskHandlers.handleAddTaskDependency.bind(
-          this.taskHandlers
-        );
       // Linear handlers
       case "linear_sync":
         return this.linearHandlers.handleLinearSync.bind(this.linearHandlers);
@@ -119,8 +115,6 @@ class MCPHandlerFactory {
       // Trace handlers
       case "get_traces":
         return this.traceHandlers.handleGetTraces.bind(this.traceHandlers);
-      case "analyze_traces":
-        return this.traceHandlers.handleAnalyzeTraces.bind(this.traceHandlers);
       case "start_browser_debug":
         return this.traceHandlers.handleStartBrowserDebug.bind(
           this.traceHandlers
@@ -193,7 +187,6 @@ class MCPHandlerFactory {
       "update_task_status",
       "get_active_tasks",
       "get_task_metrics",
-      "add_task_dependency",
       // Linear tools
       "linear_sync",
       "linear_update_task",
@@ -201,7 +194,6 @@ class MCPHandlerFactory {
       "linear_status",
       // Trace tools
       "get_traces",
-      "analyze_traces",
       "start_browser_debug",
       "take_screenshot",
       "execute_script",

package/dist/src/integrations/mcp/handlers/trace-handlers.js

@@ -11,6 +11,9 @@ class TraceHandlers {
    * Get traces with optional filtering
    */
   async handleGetTraces(args) {
+    if (args.analyze) {
+      return this.handleAnalyzeTraces(args);
+    }
     try {
       const {
         limit = 20,

package/dist/src/integrations/mcp/server.js

@@ -31,7 +31,6 @@ import { LLMContextRetrieval } from "../../core/retrieval/index.js";
 import { DiscoveryHandlers } from "./handlers/discovery-handlers.js";
 import { DiffMemHandlers } from "./handlers/diffmem-handlers.js";
 import { GreptileHandlers } from "./handlers/greptile-handlers.js";
-import { GraphitiClient } from "../graphiti/client.js";
 import { fuzzyEdit } from "../../utils/fuzzy-edit.js";
 import { v4 as uuidv4 } from "uuid";
 import {
@@ -67,7 +66,6 @@ class LocalStackMemoryMCP {
   diffMemHandlers;
   greptileHandlers;
   providerHandlers = null;
-  graphitiClient = null;
   pendingPlans = /* @__PURE__ */ new Map();
   constructor() {
     this.projectRoot = this.findProjectRoot();
@@ -142,15 +140,6 @@ class LocalStackMemoryMCP {
     this.diffMemHandlers = new DiffMemHandlers();
     this.greptileHandlers = new GreptileHandlers();
     this.initProviderHandlers();
-    if (process.env.GRAPHITI_ENDPOINT) {
-      this.graphitiClient = new GraphitiClient({
-        endpoint: process.env.GRAPHITI_ENDPOINT,
-        projectNamespace: process.env.STACKMEMORY_PROJECT_ID || this.projectId
-      });
-      logger.info("Graphiti client initialized", {
-        endpoint: process.env.GRAPHITI_ENDPOINT
-      });
-    }
     this.setupHandlers();
     this.loadInitialContext();
     this.loadPendingPlans();
@@ -711,24 +700,6 @@ ${summary}...`, 0.8);
                 properties: {}
               }
             },
-            {
-              name: "add_task_dependency",
-              description: "Add dependency relationship between tasks",
-              inputSchema: {
-                type: "object",
-                properties: {
-                  taskId: {
-                    type: "string",
-                    description: "Task that depends on another"
-                  },
-                  dependsOnId: {
-                    type: "string",
-                    description: "Task ID that this depends on"
-                  }
-                },
-                required: ["taskId", "dependsOnId"]
-              }
-            },
             {
               name: "linear_sync",
               description: "Sync tasks with Linear",
@@ -1087,51 +1058,6 @@ ${summary}...`, 0.8);
                 properties: {}
               }
             },
-            // Graphiti tools (only active when GRAPHITI_ENDPOINT is set)
-            ...this.graphitiClient ? [
-              {
-                name: "graphiti_status",
-                description: "Check Graphiti temporal knowledge graph connection status",
-                inputSchema: {
-                  type: "object",
-                  properties: {}
-                }
-              },
-              {
-                name: "graphiti_query",
-                description: "Query the Graphiti temporal knowledge graph for entities, relations, and episodes",
-                inputSchema: {
-                  type: "object",
-                  properties: {
-                    query: {
-                      type: "string",
-                      description: "Semantic text query"
-                    },
-                    entityTypes: {
-                      type: "array",
-                      items: { type: "string" },
-                      description: 'Entity types to filter (e.g., ["Person", "File", "Issue"])'
-                    },
-                    validFrom: {
-                      type: "number",
-                      description: "Start of time window (epoch ms)"
-                    },
-                    validTo: {
-                      type: "number",
-                      description: "End of time window (epoch ms)"
-                    },
-                    maxHops: {
-                      type: "number",
-                      description: "Graph traversal depth (default 2)"
-                    },
-                    k: {
-                      type: "number",
-                      description: "Top-k results (default 20)"
-                    }
-                  }
-                }
-              }
-            ] : [],
             // Greptile tools (only active when GREPTILE_API_KEY is set)
             ...process.env.GREPTILE_API_KEY ? this.greptileHandlers.getToolDefinitions() : [],
             // Provider tools (only active when STACKMEMORY_MULTI_PROVIDER=true)
@@ -1299,9 +1225,6 @@ ${summary}...`, 0.8);
             case "get_task_metrics":
               result = await this.handleGetTaskMetrics(args);
               break;
-            case "add_task_dependency":
-              result = await this.handleAddTaskDependency(args);
-              break;
             case "linear_sync":
               result = await this.handleLinearSync(args);
               break;
@@ -1456,59 +1379,6 @@ ${summary}...`, 0.8);
                 );
               }
               break;
-            // Graphiti tools
-            case "graphiti_status":
-              if (!this.graphitiClient) {
-                result = {
-                  content: [
-                    {
-                      type: "text",
-                      text: JSON.stringify({
-                        connected: false,
-                        message: "Graphiti integration disabled (GRAPHITI_ENDPOINT not set)"
-                      })
-                    }
-                  ]
-                };
-              } else {
-                const status = await this.graphitiClient.getStatus();
-                result = {
-                  content: [
-                    { type: "text", text: JSON.stringify(status, null, 2) }
-                  ]
-                };
-              }
-              break;
-            case "graphiti_query":
-              if (!this.graphitiClient) {
-                result = {
-                  content: [
-                    {
-                      type: "text",
-                      text: "Graphiti integration disabled (GRAPHITI_ENDPOINT not set)"
-                    }
-                  ]
-                };
-              } else {
-                const gCtx = await this.graphitiClient.queryTemporal({
-                  query: args.query,
-                  entityTypes: args.entityTypes,
-                  validFrom: args.validFrom,
-                  validTo: args.validTo,
-                  maxHops: args.maxHops,
-                  k: args.k
-                });
-                const text = gCtx.chunks.map((c) => c.text).join("\n\n");
-                result = {
-                  content: [
-                    {
-                      type: "text",
-                      text: text || `No results found (${gCtx.totalTokens} tokens searched)`
-                    }
-                  ]
-                };
-              }
-              break;
             default:
               throw new Error(`Unknown tool: ${name}`);
           }