@smyslenny/agent-memory 2.1.0 → 2.2.0

package/dist/index.d.ts

@@ -197,6 +197,27 @@ declare function getStrategy(intent: SearchIntent): {
     limit: number;
 };
 
+interface RerankResult {
+    index: number;
+    relevance_score: number;
+}
+interface RerankProvider {
+    id: string;
+    model: string;
+    rerank(query: string, documents: string[]): Promise<RerankResult[]>;
+}
+declare function getRerankerProviderFromEnv(): RerankProvider | null;
+declare function createOpenAIRerankProvider(opts: {
+    apiKey: string;
+    model: string;
+    baseUrl?: string;
+}): RerankProvider;
+
+/**
+ * Optionally rerank results using an external semantic reranker provider.
+ * Best-effort: on failure, returns original results unchanged.
+ */
+declare function rerankWithProvider(results: SearchResult[], query: string, provider: RerankProvider): Promise<SearchResult[]>;
 /**
  * Rerank search results based on intent strategy and priority weighting.
  */
@@ -211,18 +232,24 @@ interface EmbeddingProvider {
     id: string;
     model: string;
     dimension?: number;
+    instructionPrefix?: string | null;
     embed(text: string): Promise<number[]>;
+    embedQuery?(query: string): Promise<number[]>;
 }
+declare function getDefaultInstruction(model: string): string | null;
 declare function getEmbeddingProviderFromEnv(): EmbeddingProvider | null;
 declare function createOpenAIProvider(opts: {
+    id?: string;
     apiKey: string;
     model: string;
     baseUrl?: string;
+    instruction?: string | null;
 }): EmbeddingProvider;
 declare function createDashScopeProvider(opts: {
     apiKey: string;
     model: string;
     baseUrl?: string;
+    instruction?: string | null;
 }): EmbeddingProvider;
 
 interface HybridSearchOptions {
@@ -375,4 +402,4 @@ declare function boot(db: Database.Database, opts?: {
     corePaths?: string[];
 }): BootResult;
 
-export { type BootResult, type CreateMemoryInput, type EmbeddingProvider, type ExportResult, type GovernResult, type GuardAction, type GuardResult, type HybridSearchOptions, type IntentResult, type Link, type Memory, type MemoryType, type Path, type Priority, type RelationType, type SearchIntent, type SearchResult, type Snapshot, type SnapshotAction, type StoredEmbedding, type SyncInput, type SyncResult, type TidyResult, type UpdateMemoryInput, boot, calculateVitality, classifyIntent, contentHash, countMemories, createDashScopeProvider, createLink, createMemory, createOpenAIProvider, createPath, createSnapshot, decodeEmbedding, deleteLink, deleteMemory, deletePath, embedMemory, embedMissingForAgent, encodeEmbedding, exportMemories, getDecayedMemories, getEmbedding, getEmbeddingProviderFromEnv, getLinks, getMemory, getOutgoingLinks, getPath, getPathByUri, getPathsByDomain, getPathsByMemory, getPathsByPrefix, getSnapshot, getSnapshots, getStrategy, guard, listEmbeddings, listMemories, parseUri, recordAccess, rerank, rollback, runDecay, runGovern, runTidy, searchBM25, searchHybrid, syncBatch, syncOne, tokenize, traverse, updateMemory, upsertEmbedding };
+export { type BootResult, type CreateMemoryInput, type EmbeddingProvider, type ExportResult, type GovernResult, type GuardAction, type GuardResult, type HybridSearchOptions, type IntentResult, type Link, type Memory, type MemoryType, type Path, type Priority, type RelationType, type RerankProvider, type RerankResult, type SearchIntent, type SearchResult, type Snapshot, type SnapshotAction, type StoredEmbedding, type SyncInput, type SyncResult, type TidyResult, type UpdateMemoryInput, boot, calculateVitality, classifyIntent, contentHash, countMemories, createDashScopeProvider, createLink, createMemory, createOpenAIProvider, createOpenAIRerankProvider, createPath, createSnapshot, decodeEmbedding, deleteLink, deleteMemory, deletePath, embedMemory, embedMissingForAgent, encodeEmbedding, exportMemories, getDecayedMemories, getDefaultInstruction, getEmbedding, getEmbeddingProviderFromEnv, getLinks, getMemory, getOutgoingLinks, getPath, getPathByUri, getPathsByDomain, getPathsByMemory, getPathsByPrefix, getRerankerProviderFromEnv, getSnapshot, getSnapshots, getStrategy, guard, listEmbeddings, listMemories, parseUri, recordAccess, rerank, rerankWithProvider, rollback, runDecay, runGovern, runTidy, searchBM25, searchHybrid, syncBatch, syncOne, tokenize, traverse, updateMemory, upsertEmbedding };

package/dist/index.js

@@ -997,6 +997,26 @@ function getStrategy(intent) {
 }
 
 // src/search/rerank.ts
+async function rerankWithProvider(results, query, provider) {
+  if (results.length === 0) return results;
+  const documents = results.map((r) => r.memory.content);
+  try {
+    const apiResults = await provider.rerank(query, documents);
+    const scoreMap = new Map(apiResults.map((r) => [r.index, r.relevance_score]));
+    return results.map((r, i) => {
+      const score = scoreMap.get(i);
+      if (score === void 0) return r;
+      return {
+        ...r,
+        score,
+        matchReason: `${r.matchReason}+rerank`
+      };
+    });
+  } catch (err) {
+    console.warn("[agent-memory] External rerank failed, falling back:", err);
+    return results;
+  }
+}
 function rerank(results, opts) {
   const now2 = Date.now();
   const scored = results.map((r) => {
@@ -1112,7 +1132,8 @@ async function searchHybrid(db, query, opts) {
   if (!provider || !model) {
     return bm25.slice(0, limit);
   }
-  const qVec = Float32Array.from(await provider.embed(query));
+  const embedFn = provider.embedQuery ?? provider.embed;
+  const qVec = Float32Array.from(await embedFn.call(provider, query));
   const embeddings = listEmbeddings(db, agentId, model);
   const scored = [];
   for (const e of embeddings) {
@@ -1145,6 +1166,29 @@ async function searchHybrid(db, query, opts) {
 }
 
 // src/search/providers.ts
+var QWEN_DEFAULT_INSTRUCTION = "Given a query, retrieve the most semantically relevant document";
+function getDefaultInstruction(model) {
+  const m = model.toLowerCase();
+  if (m.includes("qwen")) return QWEN_DEFAULT_INSTRUCTION;
+  if (m.includes("gemini")) return null;
+  return null;
+}
+function resolveInstruction(model) {
+  const override = process.env.AGENT_MEMORY_EMBEDDINGS_INSTRUCTION;
+  if (override !== void 0) {
+    const normalized = override.trim();
+    if (!normalized) return null;
+    const lowered = normalized.toLowerCase();
+    if (lowered === "none" || lowered === "off" || lowered === "false" || lowered === "null") return null;
+    return normalized;
+  }
+  return getDefaultInstruction(model);
+}
+function buildQueryInput(query, instructionPrefix) {
+  if (!instructionPrefix) return query;
+  return `Instruct: ${instructionPrefix}
+Query: ${query}`;
+}
 function getEmbeddingProviderFromEnv() {
   const provider = (process.env.AGENT_MEMORY_EMBEDDINGS_PROVIDER ?? "none").toLowerCase();
   if (provider === "none" || provider === "off" || provider === "false") return null;
@@ -1153,14 +1197,24 @@ function getEmbeddingProviderFromEnv() {
     const model = process.env.AGENT_MEMORY_EMBEDDINGS_MODEL ?? "text-embedding-3-small";
     const baseUrl = process.env.OPENAI_BASE_URL ?? "https://api.openai.com/v1";
     if (!apiKey) return null;
-    return createOpenAIProvider({ apiKey, model, baseUrl });
+    const instruction = resolveInstruction(model);
+    return createOpenAIProvider({ apiKey, model, baseUrl, instruction });
+  }
+  if (provider === "gemini" || provider === "google") {
+    const apiKey = process.env.GEMINI_API_KEY ?? process.env.OPENAI_API_KEY;
+    const model = process.env.AGENT_MEMORY_EMBEDDINGS_MODEL ?? "gemini-embedding-001";
+    const baseUrl = process.env.GEMINI_BASE_URL ?? process.env.OPENAI_BASE_URL ?? "https://generativelanguage.googleapis.com/v1beta";
+    if (!apiKey) return null;
+    const instruction = resolveInstruction(model);
+    return createOpenAIProvider({ id: "gemini", apiKey, model, baseUrl, instruction });
   }
   if (provider === "qwen" || provider === "dashscope" || provider === "tongyi") {
     const apiKey = process.env.DASHSCOPE_API_KEY;
     const model = process.env.AGENT_MEMORY_EMBEDDINGS_MODEL ?? "text-embedding-v3";
     const baseUrl = process.env.DASHSCOPE_BASE_URL ?? "https://dashscope.aliyuncs.com";
     if (!apiKey) return null;
-    return createDashScopeProvider({ apiKey, model, baseUrl });
+    const instruction = resolveInstruction(model);
+    return createDashScopeProvider({ apiKey, model, baseUrl, instruction });
   }
   return null;
 }
@@ -1177,52 +1231,112 @@ function normalizeEmbedding(e) {
 }
 function createOpenAIProvider(opts) {
   const baseUrl = opts.baseUrl ?? "https://api.openai.com/v1";
+  const instructionPrefix = opts.instruction ?? null;
+  async function requestEmbedding(input) {
+    const resp = await fetch(`${baseUrl.replace(/\/$/, "")}/embeddings`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: authHeader(opts.apiKey)
+      },
+      body: JSON.stringify({ model: opts.model, input })
+    });
+    if (!resp.ok) {
+      const body = await resp.text().catch(() => "");
+      throw new Error(`OpenAI embeddings failed: ${resp.status} ${resp.statusText} ${body}`.trim());
+    }
+    const data = await resp.json();
+    return normalizeEmbedding(data.data?.[0]?.embedding);
+  }
   return {
-    id: "openai",
+    id: opts.id ?? "openai",
     model: opts.model,
+    instructionPrefix,
     async embed(text) {
-      const resp = await fetch(`${baseUrl.replace(/\/$/, "")}/embeddings`, {
-        method: "POST",
-        headers: {
-          "content-type": "application/json",
-          authorization: authHeader(opts.apiKey)
-        },
-        body: JSON.stringify({ model: opts.model, input: text })
-      });
-      if (!resp.ok) {
-        const body = await resp.text().catch(() => "");
-        throw new Error(`OpenAI embeddings failed: ${resp.status} ${resp.statusText} ${body}`.trim());
-      }
-      const data = await resp.json();
-      const emb = data.data?.[0]?.embedding;
-      return normalizeEmbedding(emb);
+      return requestEmbedding(text);
+    },
+    async embedQuery(query) {
+      return requestEmbedding(buildQueryInput(query, instructionPrefix));
     }
   };
 }
 function createDashScopeProvider(opts) {
   const baseUrl = opts.baseUrl ?? "https://dashscope.aliyuncs.com";
+  const instructionPrefix = opts.instruction ?? null;
+  async function requestEmbedding(text) {
+    const resp = await fetch(`${baseUrl.replace(/\/$/, "")}/api/v1/services/embeddings/text-embedding/text-embedding`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: authHeader(opts.apiKey)
+      },
+      body: JSON.stringify({
+        model: opts.model,
+        input: { texts: [text] }
+      })
+    });
+    if (!resp.ok) {
+      const body = await resp.text().catch(() => "");
+      throw new Error(`DashScope embeddings failed: ${resp.status} ${resp.statusText} ${body}`.trim());
+    }
+    const data = await resp.json();
+    const emb = data.output?.embeddings?.[0]?.embedding ?? data.output?.embeddings?.[0]?.vector ?? data.output?.embedding ?? data.data?.[0]?.embedding;
+    return normalizeEmbedding(emb);
+  }
   return {
     id: "dashscope",
     model: opts.model,
+    instructionPrefix,
     async embed(text) {
-      const resp = await fetch(`${baseUrl.replace(/\/$/, "")}/api/v1/services/embeddings/text-embedding/text-embedding`, {
+      return requestEmbedding(text);
+    },
+    async embedQuery(query) {
+      return requestEmbedding(buildQueryInput(query, instructionPrefix));
+    }
+  };
+}
+
+// src/search/rerank-provider.ts
+function authHeader2(apiKey) {
+  return apiKey.startsWith("Bearer ") ? apiKey : `Bearer ${apiKey}`;
+}
+function getRerankerProviderFromEnv() {
+  const provider = (process.env.AGENT_MEMORY_RERANK_PROVIDER ?? "none").toLowerCase();
+  if (provider === "none" || provider === "off") return null;
+  if (provider === "openai" || provider === "jina" || provider === "cohere") {
+    const apiKey = process.env.AGENT_MEMORY_RERANK_API_KEY ?? process.env.OPENAI_API_KEY;
+    const model = process.env.AGENT_MEMORY_RERANK_MODEL ?? "Qwen/Qwen3-Reranker-8B";
+    const baseUrl = process.env.AGENT_MEMORY_RERANK_BASE_URL ?? process.env.OPENAI_BASE_URL ?? "https://api.openai.com/v1";
+    if (!apiKey) return null;
+    return createOpenAIRerankProvider({ apiKey, model, baseUrl });
+  }
+  return null;
+}
+function createOpenAIRerankProvider(opts) {
+  const baseUrl = opts.baseUrl ?? "https://api.openai.com/v1";
+  return {
+    id: "openai-rerank",
+    model: opts.model,
+    async rerank(query, documents) {
+      const resp = await fetch(`${baseUrl.replace(/\/$/, "")}/rerank`, {
         method: "POST",
         headers: {
           "content-type": "application/json",
-          authorization: authHeader(opts.apiKey)
+          authorization: authHeader2(opts.apiKey)
         },
-        body: JSON.stringify({
-          model: opts.model,
-          input: { texts: [text] }
-        })
+        body: JSON.stringify({ model: opts.model, query, documents })
       });
       if (!resp.ok) {
         const body = await resp.text().catch(() => "");
-        throw new Error(`DashScope embeddings failed: ${resp.status} ${resp.statusText} ${body}`.trim());
+        throw new Error(`Rerank API failed: ${resp.status} ${resp.statusText} ${body}`.trim());
       }
       const data = await resp.json();
-      const emb = data?.output?.embeddings?.[0]?.embedding ?? data?.output?.embeddings?.[0]?.vector ?? data?.output?.embedding ?? data?.data?.[0]?.embedding;
-      return normalizeEmbedding(emb);
+      const results = data.results ?? [];
+      return results.map((r) => {
+        const index = typeof r.index === "number" ? r.index : Number.NaN;
+        const relevance = typeof r.relevance_score === "number" ? r.relevance_score : Number.NaN;
+        return { index, relevance_score: relevance };
+      }).filter((r) => Number.isInteger(r.index) && Number.isFinite(r.relevance_score));
     }
   };
 }
@@ -1521,6 +1635,7 @@ export {
   createLink,
   createMemory,
   createOpenAIProvider,
+  createOpenAIRerankProvider,
   createPath,
   createSnapshot,
   decodeEmbedding,
@@ -1532,6 +1647,7 @@ export {
   encodeEmbedding,
   exportMemories,
   getDecayedMemories,
+  getDefaultInstruction,
   getEmbedding,
   getEmbeddingProviderFromEnv,
   getLinks,
@@ -1542,6 +1658,7 @@ export {
   getPathsByDomain,
   getPathsByMemory,
   getPathsByPrefix,
+  getRerankerProviderFromEnv,
   getSnapshot,
   getSnapshots,
   getStrategy,
@@ -1553,6 +1670,7 @@ export {
   parseUri,
   recordAccess,
   rerank,
+  rerankWithProvider,
   rollback,
   runDecay,
   runGovern,