dsh-tdai-memory 0.1.0

package/vendor/tdai/core/store/types.js

@@ -0,0 +1,17 @@
+/**
+ * Memory Store Abstraction Layer — Core Types & Interfaces.
+ *
+ * This module defines the storage contracts that all backend implementations
+ * (SQLite local, Tencent Cloud VectorDB, etc.) must satisfy.
+ *
+ * Design principles:
+ * 1. **Backend-agnostic**: Upper-layer modules (hooks, tools, pipeline, record)
+ *    depend only on these interfaces — never on concrete implementations.
+ * 2. **Capability-based**: Features like vector search, FTS, and hybrid search
+ *    are expressed as capability flags so callers can gracefully degrade.
+ * 3. **Fault-tolerant**: All methods return empty results or `false` on
+ *    failure rather than throwing, unless explicitly documented otherwise.
+ * 4. **Sync-first**: Matches current SQLite DatabaseSync usage. TCVDB backend
+ *    adapts internally without changing these signatures.
+ */
+export {};

package/vendor/tdai/core/tdai-core.js

@@ -0,0 +1,446 @@
+/**
+ * TdaiCore — Host-neutral facade for TDAI memory capabilities.
+ *
+ * This is the single entry point that both OpenClaw and Hermes/Gateway call
+ * to perform recall, capture, search, and pipeline management. It depends
+ * only on abstract interfaces (HostAdapter, LLMRunner), never on a specific host.
+ *
+ * Usage:
+ *   // OpenClaw path (in-process)
+ *   const adapter = new OpenClawHostAdapter({ api, pluginDataDir, config });
+ *   const core = new TdaiCore({ hostAdapter: adapter, config: parsedCfg });
+ *   await core.initialize();
+ *   const recall = await core.handleBeforeRecall("user query", "session-1");
+ *
+ *   // Gateway path (HTTP)
+ *   const adapter = new StandaloneHostAdapter({ ... });
+ *   const core = new TdaiCore({ hostAdapter: adapter, config: parsedCfg });
+ *   await core.initialize();
+ *   // HTTP handler calls core.handleBeforeRecall / core.handleTurnCommitted / etc.
+ */
+import { performAutoRecall } from "./hooks/auto-recall.js";
+import { performAutoCapture } from "./hooks/auto-capture.js";
+import { executeMemorySearch, formatSearchResponse } from "./tools/memory-search.js";
+import { executeConversationSearch, formatConversationSearchResponse } from "./tools/conversation-search.js";
+import { initDataDirectories, initStores, resetStores, createPipelineManager, createL1Runner, createPersister, createL2Runner, createL3Runner, } from "../utils/pipeline-factory.js";
+import { CheckpointManager } from "../utils/checkpoint.js";
+import { SessionFilter } from "../utils/session-filter.js";
+import { StandaloneLLMRunnerFactory } from "../adapters/standalone/llm-runner.js";
+const TAG = "[memory-tdai] [core]";
+// ============================
+// TdaiCore
+// ============================
+export class TdaiCore {
+    hostAdapter;
+    cfg;
+    logger;
+    dataDir;
+    runnerFactory;
+    sessionFilter;
+    instanceId;
+    // Lazy-initialized resources
+    vectorStore;
+    embeddingService;
+    scheduler;
+    /**
+     * Promise gate for the one-shot scheduler-start sequence.
+     *
+     * ``ensureSchedulerStarted`` reads a checkpoint file (async) and then
+     * calls ``scheduler.start(restoredStates)``.  Under the Gateway, several
+     * HTTP requests can reach ``handleTurnCommitted`` concurrently and all
+     * race into that function.  Using a plain boolean flag is unsafe: the
+     * first caller flips the flag to ``true`` *before* the await completes,
+     * so subsequent callers slip past the check and touch the scheduler
+     * before ``start()`` has actually run — which makes ``start()``'s
+     * ``sessionStates.set(key, restored)`` later clobber the state that
+     * those concurrent captures already incremented.
+     *
+     * Storing the in-flight promise lets every concurrent caller ``await``
+     * the same start sequence.  Once it resolves the promise is kept as a
+     * sentinel so subsequent calls are a single already-resolved await
+     * (effectively a no-op).
+     */
+    schedulerStartPromise;
+    storeReady;
+    /**
+     * In-flight fire-and-forget background tasks started by
+     * ``handleTurnCommitted`` (currently: deferred L0 embedding for
+     * SQLite-style stores — see auto-capture.ts path A).
+     *
+     * ``destroy()`` awaits all pending entries (with a hard timeout)
+     * before closing ``vectorStore`` / ``embeddingService`` so that a
+     * late ``updateL0Embedding`` cannot land on an already-closed
+     * database connection.
+     *
+     * Each task registers itself on creation and removes itself in its
+     * own ``finally`` handler, so the set stays bounded by the number
+     * of currently-running background tasks.
+     */
+    bgTasks = new Set();
+    constructor(opts) {
+        this.hostAdapter = opts.hostAdapter;
+        this.cfg = opts.config;
+        this.logger = opts.hostAdapter.getLogger();
+        this.dataDir = opts.hostAdapter.getRuntimeContext().dataDir;
+        this.runnerFactory = opts.hostAdapter.getLLMRunnerFactory();
+        this.sessionFilter = opts.sessionFilter ?? new SessionFilter([]);
+        this.instanceId = opts.instanceId;
+    }
+    // ============================
+    // Lifecycle
+    // ============================
+    /**
+     * Initialize data directories, storage, and pipeline scheduler.
+     * Must be called once before any other methods.
+     */
+    async initialize() {
+        this.logger.debug?.(`${TAG} Initializing TDAI Core: dataDir=${this.dataDir}`);
+        initDataDirectories(this.dataDir);
+        // Initialize stores (async)
+        this.storeReady = this.initStores();
+        // Create pipeline manager (sync — does not need store)
+        if (this.cfg.extraction.enabled) {
+            this.scheduler = createPipelineManager(this.cfg, this.logger, this.sessionFilter);
+            // Wire runners after store is ready (or after store init fails — runners
+            // still work in degraded mode with JSONL fallback and no embedding)
+            this.storeReady
+                .then(() => this.wirePipelineRunners())
+                .catch((err) => {
+                this.logger.error(`${TAG} Store init failed; wiring pipeline runners in degraded mode: ${err instanceof Error ? err.message : String(err)}`);
+                this.wirePipelineRunners();
+            });
+        }
+        this.logger.debug?.(`${TAG} TDAI Core initialized`);
+    }
+    /**
+     * Destroy all resources. Call on shutdown.
+     */
+    async destroy() {
+        this.logger.debug?.(`${TAG} Destroying TDAI Core...`);
+        // Wait for store init to complete before tearing down
+        await this.storeReady?.catch(() => { });
+        if (this.scheduler && this.schedulerStartPromise) {
+            await this.scheduler.destroy();
+            this.schedulerStartPromise = undefined;
+            this.logger.debug?.(`${TAG} Scheduler destroyed`);
+        }
+        // Drain fire-and-forget background tasks started by auto-capture
+        // (currently: deferred L0 embedding writes).  We must wait for
+        // them here — BEFORE closing vectorStore / embeddingService —
+        // otherwise a late updateL0Embedding lands on an already-closed
+        // DB connection and either throws "database is not open" or
+        // (worse) corrupts state.  A hard timeout keeps destroy bounded
+        // when a background task is stuck on a hung embed HTTP call.
+        if (this.bgTasks.size > 0) {
+            const pending = [...this.bgTasks];
+            this.logger.debug?.(`${TAG} Draining ${pending.length} background task(s) before closing stores...`);
+            const BG_DRAIN_TIMEOUT_MS = 5_000;
+            let drainTimeoutId;
+            try {
+                await Promise.race([
+                    Promise.allSettled(pending).then(() => undefined),
+                    new Promise((_, reject) => {
+                        drainTimeoutId = setTimeout(() => reject(new Error("bgTasks drain timeout")), BG_DRAIN_TIMEOUT_MS);
+                    }),
+                ]);
+                this.logger.debug?.(`${TAG} Background tasks drained`);
+            }
+            catch (err) {
+                this.logger.warn(`${TAG} Background-task drain timed out (${BG_DRAIN_TIMEOUT_MS}ms): ` +
+                    `${err instanceof Error ? err.message : String(err)}. ` +
+                    `Closing stores anyway — residual writes may surface as warnings.`);
+            }
+            finally {
+                if (drainTimeoutId !== undefined)
+                    clearTimeout(drainTimeoutId);
+            }
+        }
+        if (this.vectorStore) {
+            this.vectorStore.close();
+            this.vectorStore = undefined;
+            this.logger.debug?.(`${TAG} VectorStore closed`);
+        }
+        if (this.embeddingService?.close) {
+            try {
+                await this.embeddingService.close();
+            }
+            catch (err) {
+                this.logger.warn(`${TAG} EmbeddingService close error: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            this.embeddingService = undefined;
+        }
+        resetStores(this.dataDir);
+        this.logger.debug?.(`${TAG} TDAI Core destroyed`);
+    }
+    // ============================
+    // Core capabilities
+    // ============================
+    /**
+     * Handle recall (memory retrieval) before an LLM turn.
+     * Maps to: OpenClaw `before_prompt_build` / Hermes `prefetch()`.
+     */
+    async handleBeforeRecall(userText, sessionKey) {
+        await this.storeReady?.catch(() => { });
+        const result = await performAutoRecall({
+            userText,
+            actorId: "default_user",
+            sessionKey,
+            cfg: this.cfg,
+            pluginDataDir: this.dataDir,
+            logger: this.logger,
+            vectorStore: this.vectorStore,
+            embeddingService: this.embeddingService,
+        });
+        return result ?? {};
+    }
+    /**
+     * Handle turn commitment (conversation capture + pipeline trigger).
+     * Maps to: OpenClaw `agent_end` / Hermes `sync_turn()`.
+     */
+    async handleTurnCommitted(turn) {
+        await this.storeReady?.catch(() => { });
+        await this.ensureSchedulerStarted();
+        return performAutoCapture({
+            messages: turn.messages,
+            sessionKey: turn.sessionKey,
+            sessionId: turn.sessionId,
+            cfg: this.cfg,
+            pluginDataDir: this.dataDir,
+            logger: this.logger,
+            scheduler: this.scheduler,
+            originalUserText: turn.userText,
+            originalUserMessageCount: turn.originalUserMessageCount,
+            pluginStartTimestamp: turn.startedAt ?? Date.now(),
+            vectorStore: this.vectorStore,
+            embeddingService: this.embeddingService,
+            bgTaskRegistry: this.bgTasks,
+        });
+    }
+    /**
+     * Search L1 structured memories.
+     * Maps to: `tdai_memory_search` tool.
+     */
+    async searchMemories(params) {
+        const result = await executeMemorySearch({
+            query: params.query,
+            limit: params.limit ?? 5,
+            type: params.type,
+            scene: params.scene,
+            vectorStore: this.vectorStore,
+            embeddingService: this.embeddingService,
+            logger: this.logger,
+        });
+        return {
+            text: formatSearchResponse(result),
+            total: result.total,
+            strategy: result.strategy,
+        };
+    }
+    /**
+     * Search L0 raw conversations.
+     * Maps to: `tdai_conversation_search` tool.
+     */
+    async searchConversations(params) {
+        const result = await executeConversationSearch({
+            query: params.query,
+            limit: params.limit ?? 5,
+            sessionKey: params.sessionKey,
+            vectorStore: this.vectorStore,
+            embeddingService: this.embeddingService,
+            logger: this.logger,
+        });
+        return {
+            text: formatConversationSearchResponse(result),
+            total: result.total,
+        };
+    }
+    /**
+     * Handle end-of-conversation for a single session.
+     *
+     * ⚠️ Read this if you are editing the method:
+     *
+     * There are two distinct shutdown-ish events, and they must **NOT**
+     * share an implementation:
+     *
+     *   - **`gateway_stop` (OpenClaw / process exit)**
+     *     The host is going away.  Tear everything down — scheduler,
+     *     VectorStore, EmbeddingService, caches.  That is
+     *     {@link destroy}, not this method.
+     *
+     *   - **`on_session_end` (Hermes) / `POST /session/end` (Gateway)**
+     *     One conversation ended while the process keeps serving other
+     *     concurrent sessions.  **Only** this session's buffered work
+     *     should be flushed; every other session's timers, buffers,
+     *     pipeline state, and the shared scheduler itself MUST remain
+     *     untouched.  That is this method.
+     *
+     * Historically this method did ``scheduler.destroy() +
+     * createPipelineManager()``, which conflated the two semantics and
+     * wiped concurrent sessions' in-memory state on every ``/session/end``
+     * call.  That bug is covered by the concurrency test
+     * ``P0-1: handleSessionEnd must be scoped to its session``.
+     *
+     * @param sessionKey  Session whose buffered work should be flushed.
+     *                    Unknown keys are tolerated as a no-op so callers
+     *                    don't have to pre-check whether the session was
+     *                    already evicted or never produced a capture.
+     */
+    async handleSessionEnd(sessionKey) {
+        if (!sessionKey)
+            return;
+        await this.storeReady?.catch(() => { });
+        if (!this.scheduler)
+            return;
+        await this.scheduler.flushSession(sessionKey);
+    }
+    // ============================
+    // Accessors (for migration bridge)
+    // ============================
+    /** Get the LLM runner factory (for creating host-neutral LLM runners). */
+    getLLMRunnerFactory() {
+        return this.runnerFactory;
+    }
+    /** Get the shared VectorStore (may be undefined if init failed). */
+    getVectorStore() {
+        return this.vectorStore;
+    }
+    /** Get the shared EmbeddingService (may be undefined if not configured). */
+    getEmbeddingService() {
+        return this.embeddingService;
+    }
+    /** Get the pipeline scheduler (may be undefined if extraction disabled). */
+    getScheduler() {
+        return this.scheduler;
+    }
+    /** Whether the scheduler has been started (or is currently starting). */
+    isSchedulerStarted() {
+        return this.schedulerStartPromise !== undefined;
+    }
+    /** Set the instance ID for metrics (may be resolved asynchronously). */
+    setInstanceId(id) {
+        this.instanceId = id;
+        if (this.scheduler) {
+            this.scheduler.instanceId = id;
+        }
+    }
+    // ============================
+    // Internal helpers
+    // ============================
+    async initStores() {
+        try {
+            const stores = await initStores(this.cfg, this.dataDir, this.logger);
+            this.vectorStore = stores.vectorStore;
+            this.embeddingService = stores.embeddingService;
+            this.logger.debug?.(`${TAG} Stores initialized: backend=${this.cfg.storeBackend}, embedding=${this.cfg.embedding.provider}`);
+        }
+        catch (err) {
+            this.logger.warn(`${TAG} Store init failed; recall/dedup degraded: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    wirePipelineRunners() {
+        if (!this.scheduler)
+            return;
+        // Determine whether to use standalone LLM runner for extraction.
+        // Priority: cfg.llm.enabled (explicit override) > hostType detection.
+        const useStandaloneRunner = this.cfg.llm.enabled || this.hostAdapter.hostType !== "openclaw";
+        const openclawConfig = (!useStandaloneRunner && this.hostAdapter.hostType === "openclaw")
+            ? this.hostAdapter.getOpenClawConfig?.()
+            : undefined;
+        // When standalone runner is active, create LLM runners from the factory.
+        // If cfg.llm is configured AND we're in OpenClaw mode, build a dedicated
+        // StandaloneLLMRunnerFactory from cfg.llm to override the host runner.
+        let runnerFactory = this.runnerFactory;
+        if (useStandaloneRunner && this.cfg.llm.enabled && this.hostAdapter.hostType === "openclaw") {
+            runnerFactory = new StandaloneLLMRunnerFactory({
+                config: {
+                    baseUrl: this.cfg.llm.baseUrl,
+                    apiKey: this.cfg.llm.apiKey,
+                    model: this.cfg.llm.model,
+                    maxTokens: this.cfg.llm.maxTokens,
+                    timeoutMs: this.cfg.llm.timeoutMs,
+                    disableThinking: this.cfg.llm.disableThinking,
+                },
+                logger: this.logger,
+            });
+            this.logger.debug?.(`${TAG} Using standalone LLM override: model=${this.cfg.llm.model}, baseUrl=${this.cfg.llm.baseUrl}`);
+        }
+        const l1LlmRunner = useStandaloneRunner
+            ? runnerFactory.createRunner({ enableTools: false })
+            : undefined;
+        const l2l3LlmRunner = useStandaloneRunner
+            ? runnerFactory.createRunner({ enableTools: true })
+            : undefined;
+        // L1 runner
+        this.scheduler.setL1Runner(createL1Runner({
+            pluginDataDir: this.dataDir,
+            cfg: this.cfg,
+            openclawConfig,
+            vectorStore: this.vectorStore,
+            embeddingService: this.embeddingService,
+            logger: this.logger,
+            getInstanceId: () => this.instanceId,
+            llmRunner: l1LlmRunner,
+        }));
+        // Persister
+        this.scheduler.setPersister(createPersister(this.dataDir, this.logger));
+        // L2 runner
+        this.scheduler.setL2Runner(async (sessionKey, cursor) => {
+            const l2Runner = createL2Runner({
+                pluginDataDir: this.dataDir,
+                cfg: this.cfg,
+                openclawConfig,
+                vectorStore: this.vectorStore,
+                logger: this.logger,
+                instanceId: this.instanceId,
+                llmRunner: l2l3LlmRunner,
+            });
+            return l2Runner(sessionKey, cursor);
+        });
+        // L3 runner
+        this.scheduler.setL3Runner(async () => {
+            const l3Runner = createL3Runner({
+                pluginDataDir: this.dataDir,
+                cfg: this.cfg,
+                openclawConfig,
+                vectorStore: this.vectorStore,
+                logger: this.logger,
+                instanceId: this.instanceId,
+                llmRunner: l2l3LlmRunner,
+            });
+            await l3Runner();
+        });
+        this.logger.debug?.(`${TAG} Pipeline runners wired`);
+    }
+    ensureSchedulerStarted() {
+        // Fast path: already started (or starting) — every concurrent caller
+        // awaits the same in-flight promise.  The promise is kept around as a
+        // permanently-resolved sentinel after success so subsequent calls
+        // collapse into a cheap already-resolved await.
+        if (this.schedulerStartPromise)
+            return this.schedulerStartPromise;
+        if (!this.scheduler)
+            return Promise.resolve();
+        // Capture scheduler locally so TypeScript narrows inside the closure
+        // even after ``this.scheduler`` is re-assigned by handleSessionEnd.
+        const scheduler = this.scheduler;
+        this.schedulerStartPromise = (async () => {
+            try {
+                const checkpoint = new CheckpointManager(this.dataDir, this.logger);
+                const cp = await checkpoint.read();
+                scheduler.start(checkpoint.getAllPipelineStates(cp));
+                this.logger.debug?.(`${TAG} Scheduler started`);
+            }
+            catch (err) {
+                this.logger.error(`${TAG} Failed to restore checkpoint: ${err instanceof Error ? err.message : String(err)}`);
+                scheduler.start({});
+            }
+        })();
+        // If the start sequence itself rejects we clear the gate so the next
+        // caller can retry; on success we keep the resolved promise so it
+        // short-circuits permanently.
+        this.schedulerStartPromise.catch(() => {
+            this.schedulerStartPromise = undefined;
+        });
+        return this.schedulerStartPromise;
+    }
+}

package/vendor/tdai/core/tools/conversation-search.js

@@ -0,0 +1,199 @@
+/**
+ * conversation_search tool: Agent-callable tool for searching L0 conversation records.
+ *
+ * Supports three search strategies with automatic degradation:
+ *   1. **hybrid** (default) — FTS5 keyword + vector embedding in parallel,
+ *      merged via Reciprocal Rank Fusion (RRF).
+ *   2. **embedding** — pure vector similarity (when FTS5 is unavailable).
+ *   3. **fts** — pure FTS5 keyword search (when embedding is unavailable).
+ *
+ * The tool is registered via `api.registerTool()` in index.ts.
+ */
+import { buildFtsQuery } from "../store/sqlite.js";
+const TAG = "[memory-tdai][tdai_conversation_search]";
+// ============================
+// RRF (Reciprocal Rank Fusion)
+// ============================
+/** Standard RRF constant from the original RRF paper. */
+const RRF_K = 60;
+/**
+ * Merge multiple ranked lists of `ConversationSearchResultItem` via Reciprocal
+ * Rank Fusion. Items appearing in multiple lists get their RRF scores summed.
+ *
+ * Returns items sorted by descending RRF score. The `score` field of each
+ * returned item is replaced by the RRF score for consistent ranking semantics.
+ */
+function rrfMergeL0(...lists) {
+    const map = new Map();
+    for (const list of lists) {
+        for (let rank = 0; rank < list.length; rank++) {
+            const item = list[rank];
+            const score = 1 / (RRF_K + rank + 1);
+            const existing = map.get(item.id);
+            if (existing) {
+                existing.rrfScore += score;
+            }
+            else {
+                map.set(item.id, { item, rrfScore: score });
+            }
+        }
+    }
+    return [...map.values()]
+        .sort((a, b) => b.rrfScore - a.rrfScore)
+        .map(({ item, rrfScore }) => ({ ...item, score: rrfScore }));
+}
+// ============================
+// Search implementation
+// ============================
+export async function executeConversationSearch(params) {
+    const { query, limit, sessionKey: sessionFilter, vectorStore, embeddingService, logger, } = params;
+    logger?.debug?.(`${TAG} CALLED: query="${query.slice(0, 100)}", limit=${limit}, ` +
+        `sessionFilter=${sessionFilter ?? "(none)"}, ` +
+        `vectorStore=${vectorStore ? "available" : "UNAVAILABLE"}, ` +
+        `embeddingService=${embeddingService ? "available" : "UNAVAILABLE"}`);
+    if (!query || query.trim().length === 0) {
+        logger?.debug?.(`${TAG} Empty query, returning empty`);
+        return { results: [], total: 0, strategy: "none" };
+    }
+    if (!vectorStore) {
+        logger?.warn?.(`${TAG} VectorStore not available`);
+        return { results: [], total: 0, strategy: "none" };
+    }
+    // ── Determine available capabilities ──
+    const hasEmbedding = !!embeddingService;
+    const hasFts = vectorStore.isFtsAvailable();
+    if (!hasEmbedding && !hasFts) {
+        logger?.warn?.(`${TAG} Neither EmbeddingService nor FTS5 available — cannot search`);
+        return {
+            results: [],
+            total: 0,
+            strategy: "none",
+            message: "Embedding service is not configured and FTS is not available. " +
+                "Conversation search requires an embedding provider or FTS5 support. " +
+                "Please configure an embedding provider in the embedding.provider setting (e.g. openai_compatible).",
+        };
+    }
+    // ── Over-retrieve for later filtering and RRF merging ──
+    const candidateK = sessionFilter ? limit * 4 : limit * 3;
+    // ── Run available search strategies in parallel ──
+    const [ftsItems, vecItems] = await Promise.all([
+        // FTS5 keyword search on L0
+        (async () => {
+            if (!hasFts)
+                return [];
+            try {
+                const ftsQuery = buildFtsQuery(query);
+                if (!ftsQuery) {
+                    logger?.debug?.(`${TAG} [hybrid-fts] No usable FTS tokens from query`);
+                    return [];
+                }
+                logger?.debug?.(`${TAG} [hybrid-fts] FTS5 query: "${ftsQuery}"`);
+                const ftsResults = await vectorStore.searchL0Fts(ftsQuery, candidateK);
+                logger?.debug?.(`${TAG} [hybrid-fts] FTS5 returned ${ftsResults.length} candidates`);
+                return ftsResults.map((r) => ({
+                    id: r.record_id,
+                    session_key: r.session_key,
+                    role: r.role,
+                    content: r.message_text,
+                    score: r.score,
+                    recorded_at: r.recorded_at,
+                }));
+            }
+            catch (err) {
+                logger?.warn?.(`${TAG} [hybrid-fts] FTS5 search failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+                return [];
+            }
+        })(),
+        // Vector embedding search on L0
+        (async () => {
+            if (!hasEmbedding)
+                return [];
+            try {
+                logger?.debug?.(`${TAG} [hybrid-vec] Generating query embedding...`);
+                const queryEmbedding = await embeddingService.embed(query);
+                logger?.debug?.(`${TAG} [hybrid-vec] Embedding OK, dims=${queryEmbedding.length}, searching top-${candidateK}...`);
+                const vecResults = await vectorStore.searchL0Vector(queryEmbedding, candidateK, query);
+                logger?.debug?.(`${TAG} [hybrid-vec] Vector search returned ${vecResults.length} candidates`);
+                return vecResults.map((r) => ({
+                    id: r.record_id,
+                    session_key: r.session_key,
+                    role: r.role,
+                    content: r.message_text,
+                    score: r.score,
+                    recorded_at: r.recorded_at,
+                }));
+            }
+            catch (err) {
+                logger?.warn?.(`${TAG} [hybrid-vec] Embedding search failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+                return [];
+            }
+        })(),
+    ]);
+    // ── Determine effective strategy ──
+    const ftsOk = ftsItems.length > 0;
+    const vecOk = vecItems.length > 0;
+    let strategy;
+    if (ftsOk && vecOk) {
+        strategy = "hybrid";
+    }
+    else if (vecOk) {
+        strategy = "embedding";
+    }
+    else if (ftsOk) {
+        strategy = "fts";
+    }
+    else {
+        logger?.debug?.(`${TAG} Both search paths returned 0 results`);
+        return { results: [], total: 0, strategy: hasEmbedding ? "embedding" : "fts" };
+    }
+    // ── Merge results ──
+    let results;
+    if (strategy === "hybrid") {
+        results = rrfMergeL0(ftsItems, vecItems);
+        logger?.debug?.(`${TAG} [hybrid] RRF merged: fts=${ftsItems.length}, vec=${vecItems.length} → ${results.length} unique`);
+    }
+    else {
+        // Single-source: use whichever list has results (already sorted by score)
+        results = ftsOk ? ftsItems : vecItems;
+    }
+    // ── Apply session key filter ──
+    if (sessionFilter) {
+        const preFilterCount = results.length;
+        results = results.filter((r) => r.session_key === sessionFilter);
+        logger?.debug?.(`${TAG} After session filter "${sessionFilter}": ${results.length}/${preFilterCount}`);
+    }
+    // ── Trim to requested limit ──
+    const trimmed = results.slice(0, limit);
+    logger?.debug?.(`${TAG} RESULT (strategy=${strategy}): returning ${trimmed.length} messages ` +
+        `(scores: [${trimmed.map((r) => r.score.toFixed(3)).join(", ")}])`);
+    return {
+        results: trimmed,
+        total: trimmed.length,
+        strategy,
+    };
+}
+// ============================
+// Tool response formatter
+// ============================
+export function formatConversationSearchResponse(result) {
+    if (result.message) {
+        return result.message;
+    }
+    if (result.results.length === 0) {
+        return "No matching conversation messages found.";
+    }
+    const lines = [
+        `Found ${result.total} matching message(s):`,
+        "",
+    ];
+    for (const item of result.results) {
+        const scoreStr = typeof item.score === "number" ? ` (score: ${item.score.toFixed(3)})` : "";
+        const dateStr = item.recorded_at ? ` [${item.recorded_at}]` : "";
+        lines.push(`---`);
+        lines.push(`**[${item.role}]** Session: ${item.session_key}${dateStr}${scoreStr}`);
+        lines.push("");
+        lines.push(item.content);
+        lines.push("");
+    }
+    return lines.join("\n");
+}