@stackmemoryai/stackmemory 1.2.0 → 1.2.1

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

@@ -35,6 +35,14 @@ import {
   sendCtrlC,
   sessionExists
 } from "../features/workers/tmux-manager.js";
+import {
+  CANONICAL_HOOKS,
+  mergeSettings,
+  hasDeadHooks,
+  readSettings,
+  writeSettingsAtomic,
+  getSettingsPath
+} from "../utils/hook-installer.js";
 const DEFAULT_SM_CONFIG = {
   defaultWorktree: false,
   defaultSandbox: false,
@@ -332,6 +340,62 @@ class ClaudeSM {
     }
     return null;
   }
+  /**
+   * Ensure Claude Code hooks are installed. Copies missing scripts from
+   * templates and updates settings.json. Non-fatal on any error.
+   */
+  ensureHooks() {
+    try {
+      const hooksDir = path.join(os.homedir(), ".claude", "hooks");
+      if (!fs.existsSync(hooksDir)) {
+        fs.mkdirSync(hooksDir, { recursive: true });
+      }
+      const candidateDirs = [
+        path.join(__dirname, "../../templates/claude-hooks"),
+        path.join(__dirname, "../../../templates/claude-hooks"),
+        path.join(
+          __dirname,
+          "..",
+          "..",
+          "..",
+          "..",
+          "templates",
+          "claude-hooks"
+        )
+      ];
+      const templatesDir = candidateDirs.find(
+        (d) => fs.existsSync(d) && fs.readdirSync(d).length > 0
+      );
+      if (!templatesDir) return;
+      let copiedCount = 0;
+      for (const entry of CANONICAL_HOOKS) {
+        const dest = path.join(hooksDir, entry.scriptName);
+        if (!fs.existsSync(dest)) {
+          const src = path.join(templatesDir, entry.scriptName);
+          if (fs.existsSync(src)) {
+            fs.copyFileSync(src, dest);
+            try {
+              fs.chmodSync(dest, 493);
+            } catch {
+            }
+            copiedCount++;
+          }
+        }
+      }
+      const settingsPath = getSettingsPath();
+      const current = readSettings(settingsPath);
+      if (copiedCount > 0 || hasDeadHooks(current)) {
+        const merged = mergeSettings(current, hooksDir);
+        writeSettingsAtomic(merged, settingsPath);
+      }
+      if (copiedCount > 0) {
+        console.log(
+          chalk.gray(`   Hooks: installed ${copiedCount} missing hook(s)`)
+        );
+      }
+    } catch {
+    }
+  }
   loadContext() {
     if (!this.config.contextEnabled) return;
     try {
@@ -554,6 +618,7 @@ Session ended (exit ${exitCode ?? 0})`));
       }
     }
     this.loadContext();
+    this.ensureHooks();
     process.env["CLAUDE_INSTANCE_ID"] = this.config.instanceId;
     if (this.config.worktreePath) {
       process.env["CLAUDE_WORKTREE_PATH"] = this.config.worktreePath;

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

@@ -30,6 +30,7 @@ import { TraceDetector } from "../../core/trace/trace-detector.js";
 import { LLMContextRetrieval } from "../../core/retrieval/index.js";
 import { DiscoveryHandlers } from "./handlers/discovery-handlers.js";
 import { DiffMemHandlers } from "./handlers/diffmem-handlers.js";
+import { GraphitiClient } from "../graphiti/client.js";
 import { fuzzyEdit } from "../../utils/fuzzy-edit.js";
 import { v4 as uuidv4 } from "uuid";
 import {
@@ -64,6 +65,7 @@ class LocalStackMemoryMCP {
   discoveryHandlers;
   diffMemHandlers;
   providerHandlers = null;
+  graphitiClient = null;
   pendingPlans = /* @__PURE__ */ new Map();
   constructor() {
     this.projectRoot = this.findProjectRoot();
@@ -137,6 +139,15 @@ class LocalStackMemoryMCP {
     });
     this.diffMemHandlers = new DiffMemHandlers();
     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();
@@ -1073,6 +1084,51 @@ ${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)"
+                    }
+                  }
+                }
+              }
+            ] : [],
             // Provider tools (only active when STACKMEMORY_MULTI_PROVIDER=true)
             ...isFeatureEnabled("multiProvider") ? [
               {
@@ -1373,6 +1429,59 @@ ${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}`);
           }

package/dist/src/integrations/mcp/tool-definitions.js

@@ -13,7 +13,8 @@ class MCPToolDefinitions {
       ...this.getLinearTools(),
       ...this.getTraceTools(),
       ...this.getDiscoveryTools(),
-      ...this.getEditTools()
+      ...this.getEditTools(),
+      ...this.getGraphitiTools()
     ];
   }
   /**
@@ -705,6 +706,55 @@ class MCPToolDefinitions {
       }
     ];
   }
+  /**
+   * Graphiti knowledge graph tools
+   */
+  getGraphitiTools() {
+    return [
+      {
+        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)"
+            }
+          }
+        }
+      }
+    ];
+  }
   /**
    * Get tool definition by name
    */
@@ -728,6 +778,8 @@ class MCPToolDefinitions {
         return this.getDiscoveryTools();
       case "edit":
         return this.getEditTools();
+      case "graphiti":
+        return this.getGraphitiTools();
       default:
         return [];
     }

package/dist/src/utils/hook-installer.js

@@ -0,0 +1,155 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+const CANONICAL_HOOKS = [
+  {
+    scriptName: "session-rescue.sh",
+    eventType: "Stop",
+    timeout: 12,
+    required: true
+  },
+  {
+    scriptName: "stop-checkpoint.js",
+    eventType: "Stop",
+    timeout: 5,
+    commandPrefix: "node",
+    required: true
+  },
+  {
+    scriptName: "chime-on-stop.sh",
+    eventType: "Stop",
+    timeout: 2,
+    required: true
+  },
+  {
+    scriptName: "auto-checkpoint.js",
+    eventType: "PostToolUse",
+    timeout: 2,
+    commandPrefix: "node",
+    required: true
+  }
+];
+const DEAD_HOOKS = ["sms-response-handler.js"];
+function buildCommand(entry, hooksDir) {
+  const scriptPath = path.join(hooksDir, entry.scriptName);
+  if (entry.commandPrefix) {
+    return `${entry.commandPrefix} ${scriptPath}`;
+  }
+  return scriptPath;
+}
+function hookExists(settings, entry) {
+  const groups = settings.hooks?.[entry.eventType];
+  if (!groups) return false;
+  for (const group of groups) {
+    for (const hook of group.hooks) {
+      if (hook.command.includes(entry.scriptName)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+function hasDeadHooks(settings) {
+  if (!settings.hooks) return false;
+  for (const groups of Object.values(settings.hooks)) {
+    for (const group of groups) {
+      for (const hook of group.hooks) {
+        for (const dead of DEAD_HOOKS) {
+          if (hook.command.includes(dead)) return true;
+        }
+      }
+    }
+  }
+  return false;
+}
+function removeDeadHooks(settings) {
+  if (!settings.hooks) return false;
+  let removed = false;
+  for (const eventType of Object.keys(settings.hooks)) {
+    const groups = settings.hooks[eventType];
+    for (const group of groups) {
+      const before = group.hooks.length;
+      group.hooks = group.hooks.filter((hook) => {
+        for (const dead of DEAD_HOOKS) {
+          if (hook.command.includes(dead)) return false;
+        }
+        return true;
+      });
+      if (group.hooks.length < before) removed = true;
+    }
+    settings.hooks[eventType] = groups.filter((g) => g.hooks.length > 0);
+    if (settings.hooks[eventType].length === 0) {
+      delete settings.hooks[eventType];
+    }
+  }
+  return removed;
+}
+function addHook(settings, entry, hooksDir) {
+  if (!settings.hooks) settings.hooks = {};
+  const eventGroups = settings.hooks[entry.eventType] || [];
+  const command = buildCommand(entry, hooksDir);
+  const hookCmd = { type: "command", command };
+  if (entry.timeout) hookCmd.timeout = entry.timeout;
+  const matcherValue = entry.matcher ?? void 0;
+  const targetGroup = eventGroups.find((g) => {
+    if (matcherValue) return g.matcher === matcherValue;
+    return !g.matcher;
+  });
+  if (targetGroup) {
+    targetGroup.hooks.push(hookCmd);
+  } else {
+    const newGroup = { hooks: [hookCmd] };
+    if (matcherValue) newGroup.matcher = matcherValue;
+    eventGroups.push(newGroup);
+  }
+  settings.hooks[entry.eventType] = eventGroups;
+}
+function mergeSettings(existing, hooksDir) {
+  const merged = JSON.parse(JSON.stringify(existing));
+  removeDeadHooks(merged);
+  for (const entry of CANONICAL_HOOKS) {
+    if (!hookExists(merged, entry)) {
+      addHook(merged, entry, hooksDir);
+    }
+  }
+  return merged;
+}
+function getSettingsPath() {
+  return path.join(os.homedir(), ".claude", "settings.json");
+}
+function readSettings(settingsPath) {
+  const p = settingsPath ?? getSettingsPath();
+  try {
+    if (fs.existsSync(p)) {
+      return JSON.parse(fs.readFileSync(p, "utf8"));
+    }
+  } catch {
+  }
+  return {};
+}
+function writeSettingsAtomic(settings, settingsPath) {
+  const p = settingsPath ?? getSettingsPath();
+  const dir = path.dirname(p);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  const tmp = p + ".tmp";
+  fs.writeFileSync(tmp, JSON.stringify(settings, null, 2) + "\n");
+  fs.renameSync(tmp, p);
+}
+export {
+  CANONICAL_HOOKS,
+  DEAD_HOOKS,
+  buildCommand,
+  getSettingsPath,
+  hasDeadHooks,
+  hookExists,
+  mergeSettings,
+  readSettings,
+  removeDeadHooks,
+  writeSettingsAtomic
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackmemoryai/stackmemory",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Project-scoped memory for AI coding tools. Durable context across sessions with MCP integration, frames, smart retrieval, Claude Code skills, and automatic hooks.",
   "engines": {
     "node": ">=20.0.0",
@@ -171,7 +171,7 @@
     "@types/better-sqlite3": "^7.6.8",
     "@types/express": "^4.17.25",
     "@types/js-yaml": "^4.0.9",
-    "@types/node": "^20.10.6",
+    "@types/node": "^22.0.0",
     "@types/uuid": "^10.0.0",
     "@types/ws": "^8.5.10",
     "@typescript-eslint/eslint-plugin": "^8.50.1",

package/scripts/gepa/.before-optimize.md

@@ -0,0 +1,159 @@
+AGENTS.md
+
+Purpose
+- A minimal, agent-friendly reference so code-generation agents (Codex, Claude Code, etc.) can work effectively in this repository.
+- Explains key docs, the /designs/ folder, agent responsibilities, and quick operational notes (how to run tests, what to update, and commit expectations).
+
+Repo doc descriptions
+- prompt_plan.md
+  - The agent-driven plan that sequences work into small, testable prompts and steps.
+  - Contains per-step prompts, expected artifacts, tests, rollback/idempotency notes, and a TODO checklist using Markdown checkboxes.
+  - This is the canonical agent workflow driver — update it as you make progress (see Agent responsibility rules below).
+
+- spec.md
+  - The minimal functional & technical specification that defines APIs, data models, and acceptance criteria.
+  - Includes the concise Definition of Done that must be satisfied for each plan step before marking it complete.
+
+- idea.md
+  - Free-form brainstorming, assumptions, notes, research links, and open questions.
+  - Useful for context but not authoritative — always follow spec.md and prompt_plan.md for implementation decisions.
+
+- idea_one_pager.md
+  - A short summary / one‑pager capturing Problem, Audience, Platform, Core Flow, and MVP Features (and optional Non‑Goals).
+  - Good for quick alignment and to confirm that work stays within scope.
+
+What lives in /designs/
+- UI/UX artifacts and visual assets that inform implementation:
+  - wireframes (PNG/SVG), Figma exports (.fig, .pdf), sequence diagrams, architecture diagrams (PNG/PDF/SVG), and annotated screenshots.
+  - Naming conventions: keep filenames short, include version/date and owner, e.g., dashboard_v1_2025-11-01.png or seq_query_flow_v2.pdf.
+  - Large source Figma files may live externally; include an export + a small README describing where the canonical design is stored and any viewing permissions required.
+
+How agents should interact (summary)
+- Treat prompt_plan.md as the authoritative workflow: follow the listed prompts in order and mark checklist items as you finish them.
+- Always follow TDD: write tests first, make the minimal change to pass tests, then refactor while keeping tests green.
+- After any code/test change, update the matching TODO checkbox in prompt_plan.md using the same Markdown checkbox format ('- [x]') and commit the change alongside code and tests.
+- Make the smallest change that passes tests and improves code. Do not introduce new public APIs without updating spec.md and tests.
+- Don't duplicate templates/files to work around errors — fix the original.
+- Suggest a clear manual test path for every change (even when tests cover it).
+- If you cannot open a file or content is missing, say so explicitly and stop. Do not guess.
+
+Quick operational commands (expect these to exist; if not, ask)
+- npm run dev — start local dev server
+- npm test — run unit + integration test suite
+- npm run lint — run linting
+- npm run build — build TypeScript
+- npm run migrate:up / migrate:down — database migrations
+
+Commit & PR expectations
+- Each prompt/plan step should result in a single, focused commit/PR with:
+  - Code + tests + prompt_plan.md checklist update.
+  - A short, copy-pasteable commit summary in the prompt_plan.md step completion entry.
+  - Clear CHANGELOG or Release notes entry if user-facing behavior changed (or explicitly state "No user-facing changes").
+- Use atomic commits. Include test run results in PR description.
+
+Include this governance / workflow block verbatim (do not modify)
+## Repository docs
+- 'ONE_PAGER.md' - Captures Problem, Audience, Platform, Core Flow, MVP Features; Non-Goals optional.
+- 'DEV_SPEC.md' - Minimal functional and technical specification consistent with prior docs, including a concise **Definition of Done**.
+- 'PROMPT_PLAN.md' - Agent-Ready Planner with per-step prompts, expected artifacts, tests, rollback notes, idempotency notes, and a TODO checklist using Markdown checkboxes. This file drives the agent workflow.
+- 'docs/STYLE.md' - Unified design system reference. Typography, layout, color tokens, component patterns. Inspired by Hatchet (structural layout, inset panels) and Outliner (clean hierarchy, whitespace). **All dashboard UI changes must follow this guide.**
+- 'AGENTS.md' - This file.
+
+### Agent responsibility
+- After completing any coding, refactor, or test step, **immediately update the corresponding TODO checklist item in 'prompt_plan.md'**.
+- Use the same Markdown checkbox format ('- [x]') to mark completion.
+- When creating new tasks or subtasks, add them directly under the appropriate section anchor in 'prompt_plan.md'.
+- Always commit changes to 'prompt_plan.md' alongside the code and tests that fulfill them.
+- Do not consider work "done" until the matching checklist item is checked and all related tests are green.
+- When a stage (plan step) is complete with green tests, update the README "Release notes" section with any user-facing impact (or explicitly state "No user-facing changes" if applicable).
+- Even when automated coverage exists, always suggest a feasible manual test path so the human can exercise the feature end-to-end.
+- After a plan step is finished, document its completion state with a short checklist. Include: step name & number, test results, 'prompt_plan.md' status, manual checks performed (mark as complete only after the human confirms they ran to their satisfaction), release notes status, and an inline commit summary string the human can copy & paste.
+
+#### Guardrails for agents
+- Make the smallest change that passes tests and improves the code.
+- Do not introduce new public APIs without updating 'spec.md' and relevant tests.
+- Do not duplicate templates or files to work around issues. Fix the original.
+- If a file cannot be opened or content is missing, say so explicitly and stop. Do not guess.
+- Respect privacy and logging policy: do not log secrets, prompts, completions, or PII.
+
+#### Deferred-work notation
+- When a task is intentionally paused, keep its checkbox unchecked and prepend '(Deferred)' to the TODO label in 'prompt_plan.md', followed by a short reason.
+- Apply the same '(Deferred)' tag to every downstream checklist item that depends on the paused work.
+- Remove the tag only after the work resumes; this keeps the outstanding scope visible without implying completion.
+
+
+
+#### When the prompt plan is fully satisfied
+- Once every Definition of Done task in 'prompt_plan.md' is either checked off or explicitly marked '(Deferred)', the plan is considered **complete**.
+- After that point, you no longer need to update prompt-plan TODOs or reference 'prompt_plan.md', 'spec.md', 'idea_one_pager.md', or other upstream docs to justify changes.
+- All other guardrails, testing requirements, and agent responsibilities in this file continue to apply unchanged.
+
+
+---
+
+## Testing policy (non-negotiable)
+- Tests **MUST** cover the functionality being implemented.
+- **NEVER** ignore the output of the system or the tests - logs and messages often contain **CRITICAL** information.
+- **TEST OUTPUT MUST BE PRISTINE TO PASS.**
+- If logs are **supposed** to contain errors, capture and test it.
+- **NO EXCEPTIONS POLICY:** Under no circumstances should you mark any test type as "not applicable". Every project, regardless of size or complexity, **MUST** have unit tests, integration tests, **AND** end-to-end tests. If you believe a test type doesn't apply, you need the human to say exactly **"I AUTHORIZE YOU TO SKIP WRITING TESTS THIS TIME"**.
+
+### TDD (how we work)
+- Write tests **before** implementation.
+- Only write enough code to make the failing test pass.
+- Refactor continuously while keeping tests green.
+
+**TDD cycle**
+1. Write a failing test that defines a desired function or improvement.
+2. Run the test to confirm it fails as expected.
+3. Write minimal code to make the test pass.
+4. Run the test to confirm success.
+5. Refactor while keeping tests green.
+6. Repeat for each new feature or bugfix.
+
+---
+
+## Important checks
+- **NEVER** disable functionality to hide a failure. Fix root cause.
+- **NEVER** create duplicate templates or files. Fix the original.
+- **NEVER** claim something is "working" when any functionality is disabled or broken.
+- If you can't open a file or access something requested, say so. Do not assume contents.
+- **ALWAYS** identify and fix the root cause of template or compilation errors.
+- If git is initialized, ensure a '.gitignore' exists and contains at least:
+
+  .env
+  .env.local
+  .env.*
+
+  Ask the human whether additional patterns should be added, and suggest any that you think are important given the project.
+
+## When to ask for human input
+Ask the human if any of the following is true:
+- A test type appears "not applicable". Use the exact phrase request: **"I AUTHORIZE YOU TO SKIP WRITING TESTS THIS TIME"**.
+- Required anchors conflict or are missing from upstream docs.
+- You need new environment variables or secrets.
+- An external dependency or major architectural change is required.
+- Design files are missing, unsupported or oversized
+
+(End of verbatim block)
+
+Minimal examples for checklist updates (copy/pasteable)
+- After completing a prompt step, add an entry under that step in prompt_plan.md similar to:
+  - [x] Step 5 — Implement POST /api/v1/query — tests green — manual checks: cURL example tested — README Release Notes updated — commit: "query: add /api/v1/query route, adapter integration, tests"
+- If pausing work:
+  - - [ ] (Deferred) Step 7.3 — Implement real Pinecone adapter — blocked on PINECONE_API_KEY (reason: waiting for dev key from infra)
+
+If anything is missing
+- If you cannot open prompt_plan.md, spec.md, idea.md, idea_one_pager.md, or any design file, stop and report exactly which file and why (permission/absent/parse error).
+- Ask for required secrets or permissions rather than guessing. Use the "When to ask for human input" rules above.
+
+Contact & escalation
+- When blocked on infra/secrets/design files, create a short note in prompt_plan.md under the current step and ping the human with:
+  - What I need: (e.g., PINECONE_API_KEY, AWS dev creds)
+  - Why I need it: (which step/blocker)
+  - Recommended minimal next action & fallback
+
+Notes
+- Keep AGENTS.md and the rest of the repo docs in sync. Update this file if workflow expectations change.
+
+End.