@stackmemoryai/stackmemory 1.10.5 → 1.14.0

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
+};

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

@@ -0,0 +1,126 @@
+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 * as path from "path";
+import { existsSync } from "fs";
+import Database from "better-sqlite3";
+import { ContentCache } from "../../core/cache/index.js";
+function findProjectDbPath() {
+  let dir = process.cwd();
+  while (dir !== "/") {
+    const dbPath = path.join(dir, ".stackmemory", "context.db");
+    if (existsSync(dbPath)) return dbPath;
+    dir = path.dirname(dir);
+  }
+  const home = process.env["HOME"] || "/tmp";
+  const homePath = path.join(home, ".stackmemory", "context.db");
+  if (existsSync(homePath)) return homePath;
+  return void 0;
+}
+function getProjectDb() {
+  const dbPath = findProjectDbPath();
+  if (!dbPath) return void 0;
+  return new Database(dbPath);
+}
+function createCacheCommand() {
+  const cmd = new Command("cache").description(
+    "Content-hash cache \u2014 view token savings and manage cached content"
+  );
+  cmd.command("stats").description("Show cache statistics and token savings").option("--json", "Output as JSON").action((options) => {
+    const db = getProjectDb();
+    if (!db) {
+      console.log(chalk.yellow("No project database found"));
+      return;
+    }
+    try {
+      const cache = new ContentCache(db);
+      const stats = cache.getStats();
+      if (options.json) {
+        console.log(JSON.stringify(stats, null, 2));
+        return;
+      }
+      console.log(chalk.bold("Content Cache Statistics\n"));
+      console.log(`  Entries:       ${stats.totalEntries.toLocaleString()}`);
+      console.log(
+        `  Tokens cached: ${stats.totalTokensCached.toLocaleString()}`
+      );
+      console.log(
+        `  Tokens saved:  ${chalk.green(stats.totalTokensSaved.toLocaleString())}`
+      );
+      console.log(`  Hit rate:      ${(stats.hitRate * 100).toFixed(1)}%`);
+      if (stats.topSources.length > 0) {
+        console.log(chalk.bold("\n  Top sources by tokens saved:"));
+        for (const src of stats.topSources.slice(0, 5)) {
+          console.log(
+            `    ${chalk.dim(src.source)}: ${src.tokensSaved.toLocaleString()} tokens`
+          );
+        }
+      }
+      const costSaved = stats.totalTokensSaved / 1e6 * 3;
+      if (costSaved > 0.01) {
+        console.log(
+          `
+  Est. cost saved: ${chalk.green("$" + costSaved.toFixed(2))}`
+        );
+      }
+    } finally {
+      db.close();
+    }
+  });
+  cmd.command("clear").description("Clear the content cache").option("--confirm", "Skip confirmation prompt").action((options) => {
+    if (!options.confirm) {
+      console.log(
+        chalk.yellow(
+          "This will clear all cached content. Run with --confirm to proceed."
+        )
+      );
+      return;
+    }
+    const db = getProjectDb();
+    if (!db) {
+      console.log(chalk.yellow("No project database found"));
+      return;
+    }
+    try {
+      const cache = new ContentCache(db);
+      cache.clear();
+      console.log(chalk.green("Cache cleared"));
+    } finally {
+      db.close();
+    }
+  });
+  cmd.command("search <query>").description("Search cached content by keyword").option("--limit <n>", "Max results", "10").action((query, options) => {
+    const db = getProjectDb();
+    if (!db) {
+      console.log(chalk.yellow("No project database found"));
+      return;
+    }
+    try {
+      const cache = new ContentCache(db);
+      const results = cache.search(query, parseInt(options.limit));
+      if (results.length === 0) {
+        console.log(chalk.dim(`No cached content matching "${query}"`));
+        return;
+      }
+      console.log(chalk.bold(`${results.length} result(s):
+`));
+      for (const entry of results) {
+        const preview = entry.content.slice(0, 120).replace(/\n/g, " ");
+        console.log(
+          `  ${chalk.dim(entry.hash.slice(0, 8))} ${chalk.dim(`(${entry.tokenCount} tokens, ${entry.hitCount} hits)`)}`
+        );
+        console.log(`  ${preview}${entry.content.length > 120 ? "..." : ""}`);
+        console.log();
+      }
+    } finally {
+      db.close();
+    }
+  });
+  return cmd;
+}
+export {
+  createCacheCommand
+};

package/dist/src/cli/commands/company-os.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+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 { readdirSync, readFileSync, existsSync } from "node:fs";
+import { join, extname } from "node:path";
+const WIKI_DIR = join(process.cwd(), "wiki");
+const WIKI_SOPS_DIR = join(WIKI_DIR, "sops");
+const PROSE_SPEC_PATH = join(
+  process.cwd(),
+  "docs",
+  "specs",
+  "COMPANY-OS-PROSE.md"
+);
+function collectSopFiles() {
+  const files = [];
+  const dirs = [WIKI_DIR];
+  if (existsSync(WIKI_SOPS_DIR)) dirs.push(WIKI_SOPS_DIR);
+  for (const dir of dirs) {
+    if (!existsSync(dir)) continue;
+    for (const entry of readdirSync(dir)) {
+      if (extname(entry) !== ".md") continue;
+      const filePath = join(dir, entry);
+      const content = readFileSync(filePath, "utf8");
+      const idMatch = content.match(/^# (SOP-\d+)/m);
+      const titleMatch = content.match(/^# SOP-\d+\s+(.+)/m);
+      const statusMatch = content.match(/\*\*Status:\*\*\s*(\w+)/);
+      const proseMatch = content.match(/Related PROSE Expectation.*\[(E\.\d+)/);
+      files.push({
+        id: idMatch?.[1] ?? entry.replace(".md", ""),
+        title: titleMatch?.[1] ?? entry,
+        status: statusMatch?.[1] ?? "Unknown",
+        proseId: proseMatch?.[1] ?? null,
+        path: filePath
+      });
+    }
+  }
+  return files;
+}
+function loadValidProseIds() {
+  const ids = /* @__PURE__ */ new Set();
+  if (!existsSync(PROSE_SPEC_PATH)) return ids;
+  const content = readFileSync(PROSE_SPEC_PATH, "utf8");
+  const headingRegex = /^###\s+(E\.\d+)\s+/gm;
+  let match;
+  while ((match = headingRegex.exec(content)) !== null) {
+    ids.add(match[1]);
+  }
+  return ids;
+}
+function validateSop(content) {
+  const errors = [];
+  const required = ["## Objective", "## Procedure", "## Verification"];
+  for (const section of required) {
+    if (!content.includes(section)) {
+      errors.push(`Missing section: ${section}`);
+    }
+  }
+  if (!content.match(/Related PROSE Expectation.*\[E\.\d+/)) {
+    errors.push("Missing or invalid Related PROSE Expectation");
+  }
+  if (!content.match(/^# SOP-\d+/m)) {
+    errors.push("Missing or invalid SOP ID (expected # SOP-NNN ...)");
+  }
+  return errors;
+}
+function createCompanyOsCommand() {
+  const cmd = new Command("company-os").alias("cos").description("Manage Company OS processes, SOPs, and audits");
+  cmd.command("list").description("List SOPs in the Company OS wiki").option("--json", "Output as JSON").action(() => {
+    const sops = collectSopFiles();
+    if (sops.length === 0) {
+      console.log(chalk.yellow("No SOPs found in wiki/"));
+      return;
+    }
+    console.log(chalk.cyan(`
+Company OS SOPs (${sops.length})
+`));
+    for (const sop of sops.sort((a, b) => a.id.localeCompare(b.id))) {
+      console.log(
+        `  ${chalk.bold(sop.id)}  ${chalk.white(sop.title.slice(0, 50))}`
+      );
+      console.log(
+        chalk.gray(
+          `    status: ${sop.status}  PROSE: ${sop.proseId ?? "none"}  ${sop.path}`
+        )
+      );
+    }
+    console.log();
+  });
+  cmd.command("validate").description("Validate all Company OS SOPs against the schema").option("--json", "Output as JSON").action(() => {
+    const sops = collectSopFiles();
+    const validProseIds = loadValidProseIds();
+    const results = [];
+    for (const sop of sops) {
+      const content = readFileSync(sop.path, "utf8");
+      const errors = validateSop(content);
+      if (sop.proseId && !validProseIds.has(sop.proseId)) {
+        errors.push(`Invalid PROSE Expectation: ${sop.proseId}`);
+      }
+      results.push({
+        id: sop.id,
+        path: sop.path,
+        valid: errors.length === 0,
+        errors
+      });
+    }
+    const validCount = results.filter((r) => r.valid).length;
+    if (results.every((r) => r.valid)) {
+      console.log(chalk.green(`
+\u2713 All ${validCount} SOPs are valid.
+`));
+    } else {
+      console.log(chalk.yellow(`
+SOP Validation Results
+`));
+      for (const result of results) {
+        const icon = result.valid ? chalk.green("\u2713") : chalk.red("\u2717");
+        console.log(`${icon} ${result.id}`);
+        for (const error of result.errors) {
+          console.log(chalk.gray(`    - ${error}`));
+        }
+      }
+      console.log(chalk.gray(`
+Valid: ${validCount} / ${results.length}
+`));
+      process.exitCode = 1;
+    }
+  });
+  cmd.command("audit <process>").description(
+    "Audit a Company OS process against its SOP (e.g. onboarding, pto)"
+  ).option("--json", "Output as JSON").action((processName) => {
+    const sops = collectSopFiles();
+    const normalized = processName.toLowerCase().replace(/\s+/g, "-");
+    const sop = sops.find((s) => {
+      const sopNormalized = s.title.toLowerCase().replace(/\s+/g, "-");
+      return sopNormalized.includes(normalized) || s.id.toLowerCase().includes(normalized);
+    });
+    if (!sop) {
+      console.log(
+        chalk.red(`No SOP found matching process "${processName}"`)
+      );
+      console.log(chalk.gray("Run: stackmemory company-os list"));
+      process.exitCode = 1;
+      return;
+    }
+    const content = readFileSync(sop.path, "utf8");
+    const errors = validateSop(content);
+    const validProseIds = loadValidProseIds();
+    if (sop.proseId && !validProseIds.has(sop.proseId)) {
+      errors.push(`Invalid PROSE Expectation: ${sop.proseId}`);
+    }
+    const compliant = errors.length === 0;
+    console.log(chalk.cyan(`
+Company OS Audit: ${sop.id} ${sop.title}
+`));
+    console.log(`  PROSE Expectation: ${sop.proseId ?? "none"}`);
+    console.log(
+      `  Status: ${compliant ? chalk.green("compliant") : chalk.red("non-compliant")}`
+    );
+    if (errors.length > 0) {
+      console.log(chalk.yellow("\n  Findings:"));
+      for (const error of errors) {
+        console.log(chalk.gray(`    - ${error}`));
+      }
+    } else {
+      console.log(
+        chalk.gray(
+          "\n  Note: This POC audit validates SOP structure only. A full audit would check operational data against the SOP."
+        )
+      );
+    }
+    console.log();
+    if (!compliant) {
+      process.exitCode = 1;
+    }
+  });
+  return cmd;
+}
+export {
+  createCompanyOsCommand
+};

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

@@ -34,6 +34,7 @@ function createContextCommands() {
       const frameManager = new FrameManager(db, projectId, {
         skipContextBridge: true
       });
+      await frameManager.initialize();
       const depth = frameManager.getStackDepth();
       const activePath = frameManager.getActiveFramePath();
       console.log(`
@@ -101,6 +102,7 @@ function createContextCommands() {
       const frameManager = new FrameManager(db, projectId, {
         skipContextBridge: true
       });
+      await frameManager.initialize();
       const activePath = frameManager.getActiveFramePath();
       const parentId = activePath.length > 0 ? activePath[activePath.length - 1].frame_id : void 0;
       let inputs = {};
@@ -147,6 +149,7 @@ function createContextCommands() {
       const frameManager = new FrameManager(db, projectId, {
         skipContextBridge: true
       });
+      await frameManager.initialize();
       const activePath = frameManager.getActiveFramePath();
       if (activePath.length === 0) {
         console.log("\u{1F4DA} Stack is already empty.");
@@ -193,6 +196,7 @@ function createContextCommands() {
       const frameManager = new FrameManager(db, projectId, {
         skipContextBridge: true
       });
+      await frameManager.initialize();
       const activePath = frameManager.getActiveFramePath();
       if (activePath.length === 0) {
         console.log("\u26A0\uFE0F No active context frame. Creating one...");
@@ -248,6 +252,7 @@ function createContextCommands() {
       const frameManager = new FrameManager(db, projectId, {
         skipContextBridge: true
       });
+      await frameManager.initialize();
       if (options.list || action === "list") {
         const worktreeFrames = db.prepare(
           `

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

@@ -107,6 +107,7 @@ The daemon provides:
         const services = [];
         if (newStatus.services.context.enabled) services.push("context");
         if (newStatus.services.linear.enabled) services.push("linear");
+        if (newStatus.services.github?.enabled) services.push("github");
         if (newStatus.services.maintenance?.enabled)
           services.push("maintenance");
         if (newStatus.services.memory?.enabled) services.push("memory");
@@ -232,6 +233,25 @@ The daemon provides:
         console.log(chalk.gray(`    Syncs: ${lin.syncCount}`));
       }
     }
+    const gh = status.services.github;
+    if (gh) {
+      console.log(
+        `  GitHub: ${gh.enabled ? chalk.green("Enabled") : chalk.gray("Disabled")}`
+      );
+      if (gh.enabled) {
+        console.log(
+          chalk.gray(`    Interval: ${config.github.interval} min`)
+        );
+        if (gh.syncCount) {
+          console.log(chalk.gray(`    Refreshes: ${gh.syncCount}`));
+        }
+        if (gh.lastProjectionState) {
+          console.log(
+            chalk.gray(`    Last PR state: ${gh.lastProjectionState}`)
+          );
+        }
+      }
+    }
     const maint = status.services.maintenance;
     if (maint) {
       console.log(
@@ -605,6 +625,22 @@ function getServiceHealthChecks(status, config) {
       detail: "Disabled"
     });
   }
+  const gh = status.services.github;
+  if (gh?.enabled) {
+    const intervalMs = config.github.interval * 6e4;
+    const overdue = gh.lastRun ? Date.now() - gh.lastRun > intervalMs * 2 : false;
+    checks.push({
+      name: "GitHub Service",
+      status: overdue ? "warn" : "ok",
+      detail: gh.lastRun ? `Last refresh: ${formatTimeAgo(gh.lastRun)} | Refreshes: ${gh.syncCount ?? 0}${gh.lastProjectionState ? ` | Last PR state: ${gh.lastProjectionState}` : ""}` : `Enabled (interval: ${config.github.interval}m) | No refreshes yet`
+    });
+  } else {
+    checks.push({
+      name: "GitHub Service",
+      status: "ok",
+      detail: "Disabled"
+    });
+  }
   const maint = status.services.maintenance;
   if (maint?.enabled) {
     const intervalMs = config.maintenance.interval * 6e4;
@@ -701,6 +737,11 @@ function buildHealthReport(status, config, paths) {
       enabled: status.services.linear.enabled,
       lastRun: status.services.linear.lastRun
     },
+    {
+      key: "github",
+      enabled: status.services.github?.enabled ?? false,
+      lastRun: status.services.github?.lastRun
+    },
     {
       key: "maintenance",
       enabled: status.services.maintenance?.enabled ?? false,