onbuzz 4.8.3 → 4.9.1

package/src/tools/memoryTool.js

@@ -19,6 +19,8 @@
 
 import { BaseTool } from './baseTool.js';
 import { getMemoryService, PLAN_TITLE_PREFIX } from '../services/memoryService.js';
+import { MemoryIndexer } from '../services/embeddings/indexers/memoryIndexer.js';
+import { ReminisceIndexer } from '../services/embeddings/indexers/reminisceIndexer.js';
 
 /**
  * True if the given memory title is a "working plan" — those are
@@ -99,12 +101,25 @@ After add/update of a plan/* memory, the tool DOES NOT echo the content back
 in the result — it would duplicate the header injection. You'll see the plan
 in your system prompt on the next turn instead.
 
-USAGE:
+USAGE (canonical plural — same shape across all tools):
 \`\`\`json
 {
   "toolId": "memory",
-  "action": "<action>",
-  "parameters": { ... }
+  "actions": [
+    {"type": "read", "id": "mem-123-abc"}
+  ]
+}
+\`\`\`
+
+BATCH multiple memory operations in one call:
+\`\`\`json
+{
+  "toolId": "memory",
+  "actions": [
+    {"type": "read", "id": "mem-auth-plan"},
+    {"type": "read", "id": "mem-retry-policy"},
+    {"type": "append", "id": "mem-auth-plan", "content": "Step 4 added: revoke v1 tokens"}
+  ]
 }
 \`\`\`
 
@@ -114,11 +129,13 @@ ACTIONS:
 \`\`\`json
 {
   "toolId": "memory",
-  "action": "add",
-  "title": "User prefers TypeScript",
-  "description": "Programming language preference",
-  "content": "The user explicitly stated they prefer TypeScript over JavaScript.",
-  "expiration": null
+  "actions": [{
+    "type": "add",
+    "title": "User prefers TypeScript",
+    "description": "Programming language preference",
+    "content": "The user explicitly stated they prefer TypeScript over JavaScript.",
+    "expiration": null
+  }]
 }
 \`\`\`
 
@@ -131,12 +148,14 @@ Expiration options:
 \`\`\`json
 {
   "toolId": "memory",
-  "action": "update",
-  "id": "mem-123-abc",
-  "title": "Updated title",
-  "description": "Updated description",
-  "content": "Updated content",
-  "expiration": "2025-12-31"
+  "actions": [{
+    "type": "update",
+    "id": "mem-123-abc",
+    "title": "Updated title",
+    "description": "Updated description",
+    "content": "Updated content",
+    "expiration": "2025-12-31"
+  }]
 }
 \`\`\`
 
@@ -144,8 +163,7 @@ Expiration options:
 \`\`\`json
 {
   "toolId": "memory",
-  "action": "delete",
-  "id": "mem-123-abc"
+  "actions": [{"type": "delete", "id": "mem-123-abc"}]
 }
 \`\`\`
 
@@ -153,8 +171,7 @@ Expiration options:
 \`\`\`json
 {
   "toolId": "memory",
-  "action": "list",
-  "level": "titles"
+  "actions": [{"type": "list", "level": "titles"}]
 }
 \`\`\`
 
@@ -167,8 +184,7 @@ Level options:
 \`\`\`json
 {
   "toolId": "memory",
-  "action": "read",
-  "id": "mem-123-abc"
+  "actions": [{"type": "read", "id": "mem-123-abc"}]
 }
 \`\`\`
 
@@ -176,8 +192,7 @@ Level options:
 \`\`\`json
 {
   "toolId": "memory",
-  "action": "search",
-  "query": "TypeScript"
+  "actions": [{"type": "search", "query": "TypeScript"}]
 }
 \`\`\`
 
@@ -185,7 +200,7 @@ Level options:
 \`\`\`json
 {
   "toolId": "memory",
-  "action": "stats"
+  "actions": [{"type": "stats"}]
 }
 \`\`\`
 
@@ -389,47 +404,89 @@ BEST PRACTICES:
    */
   customValidateParameters(params) {
     const errors = [];
-    const validActions = ['add', 'update', 'delete', 'list', 'read', 'search', 'stats', 'reminisce'];
+    const validActions = ['add', 'update', 'append', 'delete', 'list', 'read', 'search', 'semantic-search', 'backfill-embeddings', 'reminisce-backfill-embeddings', 'forget-stale', 'publish-to-team', 'search-team', 'unpublish-from-team', 'stats', 'reminisce'];
 
-    if (!params.action) {
-      errors.push('action is required');
-    } else if (!validActions.includes(params.action)) {
-      errors.push(`action must be one of: ${validActions.join(', ')}`);
+    // Normalize to the canonical actions[] shape and validate every action.
+    // Accepts both the canonical plural `{actions: [{type, ...}]}` and the
+    // legacy singular `{action: "X", ...}` shapes — the executor's
+    // _normalizeToActions handles the runtime promotion identically.
+    const actions = this._normalizeToActions(params);
+
+    if (actions.length === 0) {
+      errors.push('action is required (or `actions: [...]` for batched calls)');
     } else {
-      // Validate action-specific requirements
-      switch (params.action) {
-        case 'add':
-          if (!params.title) errors.push('title is required for add action');
-          if (!params.content) errors.push('content is required for add action');
-          break;
-        case 'update':
-          if (!params.id) errors.push('id is required for update action');
-          break;
-        case 'delete':
-          if (!params.id) errors.push('id is required for delete action');
-          break;
-        case 'read':
-          if (!params.id) errors.push('id is required for read action');
-          break;
-        case 'search':
-          if (!params.query) errors.push('query is required for search action');
-          break;
+      for (let i = 0; i < actions.length; i++) {
+        const a = actions[i];
+        const tag = actions.length > 1 ? `actions[${i}]: ` : '';
+        if (!a || typeof a !== 'object') {
+          errors.push(`${tag}must be an object with a "type" field`);
+          continue;
+        }
+        const t = a.type;
+        if (!t) {
+          errors.push(`${tag}"type" is required`);
+          continue;
+        }
+        if (!validActions.includes(t)) {
+          errors.push(`${tag}type must be one of: ${validActions.join(', ')}`);
+          continue;
+        }
+        switch (t) {
+          case 'add':
+            if (!a.title)   errors.push(`${tag}title is required for add`);
+            if (!a.content) errors.push(`${tag}content is required for add`);
+            break;
+          case 'update':
+            if (!a.id) errors.push(`${tag}id is required for update`);
+            break;
+          case 'append':
+            if (!a.id)      errors.push(`${tag}id is required for append`);
+            if (!a.content) errors.push(`${tag}content is required for append`);
+            break;
+          case 'delete':
+            if (!a.id) errors.push(`${tag}id is required for delete`);
+            break;
+          case 'read':
+            if (!a.id) errors.push(`${tag}id is required for read`);
+            break;
+          case 'search':
+            if (!a.query) errors.push(`${tag}query is required for search`);
+            break;
+          case 'semantic-search':
+            if (!a.query) errors.push(`${tag}query is required for semantic-search`);
+            if (a.topK != null && (!Number.isInteger(a.topK) || a.topK <= 0)) {
+              errors.push(`${tag}topK must be a positive integer when provided`);
+            }
+            break;
+          case 'forget-stale':
+            if (a.ageDays != null && (!Number.isFinite(a.ageDays) || a.ageDays <= 0)) {
+              errors.push(`${tag}ageDays must be a positive number when provided`);
+            }
+            break;
+          case 'publish-to-team':
+            if (!a.id) errors.push(`${tag}id is required for publish-to-team (the memory id to publish)`);
+            if (!a.teamId) errors.push(`${tag}teamId is required for publish-to-team`);
+            break;
+          case 'search-team':
+            if (!a.teamId) errors.push(`${tag}teamId is required for search-team`);
+            if (!a.query)  errors.push(`${tag}query is required for search-team`);
+            if (a.topK != null && (!Number.isInteger(a.topK) || a.topK <= 0)) {
+              errors.push(`${tag}topK must be a positive integer when provided`);
+            }
+            break;
+          case 'unpublish-from-team':
+            if (!a.id) errors.push(`${tag}id is required for unpublish-from-team`);
+            if (!a.teamId) errors.push(`${tag}teamId is required for unpublish-from-team`);
+            break;
+          // backfill-embeddings has no required params (re-indexes everything).
+        }
+        // Length limits (per-action).
+        if (a.title    && a.title.length    > 200)   errors.push(`${tag}title cannot exceed 200 characters`);
+        if (a.description && a.description.length > 500) errors.push(`${tag}description cannot exceed 500 characters`);
+        if (a.content  && a.content.length  > 10000) errors.push(`${tag}content cannot exceed 10000 characters`);
       }
     }
 
-    // Length limits
-    if (params.title && params.title.length > 200) {
-      errors.push('title cannot exceed 200 characters');
-    }
-
-    if (params.description && params.description.length > 500) {
-      errors.push('description cannot exceed 500 characters');
-    }
-
-    if (params.content && params.content.length > 10000) {
-      errors.push('content cannot exceed 10000 characters');
-    }
-
     return {
       valid: errors.length === 0,
       errors
@@ -443,7 +500,6 @@ BEST PRACTICES:
    * @returns {Promise<Object>}
    */
   async execute(params, context) {
-    const { action } = params;
     const { agentId } = context;
 
     if (!agentId) {
@@ -452,32 +508,110 @@ BEST PRACTICES:
 
     const memoryService = await this._ensureMemoryService();
 
+    // PLURAL-CANONICAL DISPATCH — the canonical shape is
+    // `{actions: [{type: "read", id: "X"}, ...]}` matching the rest
+    // of the tool conventions (filesystem, terminal, taskmanager).
+    // Singular `{action: "read", id: "X"}` is auto-promoted as
+    // backward-compat for the agent's training-prior emissions.
+    // See commit 5e6b817 + the "tool envelope unification" thread.
+    const actions = this._normalizeToActions(params);
+
+    if (actions.length === 0) {
+      throw new Error('memory tool requires either `action` (singular) or `actions` (plural array). Each action needs a `type` (or `action`) field.');
+    }
+
+    // Single-action path → return one result directly (no array wrap)
+    // for backward-compat with every existing caller / test that
+    // expects the shape from the singular dispatch.
+    if (actions.length === 1) {
+      return await this._dispatchSingleAction(memoryService, agentId, actions[0], context);
+    }
+
+    // Multi-action path → execute sequentially, return array of results.
+    // Errors on one action don't abort the others — each result
+    // carries its own success/error state.
+    const results = [];
+    for (const a of actions) {
+      try {
+        const r = await this._dispatchSingleAction(memoryService, agentId, a, context);
+        results.push(r);
+      } catch (err) {
+        results.push({ success: false, action: a.type || a.action, error: err.message });
+      }
+    }
+    return {
+      success: results.every(r => r.success !== false),
+      batched: true,
+      actionCount: results.length,
+      results,
+    };
+  }
+
+  /**
+   * Promote a tool-call's params into a canonical actions[] array.
+   * Accepts:
+   *   { actions: [{type, ...}] }            (canonical plural)
+   *   { actions: [{action, ...}] }           (plural with `action` instead of `type`)
+   *   { action: "read", id: "X" }            (legacy singular at top level)
+   *   { action: "read", parameters: {...} }  (legacy singular with nested params)
+   * @private
+   */
+  _normalizeToActions(params) {
+    if (!params || typeof params !== 'object') return [];
+    if (Array.isArray(params.actions)) {
+      // Normalize each item: ensure `type` is set (rename `action`→`type`).
+      return params.actions.map(a => {
+        if (!a || typeof a !== 'object') return a;
+        if (!a.type && a.action) {
+          const { action, ...rest } = a;
+          return { type: action, ...rest };
+        }
+        return a;
+      });
+    }
+    if (params.action) {
+      const { action, parameters, ...rest } = params;
+      // Merge nested `parameters` (some callers wrap fields inside).
+      return [{ type: action, ...(parameters && typeof parameters === 'object' ? parameters : {}), ...rest }];
+    }
+    return [];
+  }
+
+  /**
+   * Dispatch a single normalized action {type, ...fields}.
+   * The downstream _executeX methods expect the legacy params shape
+   * (flat with `action: "X"`), so we adapt before calling.
+   * @private
+   */
+  async _dispatchSingleAction(memoryService, agentId, action, context) {
+    const { type, ...rest } = action;
+    const legacyParams = { action: type, ...rest };
     try {
-      switch (action) {
-        case 'add':
-          return await this._executeAdd(memoryService, agentId, params);
-        case 'update':
-          return await this._executeUpdate(memoryService, agentId, params);
-        case 'delete':
-          return await this._executeDelete(memoryService, agentId, params);
-        case 'list':
-          return await this._executeList(memoryService, agentId, params);
-        case 'read':
-          return await this._executeRead(memoryService, agentId, params);
-        case 'search':
-          return await this._executeSearch(memoryService, agentId, params);
-        case 'stats':
-          return await this._executeStats(memoryService, agentId);
-        case 'reminisce':
-          return await this._executeReminisce(agentId, params, context);
+      switch (type) {
+        case 'add':       return await this._executeAdd(memoryService, agentId, legacyParams);
+        case 'update':    return await this._executeUpdate(memoryService, agentId, legacyParams);
+        case 'append':    return await this._executeAppend(memoryService, agentId, legacyParams);
+        case 'delete':    return await this._executeDelete(memoryService, agentId, legacyParams);
+        case 'list':      return await this._executeList(memoryService, agentId, legacyParams);
+        case 'read':      return await this._executeRead(memoryService, agentId, legacyParams);
+        case 'search':            return await this._executeSearch(memoryService, agentId, legacyParams);
+        case 'semantic-search':   return await this._executeSemanticSearch(memoryService, agentId, legacyParams);
+        case 'backfill-embeddings': return await this._executeBackfillEmbeddings(memoryService, agentId);
+        case 'reminisce-backfill-embeddings': return await this._executeReminisceBackfill(agentId, context);
+        case 'forget-stale': return await this._executeForgetStale(memoryService, agentId, legacyParams);
+        case 'publish-to-team': return await this._executePublishToTeam(memoryService, agentId, legacyParams);
+        case 'search-team': return await this._executeSearchTeam(agentId, legacyParams);
+        case 'unpublish-from-team': return await this._executeUnpublishFromTeam(agentId, legacyParams);
+        case 'stats':             return await this._executeStats(memoryService, agentId);
+        case 'reminisce':         return await this._executeReminisce(agentId, legacyParams, context);
         default:
-          throw new Error(`Unknown action: ${action}`);
+          throw new Error(`Unknown memory action: ${type}`);
       }
     } catch (error) {
-      this.logger?.error(`Memory tool execution failed: ${error.message}`, {
+      this.logger?.error(`Memory tool action failed: ${error.message}`, {
         agentId,
-        action,
-        error: error.stack
+        type,
+        error: error.stack,
       });
       throw error;
     }
@@ -494,6 +628,11 @@ BEST PRACTICES:
       expiration: params.expiration
     });
 
+    // Fire-and-forget index update. Best-effort by design — the indexer's
+    // public surface swallows errors and returns a result, but we don't
+    // even await it so memory writes never wait on the embedding service.
+    this._asyncIndexMemory(agentId, memory);
+
     return {
       success: true,
       action: 'add',
@@ -532,6 +671,9 @@ BEST PRACTICES:
       };
     }
 
+    // Re-index after content change. Fire-and-forget.
+    this._asyncIndexMemory(agentId, memory);
+
     return {
       success: true,
       action: 'update',
@@ -546,6 +688,47 @@ BEST PRACTICES:
     };
   }
 
+  /**
+   * Execute APPEND action — additive update with a timestamped block.
+   *
+   * Designed for the "memory grows as the agent learns" use case:
+   * agent attaches a memory to a task on creation, then appends
+   * findings/methodology as work progresses. Each append becomes a
+   * dated section so the memory reads like a journal.
+   *
+   * Soft-cap behavior: once total content exceeds ~16K chars, the
+   * service compresses older blocks into a summary on subsequent
+   * appends. See memoryService.appendToMemory.
+   */
+  async _executeAppend(memoryService, agentId, params) {
+    const memory = await memoryService.appendToMemory(agentId, params.id, params.content);
+
+    if (!memory) {
+      return {
+        success: false,
+        action: 'append',
+        message: `Memory not found: ${params.id}`
+      };
+    }
+
+    // Re-index after content grew. Fire-and-forget.
+    this._asyncIndexMemory(agentId, memory);
+
+    return {
+      success: true,
+      action: 'append',
+      memory: {
+        id: memory.id,
+        title: memory.title,
+        updatedAt: memory.updatedAt,
+        contentLength: memory.content?.length || 0,
+      },
+      message: isPlanTitle(memory.title)
+        ? `Plan updated (append): "${memory.title}" — full content appears in AGENT WORKING PLAN next turn.`
+        : `Appended to memory: "${memory.title}" (now ${memory.content?.length || 0} chars)`
+    };
+  }
+
   /**
    * Execute DELETE action
    */
@@ -560,6 +743,9 @@ BEST PRACTICES:
       };
     }
 
+    // Drop the corresponding vector from the index. Fire-and-forget.
+    this._asyncRemoveFromIndex(agentId, params.id);
+
     return {
       success: true,
       action: 'delete',
@@ -659,6 +845,577 @@ BEST PRACTICES:
     };
   }
 
+  /**
+   * Execute SEMANTIC-SEARCH action — embeddings-backed retrieval over
+   * the agent's memory. Falls back to substring search when embeddings
+   * are disabled, so the action is always safe to call regardless of
+   * configuration. Hybrid mode (semantic + substring via RRF) is the
+   * default — preserves exact-match precision while adding paraphrase
+   * recall.
+   *
+   * Params: { query, topK?=10, hybrid?=true }
+   */
+  async _executeSemanticSearch(memoryService, agentId, params) {
+    const topK = Number.isInteger(params.topK) && params.topK > 0 ? params.topK : 10;
+    const hybrid = params.hybrid !== false;
+
+    const indexer = this._getMemoryIndexer();
+    if (!indexer || !indexer.isEnabled) {
+      // Graceful fallback: when the user hasn't enabled embeddings yet,
+      // return substring results so the action is still useful (and the
+      // agent doesn't need to branch on config).
+      const results = await memoryService.searchMemories(agentId, params.query);
+      return {
+        success: true,
+        action: 'semantic-search',
+        mode: 'substring-fallback',
+        query: params.query,
+        results,
+        message: results.length === 0
+          ? `Embeddings disabled; substring search found no matches for "${params.query}"`
+          : `Embeddings disabled; substring search found ${results.length} memories`,
+      };
+    }
+
+    const { hits, error } = await indexer.search(agentId, params.query, { topK, hybrid });
+
+    // Hydrate hits → full memory objects via memoryService.readMemory.
+    // The indexer returns vector-store metadata (title/text) which is a
+    // snapshot — fetching live ensures we surface the current content
+    // (in case it was updated since the last index sync).
+    const hydrated = [];
+    for (const h of hits) {
+      // eslint-disable-next-line no-await-in-loop
+      const mem = await memoryService.readMemory(agentId, h.id);
+      if (mem) hydrated.push({ ...mem, score: h.score });
+      else hydrated.push({ id: h.id, score: h.score, missing: true, ...h.metadata });
+    }
+
+    return {
+      success: !error,
+      action: 'semantic-search',
+      mode: hybrid ? 'hybrid' : 'semantic',
+      query: params.query,
+      topK,
+      results: hydrated,
+      ...(error ? { error } : {}),
+      message: error
+        ? `Semantic search failed: ${error}`
+        : hydrated.length === 0
+          ? `No memories matched "${params.query}"`
+          : `Found ${hydrated.length} memories ranked by similarity to "${params.query}"`,
+    };
+  }
+
+  /**
+   * Execute BACKFILL-EMBEDDINGS action — drop the agent's memory index
+   * and rebuild it from scratch. Use after enabling embeddings for the
+   * first time, after switching providers/models, or whenever the index
+   * is suspected stale. Idempotent.
+   */
+  async _executeBackfillEmbeddings(memoryService, agentId) {
+    const indexer = this._getMemoryIndexer();
+    if (!indexer || !indexer.isEnabled) {
+      return {
+        success: false,
+        action: 'backfill-embeddings',
+        message: 'Embeddings are not enabled — nothing to backfill. Enable a provider in Settings → Embeddings first.',
+      };
+    }
+
+    // Pull every memory for this agent. memoryService.listMemories at
+    // 'full' detail returns the full content blob per memory.
+    const listing = await memoryService.listMemories(agentId, 'full');
+    // listMemories returns { count, grouped }. The 'full' shape gives
+    // us per-bucket arrays of memory objects. Flatten + filter.
+    const memories = [];
+    for (const bucket of Object.values(listing.grouped || {})) {
+      for (const m of bucket || []) if (m?.id) memories.push(m);
+    }
+
+    const result = await indexer.backfill(agentId, memories);
+    return {
+      success: result.ok !== false,
+      action: 'backfill-embeddings',
+      indexed: result.indexed || 0,
+      skipped: result.skipped || 0,
+      failed: result.failed || 0,
+      ...(result.error ? { error: result.error } : {}),
+      message: result.ok === false
+        ? `Backfill failed: ${result.reason || result.error || 'unknown'}`
+        : `Re-indexed ${result.indexed || 0} memories for agent ${agentId}` +
+          (result.skipped ? ` (skipped ${result.skipped} with no text)` : '') +
+          (result.failed ? ` (failed ${result.failed})` : ''),
+    };
+  }
+
+  /**
+   * Execute FORGET-STALE action — delete memories older than `ageDays`.
+   *
+   * FadeMem-style soft pruning (arXiv 2601.18642): unbounded memory
+   * growth is the real long-term problem. The right answer is graceful
+   * decay of unused old memories so the index stays signal-rich.
+   *
+   * Defaults are conservative — `ageDays=90`, plan/* memories skipped.
+   * Pass `dryRun: true` to preview what would be removed. The cascade
+   * to the vector index is automatic (memoryService.deleteMemory fires
+   * the indexer's deleteOne via _asyncRemoveFromIndex).
+   *
+   * Params: { ageDays?=90, dryRun?=false, includePlans?=false }
+   * @private
+   */
+  async _executeForgetStale(memoryService, agentId, params) {
+    const ageDays = Number.isFinite(params.ageDays) && params.ageDays > 0 ? params.ageDays : 90;
+    const dryRun = !!params.dryRun;
+    const includePlans = !!params.includePlans;
+    const cutoffMs = Date.now() - ageDays * 24 * 60 * 60 * 1000;
+
+    // Walk the full memory list. Use 'descriptions' detail — enough to
+    // decide what's stale without pulling huge content blobs.
+    const listing = await memoryService.listMemories(agentId, 'full');
+    const candidates = [];
+    for (const bucket of Object.values(listing.grouped || {})) {
+      for (const m of bucket || []) {
+        if (!m?.id || !m?.createdAt) continue;
+        const createdMs = Date.parse(m.createdAt);
+        if (!Number.isFinite(createdMs) || createdMs > cutoffMs) continue;
+        // Skip plan/* memories unless explicitly included — they're the
+        // agent's active working plan, not stale notes.
+        if (!includePlans && isPlanTitle(m.title)) continue;
+        candidates.push({
+          id: m.id,
+          title: m.title,
+          createdAt: m.createdAt,
+          ageDays: Math.round((Date.now() - createdMs) / (24 * 60 * 60 * 1000)),
+        });
+      }
+    }
+
+    if (dryRun) {
+      return {
+        success: true,
+        action: 'forget-stale',
+        dryRun: true,
+        thresholdDays: ageDays,
+        candidates,
+        count: candidates.length,
+        message: candidates.length === 0
+          ? `No memories older than ${ageDays} days.`
+          : `Would forget ${candidates.length} memories older than ${ageDays} days. Pass dryRun:false to apply.`,
+      };
+    }
+
+    let forgotten = 0;
+    let failed = 0;
+    for (const c of candidates) {
+      try {
+        const ok = await memoryService.deleteMemory(agentId, c.id);
+        if (ok) forgotten++;
+        else failed++;
+      } catch (err) {
+        this.logger?.warn?.('[memoryTool] forget-stale: delete failed', { id: c.id, error: err?.message });
+        failed++;
+      }
+    }
+
+    return {
+      success: failed === 0,
+      action: 'forget-stale',
+      thresholdDays: ageDays,
+      forgotten,
+      failed,
+      message: forgotten === 0 && failed === 0
+        ? `No memories older than ${ageDays} days.`
+        : `Forgot ${forgotten} memories older than ${ageDays} days` +
+          (failed ? `, ${failed} deletions failed` : '') + '.',
+    };
+  }
+
+  // ──────────────────────────────────────────────────────────────────
+  // Phase 6c — Team-pool memory (the explicit publish channel)
+  //
+  // Answers the design Q1: per-agent memory stays private by default;
+  // teams are an explicit, ACL-gated sharing surface. Lit-aligned with
+  // arXiv 2505.18279 "Collaborative Memory" (dual-tier private + shared
+  // with read/write policies). Pattern matches Mem0's multi-level
+  // scoping (user_id / agent_id / app_id) — we use Loxia's existing
+  // Teams primitive as the natural sharing boundary.
+  //
+  // ACL: agent must be a member of the team. Membership is read from
+  // stateManager.getTeam(teamId).memberAgentIds — the authoritative
+  // source. We refuse rather than warn so accidental cross-team leaks
+  // are impossible. The check is encapsulated in `_assertTeamMember`.
+  // ──────────────────────────────────────────────────────────────────
+
+  /**
+   * Allow callers to inject a StateManager so ACL lookups can resolve
+   * team membership. Mirrors the platformControl pattern. Without it,
+   * team-scoped actions all fail with a clean error rather than
+   * defaulting open.
+   */
+  setStateManager(stateManager) {
+    this.stateManager = stateManager;
+    this.logger?.info?.(`[memory] StateManager ${stateManager ? 'attached' : 'detached'}`);
+  }
+
+  /**
+   * Read-only ACL: throws an Error with a user-facing message if the
+   * agent isn't a member of the team. Use inside team-scoped handlers
+   * to gate writes and reads alike.
+   * @private
+   */
+  async _assertTeamMember(agentId, teamId) {
+    if (!this.stateManager?.getTeam) {
+      throw new Error('Team-scoped memory actions require a StateManager. None is attached.');
+    }
+    const team = await this.stateManager.getTeam(teamId);
+    if (!team) {
+      throw new Error(`Team not found: ${teamId}`);
+    }
+    const members = Array.isArray(team.memberAgentIds) ? team.memberAgentIds : [];
+    if (!members.includes(agentId)) {
+      throw new Error(
+        `Access denied: agent ${agentId} is not a member of team ${teamId}. ` +
+        `Ask a team admin to add you via platformcontrol.add-team-member.`,
+      );
+    }
+    return team;
+  }
+
+  /**
+   * Publish an existing per-agent memory to a team's shared pool. The
+   * memory itself stays in the agent's own pool — `publish` copies its
+   * content into the team's vector index with `publishedBy` metadata.
+   *
+   * Params: { id, teamId }
+   * @private
+   */
+  async _executePublishToTeam(memoryService, agentId, params) {
+    const indexer = this._getMemoryIndexer();
+    if (!indexer || !indexer.isEnabled) {
+      return {
+        success: false,
+        action: 'publish-to-team',
+        message: 'Embeddings are not enabled. Team-pool memory requires a configured embedding provider — enable one in Settings → Embeddings first.',
+      };
+    }
+
+    let team;
+    try { team = await this._assertTeamMember(agentId, params.teamId); }
+    catch (err) {
+      return { success: false, action: 'publish-to-team', error: err.message };
+    }
+
+    const memory = await memoryService.readMemory(agentId, params.id);
+    if (!memory) {
+      return {
+        success: false,
+        action: 'publish-to-team',
+        error: `Memory not found in your pool: ${params.id}. publish-to-team copies an existing personal memory into the team pool.`,
+      };
+    }
+
+    const result = await indexer.publishToTeam(params.teamId, memory, agentId);
+    return {
+      success: result.indexed === true,
+      action: 'publish-to-team',
+      teamId: params.teamId,
+      teamName: team?.name || params.teamId,
+      memoryId: memory.id,
+      ...(result.error ? { error: result.error } : {}),
+      message: result.indexed
+        ? `Published "${memory.title}" to team "${team?.name || params.teamId}".`
+        : `Publish failed: ${result.reason || result.error || 'unknown'}`,
+    };
+  }
+
+  /**
+   * Semantic (or hybrid) search over a team's shared memory pool.
+   * Requires team membership — otherwise no read.
+   *
+   * Params: { teamId, query, topK?=10, hybrid?=true }
+   * @private
+   */
+  async _executeSearchTeam(agentId, params) {
+    const indexer = this._getMemoryIndexer();
+    if (!indexer || !indexer.isEnabled) {
+      return {
+        success: false,
+        action: 'search-team',
+        message: 'Embeddings are not enabled. Team-pool memory requires a configured embedding provider.',
+      };
+    }
+
+    let team;
+    try { team = await this._assertTeamMember(agentId, params.teamId); }
+    catch (err) {
+      return { success: false, action: 'search-team', error: err.message };
+    }
+
+    const topK = Number.isInteger(params.topK) && params.topK > 0 ? params.topK : 10;
+    const hybrid = params.hybrid !== false;
+    const { hits, error } = await indexer.searchTeam(params.teamId, params.query, { topK, hybrid });
+    return {
+      success: !error,
+      action: 'search-team',
+      teamId: params.teamId,
+      teamName: team?.name || params.teamId,
+      query: params.query,
+      mode: hybrid ? 'hybrid' : 'semantic',
+      topK,
+      results: hits,
+      ...(error ? { error } : {}),
+      message: error
+        ? `Team search failed: ${error}`
+        : hits.length === 0
+          ? `No memories matched "${params.query}" in team "${team?.name || params.teamId}".`
+          : `Found ${hits.length} team memories ranked by similarity to "${params.query}".`,
+    };
+  }
+
+  /**
+   * Remove a memory from a team pool. Any team member can unpublish
+   * (no per-author restriction at this layer — keeps the ACL surface
+   * simple; if richer policies are needed later, layer them here).
+   *
+   * Params: { teamId, id }
+   * @private
+   */
+  async _executeUnpublishFromTeam(agentId, params) {
+    const indexer = this._getMemoryIndexer();
+    if (!indexer || !indexer.isEnabled) {
+      return {
+        success: false,
+        action: 'unpublish-from-team',
+        message: 'Embeddings are not enabled. Team-pool memory requires a configured embedding provider.',
+      };
+    }
+
+    let team;
+    try { team = await this._assertTeamMember(agentId, params.teamId); }
+    catch (err) {
+      return { success: false, action: 'unpublish-from-team', error: err.message };
+    }
+
+    const result = await indexer.unpublishFromTeam(params.teamId, params.id);
+    return {
+      success: result.deleted === true,
+      action: 'unpublish-from-team',
+      teamId: params.teamId,
+      teamName: team?.name || params.teamId,
+      memoryId: params.id,
+      ...(result.error ? { error: result.error } : {}),
+      message: result.deleted
+        ? `Removed memory ${params.id} from team "${team?.name || params.teamId}".`
+        : `Unpublish failed: ${result.reason || result.error || 'unknown'}`,
+    };
+  }
+
+  /**
+   * Lazy accessor for the per-tool MemoryIndexer.
+   *
+   * Why lazy: the EmbeddingService is attached to aiService AFTER
+   * tools are constructed. Pulling it on first use lets us avoid
+   * construction-time ordering pain.
+   *
+   * Returns null when no embedding service is available (cloud-only
+   * deploys without local provider, brand-new installs, etc.). Callers
+   * MUST check `indexer.isEnabled` before relying on it — the indexer
+   * is a thin shim that itself checks the service's enabled flag.
+   *
+   * @private
+   * @returns {import('../services/embeddings/indexers/memoryIndexer.js').MemoryIndexer | null}
+   */
+  _getMemoryIndexer() {
+    if (this._memoryIndexer) return this._memoryIndexer;
+    const svc = this.aiService?.getEmbeddingService?.();
+    if (!svc) return null;
+    this._memoryIndexer = new MemoryIndexer({ embeddingService: svc, logger: this.logger });
+    return this._memoryIndexer;
+  }
+
+  /**
+   * Fire-and-forget memory index update. Errors are logged inside the
+   * indexer; we additionally swallow any thrown error here so a runtime
+   * surprise (broken provider, full disk) NEVER affects the memory write.
+   * @private
+   */
+  _asyncIndexMemory(agentId, memory) {
+    const indexer = this._getMemoryIndexer();
+    if (!indexer || !indexer.isEnabled) return;
+    // Don't await — the result is consumed only via the indexer's own
+    // log. We bury the promise with .catch() so Node doesn't crash on
+    // unhandled rejection if something exotic blows up.
+    indexer.indexOne(agentId, memory).catch(err => {
+      this.logger?.warn?.('[memoryTool] async index failed', { agentId, id: memory?.id, error: err?.message });
+    });
+  }
+
+  /**
+   * Fire-and-forget removal from the index after a delete.
+   * @private
+   */
+  _asyncRemoveFromIndex(agentId, memoryId) {
+    const indexer = this._getMemoryIndexer();
+    if (!indexer || !indexer.isEnabled) return;
+    indexer.deleteOne(agentId, memoryId).catch(err => {
+      this.logger?.warn?.('[memoryTool] async deleteFromIndex failed', { agentId, id: memoryId, error: err?.message });
+    });
+  }
+
+  /**
+   * Lazy accessor for the per-tool ReminisceIndexer. Same lifetime model
+   * as `_getMemoryIndexer`: cached on the tool instance after first use.
+   * Returns null when the embedding service isn't attached.
+   *
+   * @private
+   * @returns {import('../services/embeddings/indexers/reminisceIndexer.js').ReminisceIndexer | null}
+   */
+  _getReminisceIndexer() {
+    if (this._reminisceIndexer) return this._reminisceIndexer;
+    const svc = this.aiService?.getEmbeddingService?.();
+    if (!svc) return null;
+    this._reminisceIndexer = new ReminisceIndexer({ embeddingService: svc, logger: this.logger });
+    return this._reminisceIndexer;
+  }
+
+  /**
+   * Reminisce semantic-search handler. Routes through the
+   * ReminisceIndexer; falls back to the existing substring-based
+   * `reminisce.search` when embeddings aren't configured.
+   *
+   * Params: { query, topK?=10, hybrid?=true }
+   * @private
+   */
+  async _executeReminisceSemanticSearch(agentId, params, context) {
+    const query = typeof params.query === 'string' ? params.query.trim() : '';
+    if (!query) {
+      return {
+        success: false,
+        action: 'reminisce',
+        mode: 'semantic-search',
+        error: 'query is required for reminisce semantic-search',
+      };
+    }
+    const topK = Number.isInteger(params.topK) && params.topK > 0 ? params.topK : 10;
+    const hybrid = params.hybrid !== false;
+
+    const indexer = this._getReminisceIndexer();
+    if (!indexer || !indexer.isEnabled) {
+      // Graceful fallback to the existing substring path so the action
+      // remains useful when embeddings are off. Mirrors memoryTool's
+      // semantic-search fallback shape for consistency.
+      const fb = await this._executeReminisce(agentId, { ...params, mode: 'search' }, context);
+      return {
+        ...fb,
+        mode: 'semantic-search',
+        modeUsed: 'substring-fallback',
+        message: 'Embeddings disabled; returned substring search results instead.',
+      };
+    }
+
+    // Run the vector search.
+    const { hits, error } = await indexer.search(agentId, query, { topK, hybrid });
+
+    // Hydrate scored messageIds back to full messages from the archive,
+    // so the agent sees `role`, `content`, `createdAt`, etc. — the same
+    // shape it gets from `reminisce.search`.
+    const agentPool = context?.agentPool;
+    let messages = null;
+    if (agentPool?.getAgent) {
+      const agent = await agentPool.getAgent(agentId);
+      messages = Array.isArray(agent?.conversations?.full?.messages) ? agent.conversations.full.messages : null;
+    }
+    const byId = new Map((messages || []).map(m => [m?.id, m]));
+    const hydrated = hits.map(h => {
+      const m = byId.get(h.messageId);
+      const base = {
+        messageId: h.messageId,
+        score: h.score,
+        chunkIndex: h.chunkIndex,
+        // Default to the index-snapshot text when the live message has
+        // gone missing (rare — only if archive was pruned).
+        snippet: h.chunkText,
+      };
+      if (!m) return { ...base, missing: true };
+      return {
+        ...base,
+        role: m.role || 'unknown',
+        at: m.createdAt || m.timestamp || null,
+        content: typeof m.content === 'string' ? m.content : '',
+      };
+    });
+
+    return {
+      success: !error,
+      action: 'reminisce',
+      mode: 'semantic-search',
+      modeUsed: hybrid ? 'hybrid' : 'semantic',
+      query,
+      topK,
+      result: {
+        hits: hydrated,
+        ...(error ? { error } : {}),
+      },
+      message: error
+        ? `Reminisce semantic search failed: ${error}`
+        : hydrated.length === 0
+          ? `No archived messages matched "${query}"`
+          : `Found ${hydrated.length} archived messages ranked by similarity to "${query}"`,
+    };
+  }
+
+  /**
+   * Drop the agent's reminisce index and rebuild from the full
+   * conversation archive. Use after first enabling embeddings, or after
+   * switching provider/model. Idempotent.
+   *
+   * NOTE: this is the canonical entry point for keeping reminisce
+   * semantic-search current today. Auto-indexing on new archive writes
+   * is a planned follow-up; until then, re-run this periodically (or
+   * via a scheduled task) to pick up the latest messages.
+   *
+   * @private
+   */
+  async _executeReminisceBackfill(agentId, context) {
+    const indexer = this._getReminisceIndexer();
+    if (!indexer || !indexer.isEnabled) {
+      return {
+        success: false,
+        action: 'reminisce-backfill-embeddings',
+        message: 'Embeddings are not enabled — nothing to backfill. Enable a provider in Settings → Embeddings first.',
+      };
+    }
+
+    const agentPool = context?.agentPool;
+    if (!agentPool?.getAgent) {
+      return {
+        success: false,
+        action: 'reminisce-backfill-embeddings',
+        error: 'agentPool is not available on the tool context; cannot read conversation archive',
+      };
+    }
+    const agent = await agentPool.getAgent(agentId);
+    const messages = Array.isArray(agent?.conversations?.full?.messages) ? agent.conversations.full.messages : [];
+
+    const result = await indexer.backfill(agentId, messages);
+    return {
+      success: result.ok !== false && !result.error,
+      action: 'reminisce-backfill-embeddings',
+      indexedMessages: result.indexedMessages || 0,
+      indexedChunks: result.indexedChunks || 0,
+      skipped: result.skipped || 0,
+      failed: result.failed || 0,
+      ...(result.error ? { error: result.error } : {}),
+      message: result.ok === false
+        ? `Reminisce backfill failed: ${result.reason || result.error || 'unknown'}`
+        : `Re-indexed ${result.indexedMessages || 0} messages` +
+          (result.indexedChunks ? ` (${result.indexedChunks} chunks)` : '') +
+          (result.skipped ? `, skipped ${result.skipped}` : '') +
+          (result.failed ? `, failed ${result.failed}` : ''),
+    };
+  }
+
   /**
    * Execute STATS action
    */
@@ -696,7 +1453,7 @@ BEST PRACTICES:
    */
   async _executeReminisce(agentId, params, context) {
     const mode = typeof params.mode === 'string' ? params.mode : '';
-    const validModes = ['overview', 'range', 'search', 'around', 'byTool', 'read'];
+    const validModes = ['overview', 'range', 'search', 'semantic-search', 'around', 'byTool', 'read'];
     if (!validModes.includes(mode)) {
       return {
         success: false,
@@ -705,6 +1462,14 @@ BEST PRACTICES:
       };
     }
 
+    // Semantic-search has a different shape than the other modes — it
+    // routes through the ReminisceIndexer (vector store) rather than the
+    // conversation-query helpers. Falls back to substring `search` when
+    // embeddings are disabled so the action is always callable.
+    if (mode === 'semantic-search') {
+      return await this._executeReminisceSemanticSearch(agentId, params, context);
+    }
+
     const agentPool = context?.agentPool;
     if (!agentPool?.getAgent) {
       return {