@agenticmail/core 0.9.14 → 0.9.15

package/dist/index.cjs

@@ -711,6 +711,7 @@ __export(index_exports, {
   AGENT_ROLES: () => AGENT_ROLES,
   AccountManager: () => AccountManager,
   AgentDeletionService: () => AgentDeletionService,
+  AgentMemoryManager: () => AgentMemoryManager,
   AgentMemoryStore: () => AgentMemoryStore,
   AgenticMailClient: () => AgenticMailClient,
   BRIDGE_OPERATOR_LIVE_WINDOW_MS: () => BRIDGE_OPERATOR_LIVE_WINDOW_MS,
@@ -727,8 +728,10 @@ __export(index_exports, {
   EmailSearchIndex: () => EmailSearchIndex,
   GatewayManager: () => GatewayManager,
   InboxWatcher: () => InboxWatcher,
+  MEMORY_CATEGORIES: () => MEMORY_CATEGORIES,
   MailReceiver: () => MailReceiver,
   MailSender: () => MailSender,
+  MemorySearchIndex: () => MemorySearchIndex,
   PHONE_MAX_CONCURRENT_MISSIONS: () => PHONE_MAX_CONCURRENT_MISSIONS,
   PHONE_MIN_WEBHOOK_SECRET_LENGTH: () => PHONE_MIN_WEBHOOK_SECRET_LENGTH,
   PHONE_MISSION_STATES: () => PHONE_MISSION_STATES,
@@ -819,7 +822,9 @@ __export(index_exports, {
   setTelemetryVersion: () => setTelemetryVersion,
   shouldSkipBridgeWakeForLiveOperator: () => shouldSkipBridgeWakeForLiveOperator,
   startRelayBridge: () => startRelayBridge,
+  stem: () => stem,
   threadIdFor: () => threadIdFor,
+  tokenize: () => tokenize,
   tryJoin: () => tryJoin,
   validateApiUrl: () => validateApiUrl,
   validatePhoneMissionPolicy: () => validatePhoneMissionPolicy,
@@ -2221,6 +2226,10 @@ var AccountManager = class {
     }
     const stmt = this.db.prepare("DELETE FROM agents WHERE id = ?");
     const result = stmt.run(id);
+    try {
+      this.db.prepare("DELETE FROM agent_memory WHERE agent_id = ?").run(id);
+    } catch {
+    }
     return result.changes > 0;
   }
   /**
@@ -10099,11 +10108,891 @@ function parse(raw) {
   }
   return out;
 }
+
+// src/memory/manager.ts
+var import_node_crypto6 = require("crypto");
+
+// src/memory/text-search.ts
+var BM25_K1 = 1.2;
+var BM25_B = 0.75;
+var FIELD_WEIGHT_TITLE = 3;
+var FIELD_WEIGHT_TAGS = 2;
+var FIELD_WEIGHT_CONTENT = 1;
+var PREFIX_MATCH_PENALTY = 0.7;
+var STOP_WORDS = /* @__PURE__ */ new Set([
+  "a",
+  "about",
+  "above",
+  "after",
+  "again",
+  "against",
+  "all",
+  "am",
+  "an",
+  "and",
+  "any",
+  "are",
+  "as",
+  "at",
+  "be",
+  "because",
+  "been",
+  "before",
+  "being",
+  "below",
+  "between",
+  "both",
+  "but",
+  "by",
+  "can",
+  "could",
+  "did",
+  "do",
+  "does",
+  "doing",
+  "down",
+  "during",
+  "each",
+  "either",
+  "every",
+  "few",
+  "for",
+  "from",
+  "further",
+  "get",
+  "got",
+  "had",
+  "has",
+  "have",
+  "having",
+  "he",
+  "her",
+  "here",
+  "hers",
+  "herself",
+  "him",
+  "himself",
+  "his",
+  "how",
+  "i",
+  "if",
+  "in",
+  "into",
+  "is",
+  "it",
+  "its",
+  "itself",
+  "just",
+  "may",
+  "me",
+  "might",
+  "more",
+  "most",
+  "must",
+  "my",
+  "myself",
+  "neither",
+  "no",
+  "nor",
+  "not",
+  "now",
+  "of",
+  "off",
+  "on",
+  "once",
+  "only",
+  "or",
+  "other",
+  "ought",
+  "our",
+  "ours",
+  "ourselves",
+  "out",
+  "over",
+  "own",
+  "same",
+  "shall",
+  "she",
+  "should",
+  "so",
+  "some",
+  "such",
+  "than",
+  "that",
+  "the",
+  "their",
+  "theirs",
+  "them",
+  "themselves",
+  "then",
+  "there",
+  "these",
+  "they",
+  "this",
+  "those",
+  "through",
+  "to",
+  "too",
+  "under",
+  "until",
+  "up",
+  "us",
+  "very",
+  "was",
+  "we",
+  "were",
+  "what",
+  "when",
+  "where",
+  "which",
+  "while",
+  "who",
+  "whom",
+  "why",
+  "will",
+  "with",
+  "would",
+  "yet",
+  "you",
+  "your",
+  "yours",
+  "yourself",
+  "yourselves"
+]);
+var STEM_RULES = [
+  // Step 1: plurals and past participles
+  [/ies$/, "i", 3],
+  // policies → polici,eries → eri
+  [/sses$/, "ss", 4],
+  // addresses → address
+  [/([^s])s$/, "$1", 3],
+  // items → item, but not "ss"
+  [/eed$/, "ee", 4],
+  // agreed → agree
+  [/ed$/, "", 3],
+  // configured → configur, but min length 3
+  [/ing$/, "", 4],
+  // running → runn → run (handled below)
+  // Step 2: derivational suffixes
+  [/ational$/, "ate", 6],
+  // relational → relate
+  [/tion$/, "t", 5],
+  // adoption → adopt
+  [/ness$/, "", 5],
+  // awareness → aware
+  [/ment$/, "", 5],
+  // deployment → deploy
+  [/able$/, "", 5],
+  // configurable → configur
+  [/ible$/, "", 5],
+  // accessible → access
+  [/ful$/, "", 5],
+  // powerful → power
+  [/ous$/, "", 5],
+  // dangerous → danger
+  [/ive$/, "", 5],
+  // interactive → interact
+  [/ize$/, "", 4],
+  // normalize → normal
+  [/ise$/, "", 4],
+  // organise → organ
+  [/ally$/, "", 5],
+  // automatically → automat
+  [/ly$/, "", 4],
+  // quickly → quick
+  [/er$/, "", 4]
+  // handler → handl
+];
+var DOUBLE_CONSONANT = /([^aeiou])\1$/;
+function stem(word) {
+  if (word.length < 3) return word;
+  let stemmed = word;
+  for (const [pattern, replacement, minLen] of STEM_RULES) {
+    if (stemmed.length >= minLen && pattern.test(stemmed)) {
+      stemmed = stemmed.replace(pattern, replacement);
+      break;
+    }
+  }
+  if (stemmed.length > 2 && DOUBLE_CONSONANT.test(stemmed)) {
+    stemmed = stemmed.slice(0, -1);
+  }
+  return stemmed;
+}
+function tokenize(text) {
+  return text.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length > 1 && !STOP_WORDS.has(t)).map(stem);
+}
+var MemorySearchIndex = class {
+  /** Posting lists: stemmed term → Set of memory IDs containing it */
+  postings = /* @__PURE__ */ new Map();
+  /** Per-document metadata for BM25 scoring */
+  docs = /* @__PURE__ */ new Map();
+  /** Pre-computed IDF values. Stale flag triggers lazy recomputation. */
+  idf = /* @__PURE__ */ new Map();
+  idfStale = true;
+  /** 3-character prefix map for prefix matching: prefix → Set of full stems */
+  prefixMap = /* @__PURE__ */ new Map();
+  /** Total weighted document length (for computing average) */
+  totalWeightedLen = 0;
+  get docCount() {
+    return this.docs.size;
+  }
+  get avgDocLen() {
+    return this.docs.size > 0 ? this.totalWeightedLen / this.docs.size : 1;
+  }
+  /**
+   * Index a memory entry. Extracts stems from title, content, and tags
+   * with field-specific weighting and builds posting lists.
+   */
+  addDocument(id, entry) {
+    if (this.docs.has(id)) this.removeDocument(id);
+    const titleTokens = tokenize(entry.title);
+    const contentTokens = tokenize(entry.content);
+    const tagTokens = entry.tags.flatMap((t) => tokenize(t));
+    const weightedTf = /* @__PURE__ */ new Map();
+    for (const t of titleTokens) weightedTf.set(t, (weightedTf.get(t) || 0) + FIELD_WEIGHT_TITLE);
+    for (const t of tagTokens) weightedTf.set(t, (weightedTf.get(t) || 0) + FIELD_WEIGHT_TAGS);
+    for (const t of contentTokens) weightedTf.set(t, (weightedTf.get(t) || 0) + FIELD_WEIGHT_CONTENT);
+    const weightedLen = titleTokens.length * FIELD_WEIGHT_TITLE + tagTokens.length * FIELD_WEIGHT_TAGS + contentTokens.length * FIELD_WEIGHT_CONTENT;
+    const allStems = /* @__PURE__ */ new Set();
+    for (const t of weightedTf.keys()) allStems.add(t);
+    const stemSequence = [...titleTokens, ...contentTokens];
+    const docRecord = { weightedTf, weightedLen, allStems, stemSequence };
+    this.docs.set(id, docRecord);
+    this.totalWeightedLen += weightedLen;
+    for (const term of allStems) {
+      let posting = this.postings.get(term);
+      if (!posting) {
+        posting = /* @__PURE__ */ new Set();
+        this.postings.set(term, posting);
+      }
+      posting.add(id);
+      if (term.length >= 3) {
+        const prefix = term.slice(0, 3);
+        let prefixSet = this.prefixMap.get(prefix);
+        if (!prefixSet) {
+          prefixSet = /* @__PURE__ */ new Set();
+          this.prefixMap.set(prefix, prefixSet);
+        }
+        prefixSet.add(term);
+      }
+    }
+    this.idfStale = true;
+  }
+  /** Remove a document from the index. */
+  removeDocument(id) {
+    const doc = this.docs.get(id);
+    if (!doc) return;
+    this.totalWeightedLen -= doc.weightedLen;
+    this.docs.delete(id);
+    for (const term of doc.allStems) {
+      const posting = this.postings.get(term);
+      if (posting) {
+        posting.delete(id);
+        if (posting.size === 0) {
+          this.postings.delete(term);
+          if (term.length >= 3) {
+            const prefixSet = this.prefixMap.get(term.slice(0, 3));
+            if (prefixSet) {
+              prefixSet.delete(term);
+              if (prefixSet.size === 0) this.prefixMap.delete(term.slice(0, 3));
+            }
+          }
+        }
+      }
+    }
+    this.idfStale = true;
+  }
+  /** Recompute IDF values for all terms. Called lazily before search. */
+  refreshIdf() {
+    if (!this.idfStale) return;
+    const N = this.docs.size;
+    this.idf.clear();
+    for (const [term, posting] of this.postings) {
+      const df = posting.size;
+      this.idf.set(term, Math.log((N - df + 0.5) / (df + 0.5) + 1));
+    }
+    this.idfStale = false;
+  }
+  /**
+   * Expand query terms with prefix matches.
+   * "deploy" → ["deploy", "deployment", "deploying", ...] (if they exist in the index)
+   */
+  expandQueryTerms(queryStems) {
+    const expanded = /* @__PURE__ */ new Map();
+    for (const qs of queryStems) {
+      if (this.postings.has(qs)) {
+        expanded.set(qs, Math.max(expanded.get(qs) || 0, 1));
+      }
+      if (qs.length >= 3) {
+        const prefix = qs.slice(0, 3);
+        const candidates = this.prefixMap.get(prefix);
+        if (candidates) {
+          for (const candidate of candidates) {
+            if (candidate !== qs && candidate.startsWith(qs)) {
+              expanded.set(candidate, Math.max(expanded.get(candidate) || 0, PREFIX_MATCH_PENALTY));
+            }
+          }
+        }
+      }
+    }
+    return expanded;
+  }
+  /**
+   * Compute bigram proximity boost: if two query terms appear adjacent
+   * in the document's stem sequence, boost the score.
+   */
+  bigramProximityBoost(docId, queryStems) {
+    if (queryStems.length < 2) return 0;
+    const doc = this.docs.get(docId);
+    if (!doc || doc.stemSequence.length < 2) return 0;
+    let boost = 0;
+    const seq = doc.stemSequence;
+    const querySet = new Set(queryStems);
+    for (let i = 0; i < seq.length - 1; i++) {
+      if (querySet.has(seq[i]) && querySet.has(seq[i + 1]) && seq[i] !== seq[i + 1]) {
+        boost += 0.5;
+      }
+    }
+    return Math.min(boost, 2);
+  }
+  /**
+   * Search the index for documents matching a query.
+   * Returns scored results sorted by BM25F relevance.
+   *
+   * @param query - Raw query string
+   * @param candidateIds - Optional: only score these document IDs (for agent-scoped search)
+   * @returns Array of { id, score } sorted by descending score
+   */
+  search(query, candidateIds) {
+    const queryStems = tokenize(query);
+    if (queryStems.length === 0) return [];
+    this.refreshIdf();
+    const expandedTerms = this.expandQueryTerms(queryStems);
+    if (expandedTerms.size === 0) return [];
+    const avgDl = this.avgDocLen;
+    const candidates = /* @__PURE__ */ new Set();
+    for (const term of expandedTerms.keys()) {
+      const posting = this.postings.get(term);
+      if (posting) {
+        for (const docId of posting) {
+          if (!candidateIds || candidateIds.has(docId)) candidates.add(docId);
+        }
+      }
+    }
+    const results = [];
+    for (const docId of candidates) {
+      const doc = this.docs.get(docId);
+      if (!doc) continue;
+      let score = 0;
+      for (const [term, weight] of expandedTerms) {
+        const tf = doc.weightedTf.get(term) || 0;
+        if (tf === 0) continue;
+        const termIdf = this.idf.get(term) || 0;
+        const numerator = tf * (BM25_K1 + 1);
+        const denominator = tf + BM25_K1 * (1 - BM25_B + BM25_B * (doc.weightedLen / avgDl));
+        score += termIdf * (numerator / denominator) * weight;
+      }
+      score += this.bigramProximityBoost(docId, queryStems);
+      if (score > 0) results.push({ id: docId, score });
+    }
+    results.sort((a, b) => b.score - a.score);
+    return results;
+  }
+  /** Check if a document exists in the index. */
+  has(id) {
+    return this.docs.has(id);
+  }
+};
+
+// src/memory/manager.ts
+function sj(v, fb = {}) {
+  if (!v) return fb;
+  try {
+    return JSON.parse(v);
+  } catch {
+    return fb;
+  }
+}
+var MEMORY_CATEGORIES = {
+  knowledge: {
+    label: "Knowledge",
+    description: "Facts, procedures, and reference information the agent has learned"
+  },
+  interaction_pattern: {
+    label: "Interaction Patterns",
+    description: "Learned patterns from past interactions"
+  },
+  preference: {
+    label: "Preferences",
+    description: "User and counterparty 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 VALID_CATEGORIES = new Set(Object.keys(MEMORY_CATEGORIES));
+var VALID_IMPORTANCE = /* @__PURE__ */ new Set(["critical", "high", "normal", "low"]);
+var IMPORTANCE_WEIGHT = {
+  critical: 4,
+  high: 3,
+  normal: 2,
+  low: 1
+};
+var AgentMemoryManager = class {
+  constructor(db2) {
+    this.db = db2;
+    this.ensureTable();
+    this.loadFromDb();
+  }
+  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();
+  initialized = false;
+  // ─── Database layer ─────────────────────────────────
+  ensureTable() {
+    if (this.initialized) return;
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS agent_memory (
+        id TEXT PRIMARY KEY,
+        agent_id TEXT NOT NULL,
+        category TEXT NOT NULL,
+        title TEXT NOT NULL,
+        content TEXT NOT NULL,
+        source TEXT NOT NULL DEFAULT 'interaction',
+        importance TEXT NOT NULL DEFAULT 'normal',
+        confidence REAL NOT NULL DEFAULT 1.0,
+        access_count INTEGER NOT NULL DEFAULT 0,
+        last_accessed_at TEXT,
+        expires_at TEXT,
+        tags TEXT NOT NULL DEFAULT '[]',
+        metadata TEXT NOT NULL DEFAULT '{}',
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+      )
+    `);
+    try {
+      this.db.exec("CREATE INDEX IF NOT EXISTS idx_agent_memory_agent ON agent_memory(agent_id)");
+    } catch {
+    }
+    try {
+      this.db.exec("CREATE INDEX IF NOT EXISTS idx_agent_memory_category ON agent_memory(category)");
+    } catch {
+    }
+    this.initialized = true;
+  }
+  /** Run a write statement, swallowing errors with a log (memory must never crash a caller). */
+  dbRun(sql, params) {
+    try {
+      this.db.prepare(sql).run(...params);
+    } catch (err) {
+      console.error("[agent-memory] DB write failed:", err.message);
+    }
+  }
+  dbAll(sql, params = []) {
+    try {
+      return this.db.prepare(sql).all(...params);
+    } catch (err) {
+      console.error("[agent-memory] DB read failed:", err.message);
+      return [];
+    }
+  }
+  loadFromDb() {
+    const rows = this.dbAll("SELECT * FROM agent_memory");
+    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 {
+      }
+    }
+  }
+  /** 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. */
+  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 ─────────────────────────────
+  /** Store a memory with minimal input — the common "just remember this" case. */
+  async storeMemory(agentId, opts) {
+    const category = opts.category && VALID_CATEGORIES.has(opts.category) ? opts.category : "context";
+    const importance = opts.importance && VALID_IMPORTANCE.has(opts.importance) ? opts.importance : "normal";
+    return this.createMemory({
+      agentId,
+      content: opts.content,
+      category,
+      importance,
+      confidence: opts.confidence ?? 1,
+      title: opts.title || opts.content.slice(0, 80),
+      source: "system",
+      tags: opts.tags ?? [],
+      metadata: {}
+    });
+  }
+  /** Search memories by text query, sorted by relevance. */
+  async recall(agentId, query, limit = 5) {
+    return this.queryMemories({ agentId, query, limit });
+  }
+  // ─── CRUD Operations ────────────────────────────────
+  /** Create a new memory entry with auto-generated id + timestamps. */
+  async createMemory(input) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const entry = {
+      ...input,
+      confidence: input.confidence ?? 0.8,
+      tags: input.tags ?? [],
+      metadata: input.metadata ?? {},
+      id: (0, import_node_crypto6.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);
+    this.dbRun(
+      `INSERT INTO agent_memory (id, agent_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.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
+      ]
+    );
+    return entry;
+  }
+  /** Update an existing memory entry by merging provided fields. */
+  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,
+      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);
+    }
+    this.dbRun(
+      `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
+      ]
+    );
+    return updated;
+  }
+  /** Delete a single memory entry. Returns true if it existed. */
+  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);
+    this.dbRun("DELETE FROM agent_memory WHERE id = ?", [id]);
+    return existed;
+  }
+  /**
+   * Purge every memory entry belonging to an agent — Map, per-agent
+   * index, search index, and the database row. Called when an agent is
+   * deleted so no orphaned memory is left behind.
+   * Returns the number of entries removed.
+   */
+  async deleteAgentMemories(agentId) {
+    const ids = Array.from(this.agentIndex.get(agentId) ?? []);
+    for (const id of ids) {
+      this.memories.delete(id);
+      this.searchIndex.removeDocument(id);
+    }
+    this.agentIndex.delete(agentId);
+    this.dbRun("DELETE FROM agent_memory WHERE agent_id = ?", [agentId]);
+    return ids.length;
+  }
+  /** Retrieve a single memory entry by id. */
+  async getMemory(id) {
+    return this.memories.get(id);
+  }
+  // ─── Query Operations ───────────────────────────────
+  /** Query an agent's memory with optional category/importance/source filters + text search. */
+  async queryMemories(opts) {
+    let results = this.getAgentMemories(opts.agentId);
+    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);
+      }
+      return [];
+    }
+    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();
+    });
+    return results.slice(0, opts.limit || 100);
+  }
+  /** 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 ────────────────────────────────
+  /** Bump access count + lastAccessedAt for a memory entry. */
+  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;
+    this.dbRun(
+      "UPDATE agent_memory SET access_count = ?, last_accessed_at = ?, updated_at = ? WHERE id = ?",
+      [entry.accessCount, entry.lastAccessedAt, entry.updatedAt, memoryId]
+    );
+  }
+  // ─── Context Generation ─────────────────────────────
+  /**
+   * Render an agent's memory as a markdown block for prompt injection.
+   * Ranks entries by confidence × access × recency × importance, with a
+   * BM25F relevance boost when a query is supplied, groups by category,
+   * and truncates to ~maxTokens (estimated at 4 chars/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 header2 = `### ${meta.label}`;
+      if (charCount + header2.length + 2 > maxChars) break;
+      lines.push(header2, "");
+      charCount += header2.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 ───────────────────────────────
+  /** Decay confidence for entries unaccessed for 7+ days. Critical entries are exempt. */
+  async decayConfidence(agentId, decayRate = 0.05) {
+    const cutoff = new Date(Date.now() - 7 * 864e5).toISOString();
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    let decayed = 0;
+    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;
+      this.dbRun(
+        "UPDATE agent_memory SET confidence = ?, updated_at = ? WHERE id = ?",
+        [entry.confidence, now, entry.id]
+      );
+      decayed += 1;
+    }
+    return decayed;
+  }
+  /** Prune entries with confidence < 0.1 or past their expiresAt. */
+  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);
+      this.dbRun("DELETE FROM agent_memory WHERE id = ?", [item.id]);
+    }
+    return toDelete.length;
+  }
+  // ─── Statistics ─────────────────────────────────────
+  /** Aggregate statistics for a specific agent's memory. */
+  async getStats(agentId) {
+    return this.computeStats(this.getAgentMemories(agentId));
+  }
+  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
+    };
+  }
+  // ─── Row Mapper ─────────────────────────────────────
+  rowToEntry(row) {
+    return {
+      id: row.id,
+      agentId: row.agent_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(sj(row.tags)) ? sj(row.tags) : [],
+      metadata: sj(row.metadata || "{}"),
+      createdAt: row.created_at,
+      updatedAt: row.updated_at
+    };
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AGENT_ROLES,
   AccountManager,
   AgentDeletionService,
+  AgentMemoryManager,
   AgentMemoryStore,
   AgenticMailClient,
   BRIDGE_OPERATOR_LIVE_WINDOW_MS,
@@ -10120,8 +11009,10 @@ function parse(raw) {
   EmailSearchIndex,
   GatewayManager,
   InboxWatcher,
+  MEMORY_CATEGORIES,
   MailReceiver,
   MailSender,
+  MemorySearchIndex,
   PHONE_MAX_CONCURRENT_MISSIONS,
   PHONE_MIN_WEBHOOK_SECRET_LENGTH,
   PHONE_MISSION_STATES,
@@ -10212,7 +11103,9 @@ function parse(raw) {
   setTelemetryVersion,
   shouldSkipBridgeWakeForLiveOperator,
   startRelayBridge,
+  stem,
   threadIdFor,
+  tokenize,
   tryJoin,
   validateApiUrl,
   validatePhoneMissionPolicy,