@romiluz/clawmongo 2026.3.26 → 2026.3.28

package/dist/plugin-sdk/src/config/types.memory.d.ts

@@ -72,6 +72,50 @@ export type MemoryMongoDBConfig = {
         enabled?: boolean;
         /** Max depth for $graphLookup. Default: 2 */
         maxGraphDepth?: number;
+        /** Entity extraction configuration */
+        entityExtraction?: {
+            /** Extraction strategy. Default: "regex" */
+            method?: "regex" | "llm";
+            /** LLM model for extraction (when method="llm"). Uses agent default if omitted */
+            model?: string;
+            /** Timeout for LLM extraction in ms. Default: 5000 */
+            timeoutMs?: number;
+        };
+    };
+    /** Query rewriting configuration */
+    queryRewriting?: {
+        /** Enable query rewriting before search. Default: false */
+        enabled?: boolean;
+        /** Rewriting strategy. Default: "synonym-expansion" */
+        method?: "synonym-expansion" | "llm" | "hyde";
+        /** Maximum rewritten query length in tokens. Default: 128 */
+        maxTokens?: number;
+    };
+    /** Cross-encoder re-ranking configuration */
+    reranking?: {
+        /** Enable cross-encoder re-ranking. Default: false */
+        enabled?: boolean;
+        /** Re-ranking model. Default: "rerank-2.5" */
+        model?: "rerank-2.5" | "rerank-2.5-lite";
+        /** Maximum documents to send to reranker. Default: 20 */
+        topN?: number;
+        /** Minimum retrieval score to be eligible for re-ranking. Default: 0.1 */
+        minScore?: number;
+        /** Voyage API key. Env fallback: VOYAGE_API_KEY */
+        voyageApiKey?: string;
+        /** Optional instruction prepended to query for rerank-2.5 instruction-following (8-11% accuracy boost). */
+        instruction?: string;
+    };
+    /** Semantic query cache configuration */
+    cache?: {
+        /** Enable query caching. Default: true */
+        enabled?: boolean;
+        /** TTL for conversation scope cache entries in seconds. Default: 300 (5 min) */
+        conversationTtlSec?: number;
+        /** TTL for KB scope cache entries in seconds. Default: 3600 (1 hour) */
+        kbTtlSec?: number;
+        /** Cosine similarity threshold for semantic cache hits. Default: 0.95 */
+        similarityThreshold?: number;
     };
     /** Explain-driven relevance settings */
     relevance?: {

package/dist/plugin-sdk/src/memory/backend-config.d.ts

@@ -57,6 +57,30 @@ export type ResolvedMongoDBConfig = {
     graph: {
         enabled: boolean;
         maxGraphDepth: number;
+        entityExtraction: {
+            method: "regex" | "llm";
+            model?: string;
+            timeoutMs: number;
+        };
+    };
+    queryRewriting: {
+        enabled: boolean;
+        method: "synonym-expansion" | "llm" | "hyde";
+        maxTokens: number;
+    };
+    reranking: {
+        enabled: boolean;
+        model: "rerank-2.5" | "rerank-2.5-lite";
+        topN: number;
+        minScore: number;
+        voyageApiKey: string;
+        instruction?: string;
+    };
+    cache: {
+        enabled: boolean;
+        conversationTtlSec: number;
+        kbTtlSec: number;
+        similarityThreshold: number;
     };
     sources: {
         reference: {

package/dist/plugin-sdk/src/memory/index.d.ts

@@ -1,10 +1,18 @@
 export type { MemoryEmbeddingProbeResult, MemoryReadResult, MemorySearchManager, MemorySearchResult, MemorySource, } from "./types.js";
 export { closeAllMemorySearchManagers, getMemorySearchManager, type MemorySearchManagerResult, } from "./search-manager.js";
-export { writeEvent, getEventsByTimeRange, getEventsBySession, getUnprojectedEvents, markEventsProjected, markEventsConsolidated, getUnconsolidatedEvents, projectChunksFromEvents, type CanonicalEvent, } from "./mongodb-events.js";
-export { upsertEntity, upsertRelation, findEntitiesByName, getEntitiesByType, expandGraph, deleteEntity, extractAndUpsertEntities, type Entity, type EntityType, type Relation, type RelationType, type GraphExpansionResult, } from "./mongodb-graph.js";
-export { materializeEpisode, getEpisodesByTimeRange, getEpisodesByType, searchEpisodes, checkAutoEpisodeTriggers, type Episode, type EpisodeType, type EpisodeSummarizer, type AutoEpisodeTriggerResult, } from "./mongodb-episodes.js";
+export { writeEvent, getEventsByTimeRange, getEventsBySession, getUnprojectedEvents, markEventsProjected, markEventsConsolidated, getUnconsolidatedEvents, projectChunksFromEvents, getSessionEventsWithBound, type CanonicalEvent, } from "./mongodb-events.js";
+export { upsertEntity, upsertRelation, findEntitiesByName, getEntitiesByType, expandGraph, deleteEntity, deleteEntityConservative, extractAndUpsertEntities, type Entity, type EntityType, type Relation, type RelationType, type GraphExpansionResult, } from "./mongodb-graph.js";
+export { materializeEpisode, getEpisodesByTimeRange, getEpisodesByType, searchEpisodes, checkAutoEpisodeTriggers, updateEpisodeStatus, getEpisodesByIds, type Episode, type EpisodeType, type EpisodeStatus, type EpisodeSummarizer, type AutoEpisodeTriggerResult, } from "./mongodb-episodes.js";
 export { recordIngestRun, recordProjectionRun, getRecentIngestRuns, getRecentProjectionRuns, getProjectionLag, } from "./mongodb-ops.js";
 export { planRetrieval, type RetrievalPlan, type RetrievalPath, } from "./mongodb-retrieval-planner.js";
-export { writeProcedure, searchProcedures, type ProcedureEntry, type ProcedureState, } from "./mongodb-procedures.js";
+export { writeProcedure, searchProcedures, recordProcedureOutcome, evolveProcedure, type ProcedureEntry, type ProcedureState, } from "./mongodb-procedures.js";
 export { backfillEventsFromChunks } from "./mongodb-migration.js";
 export { rerankResults, type RerankWeights } from "./mongodb-manager.js";
+export { queryCacheCollection, telemetryCollection, mutationsCollection, } from "./mongodb-schema.js";
+export { recordMutation, getMutationHistory, type MutationRecord, type MutationOperation, } from "./mongodb-mutations.js";
+export { checkCache, writeCache, normalizeQuery, hashQuery, type QueryCacheEntry, type QueryCacheConfig, type CacheCheckResult, DEFAULT_CACHE_CONFIG, } from "./mongodb-query-cache.js";
+export { emitTelemetry, getLatencyStats, getCacheHitRate, getOperationDistribution, type TelemetryDocument, type TelemetryOperation, type TelemetryMeta, } from "./mongodb-telemetry.js";
+export { synthesizeProfile, type ProfileSynthesis, type ProfileMemoryItem, type ProfileEntity, type ProfileEpisode, type ActivityPatterns, } from "./mongodb-profile.js";
+export { crossEncoderRerank, type RerankConfig, type RerankResult } from "./mongodb-reranker.js";
+export { rewriteQuery, expandSynonyms, type QueryRewriteConfig, type QueryRewriteResult, } from "./mongodb-query-rewriter.js";
+export { type EntityExtractor, type ExtractedEntity as ExtractedEntityV2, type EntityExtractionContext, type LLMFunction, RegexEntityExtractor, LLMEntityExtractor, buildExtractionPrompt, buildUserExtractionPrompt, buildAssistantExtractionPrompt, parseExtractionResponse, } from "./mongodb-entity-extractor.js";

package/dist/plugin-sdk/src/memory/mongodb-entity-extractor.d.ts

@@ -0,0 +1,33 @@
+export declare const STOP_WORDS: Set<string>;
+export type ExtractedEntity = {
+    name: string;
+    type: string;
+    confidence?: number;
+    extractionMethod: "regex" | "llm";
+};
+export type EntityExtractionContext = {
+    agentId: string;
+    scope: string;
+    scopeRef: string;
+    existingEntityNames?: string[];
+    role?: string;
+};
+export interface EntityExtractor {
+    extract(content: string, context?: EntityExtractionContext): Promise<ExtractedEntity[]>;
+}
+export declare class RegexEntityExtractor implements EntityExtractor {
+    extract(content: string): Promise<ExtractedEntity[]>;
+}
+export type LLMFunction = (prompt: string) => Promise<string>;
+export declare class LLMEntityExtractor implements EntityExtractor {
+    private llmFn;
+    private timeoutMs;
+    private fallback;
+    constructor(llmFn: LLMFunction, timeoutMs?: number);
+    extract(content: string, context?: EntityExtractionContext): Promise<ExtractedEntity[]>;
+    private extractWithLLM;
+}
+export declare function buildExtractionPrompt(content: string, context?: EntityExtractionContext): string;
+export declare function buildUserExtractionPrompt(content: string, context?: EntityExtractionContext): string;
+export declare function buildAssistantExtractionPrompt(content: string, context?: EntityExtractionContext): string;
+export declare function parseExtractionResponse(response: string): ExtractedEntity[];

package/dist/plugin-sdk/src/memory/mongodb-episodes.d.ts

@@ -1,6 +1,7 @@
 import type { Db } from "mongodb";
 import type { MemoryScope } from "../config/types.memory.js";
 export type EpisodeType = "daily" | "weekly" | "thread" | "topic" | "decision";
+export type EpisodeStatus = "active" | "archived" | "deleted";
 export type Episode = {
     episodeId: string;
     type: EpisodeType;
@@ -16,6 +17,7 @@ export type Episode = {
     sourceEventCount: number;
     sourceEventIds?: string[];
     tags?: string[];
+    status?: EpisodeStatus;
     updatedAt: Date;
 };
 /**
@@ -77,6 +79,20 @@ export declare function searchEpisodes(params: {
     };
     limit?: number;
 }): Promise<Episode[]>;
+export declare function updateEpisodeStatus(params: {
+    db: Db;
+    prefix: string;
+    episodeId: string;
+    agentId: string;
+    status: EpisodeStatus;
+}): Promise<boolean>;
+export declare function getEpisodesByIds(params: {
+    db: Db;
+    prefix: string;
+    episodeIds: string[];
+    agentId: string;
+    projection?: "full" | "ids-only";
+}): Promise<Episode[]>;
 export type AutoEpisodeTriggerResult = {
     triggered: boolean;
     reason?: "session_gap" | "event_count" | "explicit" | "rate_limited" | "insufficient_events";

package/dist/plugin-sdk/src/memory/mongodb-events.d.ts

@@ -79,6 +79,15 @@ export declare function getUnconsolidatedEvents(params: {
     scopeRef?: string;
     limit?: number;
 }): Promise<CanonicalEvent[]>;
+export declare function getSessionEventsWithBound(params: {
+    db: Db;
+    prefix: string;
+    agentId: string;
+    sessionId: string;
+    bound?: number;
+    scope?: MemoryScope;
+    scopeRef?: string;
+}): Promise<CanonicalEvent[]>;
 /**
  * Project unprojected events into the chunks collection.
  * Each event becomes a conversation chunk at `events/{eventId}` using a

package/dist/plugin-sdk/src/memory/mongodb-graph.d.ts

@@ -1,6 +1,7 @@
 import type { Db } from "mongodb";
 import type { MemoryScope } from "../config/types.memory.js";
-export type EntityType = "person" | "org" | "project" | "topic" | "feature" | "issue" | "document" | "custom";
+import { type EntityExtractor } from "./mongodb-entity-extractor.js";
+export type EntityType = "person" | "org" | "project" | "topic" | "feature" | "issue" | "document" | "custom" | "location" | "system" | "concept";
 export type Entity = {
     entityId: string;
     name: string;
@@ -135,6 +136,31 @@ export declare function deleteEntity(params: {
     deletedEntity: boolean;
     deletedRelations: number;
 }>;
+/**
+ * Safe wrapper around `deleteEntity` that checks for conflicting relations
+ * before proceeding. If the entity has relations and `force` is not set,
+ * the delete is blocked and the conflict is reported.
+ *
+ * When the delete proceeds:
+ * - The entity doc is read first (for audit oldValue snapshot)
+ * - `deleteEntity` is called (cascade deletes relations)
+ * - A mutation audit record is written (fire-and-forget)
+ *
+ * Audit failures never prevent the deletion from succeeding.
+ */
+export declare function deleteEntityConservative(params: {
+    db: Db;
+    prefix: string;
+    entityId: string;
+    agentId: string;
+    force?: boolean;
+}): Promise<{
+    deletedEntity: boolean;
+    deletedRelations: number;
+    conflictDetected: boolean;
+    conflictingRelationCount?: number;
+    auditRecorded: boolean;
+}>;
 type ExtractedEntity = {
     entityId: string;
     name: string;
@@ -142,8 +168,7 @@ type ExtractedEntity = {
 };
 /**
  * Extract structural entities from event content and upsert them.
- * Regex patterns: @mentions->person, #tags->topic, URLs->document,
- * file paths->document, "quoted names"->person.
+ * Uses a pluggable EntityExtractor (defaults to RegexEntityExtractor).
  *
  * Deterministic entityIds via hash of name.toLowerCase() + type.
  * Fire-and-forget: caller decides whether to await.
@@ -157,6 +182,8 @@ export declare function extractAndUpsertEntities(params: {
     scope: MemoryScope;
     scopeRef?: string;
     sourceEventId?: string;
+    extractor?: EntityExtractor;
+    role?: "user" | "assistant" | "system" | "tool";
 }): Promise<{
     entities: ExtractedEntity[];
     relationsCreated: number;

package/dist/plugin-sdk/src/memory/mongodb-manager.d.ts

@@ -5,7 +5,10 @@ import type { ResolvedMemoryBackendConfig, ResolvedMongoDBConfig } from "./backe
 import { type MemoryStats } from "./mongodb-analytics.js";
 import { type IngestRun, type ProjectionRun } from "./mongodb-ops.js";
 import type { ProcedureEntry } from "./mongodb-procedures.js";
+import { type ProfileSynthesis } from "./mongodb-profile.js";
+import { type QueryRewriteConfig } from "./mongodb-query-rewriter.js";
 import { type RelevanceArtifact, type RelevanceBenchmarkResult, type RelevanceHealth, type RelevanceReport, type RelevanceSampleState, type RelevanceSourceScope } from "./mongodb-relevance.js";
+import { type RerankConfig } from "./mongodb-reranker.js";
 import { type RetrievalPath, type RetrievalPlan } from "./mongodb-retrieval-planner.js";
 import type { DetectedCapabilities } from "./mongodb-schema.js";
 import type { StructuredMemoryEntry } from "./mongodb-structured-memory.js";
@@ -239,6 +242,14 @@ export declare class MongoDBMemoryManager implements MemorySearchManager {
         id: string;
     }>;
     getDetailedStatus(): Promise<V2Status>;
+    synthesizeProfile(params?: {
+        scope?: MemoryScope;
+        scopeRef?: string;
+        maxPerType?: number;
+        maxEntities?: number;
+        maxEpisodes?: number;
+        activityWindowMs?: number;
+    }): Promise<ProfileSynthesis>;
     private enqueueDerivedWork;
     private schedulePostWriteDerivations;
     writeConversationEvent(event: {
@@ -268,6 +279,8 @@ export declare function writeEventAndProject(db: Db, prefix: string, event: {
     path?: string;
     hash?: string;
     metadata?: Record<string, unknown>;
+}, options?: {
+    extractor?: import("./mongodb-entity-extractor.js").EntityExtractor;
 }): Promise<{
     eventId: string;
     chunksCreated: number;
@@ -276,6 +289,8 @@ export type V2SearchMetadata = {
     plan: RetrievalPlan;
     pathsExecuted: RetrievalPath[];
     resultsByPath: Record<string, number>;
+    reranked?: boolean;
+    queryRewritten?: boolean;
 };
 /**
  * Execute a v2 retrieval plan: call planRetrieval, execute top 3 paths, deduplicate results.
@@ -300,6 +315,9 @@ export declare function searchV2(db: Db, prefix: string, query: string, agentId:
         scope?: MemoryScope;
         scopeRef?: string;
         allowHybridBackstop?: boolean;
+        rerankConfig?: RerankConfig;
+        queryRewriteConfig?: QueryRewriteConfig;
+        projection?: "full" | "ids-only";
     };
 }): Promise<{
     results: MemorySearchResult[];

package/dist/plugin-sdk/src/memory/mongodb-mutations.d.ts

@@ -0,0 +1,38 @@
+import type { Db, Document } from "mongodb";
+export type MutationOperation = "create" | "update" | "delete";
+export type MutationRecord = {
+    mutationId: string;
+    collectionName: string;
+    documentId: string;
+    operation: MutationOperation;
+    agentId: string;
+    oldValue: Document | null;
+    newValue: Document | null;
+    changedFields?: string[];
+    timestamp: Date;
+    actorRole?: "user" | "assistant" | "system";
+};
+/**
+ * Insert an audit record into the memory_mutations collection.
+ * Fire-and-forget safe: callers can use Promise.allSettled to avoid blocking.
+ */
+export declare function recordMutation(params: {
+    db: Db;
+    prefix: string;
+    mutation: Omit<MutationRecord, "mutationId" | "timestamp">;
+}): Promise<{
+    mutationId: string;
+}>;
+/**
+ * Query mutation audit records with filters.
+ * Returns records sorted by timestamp descending (newest first).
+ */
+export declare function getMutationHistory(params: {
+    db: Db;
+    prefix: string;
+    agentId: string;
+    collectionName?: string;
+    documentId?: string;
+    limit?: number;
+    since?: Date;
+}): Promise<MutationRecord[]>;

package/dist/plugin-sdk/src/memory/mongodb-procedures.d.ts

@@ -33,6 +33,38 @@ export declare function writeProcedure(params: {
     upserted: boolean;
     id: string;
 }>;
+/**
+ * Record a success or failure outcome on an existing procedure.
+ * Uses atomic $inc for counters and $set for timestamp.
+ * Returns false if procedure not found (no upsert).
+ */
+export declare function recordProcedureOutcome(params: {
+    db: Db;
+    prefix: string;
+    procedureId: string;
+    agentId: string;
+    scope: MemoryScope;
+    scopeRef?: string;
+    success: boolean;
+}): Promise<boolean>;
+/**
+ * Evolve a procedure: bump version, update steps, and record in
+ * bounded evolutionHistory ($push + $slice: -20).
+ * Throws if procedure not found.
+ */
+export declare function evolveProcedure(params: {
+    db: Db;
+    prefix: string;
+    procedureId: string;
+    agentId: string;
+    scope: MemoryScope;
+    scopeRef?: string;
+    newSteps: string[];
+    changeType: string;
+    changeDescription: string;
+}): Promise<{
+    newVersion: number;
+}>;
 export declare function searchProcedures(collection: Collection, query: string, queryVector: number[] | null, opts: {
     maxResults: number;
     minScore?: number;

package/dist/plugin-sdk/src/memory/mongodb-profile.d.ts

@@ -0,0 +1,71 @@
+import type { Db } from "mongodb";
+import type { MemoryScope } from "../config/types.memory.js";
+export type ProfileSynthesis = {
+    agentId: string;
+    scope: MemoryScope;
+    scopeRef: string;
+    /** Structured memory grouped by type */
+    preferences: ProfileMemoryItem[];
+    decisions: ProfileMemoryItem[];
+    facts: ProfileMemoryItem[];
+    todos: ProfileMemoryItem[];
+    /** Top entities by relation count */
+    topEntities: ProfileEntity[];
+    /** Most recent episode summaries */
+    recentEpisodes: ProfileEpisode[];
+    /** Activity patterns derived from events */
+    activityPatterns: ActivityPatterns;
+    /** Synthesis timestamp */
+    synthesizedAt: Date;
+};
+export type ProfileMemoryItem = {
+    key: string;
+    value: string;
+    salience: string;
+    updatedAt: Date;
+};
+export type ProfileEntity = {
+    name: string;
+    type: string;
+    relationCount: number;
+};
+export type ProfileEpisode = {
+    title: string;
+    summary: string;
+    type: string;
+    timeRange: {
+        start: Date;
+        end: Date;
+    };
+};
+export type ActivityPatterns = {
+    /** Distribution of events by role (user, assistant, system, tool) */
+    roleDistribution: Record<string, number>;
+    /** Total event count in the analysis window */
+    totalEvents: number;
+    /** Most recent event timestamp */
+    lastActive: Date | null;
+};
+/**
+ * Synthesize a dynamic agent profile from structured memory, entities,
+ * episodes, and events. Read-only aggregation across 5 collections.
+ *
+ * Uses $facet for structured_mem (single pass), $lookup + $group for
+ * entity relation counts, simple find for episodes, and $group for
+ * event activity patterns.
+ */
+export declare function synthesizeProfile(params: {
+    db: Db;
+    prefix: string;
+    agentId: string;
+    scope: MemoryScope;
+    scopeRef: string;
+    /** Max items per structured memory type. Default: 20 */
+    maxPerType?: number;
+    /** Max entities to return. Default: 10 */
+    maxEntities?: number;
+    /** Max episodes to return. Default: 10 */
+    maxEpisodes?: number;
+    /** Activity window in ms. Default: 30 days */
+    activityWindowMs?: number;
+}): Promise<ProfileSynthesis>;

package/dist/plugin-sdk/src/memory/mongodb-query-cache.d.ts

@@ -0,0 +1,68 @@
+import type { Db } from "mongodb";
+import type { MemoryScope } from "../config/types.memory.js";
+import type { MemorySearchResult } from "./types.js";
+export type QueryCacheEntry = {
+    queryHash: string;
+    queryNorm: string;
+    agentId: string;
+    scope: MemoryScope;
+    scopeRef: string;
+    results: MemorySearchResult[];
+    pathUsed: string;
+    sourceScope: string;
+    createdAt: Date;
+    expiresAt: Date;
+    hitCount: number;
+    lastHitAt: Date;
+};
+export type QueryCacheConfig = {
+    enabled: boolean;
+    conversationTtlSec: number;
+    kbTtlSec: number;
+    similarityThreshold: number;
+};
+export declare const DEFAULT_CACHE_CONFIG: QueryCacheConfig;
+export type CacheCheckResult = {
+    hit: boolean;
+    tier: "exact" | "semantic" | "miss";
+    results: MemorySearchResult[];
+    pathUsed?: string;
+    sourceScope?: string;
+};
+/** Normalize query for consistent hashing: lowercase, collapse whitespace, trim. */
+export declare function normalizeQuery(query: string): string;
+/** SHA-256 hash of normalized query string. */
+export declare function hashQuery(normalizedQuery: string): string;
+/**
+ * Two-tier cache check:
+ * Tier 1: Exact SHA-256 hash match via findOne on unique index.
+ * Tier 2: $vectorSearch with autoEmbed on queryNorm field, cosine >= threshold.
+ *
+ * On hit: increments hitCount and updates lastHitAt (fire-and-forget).
+ */
+export declare function checkCache(params: {
+    db: Db;
+    prefix: string;
+    query: string;
+    agentId: string;
+    scope: MemoryScope;
+    scopeRef: string;
+    config: QueryCacheConfig;
+    vectorIndexName?: string;
+}): Promise<CacheCheckResult>;
+/**
+ * Write search results to cache. Fire-and-forget: does not block caller.
+ * Uses upsert to handle race conditions (two identical queries completing simultaneously).
+ */
+export declare function writeCache(params: {
+    db: Db;
+    prefix: string;
+    query: string;
+    agentId: string;
+    scope: MemoryScope;
+    scopeRef: string;
+    results: MemorySearchResult[];
+    pathUsed: string;
+    sourceScope: string;
+    ttlSec: number;
+}): void;

package/dist/plugin-sdk/src/memory/mongodb-query-rewriter.d.ts

@@ -0,0 +1,39 @@
+import type { Db } from "mongodb";
+export type QueryRewriteConfig = {
+    enabled: boolean;
+    method: "synonym-expansion" | "llm" | "hyde";
+    maxTokens: number;
+};
+export type QueryRewriteResult = {
+    originalQuery: string;
+    rewrittenQuery: string;
+    rewritten: boolean;
+    method: string;
+};
+/**
+ * Deterministic synonym expansion.
+ * For each word in the query:
+ *   1. Check if it is an abbreviation -- add full form
+ *   2. Check if it matches a synonym group -- add all synonyms
+ * Original words are always preserved.
+ */
+export declare function expandSynonyms(query: string): string;
+/**
+ * Rewrite a query for improved vector search recall.
+ *
+ * CRITICAL: The retrieval planner must ALWAYS see the ORIGINAL query.
+ * This function is called AFTER planRetrieval() and BEFORE search execution.
+ * The cache key must also use the ORIGINAL query.
+ *
+ * Tier 1 (synonym-expansion): Deterministic, zero latency.
+ *   - Expand known abbreviations
+ *   - Add synonyms for recognized terms
+ *   - Preserve original terms (expansion, not replacement)
+ */
+export declare function rewriteQuery(params: {
+    db: Db;
+    prefix: string;
+    agentId: string;
+    query: string;
+    config: QueryRewriteConfig;
+}): Promise<QueryRewriteResult>;

package/dist/plugin-sdk/src/memory/mongodb-reranker.d.ts

@@ -0,0 +1,32 @@
+import type { Db } from "mongodb";
+import type { MemorySearchResult } from "./types.js";
+export type RerankConfig = {
+    enabled: boolean;
+    model: "rerank-2.5" | "rerank-2.5-lite";
+    topN: number;
+    minScore: number;
+    voyageApiKey: string;
+    /** Optional instruction prepended to query for rerank-2.5 instruction-following. */
+    instruction?: string;
+};
+export type RerankResult = {
+    results: MemorySearchResult[];
+    reranked: boolean;
+    latencyMs: number;
+};
+/**
+ * Cross-encoder re-ranking of search results using Voyage rerank-2.5 API.
+ *
+ * On ANY error (network, API, JSON parse, unexpected shape): falls back to
+ * input order unchanged, logs a warning, and never crashes the search pipeline.
+ *
+ * Uses `r.snippet` for document text (MemorySearchResult has no `text` field).
+ */
+export declare function crossEncoderRerank(params: {
+    db: Db;
+    prefix: string;
+    agentId: string;
+    query: string;
+    results: MemorySearchResult[];
+    config: RerankConfig;
+}): Promise<RerankResult>;

package/dist/plugin-sdk/src/memory/mongodb-schema.d.ts

@@ -32,6 +32,9 @@ export declare function entityLinksCollection(db: Db, prefix: string): Collectio
 export declare function episodesCollection(db: Db, prefix: string): Collection;
 export declare function ingestRunsCollection(db: Db, prefix: string): Collection;
 export declare function projectionRunsCollection(db: Db, prefix: string): Collection;
+export declare function queryCacheCollection(db: Db, prefix: string): Collection;
+export declare function telemetryCollection(db: Db, prefix: string): Collection;
+export declare function mutationsCollection(db: Db, prefix: string): Collection;
 export declare function ensureCollections(db: Db, prefix: string): Promise<void>;
 /**
  * Apply JSON Schema validation to existing collections that were created