@stackmemoryai/stackmemory 1.10.5 → 1.14.0

package/dist/src/core/provenance/provenance-store.js

@@ -0,0 +1,194 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import { logger } from "../monitoring/logger.js";
+import { TraceEventSchema } from "./types.js";
+class ProvenanceStore {
+  db;
+  constructor(db) {
+    this.db = db;
+    this.initializeSchema();
+  }
+  /**
+   * Initialize database schema for trace events
+   */
+  initializeSchema() {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS trace_events (
+        trace_id TEXT PRIMARY KEY,
+        session_id TEXT NOT NULL,
+        parent_trace_id TEXT,
+        tenant_id TEXT NOT NULL,
+        timestamp TEXT NOT NULL,
+        actor TEXT NOT NULL,
+        operation TEXT NOT NULL,
+        inputs TEXT NOT NULL,
+        outputs TEXT NOT NULL,
+        tokens_in INTEGER NOT NULL DEFAULT 0,
+        tokens_out INTEGER NOT NULL DEFAULT 0,
+        cost_usd REAL NOT NULL DEFAULT 0,
+        score REAL,
+        feedback TEXT,
+        provenance TEXT NOT NULL,
+        created_at INTEGER DEFAULT (unixepoch())
+      )
+    `);
+    this.db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_trace_events_session_id ON trace_events(session_id);
+      CREATE INDEX IF NOT EXISTS idx_trace_events_tenant_id ON trace_events(tenant_id);
+      CREATE INDEX IF NOT EXISTS idx_trace_events_operation ON trace_events(operation);
+      CREATE INDEX IF NOT EXISTS idx_trace_events_timestamp ON trace_events(timestamp);
+      CREATE INDEX IF NOT EXISTS idx_trace_events_parent_trace_id ON trace_events(parent_trace_id);
+    `);
+  }
+  /**
+   * Record a trace event
+   */
+  record(event) {
+    const stmt = this.db.prepare(`
+      INSERT OR REPLACE INTO trace_events (
+        trace_id, session_id, parent_trace_id, tenant_id, timestamp,
+        actor, operation, inputs, outputs,
+        tokens_in, tokens_out, cost_usd, score, feedback, provenance
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+    try {
+      stmt.run(
+        event.traceId,
+        event.sessionId,
+        event.parentTraceId ?? null,
+        event.tenantId,
+        event.timestamp,
+        JSON.stringify(event.actor),
+        event.operation,
+        JSON.stringify(event.inputs),
+        JSON.stringify(event.outputs),
+        event.tokensIn,
+        event.tokensOut,
+        event.costUsd,
+        event.score ?? null,
+        event.feedback ?? null,
+        JSON.stringify(event.provenance)
+      );
+      logger.debug(`Recorded trace event ${event.traceId}`);
+    } catch (error) {
+      logger.error(
+        `Failed to record trace event ${event.traceId}:`,
+        error
+      );
+      throw error;
+    }
+  }
+  /**
+   * Get a trace event by traceId
+   */
+  get(traceId) {
+    const row = this.db.prepare("SELECT * FROM trace_events WHERE trace_id = ?").get(traceId);
+    if (!row) return void 0;
+    return this.rowToEvent(row);
+  }
+  /**
+   * Query trace events with filters
+   */
+  query(opts = {}) {
+    const conditions = [];
+    const params = [];
+    if (opts.sessionId) {
+      conditions.push("session_id = ?");
+      params.push(opts.sessionId);
+    }
+    if (opts.tenantId) {
+      conditions.push("tenant_id = ?");
+      params.push(opts.tenantId);
+    }
+    if (opts.operation) {
+      conditions.push("operation = ?");
+      params.push(opts.operation);
+    }
+    if (opts.since) {
+      conditions.push("timestamp >= ?");
+      params.push(opts.since);
+    }
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+    const limit = opts.limit ?? 100;
+    const rows = this.db.prepare(
+      `SELECT * FROM trace_events ${where} ORDER BY timestamp DESC LIMIT ?`
+    ).all(...params, limit);
+    return rows.map((row) => this.rowToEvent(row));
+  }
+  /**
+   * Mark a trace event as superseded by another
+   */
+  supersede(traceId, supersededBy) {
+    const row = this.db.prepare("SELECT provenance FROM trace_events WHERE trace_id = ?").get(traceId);
+    if (!row) return;
+    const provenance = JSON.parse(row.provenance);
+    provenance.supersededBy = supersededBy;
+    this.db.prepare("UPDATE trace_events SET provenance = ? WHERE trace_id = ?").run(JSON.stringify(provenance), traceId);
+  }
+  /**
+   * Follow parentTraceId chain to build lineage
+   */
+  getLineage(traceId) {
+    const lineage = [];
+    let currentId = traceId;
+    while (currentId) {
+      const event = this.get(currentId);
+      if (!event) break;
+      lineage.push(event);
+      currentId = event.parentTraceId;
+    }
+    return lineage;
+  }
+  /**
+   * Aggregate stats across trace events
+   */
+  getStats(tenantId) {
+    const where = tenantId ? "WHERE tenant_id = ?" : "";
+    const params = tenantId ? [tenantId] : [];
+    const row = this.db.prepare(
+      `
+        SELECT
+          COUNT(*) as total_events,
+          COALESCE(SUM(tokens_in), 0) as total_tokens_in,
+          COALESCE(SUM(tokens_out), 0) as total_tokens_out,
+          COALESCE(SUM(cost_usd), 0) as total_cost_usd,
+          COALESCE(AVG(json_extract(provenance, '$.confidence')), 0) as avg_confidence
+        FROM trace_events ${where}
+      `
+    ).get(...params);
+    return {
+      totalEvents: row.total_events,
+      totalTokensIn: row.total_tokens_in,
+      totalTokensOut: row.total_tokens_out,
+      totalCostUsd: row.total_cost_usd,
+      avgConfidence: row.avg_confidence
+    };
+  }
+  /**
+   * Convert a database row to a TraceEvent
+   */
+  rowToEvent(row) {
+    return TraceEventSchema.parse({
+      timestamp: row.timestamp,
+      sessionId: row.session_id,
+      traceId: row.trace_id,
+      parentTraceId: row.parent_trace_id ?? void 0,
+      tenantId: row.tenant_id,
+      actor: JSON.parse(row.actor),
+      operation: row.operation,
+      inputs: JSON.parse(row.inputs),
+      outputs: JSON.parse(row.outputs),
+      tokensIn: row.tokens_in,
+      tokensOut: row.tokens_out,
+      costUsd: row.cost_usd,
+      score: row.score ?? void 0,
+      feedback: row.feedback ?? void 0,
+      provenance: JSON.parse(row.provenance)
+    });
+  }
+}
+export {
+  ProvenanceStore
+};

package/dist/src/core/provenance/types.js

@@ -0,0 +1,82 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import { z } from "zod";
+const SourceRefSchema = z.object({
+  system: z.string(),
+  // e.g., "linear", "github", "slack", "manual"
+  externalId: z.string(),
+  // ID in source system
+  url: z.string().optional(),
+  // link to source
+  fetchedAt: z.string().datetime(),
+  // ISO8601
+  hash: z.string().optional()
+  // content hash for change detection
+});
+const ProvenanceRecordSchema = z.object({
+  sources: z.array(SourceRefSchema),
+  derivation: z.array(z.string()),
+  // chain of transformations
+  confidence: z.number().min(0).max(1),
+  supersededBy: z.string().optional(),
+  // ID of superseding record
+  programVersion: z.string().optional()
+  // version that produced this
+});
+const ActorSchema = z.object({
+  host: z.string(),
+  // e.g., "claude-code", "cursor", "codex"
+  agent: z.string(),
+  // agent identifier
+  user: z.string()
+  // user identifier
+});
+const TraceEventSchema = z.object({
+  timestamp: z.string().datetime(),
+  // ISO8601
+  sessionId: z.string(),
+  traceId: z.string(),
+  parentTraceId: z.string().optional(),
+  tenantId: z.string(),
+  actor: ActorSchema,
+  operation: z.string(),
+  // what happened
+  inputs: z.unknown(),
+  outputs: z.unknown(),
+  tokensIn: z.number().int().min(0),
+  tokensOut: z.number().int().min(0),
+  costUsd: z.number().min(0),
+  score: z.number().optional(),
+  // numeric eval (ASI-shaped)
+  feedback: z.string().optional(),
+  // textual feedback for GEPA
+  provenance: ProvenanceRecordSchema
+});
+const ConfidenceClassificationSchema = z.enum([
+  "accept",
+  "review",
+  "discard"
+]);
+const ConfidenceScoreSchema = z.object({
+  confidence: z.number().min(0).max(1),
+  signals: z.record(z.string(), z.unknown()),
+  classification: ConfidenceClassificationSchema
+});
+const ConfidenceConfigSchema = z.object({
+  thresholds: z.object({
+    accept: z.number().min(0).max(1),
+    review: z.number().min(0).max(1)
+  }),
+  weights: z.record(z.string(), z.number())
+});
+export {
+  ActorSchema,
+  ConfidenceClassificationSchema,
+  ConfidenceConfigSchema,
+  ConfidenceScoreSchema,
+  ProvenanceRecordSchema,
+  SourceRefSchema,
+  TraceEventSchema
+};

package/dist/src/core/retrieval/llm-context-retrieval.js

@@ -8,6 +8,7 @@ import {
   DEFAULT_RETRIEVAL_CONFIG
 } from "./types.js";
 import { logger } from "../monitoring/logger.js";
+import { estimateTokens } from "../cache/token-estimator.js";
 import { LazyContextLoader } from "../performance/lazy-context-loader.js";
 import { ContextCache } from "../performance/context-cache.js";
 import { createLLMProvider } from "./llm-provider.js";
@@ -113,11 +114,11 @@ class HeuristicAnalyzer {
     let tokens = 50;
     tokens += frame.eventCount * 30;
     tokens += frame.anchorCount * 40;
-    if (frame.digestPreview) tokens += frame.digestPreview.length / 4;
+    if (frame.digestPreview) tokens += estimateTokens(frame.digestPreview);
     return Math.floor(tokens);
   }
   estimateSummaryTokens(summary) {
-    return Math.floor(JSON.stringify(summary).length / 4);
+    return estimateTokens(JSON.stringify(summary));
   }
   assessQueryComplexity(query, parsedQuery) {
     const wordCount = query.split(/\s+/).length;
@@ -428,8 +429,8 @@ Respond with only the JSON object, no other text.`;
         })),
         metadata: {
           analysisTimeMs: 0,
-          summaryTokens: Math.floor(
-            JSON.stringify(request.compressedSummary).length / 4
+          summaryTokens: estimateTokens(
+            JSON.stringify(request.compressedSummary)
           ),
           queryComplexity: this.assessQueryComplexity(request.currentQuery),
           matchedPatterns: [],

package/dist/src/core/retrieval/unified-context-assembler.js

@@ -6,6 +6,7 @@ import {
   createPrivacyFilter
 } from "./privacy-filter.js";
 import { logger } from "../monitoring/logger.js";
+import { estimateTokens } from "../cache/token-estimator.js";
 const DEFAULT_UNIFIED_CONTEXT_CONFIG = {
   totalTokenBudget: 8e3,
   userKnowledgeBudget: 0.2,
@@ -16,10 +17,6 @@ const DEFAULT_UNIFIED_CONTEXT_CONFIG = {
   // 10%
   privacyMode: "standard"
 };
-function estimateTokens(content) {
-  if (!content) return 0;
-  return Math.ceil(content.length / 4);
-}
 function truncateToTokenBudget(content, tokenBudget) {
   if (!content) return "";
   const estimatedTokens = estimateTokens(content);
@@ -36,12 +33,10 @@ function truncateToTokenBudget(content, tokenBudget) {
 }
 class UnifiedContextAssembler {
   stackMemoryRetrieval;
-  diffMemHooks;
   config;
   privacyFilter;
-  constructor(stackMemoryRetrieval, diffMemHooks, config = {}) {
+  constructor(stackMemoryRetrieval, config = {}) {
     this.stackMemoryRetrieval = stackMemoryRetrieval;
-    this.diffMemHooks = diffMemHooks;
     this.config = { ...DEFAULT_UNIFIED_CONTEXT_CONFIG, ...config };
     this.privacyFilter = createPrivacyFilter(this.config.privacyMode);
     const totalAllocation = this.config.userKnowledgeBudget + this.config.taskContextBudget + this.config.systemContextBudget;
@@ -69,11 +64,10 @@ class UnifiedContextAssembler {
     const systemContextBudget = Math.floor(
       this.config.totalTokenBudget * this.config.systemContextBudget
     );
-    const {
-      content: userKnowledge,
-      memories: diffMemMemories,
-      available: diffMemAvailable
-    } = await this.gatherUserKnowledge(query, userKnowledgeBudget);
+    const { content: userKnowledge } = await this.gatherUserKnowledge(
+      query,
+      userKnowledgeBudget
+    );
     const userKnowledgeFiltered = this.privacyFilter.filter(userKnowledge);
     totalPrivacyFiltered += userKnowledgeFiltered.redactedCount;
     const filteredUserKnowledge = truncateToTokenBudget(
@@ -110,8 +104,6 @@ class UnifiedContextAssembler {
       budget: this.config.totalTokenBudget
     };
     const metadata = {
-      diffMemAvailable,
-      diffMemMemories,
       stackMemoryFrames: frameCount,
       privacyFiltered: totalPrivacyFiltered
     };
@@ -131,53 +123,10 @@ class UnifiedContextAssembler {
     };
   }
   /**
-   * Gather user knowledge from DiffMem
-   */
-  async gatherUserKnowledge(query, tokenBudget) {
-    if (!this.diffMemHooks) {
-      return { content: "", memories: 0, available: false };
-    }
-    try {
-      const status = await this.diffMemHooks.getStatus();
-      if (!status.connected) {
-        logger.debug("DiffMem not connected");
-        return { content: "", memories: 0, available: false };
-      }
-      const memories = await this.diffMemHooks.getRelevantMemories(query, 10);
-      if (memories.length === 0) {
-        return { content: "", memories: 0, available: true };
-      }
-      const sections = ["## User Knowledge"];
-      const byCategory = /* @__PURE__ */ new Map();
-      for (const memory of memories) {
-        const existing = byCategory.get(memory.category) || [];
-        existing.push(memory);
-        byCategory.set(memory.category, existing);
-      }
-      for (const [category, categoryMemories] of byCategory) {
-        sections.push(`
-### ${this.formatCategory(category)}`);
-        for (const memory of categoryMemories) {
-          const confidence = memory.confidence >= 0.8 ? "(high confidence)" : memory.confidence >= 0.5 ? "" : "(tentative)";
-          sections.push(`- ${memory.content} ${confidence}`);
-        }
-      }
-      const content = sections.join("\n");
-      return {
-        content: truncateToTokenBudget(content, tokenBudget),
-        memories: memories.length,
-        available: true
-      };
-    } catch (error) {
-      logger.warn("Failed to gather user knowledge from DiffMem", { error });
-      return { content: "", memories: 0, available: false };
-    }
-  }
-  /**
-   * Format category name for display
+   * Gather user knowledge (stub — memory service removed in v1.14)
    */
-  formatCategory(category) {
-    return category.split("_").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+  async gatherUserKnowledge(_query, _tokenBudget) {
+    return { content: "", memories: 0, available: false };
   }
   /**
    * Gather task context from StackMemory
@@ -258,12 +207,8 @@ class UnifiedContextAssembler {
     }
   }
 }
-function createUnifiedContextAssembler(stackMemoryRetrieval, diffMemHooks = null, config = {}) {
-  return new UnifiedContextAssembler(
-    stackMemoryRetrieval,
-    diffMemHooks,
-    config
-  );
+function createUnifiedContextAssembler(stackMemoryRetrieval, config = {}) {
+  return new UnifiedContextAssembler(stackMemoryRetrieval, config);
 }
 export {
   DEFAULT_UNIFIED_CONTEXT_CONFIG,

package/dist/src/core/session/project-handoff.js

@@ -0,0 +1,64 @@
+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 } from "fs";
+import { join } from "path";
+function getProjectHandoffPaths(projectRoot) {
+  return {
+    handoffPath: join(projectRoot, ".stackmemory", "last-handoff.md"),
+    metadataPath: join(projectRoot, ".stackmemory", "last-handoff-meta.json")
+  };
+}
+function parseBranchFromHandoffContent(content) {
+  const compactMatch = content.match(/^# Handoff:\s+.+?@([^\n]+)$/m);
+  if (compactMatch?.[1]) {
+    return compactMatch[1].trim();
+  }
+  const verboseMatch = content.match(/^\*\*Branch\*\*:\s+([^\n]+)$/m);
+  if (verboseMatch?.[1]) {
+    return verboseMatch[1].trim();
+  }
+  const ultraMatch = content.match(/^\[H\].+?@([^|\n]+)\|/m);
+  if (ultraMatch?.[1]) {
+    return ultraMatch[1].trim();
+  }
+  return null;
+}
+function loadProjectHandoff(projectRoot, currentBranch) {
+  const { handoffPath, metadataPath } = getProjectHandoffPaths(projectRoot);
+  if (!existsSync(handoffPath)) {
+    return null;
+  }
+  const content = readFileSync(handoffPath, "utf8").trim();
+  if (!content) {
+    return null;
+  }
+  let metadata = null;
+  if (existsSync(metadataPath)) {
+    try {
+      metadata = JSON.parse(readFileSync(metadataPath, "utf8"));
+    } catch {
+      metadata = null;
+    }
+  }
+  const branch = metadata?.branch || parseBranchFromHandoffContent(content);
+  if (currentBranch && branch && branch !== currentBranch) {
+    return {
+      content,
+      branch,
+      compatible: false,
+      mismatchReason: `handoff is for branch ${branch}, current branch is ${currentBranch}`
+    };
+  }
+  return {
+    content,
+    branch: branch || null,
+    compatible: true
+  };
+}
+export {
+  getProjectHandoffPaths,
+  loadProjectHandoff,
+  parseBranchFromHandoffContent
+};

package/dist/src/core/session/session-manager.js

@@ -7,6 +7,7 @@ import * as fs from "fs/promises";
 import * as path from "path";
 import { logger } from "../monitoring/logger.js";
 import { SystemError, ErrorCode } from "../errors/index.js";
+import { canonicalStateStore } from "../shared-state/canonical-store.js";
 function _getEnv(key, defaultValue) {
   const value = process.env[key];
   if (value === void 0) {
@@ -119,6 +120,16 @@ class SessionManager {
     };
     await this.saveSession(session);
     await this.setProjectActiveSession(params.projectId, session.sessionId);
+    await canonicalStateStore.appendEvent({
+      type: "session_created",
+      tool: "stackmemory",
+      sessionId: session.sessionId,
+      projectId: session.projectId,
+      branch: session.branch,
+      payload: {
+        state: session.state
+      }
+    });
     this.currentSession = session;
     logger.info("Created new session", {
       sessionId: session.sessionId,
@@ -152,6 +163,14 @@ class SessionManager {
       `${session.sessionId}.json`
     );
     await fs.writeFile(sessionPath, JSON.stringify(session, null, 2));
+    await canonicalStateStore.upsertSession({
+      sessionId: session.sessionId,
+      tool: "stackmemory",
+      projectId: session.projectId,
+      branch: session.branch,
+      status: session.state,
+      metadata: session.metadata
+    });
   }
   async suspendSession(sessionId) {
     const id = sessionId || this.currentSession?.sessionId;
@@ -193,6 +212,15 @@ class SessionManager {
         `${session.sessionId}.json`
       );
       await fs.rename(sessionPath, historyPath);
+      await canonicalStateStore.endSession(session.sessionId, "closed");
+      await canonicalStateStore.appendEvent({
+        type: "session_closed",
+        tool: "stackmemory",
+        sessionId: session.sessionId,
+        projectId: session.projectId,
+        branch: session.branch,
+        payload: {}
+      });
     }
   }
   async listSessions(filter) {