agentdb 3.0.0 → 3.2.0

package/dist/src/controllers/episode-hybrid.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Hybrid (dense + BM25) episode retrieval for ReflexionMemory (ADR-016).
+ *
+ * Dense search alone misses episodes whose wording matches the query but whose embedding does not (names, error
+ * codes, numbers). This keeps a BM25 index over the most recent episodes, rebuilt only when the episodes table
+ * changes, and fuses its ranking with the dense ranking by reciprocal-rank fusion. On LongMemEval session retrieval
+ * (benchmarks/longmemeval, which runs these ranking functions over turn chunks, not the episode store), the same
+ * fusion lifts recall_all@5 over dense-only ranking of the same chunks from 0.883 to 0.900 (S) and from 0.630 to
+ * 0.719 (M), with the default MiniLM embedder. See ADR-016.
+ */
+import type { IDatabaseConnection } from '../types/database.types.js';
+/**
+ * Episodes indexed for BM25, newest first; older episodes are still found by dense search. The first search in a
+ * process builds the index (about 200 ms at 10k episodes, 1 s at 50k); later writes are appended incrementally.
+ */
+export declare const HYBRID_MAX_INDEXED: number;
+/** The candidate pool each side contributes before fusion. */
+export declare const HYBRID_MAX_POOL = 500;
+/** Weight of the BM25 ranking against the dense ranking. Equal weights won on LongMemEval_M; see ADR-016. */
+export declare const HYBRID_LEXICAL_WEIGHT = 1;
+/**
+ * A BM25 index over episode text. New episodes are appended incrementally (the common write-then-read pattern);
+ * the index is rebuilt only when rows were deleted or replaced, or it has grown past 1.25x its cap.
+ */
+export declare class EpisodeLexicalIndex {
+    private readonly db;
+    private readonly maxDocs;
+    private count;
+    private maxId;
+    private ids;
+    private index;
+    constructor(db: IDatabaseConnection, maxDocs?: number);
+    private static textOf;
+    private refresh;
+    /** Episode ids with a BM25 match, best first, at most `limit`. */
+    search(query: string, limit: number): {
+        id: number;
+        score: number;
+    }[];
+}
+/**
+ * Weighted RRF scores of a dense ranking (best first) and a lexical ranking (best first) over episode ids.
+ * Episodes only in the lexical list are ranked just past the dense pool on the dense side.
+ */
+export declare function fuseEpisodeScores(denseIds: readonly number[], lexical: readonly {
+    id: number;
+}[], lexicalWeight?: number): Map<number, number>;
+/** Ids ordered by score, ties broken by dense order, then by newer id. */
+export declare function orderByScore(score: ReadonlyMap<number, number>, denseIds?: readonly number[]): number[];
+/** Fused ranking of episode ids, best first. */
+export declare function fuseEpisodeRankings(denseIds: readonly number[], lexical: readonly {
+    id: number;
+}[], lexicalWeight?: number): number[];
+/** Candidates the cross-encoder reads: the top `RERANK_DEPTH` of each ranking (the configuration benchmarked in ADR-016). */
+export declare const RERANK_DEPTH = 60;
+/** Weight of the cross-encoder rank in the fusion; best on LongMemEval_M (ADR-016). */
+export declare const RERANK_WEIGHT = 8;
+/**
+ * Adds `RERANK_WEIGHT`/(k + cross-encoder rank) to each candidate's fused score, in place. Candidates without text
+ * are skipped. Throws if the model cannot be loaded; the caller keeps the hybrid order.
+ */
+export declare function applyCrossEncoder(query: string, score: Map<number, number>, candidates: readonly number[], textOf: (id: number) => string | undefined, model?: string): Promise<void>;
+//# sourceMappingURL=episode-hybrid.d.ts.map

package/dist/src/controllers/episode-hybrid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"episode-hybrid.d.ts","sourceRoot":"","sources":["../../../src/controllers/episode-hybrid.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAItE;;;GAGG;AACH,eAAO,MAAM,kBAAkB,QAA0E,CAAC;AAM1G,8DAA8D;AAC9D,eAAO,MAAM,eAAe,MAAM,CAAC;AACnC,6GAA6G;AAC7G,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAWvC;;;GAGG;AACH,qBAAa,mBAAmB;IAO5B,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAP1B,OAAO,CAAC,KAAK,CAAM;IACnB,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,GAAG,CAAgB;IAC3B,OAAO,CAAC,KAAK,CAA0B;gBAGpB,EAAE,EAAE,mBAAmB,EACvB,OAAO,SAAqB;IAG/C,OAAO,CAAC,MAAM,CAAC,MAAM;IAIrB,OAAO,CAAC,OAAO;IA4Bf,kEAAkE;IAClE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE;CAStE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EAAE,EAAE,aAAa,SAAwB,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAS7J;AAED,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,GAAE,SAAS,MAAM,EAAO,GAAG,MAAM,EAAE,CAM3G;AAED,gDAAgD;AAChD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EAAE,EAAE,aAAa,SAAwB,GAAG,MAAM,EAAE,CAEpJ;AAED,6HAA6H;AAC7H,eAAO,MAAM,YAAY,KAAK,CAAC;AAC/B,uFAAuF;AACvF,eAAO,MAAM,aAAa,IAAI,CAAC;AAE/B;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAC1B,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,EAC1C,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAKf"}

package/dist/src/controllers/episode-hybrid.js

@@ -0,0 +1,117 @@
+import { Bm25Index, tokenize } from '../search/conversation-retrieval.js';
+import { crossEncoderScores } from '../search/cross-encoder.js';
+/**
+ * Episodes indexed for BM25, newest first; older episodes are still found by dense search. The first search in a
+ * process builds the index (about 200 ms at 10k episodes, 1 s at 50k); later writes are appended incrementally.
+ */
+export const HYBRID_MAX_INDEXED = clampInt(process.env.AGENTDB_HYBRID_MAX_EPISODES, 10_000, 1, 1_000_000);
+function clampInt(raw, fallback, min, max) {
+    const n = Math.floor(Number(raw));
+    return Number.isFinite(n) && n >= min ? Math.min(n, max) : fallback;
+}
+/** The candidate pool each side contributes before fusion. */
+export const HYBRID_MAX_POOL = 500;
+/** Weight of the BM25 ranking against the dense ranking. Equal weights won on LongMemEval_M; see ADR-016. */
+export const HYBRID_LEXICAL_WEIGHT = 1;
+const RRF_K = 60;
+/**
+ * A BM25 index over episode text. New episodes are appended incrementally (the common write-then-read pattern);
+ * the index is rebuilt only when rows were deleted or replaced, or it has grown past 1.25x its cap.
+ */
+export class EpisodeLexicalIndex {
+    db;
+    maxDocs;
+    count = -1;
+    maxId = 0;
+    ids = [];
+    index = null;
+    constructor(db, maxDocs = HYBRID_MAX_INDEXED) {
+        this.db = db;
+        this.maxDocs = maxDocs;
+    }
+    static textOf(r) {
+        return tokenize([r.task, r.input, r.output, r.critique].filter(Boolean).join('\n'));
+    }
+    refresh() {
+        const sig = this.db.prepare('SELECT COUNT(*) AS c, MAX(id) AS m FROM episodes').get();
+        const count = sig?.c ?? 0;
+        const maxId = sig?.m ?? 0;
+        if (this.index && count === this.count && maxId === this.maxId)
+            return;
+        if (this.index && count > this.count && maxId > this.maxId && this.ids.length < this.maxDocs * 1.25) {
+            const added = this.db
+                .prepare('SELECT id, task, input, output, critique FROM episodes WHERE id > ? ORDER BY id ASC')
+                .all(this.maxId);
+            if (this.count + added.length === count) {
+                for (const r of added) {
+                    this.index.add(EpisodeLexicalIndex.textOf(r));
+                    this.ids.push(r.id);
+                }
+                this.count = count;
+                this.maxId = maxId;
+                return;
+            }
+        }
+        const rows = this.db
+            .prepare('SELECT id, task, input, output, critique FROM episodes ORDER BY id DESC LIMIT ?')
+            .all(this.maxDocs);
+        this.index = new Bm25Index(rows.map(r => EpisodeLexicalIndex.textOf(r)));
+        this.ids = rows.map(r => r.id);
+        this.count = count;
+        this.maxId = maxId;
+    }
+    /** Episode ids with a BM25 match, best first, at most `limit`. */
+    search(query, limit) {
+        this.refresh();
+        if (!this.index || this.ids.length === 0)
+            return [];
+        const scores = this.index.score(tokenize(query, 256));
+        const hits = [];
+        for (let i = 0; i < scores.length; i++)
+            if (scores[i] > 0)
+                hits.push({ id: this.ids[i], score: scores[i] });
+        hits.sort((a, z) => z.score - a.score || z.id - a.id);
+        return hits.slice(0, limit);
+    }
+}
+/**
+ * Weighted RRF scores of a dense ranking (best first) and a lexical ranking (best first) over episode ids.
+ * Episodes only in the lexical list are ranked just past the dense pool on the dense side.
+ */
+export function fuseEpisodeScores(denseIds, lexical, lexicalWeight = HYBRID_LEXICAL_WEIGHT) {
+    const score = new Map();
+    const denseMiss = denseIds.length + 1;
+    denseIds.forEach((id, r) => score.set(id, 1 / (RRF_K + r + 1)));
+    lexical.forEach(({ id }, r) => {
+        const base = score.get(id) ?? 1 / (RRF_K + denseMiss);
+        score.set(id, base + lexicalWeight / (RRF_K + r + 1));
+    });
+    return score;
+}
+/** Ids ordered by score, ties broken by dense order, then by newer id. */
+export function orderByScore(score, denseIds = []) {
+    const order = new Map();
+    denseIds.forEach((id, i) => order.set(id, i));
+    return [...score.entries()]
+        .sort((a, z) => z[1] - a[1] || (order.get(a[0]) ?? Infinity) - (order.get(z[0]) ?? Infinity) || z[0] - a[0])
+        .map(([id]) => id);
+}
+/** Fused ranking of episode ids, best first. */
+export function fuseEpisodeRankings(denseIds, lexical, lexicalWeight = HYBRID_LEXICAL_WEIGHT) {
+    return orderByScore(fuseEpisodeScores(denseIds, lexical, lexicalWeight), denseIds);
+}
+/** Candidates the cross-encoder reads: the top `RERANK_DEPTH` of each ranking (the configuration benchmarked in ADR-016). */
+export const RERANK_DEPTH = 60;
+/** Weight of the cross-encoder rank in the fusion; best on LongMemEval_M (ADR-016). */
+export const RERANK_WEIGHT = 8;
+/**
+ * Adds `RERANK_WEIGHT`/(k + cross-encoder rank) to each candidate's fused score, in place. Candidates without text
+ * are skipped. Throws if the model cannot be loaded; the caller keeps the hybrid order.
+ */
+export async function applyCrossEncoder(query, score, candidates, textOf, model) {
+    const ids = candidates.filter(id => score.has(id) && textOf(id));
+    const ce = await crossEncoderScores(query, ids.map(id => textOf(id)), model);
+    const byCe = ids.map((_, i) => i).sort((a, z) => ce[z] - ce[a] || a - z);
+    byCe.forEach((i, r) => score.set(ids[i], score.get(ids[i]) + RERANK_WEIGHT / (RRF_K + r + 1)));
+}
+//# sourceMappingURL=episode-hybrid.js.map

package/dist/src/controllers/episode-hybrid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"episode-hybrid.js","sourceRoot":"","sources":["../../../src/controllers/episode-hybrid.ts"],"names":[],"mappings":"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"}

package/dist/src/mcp/agentdb-mcp-server.js

@@ -7,7 +7,11 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { createDatabase } from '../db-fallback.js';
+import { createDatabase, getDatabaseInfo } from '../db-fallback.js';
+import { NativeAccelerator } from '../backends/rvf/NativeAccelerator.js';
+import { detectBackends } from '../backends/factory.js';
+import { DEFAULT_EXACT_SEARCH_THRESHOLD } from '../backends/VectorBackend.js';
+import { DEFAULT_RERANK_WEIGHTS } from '../controllers/ReasoningBank.js';
 import { CausalMemoryGraph } from '../controllers/CausalMemoryGraph.js';
 import { CausalRecall } from '../controllers/CausalRecall.js';
 import { ReflexionMemory } from '../controllers/ReflexionMemory.js';
@@ -32,6 +36,21 @@ const toolPolicy = buildMcpToolPolicy();
 // Request-size limits at the MCP boundary
 const MAX_INSERT_BATCH_ITEMS = 1000;
 const MAX_SEARCH_K = 100;
+const MAX_FEEDBACK_LATENCY_MS = 24 * 60 * 60 * 1000;
+/**
+ * Outcome feedback at the MCP boundary (ADR-015): a boolean success, a reward
+ * in [0, 1], or both. A reward alone counts as a success when >= 0.5.
+ */
+function validateFeedback(args) {
+    const hasReward = args?.reward !== undefined && args?.reward !== null;
+    const hasSuccess = args?.success !== undefined && args?.success !== null;
+    if (!hasReward && !hasSuccess) {
+        throw new ValidationError('success or reward is required', 'MISSING_REQUIRED_FIELD', 'success');
+    }
+    const reward = hasReward ? validateNumericRange(args.reward, 'reward', 0, 1) : undefined;
+    const success = hasSuccess ? validateBoolean(args.success, 'success') : reward >= 0.5;
+    return { success, reward };
+}
 // stdout belongs exclusively to JSON-RPC when running over stdio. Route every
 // transitive diagnostic (including legacy controller console.log calls) to
 // stderr before database and embedding initialization begins.
@@ -242,6 +261,40 @@ const learningSystem = new LearningSystem(db, embeddingService);
 const batchOps = new BatchOperations(db, embeddingService);
 const reasoningBank = new ReasoningBank(db, embeddingService);
 const caches = new MCPToolCaches();
+// agentdb_capabilities: native probing is done once, on first request
+let acceleratorProbe = null;
+async function describeCapabilities() {
+    acceleratorProbe ??= (async () => {
+        const accelerator = new NativeAccelerator();
+        await accelerator.initialize();
+        return accelerator;
+    })();
+    const [accelerator, detected] = await Promise.all([acceleratorProbe, detectBackends()]);
+    const exactThreshold = Number(process.env.AGENTDB_EXACT_SEARCH_THRESHOLD);
+    return {
+        nativeAccelerator: accelerator.capabilities(),
+        vectorBackend: {
+            // This server's controllers are built without a vector index: every
+            // search here is an exact cosine scan over the SQL embedding tables.
+            inUse: 'sql-exact-scan',
+            available: detected.available,
+            ruvector: detected.ruvector,
+            rvf: detected.rvf,
+            hnswlib: detected.hnswlib,
+            sqljsRvf: detected.sqljsRvf,
+            ruvectorBackendEnv: process.env.RUVECTOR_BACKEND ?? null,
+        },
+        sqlDriver: getDatabaseInfo(),
+        embedding: embeddingService.getRuntimeInfo(),
+        retrieval: {
+            exactSearchThreshold: Number.isFinite(exactThreshold) && exactThreshold >= 0
+                ? exactThreshold
+                : DEFAULT_EXACT_SEARCH_THRESHOLD,
+            patternRerankWeights: DEFAULT_RERANK_WEIGHTS,
+        },
+        mcpProfile: toolPolicy.profile,
+    };
+}
 // ============================================================================
 // MCP Server Setup
 // ============================================================================
@@ -312,13 +365,15 @@ const tools = [
     },
     {
         name: 'agentdb_search',
-        description: 'Semantic k-NN vector search using cosine similarity. Returns the most relevant results ranked by similarity score.',
+        description: 'Hybrid episode search: dense k-NN (cosine) fused with BM25 keyword ranking by reciprocal-rank fusion. Set hybrid=false for pure vector order.',
         inputSchema: {
             type: 'object',
             properties: {
                 query: { type: 'string', description: 'Search query text' },
                 k: { type: 'number', description: 'Number of results to return (max 100)', default: 10, minimum: 1, maximum: 100 },
                 min_similarity: { type: 'number', description: 'Minimum similarity threshold (0-1)', default: 0.0 },
+                hybrid: { type: 'boolean', description: 'Fuse BM25 keyword ranking with the vector ranking (ADR-016)', default: true },
+                rerank: { type: 'boolean', description: 'Rerank the top candidates with a local cross-encoder (ADR-016; ~200 ms on CPU, 23 MB model on first use)', default: false },
                 filters: {
                     type: 'object',
                     properties: {
@@ -708,6 +763,41 @@ const tools = [
             properties: {},
         },
     },
+    {
+        name: 'agentdb_pattern_feedback',
+        description: 'Record the outcome of using a reasoning pattern. Updates its success rate and average reward, which agentdb_pattern_search ranks by (0.7 similarity + 0.2 success rate + 0.1 reward). Give success, reward, or both.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                pattern_id: { type: 'integer', minimum: 0, description: 'Pattern ID from agentdb_pattern_store or agentdb_pattern_search' },
+                success: { type: 'boolean', description: 'Whether applying the pattern succeeded' },
+                reward: { type: 'number', minimum: 0, maximum: 1, description: 'Reward in [0, 1]; defaults to 1 for success, 0 for failure. A reward alone counts as success when >= 0.5' },
+            },
+            required: ['pattern_id'],
+        },
+    },
+    {
+        name: 'agentdb_skill_feedback',
+        description: 'Record the outcome of using a skill. Updates its uses, success rate, average reward and (optionally) latency, which skill_search ranks by. Give success, reward, or both.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                skill_id: { type: 'integer', minimum: 0, description: 'Skill ID from skill_create or skill_search' },
+                success: { type: 'boolean', description: 'Whether the skill succeeded' },
+                reward: { type: 'number', minimum: 0, maximum: 1, description: 'Reward in [0, 1]; defaults to 1 for success, 0 for failure. A reward alone counts as success when >= 0.5' },
+                latency_ms: { type: 'number', minimum: 0, description: 'Observed latency in milliseconds (optional)' },
+            },
+            required: ['skill_id'],
+        },
+    },
+    {
+        name: 'agentdb_capabilities',
+        description: 'Report what this AgentDB server is running on: native accelerator features that loaded, the vector backend in use and the ones available, the SQL driver, the embedding model and dimension (and whether it is the hash fallback), and the ranking defaults. Read-only.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
     {
         name: 'agentdb_clear_cache',
         description: 'Clear query cache to refresh statistics and search results',
@@ -981,13 +1071,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 };
             }
             case 'agentdb_search': {
-                const queryText = args?.query;
+                const queryText = validateTaskString(args?.query, 'query');
                 const k = Math.floor(validateNumericRange(args?.k ?? 10, 'k', 1, MAX_SEARCH_K));
                 const minSimilarity = args?.min_similarity || 0.0;
                 const filters = args?.filters;
                 const query = {
                     task: queryText,
                     k,
+                    hybrid: args?.hybrid !== false,
+                    rerank: args?.rerank === true,
                 };
                 if (filters) {
                     if (filters.min_reward !== undefined) {
@@ -1403,6 +1495,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                                 `Top Results:\n` +
                                 patterns.slice(0, 5).map((p, i) => `${i + 1}. [ID: ${p.id}] ${p.taskType}\n` +
                                     `   Similarity: ${(p.similarity || 0).toFixed(3)}\n` +
+                                    (p.score !== undefined ? `   Rank score: ${p.score.toFixed(3)} (similarity + outcome)\n` : '') +
                                     `   Success Rate: ${(p.successRate * 100).toFixed(1)}%\n` +
                                     `   Approach: ${p.approach.substring(0, 80)}${p.approach.length > 80 ? '...' : ''}\n` +
                                     `   Uses: ${p.uses || 0}`).join('\n\n') +
@@ -1447,6 +1540,56 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     ],
                 };
             }
+            case 'agentdb_pattern_feedback': {
+                const patternId = validateId(args?.pattern_id, 'pattern_id');
+                const { success, reward } = validateFeedback(args);
+                if (!(await reasoningBank.recordOutcome(patternId, success, reward))) {
+                    throw new ValidationError(`Pattern ${patternId} not found`, 'NOT_FOUND', 'pattern_id');
+                }
+                caches.stats.clear();
+                const pattern = reasoningBank.getPattern(patternId);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                patternId,
+                                recorded: { success, reward: reward ?? (success ? 1 : 0) },
+                                uses: pattern.uses,
+                                successRate: pattern.successRate,
+                                avgReward: pattern.avgReward,
+                            }, null, 2),
+                        }],
+                };
+            }
+            case 'agentdb_skill_feedback': {
+                const skillId = validateId(args?.skill_id, 'skill_id');
+                const { success, reward } = validateFeedback(args);
+                const latencyMs = args?.latency_ms === undefined || args?.latency_ms === null
+                    ? undefined
+                    : validateNumericRange(args.latency_ms, 'latency_ms', 0, MAX_FEEDBACK_LATENCY_MS);
+                if (!skills.recordOutcome(skillId, success, reward, latencyMs)) {
+                    throw new ValidationError(`Skill ${skillId} not found`, 'NOT_FOUND', 'skill_id');
+                }
+                const row = db.prepare('SELECT uses, success_rate, avg_reward, avg_latency_ms FROM skills WHERE id = ?').get(skillId);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                skillId,
+                                recorded: { success, reward: reward ?? (success ? 1 : 0), latencyMs },
+                                uses: row.uses,
+                                successRate: row.success_rate,
+                                avgReward: row.avg_reward,
+                                avgLatencyMs: row.avg_latency_ms,
+                            }, null, 2),
+                        }],
+                };
+            }
+            case 'agentdb_capabilities': {
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(await describeCapabilities(), null, 2) }],
+                };
+            }
             case 'agentdb_clear_cache': {
                 const cacheType = args?.cache_type || 'all';
                 let cleared = 0;