@agenticmail/enterprise 0.5.261 → 0.5.262

package/dist/chunk-4BBEW5L4.js

@@ -0,0 +1,595 @@
+import {
+  MemorySearchIndex
+} from "./chunk-TYW5XTOW.js";
+
+// src/engine/agent-memory.ts
+function sj(v, fb = {}) {
+  if (!v) return fb;
+  try {
+    return JSON.parse(v);
+  } catch {
+    return fb;
+  }
+}
+var MEMORY_CATEGORIES = {
+  org_knowledge: {
+    label: "Organization Knowledge",
+    description: "Policies, procedures, and organizational information"
+  },
+  interaction_pattern: {
+    label: "Interaction Patterns",
+    description: "Learned patterns from past interactions"
+  },
+  preference: {
+    label: "Preferences",
+    description: "User and organizational preferences"
+  },
+  correction: {
+    label: "Corrections",
+    description: "Corrections and feedback received"
+  },
+  skill: {
+    label: "Skills",
+    description: "Learned abilities and competencies"
+  },
+  context: {
+    label: "Context",
+    description: "Contextual information and background knowledge"
+  },
+  reflection: {
+    label: "Reflections",
+    description: "Self-reflective insights and learnings"
+  },
+  session_learning: {
+    label: "Session Learnings",
+    description: "Insights captured during conversation sessions"
+  },
+  system_notice: {
+    label: "System Notices",
+    description: "System-generated notifications about configuration changes"
+  }
+};
+var IMPORTANCE_WEIGHT = {
+  critical: 4,
+  high: 3,
+  normal: 2,
+  low: 1
+};
+var AgentMemoryManager = class {
+  memories = /* @__PURE__ */ new Map();
+  /** Per-agent index: agentId → Set of memory IDs for O(1) agent lookups */
+  agentIndex = /* @__PURE__ */ new Map();
+  /** Full-text search index (BM25F + stemming + inverted index) */
+  searchIndex = new MemorySearchIndex();
+  engineDb;
+  // ─── Database Lifecycle ─────────────────────────────
+  async setDb(db) {
+    this.engineDb = db;
+    await this.loadFromDb();
+  }
+  async loadFromDb() {
+    if (!this.engineDb) return;
+    try {
+      const rows = await this.engineDb.query("SELECT * FROM agent_memory");
+      console.log(`[memory] Loaded ${rows.length} memories from DB`);
+      for (const r of rows) {
+        try {
+          const entry = this.rowToEntry(r);
+          this.memories.set(entry.id, entry);
+          this.indexAdd(entry.agentId, entry.id);
+          this.searchIndex.addDocument(entry.id, entry);
+        } catch (entryErr) {
+          console.warn(`[memory] Skipped entry ${r.id}: ${entryErr.message}`);
+        }
+      }
+    } catch (loadErr) {
+      console.error("[memory] loadFromDb failed:", loadErr.message);
+    }
+  }
+  /** Add a memory ID to the per-agent index. */
+  indexAdd(agentId, memoryId) {
+    let set = this.agentIndex.get(agentId);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.agentIndex.set(agentId, set);
+    }
+    set.add(memoryId);
+  }
+  /** Remove a memory ID from the per-agent index. */
+  indexRemove(agentId, memoryId) {
+    const set = this.agentIndex.get(agentId);
+    if (set) {
+      set.delete(memoryId);
+      if (set.size === 0) this.agentIndex.delete(agentId);
+    }
+  }
+  /** Get all memory entries for an agent via the index — O(n) where n is that agent's entries, not total. */
+  getAgentMemories(agentId) {
+    const ids = this.agentIndex.get(agentId);
+    if (!ids || ids.size === 0) return [];
+    const result = [];
+    for (const id of ids) {
+      const entry = this.memories.get(id);
+      if (entry) result.push(entry);
+    }
+    return result;
+  }
+  // ─── Convenience Methods ─────────────────────────────
+  /**
+   * Convenience method for storing a memory with minimal input.
+   * Handles the common case where you just want to store a piece of text.
+   */
+  async storeMemory(agentId, opts) {
+    return this.createMemory({
+      agentId,
+      orgId: opts.orgId || "default",
+      content: opts.content,
+      category: opts.category || "general",
+      importance: opts.importance || "normal",
+      confidence: opts.confidence ?? 1,
+      title: opts.title || "",
+      source: "system",
+      tags: [],
+      metadata: {}
+    });
+  }
+  /**
+   * Convenience method for searching memories by text query.
+   * Returns matching entries sorted by relevance.
+   */
+  async recall(agentId, query, limit = 5) {
+    return this.queryMemories({ agentId, query, limit });
+  }
+  // ─── CRUD Operations ────────────────────────────────
+  /**
+   * Creates a new memory entry with auto-generated id and timestamps.
+   * Persists to both the in-memory Map and the database.
+   */
+  async createMemory(input) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const entry = {
+      ...input,
+      confidence: input.confidence ?? 0.8,
+      tags: input.tags ?? [],
+      metadata: input.metadata ?? {},
+      id: crypto.randomUUID(),
+      accessCount: 0,
+      createdAt: now,
+      updatedAt: now
+    };
+    this.memories.set(entry.id, entry);
+    this.indexAdd(entry.agentId, entry.id);
+    this.searchIndex.addDocument(entry.id, entry);
+    await this.engineDb?.execute(
+      `INSERT INTO agent_memory (id, agent_id, org_id, category, title, content, source, importance, confidence, access_count, last_accessed_at, expires_at, tags, metadata, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        entry.id,
+        entry.agentId,
+        entry.orgId,
+        entry.category,
+        entry.title,
+        entry.content,
+        entry.source,
+        entry.importance,
+        entry.confidence,
+        entry.accessCount,
+        entry.lastAccessedAt || null,
+        entry.expiresAt || null,
+        JSON.stringify(entry.tags),
+        JSON.stringify(entry.metadata),
+        entry.createdAt,
+        entry.updatedAt
+      ]
+    ).catch((err) => {
+      console.error("[agent-memory] Failed to persist memory entry:", err);
+    });
+    return entry;
+  }
+  /**
+   * Updates an existing memory entry by merging provided fields.
+   * Returns the updated entry or null if not found.
+   */
+  async updateMemory(id, updates) {
+    const existing = this.memories.get(id);
+    if (!existing) return null;
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const updated = {
+      ...existing,
+      ...updates,
+      id: existing.id,
+      agentId: existing.agentId,
+      orgId: existing.orgId,
+      createdAt: existing.createdAt,
+      updatedAt: now
+    };
+    this.memories.set(id, updated);
+    if (updates.title !== void 0 || updates.content !== void 0 || updates.tags !== void 0) {
+      this.searchIndex.addDocument(id, updated);
+    }
+    await this.engineDb?.execute(
+      `UPDATE agent_memory SET
+        category = ?, title = ?, content = ?, source = ?,
+        importance = ?, confidence = ?, access_count = ?,
+        last_accessed_at = ?, expires_at = ?, tags = ?,
+        metadata = ?, updated_at = ?
+       WHERE id = ?`,
+      [
+        updated.category,
+        updated.title,
+        updated.content,
+        updated.source,
+        updated.importance,
+        updated.confidence,
+        updated.accessCount,
+        updated.lastAccessedAt || null,
+        updated.expiresAt || null,
+        JSON.stringify(updated.tags),
+        JSON.stringify(updated.metadata),
+        updated.updatedAt,
+        id
+      ]
+    ).catch((err) => {
+      console.error("[agent-memory] Failed to update memory entry:", err);
+    });
+    return updated;
+  }
+  /**
+   * Deletes a memory entry from both the in-memory Map and the database.
+   * Returns true if the entry existed and was deleted.
+   */
+  async deleteMemory(id) {
+    const entry = this.memories.get(id);
+    const existed = this.memories.delete(id);
+    if (entry) this.indexRemove(entry.agentId, id);
+    this.searchIndex.removeDocument(id);
+    await this.engineDb?.execute(
+      "DELETE FROM agent_memory WHERE id = ?",
+      [id]
+    ).catch((err) => {
+      console.error("[agent-memory] Failed to delete memory entry:", err);
+    });
+    return existed;
+  }
+  /**
+   * Retrieves a single memory entry by id.
+   * Returns from the in-memory Map (async for interface compatibility).
+   */
+  async getMemory(id) {
+    return this.memories.get(id);
+  }
+  // ─── Query Operations ───────────────────────────────
+  /**
+   * Queries memory entries for a specific agent with optional filters.
+   * Supports filtering by category, importance, source, and text search on title/content.
+   */
+  async queryMemories(opts) {
+    let results = this.getAgentMemories(opts.agentId);
+    if (results.length === 0 && this.engineDb && opts.agentId) {
+      try {
+        const rows = await this.engineDb.query(
+          "SELECT * FROM agent_memory WHERE agent_id = ?",
+          [opts.agentId]
+        );
+        console.log(`[memory] Lazy-loaded ${rows.length} memories for agent ${opts.agentId}`);
+        for (const r of rows) {
+          try {
+            const entry = this.rowToEntry(r);
+            this.memories.set(entry.id, entry);
+            this.indexAdd(entry.agentId, entry.id);
+            this.searchIndex.addDocument(entry.id, entry);
+          } catch {
+          }
+        }
+        results = this.getAgentMemories(opts.agentId);
+      } catch (e) {
+        console.error("[memory] Lazy-load failed:", e.message);
+      }
+    }
+    if (opts.category) {
+      results = results.filter((m) => m.category === opts.category);
+    }
+    if (opts.importance) {
+      results = results.filter((m) => m.importance === opts.importance);
+    }
+    if (opts.source) {
+      results = results.filter((m) => m.source === opts.source);
+    }
+    if (opts.query) {
+      const candidateIds = new Set(results.map((m) => m.id));
+      const searchResults = this.searchIndex.search(opts.query, candidateIds);
+      if (searchResults.length > 0) {
+        const scored = searchResults.map((r) => {
+          const entry = this.memories.get(r.id);
+          return entry ? { entry, score: r.score * IMPORTANCE_WEIGHT[entry.importance] } : null;
+        }).filter((r) => r !== null);
+        scored.sort((a, b) => b.score - a.score);
+        return scored.slice(0, opts.limit || 100).map((d) => d.entry);
+      }
+    }
+    results.sort((a, b) => {
+      const weightDiff = IMPORTANCE_WEIGHT[b.importance] - IMPORTANCE_WEIGHT[a.importance];
+      if (weightDiff !== 0) return weightDiff;
+      return new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime();
+    });
+    const limit = opts.limit || 100;
+    return results.slice(0, limit);
+  }
+  /**
+   * Returns memories created within the last N hours for an agent.
+   */
+  async getRecentMemories(agentId, hours = 24) {
+    const cutoff = new Date(Date.now() - hours * 36e5).toISOString();
+    return this.getAgentMemories(agentId).filter((m) => m.createdAt >= cutoff).sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+  }
+  // ─── Access Tracking ────────────────────────────────
+  /**
+   * Increments the access count and updates lastAccessedAt for a memory entry.
+   * Used to track frequently referenced knowledge.
+   */
+  async recordAccess(memoryId) {
+    const entry = this.memories.get(memoryId);
+    if (!entry) return;
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    entry.accessCount += 1;
+    entry.lastAccessedAt = now;
+    entry.updatedAt = now;
+    await this.engineDb?.execute(
+      `UPDATE agent_memory SET access_count = ?, last_accessed_at = ?, updated_at = ? WHERE id = ?`,
+      [entry.accessCount, entry.lastAccessedAt, entry.updatedAt, memoryId]
+    ).catch((err) => {
+      console.error("[agent-memory] Failed to record access:", err);
+    });
+  }
+  // ─── Context Generation ─────────────────────────────
+  /**
+   * Generates a markdown context string suitable for injection into an agent's system prompt.
+   *
+   * Ranking strategy:
+   * 1. Critical importance entries always come first
+   * 2. Remaining entries scored by: confidence * accessWeight * recencyWeight
+   * 3. If a query is provided, entries matching query terms get a relevance boost
+   * 4. Output is grouped by category with markdown headers
+   * 5. Truncated to maxTokens (estimated at ~4 chars per token)
+   */
+  async generateMemoryContext(agentId, query, maxTokens = 1500) {
+    const entries = this.getAgentMemories(agentId).filter((m) => m.confidence >= 0.1);
+    if (entries.length === 0) return "";
+    const now = Date.now();
+    let relevanceMap;
+    if (query) {
+      const candidateIds = new Set(entries.map((e) => e.id));
+      const searchResults = this.searchIndex.search(query, candidateIds);
+      if (searchResults.length > 0) {
+        relevanceMap = /* @__PURE__ */ new Map();
+        const maxScore = searchResults[0].score;
+        for (const r of searchResults) {
+          relevanceMap.set(r.id, maxScore > 0 ? r.score / maxScore : 0);
+        }
+      }
+    }
+    const scored = entries.map((entry) => {
+      const accessWeight = 1 + Math.log1p(entry.accessCount) * 0.3;
+      const lastTouch = entry.lastAccessedAt || entry.createdAt;
+      const ageHours = Math.max(1, (now - new Date(lastTouch).getTime()) / 36e5);
+      const recencyWeight = 1 / (1 + Math.log1p(ageHours / 24) * 0.2);
+      let score = entry.confidence * accessWeight * recencyWeight;
+      score *= IMPORTANCE_WEIGHT[entry.importance];
+      if (relevanceMap) {
+        const relevance = relevanceMap.get(entry.id) || 0;
+        if (relevance > 0) {
+          score *= 1 + relevance * 3;
+        }
+      }
+      return { entry, score };
+    });
+    scored.sort((a, b) => b.score - a.score);
+    const grouped = /* @__PURE__ */ new Map();
+    for (const { entry } of scored) {
+      const group = grouped.get(entry.category) || [];
+      group.push(entry);
+      grouped.set(entry.category, group);
+    }
+    const maxChars = maxTokens * 4;
+    const lines = ["## Agent Memory", ""];
+    let charCount = lines.join("\n").length;
+    for (const [category, categoryEntries] of Array.from(grouped.entries())) {
+      const meta = MEMORY_CATEGORIES[category];
+      if (!meta) continue;
+      const header = `### ${meta.label}`;
+      if (charCount + header.length + 2 > maxChars) break;
+      lines.push(header);
+      lines.push("");
+      charCount += header.length + 2;
+      for (const entry of categoryEntries) {
+        const badge = entry.importance === "critical" ? "[CRITICAL] " : entry.importance === "high" ? "[HIGH] " : "";
+        const entryLine = `- **${badge}${entry.title}**: ${entry.content}`;
+        if (charCount + entryLine.length + 1 > maxChars) break;
+        lines.push(entryLine);
+        charCount += entryLine.length + 1;
+      }
+      lines.push("");
+      charCount += 1;
+    }
+    return lines.join("\n").trim();
+  }
+  // ─── Memory Lifecycle ───────────────────────────────
+  /**
+   * Decays confidence scores for entries that have not been accessed in 7+ days.
+   * Critical importance entries are exempt from decay.
+   *
+   * @param agentId - The agent whose memories to decay
+   * @param decayRate - How much to reduce confidence (default 0.05)
+   * @returns Number of entries that were decayed
+   */
+  async decayConfidence(agentId, decayRate = 0.05) {
+    const cutoff = new Date(Date.now() - 7 * 864e5).toISOString();
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const decayed = [];
+    for (const entry of this.getAgentMemories(agentId)) {
+      if (entry.importance === "critical") continue;
+      const lastTouch = entry.lastAccessedAt || entry.createdAt;
+      if (lastTouch >= cutoff) continue;
+      const newConfidence = Math.max(0, entry.confidence - decayRate);
+      if (newConfidence === entry.confidence) continue;
+      entry.confidence = parseFloat(newConfidence.toFixed(4));
+      entry.updatedAt = now;
+      decayed.push({ id: entry.id, confidence: entry.confidence });
+    }
+    if (decayed.length > 0 && this.engineDb) {
+      await Promise.all(
+        decayed.map(
+          (d) => this.engineDb.execute(
+            "UPDATE agent_memory SET confidence = ?, updated_at = ? WHERE id = ?",
+            [d.confidence, now, d.id]
+          ).catch((err) => console.error("[agent-memory] Failed to decay confidence:", err))
+        )
+      );
+    }
+    return decayed.length;
+  }
+  /**
+   * Prunes (deletes) memory entries that are expired or have very low confidence.
+   * An entry is pruned if:
+   * - confidence < 0.1, OR
+   * - expiresAt is set and has passed
+   *
+   * @param agentId - Optional: limit pruning to a specific agent. If omitted, prunes all.
+   * @returns Number of entries pruned
+   */
+  async pruneExpired(agentId) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const toDelete = [];
+    const entries = agentId ? this.getAgentMemories(agentId) : Array.from(this.memories.values());
+    for (const entry of entries) {
+      const isLowConfidence = entry.confidence < 0.1;
+      const isExpired = entry.expiresAt && entry.expiresAt <= now;
+      if (isLowConfidence || isExpired) {
+        toDelete.push({ id: entry.id, agentId: entry.agentId });
+      }
+    }
+    for (const item of toDelete) {
+      this.memories.delete(item.id);
+      this.indexRemove(item.agentId, item.id);
+      this.searchIndex.removeDocument(item.id);
+    }
+    if (toDelete.length > 0 && this.engineDb) {
+      await Promise.all(
+        toDelete.map(
+          (item) => this.engineDb.execute("DELETE FROM agent_memory WHERE id = ?", [item.id]).catch((err) => console.error("[agent-memory] Failed to prune memory entry:", err))
+        )
+      );
+    }
+    return toDelete.length;
+  }
+  // ─── Statistics ─────────────────────────────────────
+  /**
+   * Returns aggregate statistics for a specific agent's memory entries.
+   */
+  async getStats(agentId) {
+    let entries = this.getAgentMemories(agentId);
+    if (entries.length === 0 && this.engineDb) {
+      await this.queryMemories({ agentId, limit: 1e3 });
+      entries = this.getAgentMemories(agentId);
+    }
+    return this.computeStats(entries);
+  }
+  /**
+   * Returns per-agent memory statistics for all agents in an organization.
+   */
+  async getStatsByOrg(orgId) {
+    const agentMap = /* @__PURE__ */ new Map();
+    for (const entry of this.memories.values()) {
+      if (entry.orgId !== orgId) continue;
+      const group = agentMap.get(entry.agentId) || [];
+      group.push(entry);
+      agentMap.set(entry.agentId, group);
+    }
+    const results = [];
+    for (const [agentId, entries] of Array.from(agentMap.entries())) {
+      results.push({ agentId, stats: this.computeStats(entries) });
+    }
+    return results;
+  }
+  /**
+   * Computes statistics from a set of memory entries.
+   */
+  computeStats(entries) {
+    const byCategory = {};
+    const byImportance = {};
+    const bySource = {};
+    let totalConfidence = 0;
+    for (const entry of entries) {
+      byCategory[entry.category] = (byCategory[entry.category] || 0) + 1;
+      byImportance[entry.importance] = (byImportance[entry.importance] || 0) + 1;
+      bySource[entry.source] = (bySource[entry.source] || 0) + 1;
+      totalConfidence += entry.confidence;
+    }
+    return {
+      totalEntries: entries.length,
+      byCategory,
+      byImportance,
+      bySource,
+      avgConfidence: entries.length > 0 ? parseFloat((totalConfidence / entries.length).toFixed(4)) : 0
+    };
+  }
+  // ─── Policy Integration ─────────────────────────────
+  /**
+   * Creates a memory entry from an organization policy.
+   * Used during onboarding to seed agent memory with policy knowledge.
+   *
+   * Importance is derived from policy enforcement level:
+   * - mandatory  -> critical
+   * - recommended -> high
+   * - informational / other -> normal
+   */
+  async createFromPolicy(agentId, policy) {
+    const importance = policy.enforcement === "mandatory" ? "critical" : policy.enforcement === "recommended" ? "high" : "normal";
+    return this.createMemory({
+      agentId,
+      orgId: policy.orgId,
+      category: "org_knowledge",
+      title: policy.name,
+      content: policy.content,
+      source: "onboarding",
+      importance,
+      confidence: 1,
+      lastAccessedAt: void 0,
+      expiresAt: void 0,
+      tags: ["policy", policy.category],
+      metadata: {
+        policyId: policy.id,
+        enforcement: policy.enforcement
+      }
+    });
+  }
+  // ─── Row Mapper ─────────────────────────────────────
+  /**
+   * Converts a database row into an AgentMemoryEntry.
+   */
+  rowToEntry(row) {
+    return {
+      id: row.id,
+      agentId: row.agent_id,
+      orgId: row.org_id,
+      category: row.category,
+      title: row.title,
+      content: row.content,
+      source: row.source,
+      importance: row.importance,
+      confidence: row.confidence,
+      accessCount: row.access_count || 0,
+      lastAccessedAt: row.last_accessed_at || void 0,
+      expiresAt: row.expires_at || void 0,
+      tags: Array.isArray(row.tags) ? row.tags : Array.isArray(sj(row.tags)) ? sj(row.tags) : [],
+      metadata: sj(row.metadata || "{}"),
+      createdAt: row.created_at,
+      updatedAt: row.updated_at
+    };
+  }
+};
+
+export {
+  MEMORY_CATEGORIES,
+  AgentMemoryManager
+};