@stackmemoryai/stackmemory 1.12.0 → 1.14.0

package/LICENSE

@@ -1,64 +1,131 @@
-Business Source License 1.1
-
-Parameters
-
-Licensor:             StackMemory AI
-Licensed Work:        StackMemory v1.0.0
-                      The Licensed Work is (c) 2026 StackMemory AI
-Additional Use Grant: You may make production use of the Licensed Work,
-                      provided such use does not include offering the
-                      Licensed Work to third parties on a hosted or
-                      embedded basis which is competitive with StackMemory
-                      AI's products.
-Change Date:          2030-02-10
-Change License:       MIT
-
-For information about alternative licensing arrangements for the Licensed
-Work, please contact: hello@stackmemory.ai
-
-Notice
-
-Business Source License 1.1
-
-Terms
-
-The Licensor hereby grants you the right to copy, modify, create
-derivative works, redistribute, and make non-production use of the
-Licensed Work. The Licensor may make an Additional Use Grant, above,
-permitting limited production use.
-
-Effective on the Change Date, or the fourth anniversary of the first
-publicly available distribution of a specific version of the Licensed
-Work under this License, whichever comes first, the Licensor hereby
-grants you rights under the terms of the Change License, and the rights
-granted in the paragraph above terminate.
-
-If your use of the Licensed Work does not comply with the requirements
-currently in effect as described in this License, you must purchase a
-commercial license from the Licensor, its affiliated entities, or
-authorized resellers, or you must refrain from using the Licensed Work.
-
-All copies of the original and modified Licensed Work, and derivative
-works of the Licensed Work, are subject to this License. This License
-applies separately for each version of the Licensed Work and the Change
-Date may vary for each version of the Licensed Work released by
-Licensor.
-
-You must conspicuously display this License on each original or modified
-copy of the Licensed Work. If you receive the Licensed Work in original
-or modified form from a third party, the terms and conditions set forth
-in this License apply to your use of that work.
-
-Any use of the Licensed Work in violation of this License will
-automatically terminate your rights under this License for the current
-and all other versions of the Licensed Work.
-
-This License does not grant you any right in any trademark or logo of
-Licensor or its affiliates (provided that you may use a trademark or
-logo of Licensor as expressly required by this License).
-
-TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS
-PROVIDED ON AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES
-AND CONDITIONS, EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION)
-WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
-NON-INFRINGEMENT, AND TITLE.
+PolyForm Noncommercial License 1.0.0
+
+https://polyformproject.org/licenses/noncommercial/1.0.0
+
+Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose. However, you may
+only distribute the software according to Distribution
+License and make changes or new works
+based on the software according to Changes and New Works
+License.
+
+Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software. Your license
+to distribute covers distributing the software with
+changes and new works permitted by Changes and New Works
+License.
+
+Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software. For example:
+
+> Required Notice: Copyright StackMemory AI (https://stackmemory.ai)
+
+Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization,
+or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else. These terms do not imply
+any other licenses.
+
+Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice. Otherwise, all your licenses
+end immediately.
+
+No Liability
+
+As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.
+
+Definitions
+
+The licensor is the individual or entity offering these
+terms, and the software is the software the licensor makes
+available under these terms.
+
+You refers to the individual or entity agreeing to these
+terms.
+
+Your company is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization. Control
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise. Control can be direct or indirect.
+
+Your licenses are all the licenses granted to you for the
+software under these terms.
+
+Use means anything you do with the software requiring one
+of your licenses.

package/README.md

@@ -512,4 +512,6 @@ Grounded in distributed systems theory: FLP impossibility, Byzantine→Crash con
 
 ## License
 
-Licensed under the [Business Source License 1.1](./LICENSE). You can use, modify, and self-host StackMemory freely. The one restriction: you may not offer it as a competing hosted service. The license converts to MIT after 4 years per release.
+Licensed under the [PolyForm Noncommercial License 1.0.0](./LICENSE).
+
+Free for personal, research, educational, and noncommercial use. Commercial use requires a separate license from StackMemory AI.

package/bin/claude-sm

@@ -3,4 +3,19 @@
  * Claude-SM CLI Launcher (ESM)
  * Delegates to built CLI in dist without requiring tsx.
  */
-import('../dist/src/cli/claude-sm.js');
+import { existsSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const target = join(__dirname, '../dist/src/cli/claude-sm.js');
+
+if (!existsSync(target)) {
+  console.error('Error: StackMemory has not been built.');
+  console.error(`Missing: ${target}`);
+  console.error('Run: npm install && npm run build');
+  process.exit(1);
+}
+
+import(target);

package/bin/claude-smd

@@ -3,4 +3,19 @@
  * Claude-SM-Danger CLI Launcher (ESM)
  * Delegates to built CLI in dist without requiring tsx.
  */
-import('../dist/src/cli/claude-sm-danger.js');
+import { existsSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const target = join(__dirname, '../dist/src/cli/claude-sm-danger.js');
+
+if (!existsSync(target)) {
+  console.error('Error: StackMemory has not been built.');
+  console.error(`Missing: ${target}`);
+  console.error('Run: npm install && npm run build');
+  process.exit(1);
+}
+
+import(target);

package/bin/codex-smd

@@ -3,4 +3,19 @@
  * Codex-SM-Danger CLI Launcher (ESM)
  * Delegates to built CLI in dist without requiring tsx.
  */
-import('../dist/src/cli/codex-sm-danger.js');
+import { existsSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const target = join(__dirname, '../dist/src/cli/codex-sm-danger.js');
+
+if (!existsSync(target)) {
+  console.error('Error: StackMemory has not been built.');
+  console.error(`Missing: ${target}`);
+  console.error('Run: npm install && npm run build');
+  process.exit(1);
+}
+
+import(target);

package/bin/gemini-sm

@@ -3,4 +3,19 @@
  * Gemini-SM CLI Launcher (ESM)
  * Delegates to built CLI in dist without requiring tsx.
  */
-import('../dist/src/cli/gemini-sm.js');
+import { existsSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const target = join(__dirname, '../dist/src/cli/gemini-sm.js');
+
+if (!existsSync(target)) {
+  console.error('Error: StackMemory has not been built.');
+  console.error(`Missing: ${target}`);
+  console.error('Run: npm install && npm run build');
+  process.exit(1);
+}
+
+import(target);

package/bin/hermes-sm

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * Hermes-SM CLI Launcher (ESM)
+ * Delegates to built CLI in dist without requiring tsx.
+ */
+import { existsSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const target = join(__dirname, '../dist/src/cli/hermes-sm.js');
+
+if (!existsSync(target)) {
+  console.error('Error: StackMemory has not been built.');
+  console.error(`Missing: ${target}`);
+  console.error('Run: npm install && npm run build');
+  process.exit(1);
+}
+
+import(target);

package/bin/hermes-smd

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * Hermes-SM-Danger CLI Launcher (ESM) — danger mode
+ * Delegates to built CLI in dist without requiring tsx.
+ */
+import { existsSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const target = join(__dirname, '../dist/src/cli/hermes-sm.js');
+
+if (!existsSync(target)) {
+  console.error('Error: StackMemory has not been built.');
+  console.error(`Missing: ${target}`);
+  console.error('Run: npm install && npm run build');
+  process.exit(1);
+}
+
+import(target);

package/bin/opencode-sm

@@ -3,4 +3,19 @@
  * OpenCode-SM CLI Launcher (ESM)
  * Delegates to built CLI in dist without requiring tsx.
  */
-import('../dist/src/cli/opencode-sm.js');
+import { existsSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const target = join(__dirname, '../dist/src/cli/opencode-sm.js');
+
+if (!existsSync(target)) {
+  console.error('Error: StackMemory has not been built.');
+  console.error(`Missing: ${target}`);
+  console.error('Run: npm install && npm run build');
+  process.exit(1);
+}
+
+import(target);

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

@@ -11,7 +11,11 @@ import { program } from "commander";
 import { v4 as uuidv4 } from "uuid";
 import chalk from "chalk";
 import { initializeTracing, trace } from "../core/trace/index.js";
-import { resolveRealCliBin } from "./utils/real-cli-bin.js";
+import {
+  resolveRealCliBin,
+  resolveNativeCodexBin,
+  resolveNvmBin
+} from "./utils/real-cli-bin.js";
 import {
   startDeterminismWatcher,
   stopDeterminismWatcher
@@ -131,20 +135,15 @@ class CodexSM {
       explicitBin: this.config.codexBin,
       envBin: process.env["CODEX_BIN"],
       preferredPaths: [
-        path.join(
-          os.homedir(),
-          ".nvm",
-          "versions",
-          "node",
-          "v22.22.0",
-          "bin",
-          "codex"
-        ),
+        ...resolveNativeCodexBin(),
+        // native binary first (no wrapper overhead)
+        resolveNvmBin("codex"),
+        // dynamic nvm/fnm/volta path
         "/usr/local/bin/codex",
         "/opt/homebrew/bin/codex",
         "/usr/local/bin/codex-cli",
         "/opt/homebrew/bin/codex-cli"
-      ],
+      ].filter((p) => !!p),
       pathCommands: ["codex", "codex-cli"]
     });
   }
@@ -202,6 +201,46 @@ class CodexSM {
     } catch {
     }
   }
+  /**
+   * Emit context budget advice based on tool-call count from checkpoint state.
+   * Mirrors the Claude Code context-budget.js hook.
+   */
+  emitContextBudgetAdvice() {
+    const COMPACT_SUGGEST = 50;
+    const COMPACT_STRONG = 65;
+    const RESTART_RECOMMEND = 80;
+    try {
+      const stateFile = path.join(
+        os.homedir(),
+        ".stackmemory",
+        `checkpoint-state-${this.config.instanceId}.json`
+      );
+      if (!fs.existsSync(stateFile)) return;
+      const state = JSON.parse(fs.readFileSync(stateFile, "utf-8"));
+      const cwd = process.cwd();
+      const toolCount = state.projects?.[cwd]?.toolCount || 0;
+      if (toolCount >= RESTART_RECOMMEND) {
+        console.log(
+          chalk.yellow(
+            `[CONTEXT_BUDGET] ${toolCount} tool calls (~150K+ tokens). Recommend: save context then start fresh session.`
+          )
+        );
+      } else if (toolCount >= COMPACT_STRONG) {
+        console.log(
+          chalk.yellow(
+            `[CONTEXT_BUDGET] ${toolCount} tool calls (~100-130K tokens). Context heavy \u2014 consider compacting or restarting.`
+          )
+        );
+      } else if (toolCount >= COMPACT_SUGGEST) {
+        console.log(
+          chalk.gray(
+            `[CONTEXT_BUDGET] ${toolCount} tool calls (~80-100K tokens). Context getting heavy.`
+          )
+        );
+      }
+    } catch {
+    }
+  }
   loadContext() {
     if (!this.config.contextEnabled) return;
     try {
@@ -494,6 +533,7 @@ class CodexSM {
         });
       } catch {
       }
+      this.emitContextBudgetAdvice();
       if (this.config.tracingEnabled) {
         const summary = trace.getExecutionSummary();
         console.log();

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

@@ -0,0 +1,206 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import { Command } from "commander";
+import chalk from "chalk";
+import { openBrain } from "../../core/brain/index.js";
+function fmtEntry(e, verbose = false) {
+  const id = chalk.dim(e.entryId.slice(0, 8));
+  const kind = chalk.cyan(e.kind.padEnd(10));
+  const agent = chalk.magenta(`@${e.agent}`);
+  const when = new Date(e.createdAt).toISOString().slice(0, 10);
+  const head = `${id} ${kind} ${agent} ${chalk.gray(when)}  ${chalk.bold(e.title)}`;
+  if (!verbose) {
+    const concl = e.conclusion ? `
+     ${chalk.green("\u2192")} ${e.conclusion}` : "";
+    return head + concl;
+  }
+  const lines = [head];
+  if (e.summary) lines.push(`  ${chalk.gray("summary:")} ${e.summary}`);
+  if (e.conclusion)
+    lines.push(`  ${chalk.green("conclusion:")} ${e.conclusion}`);
+  if (e.tags.length)
+    lines.push(`  ${chalk.gray("tags:")} ${e.tags.join(", ")}`);
+  if (e.refs.length)
+    lines.push(`  ${chalk.gray("refs:")} ${e.refs.join(", ")}`);
+  lines.push(`  ${chalk.gray("confidence:")} ${e.confidence}`);
+  return lines.join("\n");
+}
+function createBrainCommand() {
+  const cmd = new Command("brain").description("Shared, compounding context state (per repo + org)").addHelpText(
+    "after",
+    `
+Examples:
+  stackmemory brain record --kind experiment \\
+    --title "Retry with jitter cut 5xx" \\
+    --summary "Tried exp backoff + jitter on the sync client" \\
+    --conclusion "p99 errors dropped 60%; ship it" --tags sync,reliability
+  stackmemory brain recall "retry"            Search this repo's brain
+  stackmemory brain recall "auth" --org       Search the whole org
+  stackmemory brain list --limit 10
+  stackmemory brain show <id>
+  stackmemory brain sync                       Push + pull online
+  stackmemory brain status
+
+Every agent (Claude, Codex, OpenCode, Hermes) shares this brain \u2014 log
+experiment conclusions so mutual thinking compounds. See docs/guides/BRAIN.md.
+`
+  );
+  cmd.command("record").description("Record an experiment / decision / insight / note").option("--title <title>", "Short title (required)").option("--summary <text>", "What was done / context").option("--conclusion <text>", "What was concluded (the payload)").option("--kind <kind>", "experiment | decision | insight | note", "note").option("--agent <name>", "Agent that produced this", "claude").option("--tags <tags>", "Comma-separated tags").option("--refs <refs>", "Comma-separated refs (issues, commits, files)").option("--confidence <n>", "Confidence 0..1", "0.7").option("--json", "Output as JSON").action((options) => {
+    if (!options.title) {
+      console.error(chalk.red("--title is required"));
+      process.exit(1);
+    }
+    const ctx = openBrain();
+    try {
+      const entry = ctx.store.record({
+        title: options.title,
+        summary: options.summary,
+        conclusion: options.conclusion,
+        kind: options.kind,
+        agent: options.agent,
+        tags: splitList(options.tags),
+        refs: splitList(options.refs),
+        confidence: parseFloat(options.confidence)
+      });
+      if (options.json) {
+        console.log(JSON.stringify(entry, null, 2));
+      } else {
+        console.log(
+          chalk.green("\u2713 recorded"),
+          chalk.dim(entry.entryId.slice(0, 8))
+        );
+        console.log(fmtEntry(entry));
+      }
+    } finally {
+      ctx.close();
+    }
+  });
+  cmd.command("recall").description("Search the brain (this repo by default, --org for the org)").argument("[query]", "Free-text query").option("--org", "Search across the whole org (all repos)").option("--agent <name>", "Filter by agent").option("--kind <kind>", "Filter by kind").option("--limit <n>", "Max results", "20").option("--all", "Include superseded entries").option("--json", "Output as JSON").action((query, options) => {
+    const ctx = openBrain();
+    try {
+      const q = {
+        org: !!options.org,
+        limit: parseInt(options.limit, 10),
+        includeSuperseded: !!options.all,
+        ...query ? { text: query } : {},
+        ...options.agent ? { agent: options.agent } : {},
+        ...options.kind ? { kind: options.kind } : {}
+      };
+      const results = ctx.store.recall(q);
+      if (options.json) {
+        console.log(JSON.stringify(results, null, 2));
+        return;
+      }
+      if (results.length === 0) {
+        console.log(chalk.yellow("No matching brain entries."));
+        return;
+      }
+      const scope = options.org ? "org" : "repo";
+      console.log(chalk.bold(`${results.length} result(s) [${scope}]`));
+      for (const e of results) console.log("\n" + fmtEntry(e));
+    } finally {
+      ctx.close();
+    }
+  });
+  cmd.command("list").description("List recent brain entries for this repo").option("--limit <n>", "Max results", "20").option("--json", "Output as JSON").action((options) => {
+    const ctx = openBrain();
+    try {
+      const results = ctx.store.recall({
+        limit: parseInt(options.limit, 10)
+      });
+      if (options.json) {
+        console.log(JSON.stringify(results, null, 2));
+        return;
+      }
+      if (results.length === 0) {
+        console.log(chalk.yellow("Brain is empty for this repo."));
+        return;
+      }
+      for (const e of results) console.log(fmtEntry(e) + "\n");
+    } finally {
+      ctx.close();
+    }
+  });
+  cmd.command("show").description("Show a single entry in full").argument("<id>", "Entry id (or prefix)").option("--json", "Output as JSON").action((id, options) => {
+    const ctx = openBrain();
+    try {
+      const entry = ctx.store.get(id);
+      if (!entry) {
+        console.error(chalk.red(`No entry matching '${id}'`));
+        process.exit(1);
+      }
+      console.log(
+        options.json ? JSON.stringify(entry, null, 2) : fmtEntry(entry, true)
+      );
+    } finally {
+      ctx.close();
+    }
+  });
+  cmd.command("sync").description("Push + pull brain entries online").option("--push", "Push only").option("--pull", "Pull only").option("--json", "Output as JSON").action(async (options) => {
+    const ctx = openBrain();
+    try {
+      if (!ctx.sync) {
+        console.error(
+          chalk.yellow(
+            "Online brain not configured. Run `stackmemory login`."
+          )
+        );
+        process.exit(1);
+      }
+      const result = options.push ? await ctx.sync.push() : options.pull ? await ctx.sync.pull() : await ctx.sync.sync();
+      if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else if (result.success) {
+        console.log(
+          chalk.green(
+            `\u2713 pushed ${result.pushed}, pulled ${result.pulled} (applied ${result.applied})`
+          )
+        );
+      } else {
+        console.error(chalk.red(`Sync failed: ${result.error}`));
+        process.exit(1);
+      }
+    } finally {
+      ctx.close();
+    }
+  });
+  cmd.command("status").description("Show brain scope + entry counts").option("--json", "Output as JSON").action((options) => {
+    const ctx = openBrain();
+    try {
+      const status = {
+        projectId: ctx.projectId,
+        workspaceId: ctx.workspaceId || null,
+        repoEntries: ctx.store.count(false),
+        orgEntries: ctx.workspaceId ? ctx.store.count(true) : 0,
+        online: !!ctx.sync
+      };
+      if (options.json) {
+        console.log(JSON.stringify(status, null, 2));
+        return;
+      }
+      console.log(chalk.bold("Brain Status"));
+      console.log(`  Repo (project):  ${status.projectId}`);
+      console.log(
+        `  Org (workspace): ${status.workspaceId ?? chalk.dim("not logged in")}`
+      );
+      console.log(`  Repo entries:    ${status.repoEntries}`);
+      if (ctx.workspaceId)
+        console.log(`  Org entries:     ${status.orgEntries}`);
+      console.log(
+        `  Online sync:     ${status.online ? chalk.green("configured") : chalk.dim("local-only")}`
+      );
+    } finally {
+      ctx.close();
+    }
+  });
+  return cmd;
+}
+function splitList(v) {
+  if (!v) return [];
+  return v.split(",").map((s) => s.trim()).filter(Boolean);
+}
+export {
+  createBrainCommand
+};