onbuzz 4.9.0 → 4.9.5

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
@@ -402,7 +404,7 @@ BEST PRACTICES:
    */
   customValidateParameters(params) {
     const errors = [];
-    const validActions = ['add', 'update', 'append', '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'];
 
     // Normalize to the canonical actions[] shape and validate every action.
     // Accepts both the canonical plural `{actions: [{type, ...}]}` and the
@@ -450,6 +452,33 @@ BEST PRACTICES:
           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`);
@@ -565,9 +594,16 @@ BEST PRACTICES:
         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 'stats':     return await this._executeStats(memoryService, agentId);
-        case 'reminisce': return await this._executeReminisce(agentId, legacyParams, context);
+        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 memory action: ${type}`);
       }
@@ -592,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',
@@ -630,6 +671,9 @@ BEST PRACTICES:
       };
     }
 
+    // Re-index after content change. Fire-and-forget.
+    this._asyncIndexMemory(agentId, memory);
+
     return {
       success: true,
       action: 'update',
@@ -667,6 +711,9 @@ BEST PRACTICES:
       };
     }
 
+    // Re-index after content grew. Fire-and-forget.
+    this._asyncIndexMemory(agentId, memory);
+
     return {
       success: true,
       action: 'append',
@@ -696,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',
@@ -795,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
    */
@@ -832,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,
@@ -841,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 {