@stackmemoryai/stackmemory 1.2.2 → 1.2.4

package/templates/claude-hooks/cord-trace.js

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+
+/**
+ * Cord Trace Hook (PostToolUse)
+ *
+ * Fires on every cord_* MCP tool call, logging metrics to a JSONL trace file
+ * and accumulating session metrics in a per-session state file.
+ *
+ * Trace dir: ~/.stackmemory/cord-traces/
+ *   cord-trace-{date}.jsonl      — append-only trace log
+ *   cord-state-{session_id}.json — running session metrics
+ *
+ * Must complete in <50ms — pure file I/O only.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const HOME = process.env.HOME || '/tmp';
+const TRACE_DIR = path.join(HOME, '.stackmemory', 'cord-traces');
+const CORD_TOOLS = new Set([
+  'cord_spawn',
+  'cord_fork',
+  'cord_complete',
+  'cord_ask',
+  'cord_tree',
+]);
+
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+function safeWriteFile(filePath, content) {
+  const tmp = filePath + '.tmp';
+  fs.writeFileSync(tmp, content);
+  fs.renameSync(tmp, filePath);
+}
+
+/**
+ * Extract the cord tool name from the full MCP tool name.
+ * e.g. "mcp__stackmemory-refactored__cord_spawn" -> "cord_spawn"
+ */
+function extractCordTool(toolName) {
+  if (!toolName) return null;
+  for (const t of CORD_TOOLS) {
+    if (toolName.endsWith(t)) return t;
+  }
+  return null;
+}
+
+function loadState(sessionId) {
+  const stateFile = path.join(TRACE_DIR, `cord-state-${sessionId}.json`);
+  try {
+    if (fs.existsSync(stateFile)) {
+      return JSON.parse(fs.readFileSync(stateFile, 'utf-8'));
+    }
+  } catch {
+    // Corrupted state, start fresh
+  }
+  return {
+    session_id: sessionId,
+    started: new Date().toISOString(),
+    tool_counts: {},
+    task_ids: [],
+    context_modes: {},
+    unblocked_total: 0,
+    max_depth: 0,
+    completion_rate: 0,
+    ask_count: 0,
+    completed_count: 0,
+    spawn_fork_count: 0,
+  };
+}
+
+function saveState(sessionId, state) {
+  const stateFile = path.join(TRACE_DIR, `cord-state-${sessionId}.json`);
+  safeWriteFile(stateFile, JSON.stringify(state, null, 2));
+}
+
+function appendTrace(entry) {
+  const date = new Date().toISOString().slice(0, 10);
+  const traceFile = path.join(TRACE_DIR, `cord-trace-${date}.jsonl`);
+  fs.appendFileSync(traceFile, JSON.stringify(entry) + '\n');
+}
+
+/**
+ * Safely extract metadata from tool_response.
+ * MCP tool responses come as { content: [{ type, text }], metadata: {...} }.
+ * The hook receives tool_response which may be the raw MCP result or a string.
+ */
+function extractMetadata(toolResponse) {
+  if (!toolResponse) return {};
+  if (typeof toolResponse === 'string') {
+    try {
+      const parsed = JSON.parse(toolResponse);
+      return parsed.metadata || parsed;
+    } catch {
+      return {};
+    }
+  }
+  if (toolResponse.metadata) return toolResponse.metadata;
+  return toolResponse;
+}
+
+function updateState(state, cordTool, toolInput, toolResponse) {
+  // Increment tool count
+  state.tool_counts[cordTool] = (state.tool_counts[cordTool] || 0) + 1;
+
+  const meta = extractMetadata(toolResponse);
+
+  switch (cordTool) {
+    case 'cord_spawn':
+    case 'cord_fork': {
+      state.spawn_fork_count++;
+
+      // Track context mode
+      const mode = meta.context_mode || cordTool.replace('cord_', '');
+      state.context_modes[mode] = (state.context_modes[mode] || 0) + 1;
+
+      // Track task ID
+      if (meta.task_id && !state.task_ids.includes(meta.task_id)) {
+        state.task_ids.push(meta.task_id);
+      }
+
+      // Track max depth
+      const depth = meta.depth ?? 0;
+      if (depth > state.max_depth) {
+        state.max_depth = depth;
+      }
+      break;
+    }
+
+    case 'cord_complete': {
+      state.completed_count++;
+
+      // Count unblocked tasks
+      const unblocked = meta.unblocked;
+      if (Array.isArray(unblocked)) {
+        state.unblocked_total += unblocked.length;
+      }
+
+      // Update completion rate
+      if (state.spawn_fork_count > 0) {
+        state.completion_rate = +(
+          state.completed_count / state.spawn_fork_count
+        ).toFixed(3);
+      }
+      break;
+    }
+
+    case 'cord_ask': {
+      state.ask_count++;
+
+      // Track task ID
+      if (meta.task_id && !state.task_ids.includes(meta.task_id)) {
+        state.task_ids.push(meta.task_id);
+      }
+
+      // Track context mode
+      state.context_modes['ask'] = (state.context_modes['ask'] || 0) + 1;
+      break;
+    }
+
+    case 'cord_tree':
+      // Read-only — no state change
+      break;
+  }
+}
+
+function buildMetricsSummary(state) {
+  return {
+    task_count: state.task_ids.length,
+    active: state.spawn_fork_count - state.completed_count,
+    completed: state.completed_count,
+    asks: state.ask_count,
+  };
+}
+
+async function readInput() {
+  let input = '';
+  for await (const chunk of process.stdin) {
+    input += chunk;
+  }
+  return JSON.parse(input);
+}
+
+async function main() {
+  try {
+    const input = await readInput();
+    const { tool_name, tool_input, tool_response, session_id } = input;
+
+    const cordTool = extractCordTool(tool_name);
+    if (!cordTool) return; // Not a cord tool, shouldn't happen given matcher
+
+    const sid =
+      session_id || process.env.CLAUDE_INSTANCE_ID || String(process.ppid);
+
+    ensureDir(TRACE_DIR);
+
+    // Load and update state
+    const state = loadState(sid);
+    updateState(state, cordTool, tool_input, tool_response);
+
+    // Build trace entry
+    const entry = {
+      ts: new Date().toISOString(),
+      session_id: sid,
+      cwd: input.cwd || process.cwd(),
+      tool: cordTool,
+      input: tool_input || {},
+      response: extractMetadata(tool_response),
+      metrics: buildMetricsSummary(state),
+    };
+
+    // Append trace + save state
+    appendTrace(entry);
+    saveState(sid, state);
+  } catch {
+    // Silent fail — never block the agent
+  }
+}
+
+main();

package/dist/src/core/config/storage-config.js

@@ -1,114 +0,0 @@
-import { fileURLToPath as __fileURLToPath } from 'url';
-import { dirname as __pathDirname } from 'path';
-const __filename = __fileURLToPath(import.meta.url);
-const __dirname = __pathDirname(__filename);
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
-import { join } from "path";
-import { homedir } from "os";
-const DEFAULT_STORAGE_CONFIG = {
-  mode: "sqlite",
-  chromadb: {
-    enabled: false
-  }
-};
-const STACKMEMORY_DIR = join(homedir(), ".stackmemory");
-const CONFIG_FILE = join(STACKMEMORY_DIR, "storage-config.json");
-function loadStorageConfig() {
-  try {
-    if (existsSync(CONFIG_FILE)) {
-      const content = readFileSync(CONFIG_FILE, "utf-8");
-      const config = JSON.parse(content);
-      return {
-        mode: config.mode || DEFAULT_STORAGE_CONFIG.mode,
-        chromadb: {
-          ...DEFAULT_STORAGE_CONFIG.chromadb,
-          ...config.chromadb
-        }
-      };
-    }
-  } catch (error) {
-    console.warn("Failed to load storage config, using defaults:", error);
-  }
-  return DEFAULT_STORAGE_CONFIG;
-}
-function saveStorageConfig(config) {
-  try {
-    if (!existsSync(STACKMEMORY_DIR)) {
-      mkdirSync(STACKMEMORY_DIR, { recursive: true });
-    }
-    writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), "utf-8");
-  } catch (error) {
-    console.error("Failed to save storage config:", error);
-    throw error;
-  }
-}
-function isChromaDBEnabled() {
-  const config = loadStorageConfig();
-  if (!config.chromadb.enabled) {
-    return false;
-  }
-  const apiKey = config.chromadb.apiKey || process.env["CHROMADB_API_KEY"];
-  if (!apiKey) {
-    return false;
-  }
-  return true;
-}
-function getStorageMode() {
-  const config = loadStorageConfig();
-  if (config.mode === "hybrid" && !isChromaDBEnabled()) {
-    return "sqlite";
-  }
-  return config.mode;
-}
-function getChromaDBConfig() {
-  if (!isChromaDBEnabled()) {
-    return null;
-  }
-  const config = loadStorageConfig();
-  const apiKey = config.chromadb.apiKey || process.env["CHROMADB_API_KEY"];
-  const apiUrl = config.chromadb.apiUrl || process.env["CHROMADB_API_URL"] || "https://api.trychroma.com";
-  return {
-    enabled: true,
-    apiKey,
-    apiUrl,
-    tenant: config.chromadb.tenant || process.env["CHROMADB_TENANT"] || "default_tenant",
-    database: config.chromadb.database || process.env["CHROMADB_DATABASE"] || "default_database"
-  };
-}
-function enableChromaDB(chromaConfig) {
-  const config = loadStorageConfig();
-  config.mode = "hybrid";
-  config.chromadb = {
-    enabled: true,
-    apiKey: chromaConfig.apiKey,
-    apiUrl: chromaConfig.apiUrl || "https://api.trychroma.com",
-    tenant: chromaConfig.tenant || "default_tenant",
-    database: chromaConfig.database || "default_database"
-  };
-  saveStorageConfig(config);
-}
-function disableChromaDB() {
-  const config = loadStorageConfig();
-  config.mode = "sqlite";
-  config.chromadb = {
-    enabled: false
-  };
-  saveStorageConfig(config);
-}
-function getStorageModeDescription() {
-  const mode = getStorageMode();
-  if (mode === "hybrid") {
-    return "Hybrid (SQLite + ChromaDB for semantic search and cloud backup)";
-  }
-  return "SQLite (local storage only, fast, no external dependencies)";
-}
-export {
-  disableChromaDB,
-  enableChromaDB,
-  getChromaDBConfig,
-  getStorageMode,
-  getStorageModeDescription,
-  isChromaDBEnabled,
-  loadStorageConfig,
-  saveStorageConfig
-};

package/dist/src/core/storage/chromadb-adapter.js

@@ -1,379 +0,0 @@
-import { fileURLToPath as __fileURLToPath } from 'url';
-import { dirname as __pathDirname } from 'path';
-const __filename = __fileURLToPath(import.meta.url);
-const __dirname = __pathDirname(__filename);
-import { v4 as uuidv4 } from "uuid";
-import { Logger } from "../monitoring/logger.js";
-let chromadbModule = null;
-async function getChromaDB() {
-  if (!chromadbModule) {
-    try {
-      chromadbModule = await import("chromadb");
-    } catch {
-      throw new Error(
-        "chromadb is not installed. Install it with: npm install chromadb"
-      );
-    }
-  }
-  return chromadbModule;
-}
-class ChromaDBAdapter {
-  client = null;
-  collection = null;
-  logger;
-  config;
-  userId;
-  teamId;
-  constructor(config, userId, teamId) {
-    this.config = config;
-    this.userId = userId;
-    this.teamId = teamId;
-    this.logger = new Logger("ChromaDBAdapter");
-  }
-  /**
-   * Factory method to create and initialize the adapter
-   */
-  static async create(config, userId, teamId) {
-    const adapter = new ChromaDBAdapter(config, userId, teamId);
-    await adapter.initClient();
-    return adapter;
-  }
-  async initClient() {
-    const chromadb = await getChromaDB();
-    this.client = new chromadb.CloudClient({
-      apiKey: this.config.apiKey,
-      tenant: this.config.tenant,
-      database: this.config.database
-    });
-  }
-  async initialize() {
-    try {
-      if (!this.client) {
-        await this.initClient();
-      }
-      const collectionName = this.config.collectionName || "stackmemory_contexts";
-      this.collection = await this.client.getOrCreateCollection({
-        name: collectionName,
-        metadata: {
-          description: "StackMemory context storage",
-          version: "1.0.0",
-          created_at: (/* @__PURE__ */ new Date()).toISOString()
-        }
-      });
-      this.logger.info(`ChromaDB collection '${collectionName}' initialized`);
-    } catch (error) {
-      this.logger.error("Failed to initialize ChromaDB collection", error);
-      throw error;
-    }
-  }
-  /**
-   * Store a frame in ChromaDB
-   */
-  async storeFrame(frame) {
-    if (!this.collection) {
-      throw new Error("ChromaDB not initialized");
-    }
-    try {
-      const frameMetadata = {
-        user_id: this.userId,
-        frame_id: frame.frameId,
-        session_id: frame.sessionId || "unknown",
-        project_name: frame.projectName || "default",
-        timestamp: frame.timestamp,
-        type: "frame",
-        score: frame.score,
-        tags: frame.tags || []
-      };
-      if (this.teamId) {
-        frameMetadata.team_id = this.teamId;
-      }
-      const document = {
-        id: `frame_${frame.frameId}_${this.userId}`,
-        document: this.frameToDocument(frame),
-        metadata: frameMetadata
-      };
-      await this.collection.add({
-        ids: [document.id],
-        documents: [document.document],
-        metadatas: [document.metadata]
-      });
-      this.logger.debug(
-        `Stored frame ${frame.frameId} for user ${this.userId}`
-      );
-    } catch (error) {
-      this.logger.error(`Failed to store frame ${frame.frameId}`, error);
-      throw error;
-    }
-  }
-  /**
-   * Store a decision or observation
-   */
-  async storeContext(type, content, metadata) {
-    if (!this.collection) {
-      throw new Error("ChromaDB not initialized");
-    }
-    try {
-      const contextId = `${type}_${uuidv4()}_${this.userId}`;
-      const documentMetadata = {
-        user_id: this.userId,
-        frame_id: metadata?.frame_id || "none",
-        session_id: metadata?.session_id || "unknown",
-        project_name: metadata?.project_name || "default",
-        timestamp: Date.now(),
-        type,
-        ...metadata
-      };
-      if (this.teamId) {
-        documentMetadata.team_id = this.teamId;
-      }
-      const document = {
-        id: contextId,
-        document: content,
-        metadata: documentMetadata
-      };
-      await this.collection.add({
-        ids: [document.id],
-        documents: [document.document],
-        metadatas: [document.metadata]
-      });
-      this.logger.debug(`Stored ${type} for user ${this.userId}`);
-    } catch (error) {
-      this.logger.error(`Failed to store ${type}`, error);
-      throw error;
-    }
-  }
-  /**
-   * Query contexts by semantic similarity
-   */
-  async queryContexts(query, limit = 10, filters) {
-    if (!this.collection) {
-      throw new Error("ChromaDB not initialized");
-    }
-    try {
-      const whereClause = {
-        user_id: this.userId
-      };
-      if (this.teamId) {
-        whereClause["$or"] = [
-          { team_id: this.teamId },
-          { user_id: this.userId }
-        ];
-      }
-      if (filters?.type && filters.type.length > 0) {
-        whereClause.type = { $in: filters.type };
-      }
-      if (filters?.projectName) {
-        whereClause.project_name = filters.projectName;
-      }
-      if (filters?.sessionId) {
-        whereClause.session_id = filters.sessionId;
-      }
-      if (filters?.startTime || filters?.endTime) {
-        whereClause.timestamp = {};
-        if (filters.startTime) {
-          whereClause.timestamp.$gte = filters.startTime;
-        }
-        if (filters.endTime) {
-          whereClause.timestamp.$lte = filters.endTime;
-        }
-      }
-      const results = await this.collection.query({
-        queryTexts: [query],
-        nResults: limit,
-        where: whereClause,
-        include: ["documents", "metadatas", "distances"]
-      });
-      const contexts = [];
-      if (results.documents && results.documents[0]) {
-        for (let i = 0; i < results.documents[0].length; i++) {
-          contexts.push({
-            content: results.documents[0][i] || "",
-            metadata: results.metadatas?.[0]?.[i] || {},
-            distance: results.distances?.[0]?.[i] || 0
-          });
-        }
-      }
-      this.logger.debug(`Found ${contexts.length} contexts for query`);
-      return contexts;
-    } catch (error) {
-      this.logger.error("Failed to query contexts", error);
-      throw error;
-    }
-  }
-  /**
-   * Get user's recent contexts
-   */
-  async getRecentContexts(limit = 20, type) {
-    if (!this.collection) {
-      throw new Error("ChromaDB not initialized");
-    }
-    try {
-      const whereClause = {
-        user_id: this.userId
-      };
-      if (type) {
-        whereClause.type = type;
-      }
-      const results = await this.collection.get({
-        where: whereClause,
-        include: ["documents", "metadatas"]
-      });
-      const contexts = [];
-      if (results.documents) {
-        const indexed = results.documents.map((doc, i) => ({
-          content: doc || "",
-          metadata: results.metadatas?.[i] || {}
-        }));
-        indexed.sort(
-          (a, b) => (b.metadata.timestamp || 0) - (a.metadata.timestamp || 0)
-        );
-        contexts.push(...indexed.slice(0, limit));
-      }
-      return contexts;
-    } catch (error) {
-      this.logger.error("Failed to get recent contexts", error);
-      throw error;
-    }
-  }
-  /**
-   * Delete old contexts (retention policy)
-   */
-  async deleteOldContexts(olderThanDays = 30) {
-    if (!this.collection) {
-      throw new Error("ChromaDB not initialized");
-    }
-    try {
-      const cutoffTime = Date.now() - olderThanDays * 24 * 60 * 60 * 1e3;
-      const results = await this.collection.get({
-        where: {
-          user_id: this.userId,
-          timestamp: { $lt: cutoffTime }
-        },
-        include: ["ids"]
-      });
-      if (!results.ids || results.ids.length === 0) {
-        return 0;
-      }
-      await this.collection.delete({
-        ids: results.ids
-      });
-      this.logger.info(`Deleted ${results.ids.length} old contexts`);
-      return results.ids.length;
-    } catch (error) {
-      this.logger.error("Failed to delete old contexts", error);
-      throw error;
-    }
-  }
-  /**
-   * Get team contexts (if user is part of a team)
-   */
-  async getTeamContexts(limit = 20) {
-    if (!this.collection || !this.teamId) {
-      return [];
-    }
-    try {
-      const results = await this.collection.get({
-        where: {
-          team_id: this.teamId
-        },
-        include: ["documents", "metadatas"],
-        limit
-      });
-      const contexts = [];
-      if (results.documents) {
-        for (let i = 0; i < results.documents.length; i++) {
-          contexts.push({
-            content: results.documents[i] || "",
-            metadata: results.metadatas?.[i] || {}
-          });
-        }
-      }
-      return contexts;
-    } catch (error) {
-      this.logger.error("Failed to get team contexts", error);
-      return [];
-    }
-  }
-  /**
-   * Convert frame to searchable document
-   */
-  frameToDocument(frame) {
-    const parts = [
-      `Frame: ${frame.title}`,
-      `Type: ${frame.type}`,
-      `Status: ${frame.status}`
-    ];
-    if (frame.description) {
-      parts.push(`Description: ${frame.description}`);
-    }
-    if (frame.inputs && frame.inputs.length > 0) {
-      parts.push(`Inputs: ${frame.inputs.join(", ")}`);
-    }
-    if (frame.outputs && frame.outputs.length > 0) {
-      parts.push(`Outputs: ${frame.outputs.join(", ")}`);
-    }
-    if (frame.tags && frame.tags.length > 0) {
-      parts.push(`Tags: ${frame.tags.join(", ")}`);
-    }
-    if (frame.digest_json) {
-      try {
-        const digest = JSON.parse(frame.digest_json);
-        if (digest.summary) {
-          parts.push(`Summary: ${digest.summary}`);
-        }
-        if (digest.keyDecisions) {
-          parts.push(`Decisions: ${digest.keyDecisions.join(". ")}`);
-        }
-      } catch {
-      }
-    }
-    return parts.join("\n");
-  }
-  /**
-   * Update team ID for a user
-   */
-  async updateTeamId(newTeamId) {
-    this.teamId = newTeamId;
-    this.logger.info(`Updated team ID to ${newTeamId} for user ${this.userId}`);
-  }
-  /**
-   * Get storage statistics
-   */
-  async getStats() {
-    if (!this.collection) {
-      throw new Error("ChromaDB not initialized");
-    }
-    try {
-      const userResults = await this.collection.get({
-        where: { user_id: this.userId },
-        include: ["metadatas"]
-      });
-      const stats = {
-        totalDocuments: 0,
-        userDocuments: userResults.ids?.length || 0,
-        documentsByType: {}
-      };
-      if (userResults.metadatas) {
-        for (const metadata of userResults.metadatas) {
-          const type = metadata?.type || "unknown";
-          stats.documentsByType[type] = (stats.documentsByType[type] || 0) + 1;
-        }
-      }
-      if (this.teamId) {
-        const teamResults = await this.collection.get({
-          where: { team_id: this.teamId },
-          include: ["ids"]
-        });
-        stats.teamDocuments = teamResults.ids?.length || 0;
-      }
-      stats.totalDocuments = stats.userDocuments + (stats.teamDocuments || 0);
-      return stats;
-    } catch (error) {
-      this.logger.error("Failed to get stats", error);
-      throw error;
-    }
-  }
-}
-export {
-  ChromaDBAdapter
-};