@hasna/mementos 0.11.1 → 0.14.0

package/dist/server/index.js

@@ -4,6 +4,7 @@ var __create = Object.create;
 var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __toESM = (mod, isNodeMode, target) => {
   target = mod != null ? __create(__getProtoOf(mod)) : {};
@@ -16,6 +17,20 @@ var __toESM = (mod, isNodeMode, target) => {
       });
   return to;
 };
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
@@ -92,6 +107,17 @@ var init_types = __esm(() => {
 });
 
 // src/db/database.ts
+var exports_database = {};
+__export(exports_database, {
+  uuid: () => uuid,
+  shortUuid: () => shortUuid,
+  resolvePartialId: () => resolvePartialId,
+  resetDatabase: () => resetDatabase,
+  now: () => now,
+  getDbPath: () => getDbPath,
+  getDatabase: () => getDatabase,
+  closeDatabase: () => closeDatabase
+});
 import { Database } from "bun:sqlite";
 import { existsSync, mkdirSync } from "fs";
 import { dirname, join, resolve } from "path";
@@ -177,6 +203,15 @@ function runMigrations(db) {
     }
   }
 }
+function closeDatabase() {
+  if (_db) {
+    _db.close();
+    _db = null;
+  }
+}
+function resetDatabase() {
+  _db = null;
+}
 function now() {
   return new Date().toISOString();
 }
@@ -902,6 +937,44 @@ CREATE INDEX IF NOT EXISTS idx_memory_embeddings_model ON memory_embeddings(mode
 
 PRAGMA foreign_keys = ON;
 INSERT OR IGNORE INTO _migrations (id) VALUES (29);
+`,
+    `
+ALTER TABLE memories ADD COLUMN when_to_use TEXT DEFAULT NULL;
+CREATE INDEX IF NOT EXISTS idx_memories_when_to_use ON memories(when_to_use) WHERE when_to_use IS NOT NULL;
+ALTER TABLE memory_versions ADD COLUMN when_to_use TEXT;
+INSERT OR IGNORE INTO _migrations (id) VALUES (30);
+`,
+    `
+CREATE TABLE IF NOT EXISTS tool_events (
+  id TEXT PRIMARY KEY,
+  tool_name TEXT NOT NULL,
+  action TEXT,
+  success INTEGER NOT NULL DEFAULT 1,
+  error_type TEXT CHECK(error_type IS NULL OR error_type IN ('timeout', 'permission', 'not_found', 'syntax', 'rate_limit', 'other')),
+  error_message TEXT,
+  tokens_used INTEGER,
+  latency_ms INTEGER,
+  context TEXT,
+  lesson TEXT,
+  when_to_use TEXT,
+  agent_id TEXT REFERENCES agents(id) ON DELETE SET NULL,
+  project_id TEXT REFERENCES projects(id) ON DELETE SET NULL,
+  session_id TEXT,
+  metadata TEXT DEFAULT '{}',
+  created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+CREATE INDEX IF NOT EXISTS idx_tool_events_tool_name ON tool_events(tool_name);
+CREATE INDEX IF NOT EXISTS idx_tool_events_agent ON tool_events(agent_id);
+CREATE INDEX IF NOT EXISTS idx_tool_events_project ON tool_events(project_id);
+CREATE INDEX IF NOT EXISTS idx_tool_events_success ON tool_events(success);
+CREATE INDEX IF NOT EXISTS idx_tool_events_created ON tool_events(created_at);
+INSERT OR IGNORE INTO _migrations (id) VALUES (31);
+`,
+    `
+ALTER TABLE memories ADD COLUMN sequence_group TEXT DEFAULT NULL;
+ALTER TABLE memories ADD COLUMN sequence_order INTEGER DEFAULT NULL;
+CREATE INDEX IF NOT EXISTS idx_memories_sequence_group ON memories(sequence_group) WHERE sequence_group IS NOT NULL;
+INSERT OR IGNORE INTO _migrations (id) VALUES (32);
 `
   ];
 });
@@ -1249,6 +1322,9 @@ function parseMemoryRow(row) {
     session_id: row["session_id"] || null,
     machine_id: row["machine_id"] || null,
     flag: row["flag"] || null,
+    when_to_use: row["when_to_use"] || null,
+    sequence_group: row["sequence_group"] || null,
+    sequence_order: row["sequence_order"] ?? null,
     content_type: row["content_type"] || "text",
     namespace: row["namespace"] || null,
     created_by_agent: row["created_by_agent"] || null,
@@ -1307,6 +1383,7 @@ function createMemory(input, dedupeMode = "merge", db) {
       d.run(`UPDATE memories SET
            value = ?, category = ?, summary = ?, tags = ?,
            importance = ?, metadata = ?, expires_at = ?,
+           when_to_use = ?,
            pinned = COALESCE(pinned, 0),
            version = version + 1, updated_at = ?
          WHERE id = ?`, [
@@ -1317,6 +1394,7 @@ function createMemory(input, dedupeMode = "merge", db) {
         input.importance ?? 5,
         metadataJson,
         expiresAt,
+        input.when_to_use || null,
         timestamp,
         existing.id
       ]);
@@ -1341,8 +1419,8 @@ function createMemory(input, dedupeMode = "merge", db) {
       return merged;
     }
   }
-  d.run(`INSERT INTO memories (id, key, value, category, scope, summary, tags, importance, source, status, pinned, agent_id, project_id, session_id, machine_id, namespace, created_by_agent, metadata, access_count, version, expires_at, valid_from, valid_until, ingested_at, created_at, updated_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'active', 0, ?, ?, ?, ?, ?, ?, ?, 0, 1, ?, ?, ?, ?, ?, ?)`, [
+  d.run(`INSERT INTO memories (id, key, value, category, scope, summary, tags, importance, source, status, pinned, agent_id, project_id, session_id, machine_id, namespace, created_by_agent, when_to_use, sequence_group, sequence_order, metadata, access_count, version, expires_at, valid_from, valid_until, ingested_at, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'active', 0, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0, 1, ?, ?, ?, ?, ?, ?)`, [
     id,
     input.key,
     input.value,
@@ -1358,6 +1436,9 @@ function createMemory(input, dedupeMode = "merge", db) {
     input.machine_id || null,
     input.namespace || null,
     input.agent_id || null,
+    input.when_to_use || null,
+    input.sequence_group || null,
+    input.sequence_order ?? null,
     metadataJson,
     expiresAt,
     input.metadata?.valid_from ?? timestamp,
@@ -1568,8 +1649,8 @@ function updateMemory(id, input, db) {
     throw new VersionConflictError(id, input.version, existing.version);
   }
   try {
-    d.run(`INSERT OR IGNORE INTO memory_versions (id, memory_id, version, value, importance, scope, category, tags, summary, pinned, status, created_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+    d.run(`INSERT OR IGNORE INTO memory_versions (id, memory_id, version, value, importance, scope, category, tags, summary, pinned, status, when_to_use, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
       uuid(),
       existing.id,
       existing.version,
@@ -1581,6 +1662,7 @@ function updateMemory(id, input, db) {
       existing.summary,
       existing.pinned ? 1 : 0,
       existing.status,
+      existing.when_to_use || null,
       existing.updated_at
     ]);
   } catch {}
@@ -1626,6 +1708,10 @@ function updateMemory(id, input, db) {
     sets.push("flag = ?");
     params.push(input.flag ?? null);
   }
+  if (input.when_to_use !== undefined) {
+    sets.push("when_to_use = ?");
+    params.push(input.when_to_use ?? null);
+  }
   if (input.tags !== undefined) {
     sets.push("tags = ?");
     params.push(JSON.stringify(input.tags));
@@ -3763,6 +3849,311 @@ var init_synthesis = __esm(() => {
   init_database();
 });
 
+// src/lib/when-to-use-generator.ts
+var exports_when_to_use_generator = {};
+__export(exports_when_to_use_generator, {
+  generateWhenToUse: () => generateWhenToUse,
+  autoGenerateWhenToUse: () => autoGenerateWhenToUse
+});
+async function generateWhenToUse(key, value, category, tags) {
+  if (process.env["MEMENTOS_AUTO_WHEN_TO_USE"] !== "true")
+    return null;
+  const apiKey = process.env["ANTHROPIC_API_KEY"];
+  if (!apiKey)
+    return null;
+  try {
+    const userMessage = `Key: "${key}"
+Value: "${value}"
+Category: ${category}
+Tags: ${tags.join(", ") || "none"}
+
+Generate the when_to_use activation context (1-2 sentences):`;
+    const response = await fetch("https://api.anthropic.com/v1/messages", {
+      method: "POST",
+      headers: {
+        "x-api-key": apiKey,
+        "anthropic-version": "2023-06-01",
+        "content-type": "application/json"
+      },
+      body: JSON.stringify({
+        model: "claude-haiku-4-5-20251001",
+        max_tokens: 150,
+        system: SYSTEM_PROMPT,
+        messages: [{ role: "user", content: userMessage }]
+      })
+    });
+    if (!response.ok)
+      return null;
+    const data = await response.json();
+    const text = data.content?.[0]?.text?.trim();
+    return text || null;
+  } catch {
+    return null;
+  }
+}
+async function autoGenerateWhenToUse(ctx) {
+  if (ctx.memory.when_to_use)
+    return;
+  if (process.env["MEMENTOS_AUTO_WHEN_TO_USE"] !== "true")
+    return;
+  try {
+    const whenToUse = await generateWhenToUse(ctx.memory.key, ctx.memory.value, ctx.memory.category, ctx.memory.tags);
+    if (whenToUse) {
+      const db = getDatabase();
+      db.run("UPDATE memories SET when_to_use = ? WHERE id = ? AND when_to_use IS NULL", [whenToUse, ctx.memory.id]);
+    }
+  } catch {}
+}
+var SYSTEM_PROMPT = `You generate activation contexts for memory records. Given a memory's key, value, category, and tags, output a 1-2 sentence "when to use" description that describes the SITUATION or CONDITION under which an AI agent should retrieve this memory.
+
+Rules:
+- Start with "When" or "If"
+- Describe the situation, not the content
+- Be specific enough to avoid false matches but general enough to catch relevant scenarios
+- Focus on the task/action the agent would be doing, not what the memory contains
+
+Examples:
+- Key: "preferred-language", Value: "Always use TypeScript, never JavaScript" \u2192 "When choosing a programming language for a new file or project"
+- Key: "db-migration-order", Value: "Always run migrations before deploying" \u2192 "When deploying or updating database schema"
+- Key: "bash-chain-bug", Value: "Bash tool mangles && chains" \u2192 "When chaining commands with && in the Bash tool"`;
+var init_when_to_use_generator = __esm(() => {
+  init_database();
+});
+
+// src/lib/profile-synthesizer.ts
+var exports_profile_synthesizer = {};
+__export(exports_profile_synthesizer, {
+  synthesizeProfile: () => synthesizeProfile,
+  markProfileStale: () => markProfileStale,
+  getProfileKey: () => getProfileKey
+});
+function getProfileKey(scope, id) {
+  return `_profile_${scope}_${id}`;
+}
+async function synthesizeProfile(options) {
+  const scope = options.scope || (options.project_id ? "project" : options.agent_id ? "agent" : "global");
+  const id = options.project_id || options.agent_id || "global";
+  const profileKey = getProfileKey(scope, id);
+  if (!options.force_refresh) {
+    const cached = getMemoryByKey(profileKey, "shared", undefined, options.project_id);
+    if (cached) {
+      const age = Date.now() - new Date(cached.updated_at).getTime();
+      const maxAge = 24 * 60 * 60 * 1000;
+      const isStale = cached.metadata?.stale === true;
+      if (age < maxAge && !isStale) {
+        return { profile: cached.value, memory_count: 0, from_cache: true };
+      }
+    }
+  }
+  const prefMemories = listMemories({
+    category: "preference",
+    project_id: options.project_id,
+    status: "active",
+    limit: 30
+  });
+  const factMemories = listMemories({
+    category: "fact",
+    project_id: options.project_id,
+    status: "active",
+    limit: 30
+  });
+  const allMemories = [...prefMemories, ...factMemories];
+  if (allMemories.length === 0)
+    return null;
+  const apiKey = process.env["ANTHROPIC_API_KEY"];
+  if (!apiKey) {
+    const lines = allMemories.map((m) => `- ${m.key}: ${m.value}`).join(`
+`);
+    const fallbackProfile = `## Profile
+${lines}`;
+    saveProfile(profileKey, fallbackProfile, allMemories.length, options);
+    return { profile: fallbackProfile, memory_count: allMemories.length, from_cache: false };
+  }
+  try {
+    const memoryList = allMemories.sort((a, b) => b.importance - a.importance).map((m) => `[${m.category}] ${m.key}: ${m.value}`).join(`
+`);
+    const response = await fetch("https://api.anthropic.com/v1/messages", {
+      method: "POST",
+      headers: {
+        "x-api-key": apiKey,
+        "anthropic-version": "2023-06-01",
+        "content-type": "application/json"
+      },
+      body: JSON.stringify({
+        model: "claude-haiku-4-5-20251001",
+        max_tokens: 500,
+        system: PROFILE_PROMPT,
+        messages: [{ role: "user", content: `Synthesize a profile from these ${allMemories.length} memories:
+
+${memoryList}` }]
+      })
+    });
+    if (!response.ok)
+      return null;
+    const data = await response.json();
+    const profile = data.content?.[0]?.text?.trim();
+    if (!profile)
+      return null;
+    saveProfile(profileKey, profile, allMemories.length, options);
+    return { profile, memory_count: allMemories.length, from_cache: false };
+  } catch {
+    return null;
+  }
+}
+function saveProfile(key, value, memoryCount, options) {
+  try {
+    createMemory({
+      key,
+      value,
+      category: "fact",
+      scope: "shared",
+      importance: 10,
+      source: "auto",
+      tags: ["profile", "synthesized"],
+      when_to_use: "When needing to understand this agent's or project's preferences, style, and conventions",
+      metadata: { memory_count: memoryCount, synthesized_at: new Date().toISOString(), stale: false },
+      agent_id: options.agent_id,
+      project_id: options.project_id
+    });
+  } catch {}
+}
+function markProfileStale(projectId, _agentId) {
+  try {
+    const { getDatabase: getDatabase2 } = (init_database(), __toCommonJS(exports_database));
+    const db = getDatabase2();
+    db.run(`UPDATE memories SET metadata = json_set(COALESCE(metadata, '{}'), '$.stale', json('true'))
+       WHERE key LIKE '_profile_%' AND COALESCE(project_id, '') = ?`, [projectId || ""]);
+  } catch {}
+}
+var PROFILE_PROMPT = `You synthesize a coherent agent/project profile from individual preference and fact memories.
+
+Output a concise profile (200-300 words max) organized by:
+- **Stack & Tools**: Languages, frameworks, package managers, etc.
+- **Code Style**: Formatting, patterns, naming conventions
+- **Workflow**: Testing, deployment, git practices
+- **Communication**: Response style, verbosity, formatting preferences
+- **Key Facts**: Architecture decisions, constraints, team conventions
+
+Only include sections that have relevant data. Be specific and actionable.
+Output in markdown format.`;
+var init_profile_synthesizer = __esm(() => {
+  init_memories();
+});
+
+// src/lib/contradiction.ts
+var exports_contradiction = {};
+__export(exports_contradiction, {
+  invalidateFact: () => invalidateFact,
+  detectContradiction: () => detectContradiction
+});
+function invalidateFact(oldMemoryId, newMemoryId, db) {
+  const d = db || getDatabase();
+  const timestamp = now();
+  d.run("UPDATE memories SET valid_until = ?, updated_at = ? WHERE id = ?", [timestamp, timestamp, oldMemoryId]);
+  if (newMemoryId) {
+    const row = d.query("SELECT metadata FROM memories WHERE id = ?").get(newMemoryId);
+    if (row) {
+      const metadata = JSON.parse(row.metadata || "{}");
+      metadata.supersedes_id = oldMemoryId;
+      d.run("UPDATE memories SET metadata = ?, updated_at = ? WHERE id = ?", [JSON.stringify(metadata), timestamp, newMemoryId]);
+    }
+  }
+  return {
+    invalidated_memory_id: oldMemoryId,
+    new_memory_id: newMemoryId || null,
+    valid_until: timestamp,
+    supersedes_id: oldMemoryId
+  };
+}
+function heuristicContradictionScore(newValue, existingValue, newKey, existingKey) {
+  if (newKey !== existingKey)
+    return 0;
+  const newLower = newValue.toLowerCase().trim();
+  const existingLower = existingValue.toLowerCase().trim();
+  if (newLower === existingLower)
+    return 0;
+  const newWords = new Set(newLower.split(/\s+/));
+  const existingWords = new Set(existingLower.split(/\s+/));
+  let overlap = 0;
+  for (const w of newWords) {
+    if (existingWords.has(w))
+      overlap++;
+  }
+  const totalUnique = new Set([...newWords, ...existingWords]).size;
+  const overlapRatio = totalUnique > 0 ? overlap / totalUnique : 0;
+  if (overlapRatio < 0.3)
+    return 0.7;
+  if (overlapRatio < 0.5)
+    return 0.4;
+  return 0.1;
+}
+async function llmContradictionCheck(_newValue, _existingValue, _key) {
+  const provider = providerRegistry.getAvailable();
+  if (!provider) {
+    return { contradicts: false, confidence: 0, reasoning: "No LLM provider available" };
+  }
+  try {
+    return { contradicts: false, confidence: 0, reasoning: "LLM check skipped \u2014 using heuristic only" };
+  } catch {
+    return { contradicts: false, confidence: 0, reasoning: "LLM check failed" };
+  }
+}
+async function detectContradiction(newKey, newValue, options = {}, db) {
+  const d = db || getDatabase();
+  const { scope, project_id, min_importance = 7, use_llm = false } = options;
+  const conditions = ["key = ?", "status = 'active'", "importance >= ?"];
+  const params = [newKey, min_importance];
+  if (scope) {
+    conditions.push("scope = ?");
+    params.push(scope);
+  }
+  if (project_id) {
+    conditions.push("project_id = ?");
+    params.push(project_id);
+  }
+  conditions.push("(valid_until IS NULL OR valid_until > datetime('now'))");
+  const sql = `SELECT * FROM memories WHERE ${conditions.join(" AND ")} ORDER BY importance DESC LIMIT 10`;
+  const rows = d.query(sql).all(...params);
+  if (rows.length === 0) {
+    return { contradicts: false, conflicting_memory: null, confidence: 0, reasoning: "No existing memories with this key" };
+  }
+  let bestContradiction = {
+    contradicts: false,
+    conflicting_memory: null,
+    confidence: 0,
+    reasoning: "No contradiction detected"
+  };
+  for (const row of rows) {
+    const existing = parseMemoryRow(row);
+    const heuristicScore = heuristicContradictionScore(newValue, existing.value, newKey, existing.key);
+    if (heuristicScore > bestContradiction.confidence) {
+      bestContradiction = {
+        contradicts: heuristicScore >= 0.5,
+        conflicting_memory: existing,
+        confidence: heuristicScore,
+        reasoning: heuristicScore >= 0.7 ? `New value for "${newKey}" significantly differs from existing high-importance memory (importance ${existing.importance})` : heuristicScore >= 0.5 ? `New value for "${newKey}" partially conflicts with existing memory (importance ${existing.importance})` : `Minor difference detected for "${newKey}"`
+      };
+    }
+  }
+  if (use_llm && bestContradiction.confidence >= 0.3 && bestContradiction.confidence < 0.7 && bestContradiction.conflicting_memory) {
+    const llmResult = await llmContradictionCheck(newValue, bestContradiction.conflicting_memory.value, newKey);
+    if (llmResult.confidence > bestContradiction.confidence) {
+      bestContradiction = {
+        ...bestContradiction,
+        contradicts: llmResult.contradicts,
+        confidence: llmResult.confidence,
+        reasoning: llmResult.reasoning
+      };
+    }
+  }
+  return bestContradiction;
+}
+var init_contradiction = __esm(() => {
+  init_database();
+  init_memories();
+  init_registry();
+});
+
 // src/server/index.ts
 init_memories();
 import { existsSync as existsSync3 } from "fs";
@@ -4348,10 +4739,76 @@ hookRegistry.register({
   description: "Generate and store vector embedding for semantic memory search",
   handler: async (ctx) => {
     const { indexMemoryEmbedding: indexMemoryEmbedding2 } = await Promise.resolve().then(() => (init_memories(), exports_memories));
-    const text = [ctx.memory.value, ctx.memory.summary].filter(Boolean).join(" ");
+    const text = ctx.memory.when_to_use || [ctx.memory.value, ctx.memory.summary].filter(Boolean).join(" ");
     indexMemoryEmbedding2(ctx.memory.id, text);
   }
 });
+hookRegistry.register({
+  type: "PostMemorySave",
+  blocking: false,
+  builtin: true,
+  priority: 60,
+  description: "Auto-generate when_to_use activation context via LLM if missing",
+  handler: async (ctx) => {
+    const { autoGenerateWhenToUse: autoGenerateWhenToUse2 } = await Promise.resolve().then(() => (init_when_to_use_generator(), exports_when_to_use_generator));
+    await autoGenerateWhenToUse2(ctx);
+  }
+});
+hookRegistry.register({
+  type: "PostMemorySave",
+  blocking: false,
+  builtin: true,
+  priority: 65,
+  description: "Mark synthesized profile as stale when a preference or fact memory is saved",
+  handler: async (ctx) => {
+    const category = ctx.memory?.category;
+    if (category !== "preference" && category !== "fact")
+      return;
+    try {
+      const { markProfileStale: markProfileStale2 } = await Promise.resolve().then(() => (init_profile_synthesizer(), exports_profile_synthesizer));
+      markProfileStale2(ctx.projectId, ctx.agentId);
+    } catch {}
+  }
+});
+hookRegistry.register({
+  type: "PostMemorySave",
+  blocking: false,
+  builtin: true,
+  priority: 70,
+  description: "Auto-decay importance of existing memories contradicted by the newly saved memory",
+  handler: async (ctx) => {
+    if (ctx.wasUpdated)
+      return;
+    const memory = ctx.memory;
+    if (memory.category !== "fact" && memory.category !== "knowledge")
+      return;
+    try {
+      const { detectContradiction: detectContradiction2 } = await Promise.resolve().then(() => (init_contradiction(), exports_contradiction));
+      const { updateMemory: updateMemory2, getMemory: getMemory2 } = await Promise.resolve().then(() => (init_memories(), exports_memories));
+      const result = await detectContradiction2(memory.key, memory.value, {
+        scope: memory.scope,
+        project_id: ctx.projectId,
+        min_importance: 1
+      });
+      if (!result.contradicts || !result.conflicting_memory)
+        return;
+      const conflicting = result.conflicting_memory;
+      if (conflicting.id === memory.id)
+        return;
+      const fresh = getMemory2(conflicting.id);
+      if (!fresh || fresh.status !== "active")
+        return;
+      const halvedImportance = Math.max(1, Math.floor(fresh.importance / 2));
+      const metadata = { ...fresh.metadata || {}, contradicted_by: memory.id };
+      updateMemory2(fresh.id, {
+        importance: halvedImportance,
+        flag: "contradicted",
+        metadata,
+        version: fresh.version
+      });
+    } catch {}
+  }
+});
 hookRegistry.register({
   type: "PostMemoryInject",
   blocking: false,
@@ -5434,12 +5891,349 @@ function getNextPendingJob(db) {
   return parseJobRow(row);
 }
 
+// src/db/tool-events.ts
+init_database();
+function parseToolEventRow(row) {
+  return {
+    id: row["id"],
+    tool_name: row["tool_name"],
+    action: row["action"] || null,
+    success: !!row["success"],
+    error_type: row["error_type"] || null,
+    error_message: row["error_message"] || null,
+    tokens_used: row["tokens_used"] ?? null,
+    latency_ms: row["latency_ms"] ?? null,
+    context: row["context"] || null,
+    lesson: row["lesson"] || null,
+    when_to_use: row["when_to_use"] || null,
+    agent_id: row["agent_id"] || null,
+    project_id: row["project_id"] || null,
+    session_id: row["session_id"] || null,
+    metadata: JSON.parse(row["metadata"] || "{}"),
+    created_at: row["created_at"]
+  };
+}
+function saveToolEvent(input, db) {
+  const d = db || getDatabase();
+  const id = uuid();
+  const timestamp = now();
+  const metadataJson = JSON.stringify(input.metadata || {});
+  d.run(`INSERT INTO tool_events (id, tool_name, action, success, error_type, error_message, tokens_used, latency_ms, context, lesson, when_to_use, agent_id, project_id, session_id, metadata, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+    id,
+    input.tool_name,
+    input.action || null,
+    input.success ? 1 : 0,
+    input.error_type || null,
+    input.error_message || null,
+    input.tokens_used ?? null,
+    input.latency_ms ?? null,
+    input.context || null,
+    input.lesson || null,
+    input.when_to_use || null,
+    input.agent_id || null,
+    input.project_id || null,
+    input.session_id || null,
+    metadataJson,
+    timestamp
+  ]);
+  return getToolEvent(id, d);
+}
+function getToolEvent(id, db) {
+  const d = db || getDatabase();
+  const row = d.query("SELECT * FROM tool_events WHERE id = ?").get(id);
+  if (!row)
+    return null;
+  return parseToolEventRow(row);
+}
+function getToolEvents(filters, db) {
+  const d = db || getDatabase();
+  const conditions = [];
+  const params = [];
+  if (filters.tool_name) {
+    conditions.push("tool_name = ?");
+    params.push(filters.tool_name);
+  }
+  if (filters.agent_id) {
+    conditions.push("agent_id = ?");
+    params.push(filters.agent_id);
+  }
+  if (filters.project_id) {
+    conditions.push("project_id = ?");
+    params.push(filters.project_id);
+  }
+  if (filters.success !== undefined) {
+    conditions.push("success = ?");
+    params.push(filters.success ? 1 : 0);
+  }
+  if (filters.from_date) {
+    conditions.push("created_at >= ?");
+    params.push(filters.from_date);
+  }
+  if (filters.to_date) {
+    conditions.push("created_at <= ?");
+    params.push(filters.to_date);
+  }
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+  const limit = filters.limit || 50;
+  const offset = filters.offset || 0;
+  const rows = d.query(`SELECT * FROM tool_events ${where} ORDER BY created_at DESC LIMIT ? OFFSET ?`).all(...params, limit, offset);
+  return rows.map(parseToolEventRow);
+}
+function getToolStats(tool_name, project_id, db) {
+  const d = db || getDatabase();
+  let where = "WHERE tool_name = ?";
+  const params = [tool_name];
+  if (project_id) {
+    where += " AND project_id = ?";
+    params.push(project_id);
+  }
+  const stats = d.query(`SELECT
+      COUNT(*) as total_calls,
+      SUM(CASE WHEN success = 1 THEN 1 ELSE 0 END) as success_count,
+      SUM(CASE WHEN success = 0 THEN 1 ELSE 0 END) as failure_count,
+      AVG(CASE WHEN tokens_used IS NOT NULL THEN tokens_used END) as avg_tokens,
+      AVG(CASE WHEN latency_ms IS NOT NULL THEN latency_ms END) as avg_latency_ms,
+      MAX(created_at) as last_used
+    FROM tool_events ${where}`).get(...params);
+  const total = stats["total_calls"] || 0;
+  const successCount = stats["success_count"] || 0;
+  const errorRows = d.query(`SELECT error_type, COUNT(*) as count
+     FROM tool_events ${where} AND error_type IS NOT NULL
+     GROUP BY error_type ORDER BY count DESC LIMIT 5`).all(...params);
+  return {
+    tool_name,
+    total_calls: total,
+    success_count: successCount,
+    failure_count: stats["failure_count"] || 0,
+    success_rate: total > 0 ? successCount / total : 0,
+    avg_tokens: stats["avg_tokens"] ?? null,
+    avg_latency_ms: stats["avg_latency_ms"] ?? null,
+    common_errors: errorRows,
+    last_used: stats["last_used"] || ""
+  };
+}
+function getToolLessons(tool_name, project_id, limit, db) {
+  const d = db || getDatabase();
+  let where = "WHERE tool_name = ? AND lesson IS NOT NULL";
+  const params = [tool_name];
+  if (project_id) {
+    where += " AND project_id = ?";
+    params.push(project_id);
+  }
+  const rows = d.query(`SELECT lesson, when_to_use, created_at FROM tool_events ${where} ORDER BY created_at DESC LIMIT ?`).all(...params, limit || 20);
+  return rows;
+}
+
+// src/server/index.ts
+init_profile_synthesizer();
+
 // src/lib/session-queue.ts
 init_database();
 
 // src/lib/session-processor.ts
 init_memories();
 init_registry();
+
+// src/lib/tool-lesson-extractor.ts
+init_memories();
+var SYSTEM_PROMPT2 = `You are a tool usage analyst. Given a session transcript containing tool calls and their results, extract actionable lessons about tool usage.
+
+For each tool lesson, output a JSON array of objects with these fields:
+- tool_name: name of the tool
+- lesson: the insight (1-2 sentences)
+- when_to_use: activation context \u2014 when should an agent recall this lesson (start with "When" or "If")
+- success: boolean \u2014 was the tool call that taught this lesson successful?
+- error_type: if failed, one of: timeout, permission, not_found, syntax, rate_limit, other (or null if success)
+
+Focus on:
+1. Successful patterns: what worked and why
+2. Failure lessons: what went wrong and how to avoid it
+3. Parameter insights: optimal settings discovered
+4. Alternative tools: when one tool is better than another
+5. Error recovery: what to do when a specific error occurs
+
+Only extract genuinely useful, non-obvious lessons. Skip trivial observations.
+Output ONLY the JSON array, no markdown or explanation.`;
+async function extractToolLessons(transcript, options) {
+  const apiKey = process.env["ANTHROPIC_API_KEY"];
+  if (!apiKey)
+    return [];
+  try {
+    const truncated = transcript.length > 8000 ? transcript.slice(0, 8000) + `
+[...truncated]` : transcript;
+    const response = await fetch("https://api.anthropic.com/v1/messages", {
+      method: "POST",
+      headers: {
+        "x-api-key": apiKey,
+        "anthropic-version": "2023-06-01",
+        "content-type": "application/json"
+      },
+      body: JSON.stringify({
+        model: "claude-haiku-4-5-20251001",
+        max_tokens: 1500,
+        system: SYSTEM_PROMPT2,
+        messages: [{ role: "user", content: `Extract tool lessons from this session transcript:
+
+${truncated}` }]
+      })
+    });
+    if (!response.ok)
+      return [];
+    const data = await response.json();
+    const text = data.content?.[0]?.text?.trim();
+    if (!text)
+      return [];
+    const lessons = JSON.parse(text);
+    if (!Array.isArray(lessons))
+      return [];
+    for (const lesson of lessons) {
+      if (!lesson.tool_name || !lesson.lesson)
+        continue;
+      try {
+        saveToolEvent({
+          tool_name: lesson.tool_name,
+          success: lesson.success,
+          error_type: lesson.error_type || undefined,
+          lesson: lesson.lesson,
+          when_to_use: lesson.when_to_use,
+          context: "extracted from session transcript",
+          agent_id: options?.agent_id,
+          project_id: options?.project_id,
+          session_id: options?.session_id
+        });
+      } catch {}
+      try {
+        createMemory({
+          key: `tool-lesson-${lesson.tool_name}-${Date.now()}`,
+          value: lesson.lesson,
+          category: "knowledge",
+          scope: "shared",
+          importance: 7,
+          source: "auto",
+          tags: ["tool-memory", lesson.tool_name, "auto-extracted"],
+          when_to_use: lesson.when_to_use,
+          agent_id: options?.agent_id,
+          project_id: options?.project_id,
+          session_id: options?.session_id
+        });
+      } catch {}
+    }
+    return lessons;
+  } catch {
+    return [];
+  }
+}
+
+// src/lib/procedural-extractor.ts
+init_memories();
+init_database();
+var SYSTEM_PROMPT3 = `You extract procedural knowledge from session transcripts \u2014 workflows, step sequences, and problem-solution patterns.
+
+For each procedure found, output a JSON array of objects:
+{
+  "title": "short name for the workflow",
+  "steps": [
+    {"action": "what to do", "when_to_use": "activation context for this step"},
+    {"action": "next step", "when_to_use": "activation context"}
+  ],
+  "failure_patterns": ["what to avoid and why"],
+  "when_to_use": "overall activation context for the whole procedure"
+}
+
+Focus on:
+1. Multi-step workflows that were completed successfully
+2. Step sequences where order matters
+3. Failure \u2192 recovery patterns (what went wrong, how it was fixed)
+4. Problem-solution pairs (when X happens, do Y)
+
+Only extract non-trivial procedures (3+ steps or genuinely useful patterns).
+Output ONLY the JSON array.`;
+async function extractProcedures(transcript, options) {
+  const apiKey = process.env["ANTHROPIC_API_KEY"];
+  if (!apiKey)
+    return [];
+  try {
+    const truncated = transcript.length > 8000 ? transcript.slice(0, 8000) + `
+[...truncated]` : transcript;
+    const response = await fetch("https://api.anthropic.com/v1/messages", {
+      method: "POST",
+      headers: {
+        "x-api-key": apiKey,
+        "anthropic-version": "2023-06-01",
+        "content-type": "application/json"
+      },
+      body: JSON.stringify({
+        model: "claude-haiku-4-5-20251001",
+        max_tokens: 2000,
+        system: SYSTEM_PROMPT3,
+        messages: [{ role: "user", content: `Extract procedures from this session:
+
+${truncated}` }]
+      })
+    });
+    if (!response.ok)
+      return [];
+    const data = await response.json();
+    const text = data.content?.[0]?.text?.trim();
+    if (!text)
+      return [];
+    const procedures = JSON.parse(text);
+    if (!Array.isArray(procedures))
+      return [];
+    for (const proc of procedures) {
+      if (!proc.title || !proc.steps?.length)
+        continue;
+      const sequenceGroup = `proc-${shortUuid()}`;
+      for (let i = 0;i < proc.steps.length; i++) {
+        const step = proc.steps[i];
+        if (!step)
+          continue;
+        try {
+          createMemory({
+            key: `${sequenceGroup}-step-${i + 1}`,
+            value: step.action,
+            category: "procedural",
+            scope: "shared",
+            importance: 7,
+            source: "auto",
+            tags: ["procedure", "auto-extracted", proc.title.toLowerCase().replace(/\s+/g, "-")],
+            when_to_use: step.when_to_use || proc.when_to_use,
+            sequence_group: sequenceGroup,
+            sequence_order: i + 1,
+            agent_id: options?.agent_id,
+            project_id: options?.project_id,
+            session_id: options?.session_id
+          });
+        } catch {}
+      }
+      for (const pattern of proc.failure_patterns || []) {
+        try {
+          createMemory({
+            key: `${sequenceGroup}-warning-${shortUuid()}`,
+            value: `WARNING: ${pattern}`,
+            category: "procedural",
+            scope: "shared",
+            importance: 8,
+            source: "auto",
+            tags: ["procedure", "failure-pattern", "auto-extracted"],
+            when_to_use: proc.when_to_use,
+            sequence_group: sequenceGroup,
+            sequence_order: 999,
+            agent_id: options?.agent_id,
+            project_id: options?.project_id,
+            session_id: options?.session_id
+          });
+        } catch {}
+      }
+    }
+    return procedures;
+  } catch {
+    return [];
+  }
+}
+
+// src/lib/session-processor.ts
 var SESSION_EXTRACTION_USER_TEMPLATE = (chunk, sessionId) => `Extract memories from this session chunk (session: ${sessionId}):
 
 ${chunk}
@@ -5601,6 +6395,20 @@ async function processSessionJob(jobId, db) {
     }
   }
   result.memoriesExtracted = totalMemories;
+  try {
+    await extractToolLessons(job.transcript, {
+      agent_id: job.agent_id ?? undefined,
+      project_id: job.project_id ?? undefined,
+      session_id: job.session_id
+    });
+  } catch {}
+  try {
+    await extractProcedures(job.transcript, {
+      agent_id: job.agent_id ?? undefined,
+      project_id: job.project_id ?? undefined,
+      session_id: job.session_id
+    });
+  } catch {}
   try {
     if (result.errors.length > 0 && result.chunksProcessed === 0) {
       updateSessionJob(jobId, {
@@ -6981,6 +7789,66 @@ addRoute("GET", "/api/sessions/jobs/:id", (_req, _url, params) => {
   return json(job);
 });
 addRoute("GET", "/api/sessions/queue/stats", () => json(getSessionQueueStats()));
+addRoute("POST", "/api/tool-events", async (req) => {
+  const body = await readJson(req);
+  if (!body || !body["tool_name"]) {
+    return errorResponse("Missing required field: tool_name", 400);
+  }
+  const event = saveToolEvent(body);
+  return json(event, 201);
+});
+addRoute("GET", "/api/tool-events", (_req, url) => {
+  const q = getSearchParams(url);
+  const filters = {};
+  if (q["tool_name"])
+    filters.tool_name = q["tool_name"];
+  if (q["agent_id"])
+    filters.agent_id = q["agent_id"];
+  if (q["project_id"])
+    filters.project_id = q["project_id"];
+  if (q["success"] !== undefined && q["success"] !== "")
+    filters.success = q["success"] === "true";
+  if (q["from_date"])
+    filters.from_date = q["from_date"];
+  if (q["to_date"])
+    filters.to_date = q["to_date"];
+  if (q["limit"])
+    filters.limit = parseInt(q["limit"], 10);
+  if (q["offset"])
+    filters.offset = parseInt(q["offset"], 10);
+  const events = getToolEvents(filters);
+  return json({ events, count: events.length });
+});
+addRoute("GET", "/api/tool-insights/:tool_name", (_req, url, params) => {
+  const q = getSearchParams(url);
+  const toolName = decodeURIComponent(params["tool_name"]);
+  const projectId = q["project_id"];
+  const lessonsLimit = q["limit"] ? parseInt(q["limit"], 10) : 20;
+  const stats = getToolStats(toolName, projectId || undefined);
+  const lessons = getToolLessons(toolName, projectId || undefined, lessonsLimit);
+  return json({ stats, lessons });
+});
+addRoute("GET", "/api/profile/synthesize", async (_req, url) => {
+  const q = getSearchParams(url);
+  const result = await synthesizeProfile({
+    project_id: q["project_id"] || undefined,
+    agent_id: q["agent_id"] || undefined,
+    force_refresh: q["force_refresh"] === "true"
+  });
+  if (!result) {
+    return json({ profile: null, message: "No preference/fact memories found to synthesize" });
+  }
+  return json(result);
+});
+addRoute("GET", "/api/chains/:sequence_group", (_req, _url, params) => {
+  const db = getDatabase();
+  const sequenceGroup = decodeURIComponent(params["sequence_group"]);
+  const rows = db.query(`SELECT * FROM memories WHERE sequence_group = ? AND status = 'active' ORDER BY sequence_order ASC`).all(sequenceGroup);
+  if (rows.length === 0) {
+    return json({ chain: [], count: 0, sequence_group: sequenceGroup });
+  }
+  return json({ chain: rows, count: rows.length, sequence_group: sequenceGroup });
+});
 function startServer(port) {
   loadWebhooksFromDb();
   startSessionQueueWorker();