@agentskit/memory 0.8.0 → 0.8.3

package/dist/index.js

@@ -1,4 +1,4 @@
-import { serializeMessages, deserializeMessages } from '@agentskit/core';
+import { serializeMessages, deserializeMessages, MemoryError, ErrorCodes, ConfigError } from '@agentskit/core';
 
 var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
   get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
@@ -47,7 +47,11 @@ async function openDatabase(path) {
     const Database = mod.default ?? mod;
     return new Database(path);
   } catch {
-    throw new Error("Install better-sqlite3 to use sqliteChatMemory: npm install better-sqlite3");
+    throw new MemoryError({
+      code: ErrorCodes.AK_MEMORY_PEER_MISSING,
+      message: "Install better-sqlite3 to use sqliteChatMemory: npm install better-sqlite3",
+      hint: 'sqliteChatMemory uses the optional peer "better-sqlite3".'
+    });
   }
 }
 function sqliteChatMemory(config) {
@@ -98,7 +102,11 @@ async function loadSdk() {
           moduleId
         );
       } catch {
-        throw new Error("Install @libsql/client to use tursoChatMemory: npm install @libsql/client");
+        throw new MemoryError({
+          code: ErrorCodes.AK_MEMORY_PEER_MISSING,
+          message: "Install @libsql/client to use tursoChatMemory: npm install @libsql/client",
+          hint: 'tursoChatMemory uses the optional peer "@libsql/client".'
+        });
       }
     })();
   }
@@ -159,14 +167,16 @@ function tursoChatMemory(config) {
     }
   };
 }
-
-// src/redis-client.ts
 async function createRedisClientAdapter(url) {
   let redis;
   try {
     redis = await import('redis');
   } catch {
-    throw new Error("Install redis to use Redis memory backends: npm install redis");
+    throw new MemoryError({
+      code: ErrorCodes.AK_MEMORY_PEER_MISSING,
+      message: "Install redis to use Redis memory backends: npm install redis",
+      hint: 'redisChatMemory and redisVectorMemory use the optional peer "redis".'
+    });
   }
   const client = redis.createClient({ url });
   await client.connect();
@@ -392,9 +402,11 @@ function requireVectra() {
   try {
     return __require("vectra");
   } catch {
-    throw new Error(
-      "Install vectra to use fileVectorMemory: npm install vectra"
-    );
+    throw new MemoryError({
+      code: ErrorCodes.AK_MEMORY_PEER_MISSING,
+      message: "Install vectra to use fileVectorMemory: npm install vectra",
+      hint: 'fileVectorMemory uses the optional peer "vectra" for the on-disk index.'
+    });
   }
 }
 function createVectraStore(dirPath) {
@@ -632,8 +644,6 @@ function pgvector(config) {
     }
   };
 }
-
-// src/vector/pinecone.ts
 async function call(config, path, body) {
   const fetchImpl = config.fetch ?? globalThis.fetch;
   const response = await fetchImpl(`${config.indexUrl}${path}`, {
@@ -645,7 +655,13 @@ async function call(config, path, body) {
     body: JSON.stringify(body)
   });
   const text = await response.text();
-  if (!response.ok) throw new Error(`pinecone ${response.status}: ${text.slice(0, 200)}`);
+  if (!response.ok) {
+    throw new MemoryError({
+      code: ErrorCodes.AK_MEMORY_REMOTE_HTTP,
+      message: `pinecone ${response.status}: ${text.slice(0, 200)}`,
+      hint: `URL ${config.indexUrl}${path}. Check api-key + index URL/namespace.`
+    });
+  }
   return text.length > 0 ? JSON.parse(text) : {};
 }
 function pinecone(config) {
@@ -685,8 +701,6 @@ function pinecone(config) {
     }
   };
 }
-
-// src/vector/qdrant.ts
 async function call2(config, method, path, body) {
   const fetchImpl = config.fetch ?? globalThis.fetch;
   const response = await fetchImpl(`${config.url}${path}`, {
@@ -698,7 +712,13 @@ async function call2(config, method, path, body) {
     body: body === void 0 ? void 0 : JSON.stringify(body)
   });
   const text = await response.text();
-  if (!response.ok) throw new Error(`qdrant ${response.status}: ${text.slice(0, 200)}`);
+  if (!response.ok) {
+    throw new MemoryError({
+      code: ErrorCodes.AK_MEMORY_REMOTE_HTTP,
+      message: `qdrant ${response.status}: ${text.slice(0, 200)}`,
+      hint: `URL ${config.url}${path}. Check api-key + collection "${config.collection}".`
+    });
+  }
   return text.length > 0 ? JSON.parse(text) : {};
 }
 function qdrant(config) {
@@ -737,8 +757,6 @@ function qdrant(config) {
     }
   };
 }
-
-// src/vector/chroma.ts
 async function call3(config, method, path, body) {
   const fetchImpl = config.fetch ?? globalThis.fetch;
   const response = await fetchImpl(`${config.url}${path}`, {
@@ -747,7 +765,13 @@ async function call3(config, method, path, body) {
     body: body === void 0 ? void 0 : JSON.stringify(body)
   });
   const text = await response.text();
-  if (!response.ok) throw new Error(`chroma ${response.status}: ${text.slice(0, 200)}`);
+  if (!response.ok) {
+    throw new MemoryError({
+      code: ErrorCodes.AK_MEMORY_REMOTE_HTTP,
+      message: `chroma ${response.status}: ${text.slice(0, 200)}`,
+      hint: `URL ${config.url}${path}. Check Chroma server health + collection name.`
+    });
+  }
   return text.length > 0 ? JSON.parse(text) : {};
 }
 function chroma(config) {
@@ -786,8 +810,6 @@ function chroma(config) {
     }
   };
 }
-
-// src/vector/upstash.ts
 async function call4(config, path, body) {
   const fetchImpl = config.fetch ?? globalThis.fetch;
   const response = await fetchImpl(`${config.url}${path}`, {
@@ -799,7 +821,13 @@ async function call4(config, path, body) {
     body: JSON.stringify(body)
   });
   const text = await response.text();
-  if (!response.ok) throw new Error(`upstash-vector ${response.status}: ${text.slice(0, 200)}`);
+  if (!response.ok) {
+    throw new MemoryError({
+      code: ErrorCodes.AK_MEMORY_REMOTE_HTTP,
+      message: `upstash-vector ${response.status}: ${text.slice(0, 200)}`,
+      hint: `URL ${config.url}${path}. Check token + index URL.`
+    });
+  }
   return text.length > 0 ? JSON.parse(text) : {};
 }
 function upstashVector(config) {
@@ -834,8 +862,6 @@ function upstashVector(config) {
     }
   };
 }
-
-// src/vector/supabase.ts
 var cachedSdk2 = null;
 async function loadSdk2() {
   if (!cachedSdk2) {
@@ -847,9 +873,11 @@ async function loadSdk2() {
           moduleId
         );
       } catch {
-        throw new Error(
-          "Install @supabase/supabase-js to use supabaseVectorStore: npm install @supabase/supabase-js"
-        );
+        throw new MemoryError({
+          code: ErrorCodes.AK_MEMORY_PEER_MISSING,
+          message: "Install @supabase/supabase-js to use supabaseVectorStore: npm install @supabase/supabase-js",
+          hint: 'supabaseVectorStore uses the optional peer "@supabase/supabase-js".'
+        });
       }
     })();
   }
@@ -859,7 +887,13 @@ function buildRunner(client) {
   return {
     async query(sql, params) {
       const result = await client.rpc("agentskit_execute_sql", { sql, params });
-      if (result.error) throw new Error(`supabase: ${result.error.message}`);
+      if (result.error) {
+        throw new MemoryError({
+          code: ErrorCodes.AK_MEMORY_REMOTE_HTTP,
+          message: `supabase: ${result.error.message}`,
+          hint: "Check the agentskit_execute_sql RPC + service role key permissions."
+        });
+      }
       return { rows: result.data ?? [] };
     }
   };
@@ -903,8 +937,6 @@ function supabaseVectorStore(config) {
     }
   };
 }
-
-// src/vector/weaviate.ts
 async function call5(config, method, path, body) {
   const fetchImpl = config.fetch ?? globalThis.fetch;
   const response = await fetchImpl(`${config.url}${path}`, {
@@ -916,7 +948,13 @@ async function call5(config, method, path, body) {
     body: body === void 0 ? void 0 : JSON.stringify(body)
   });
   const text = await response.text();
-  if (!response.ok) throw new Error(`weaviate ${response.status}: ${text.slice(0, 200)}`);
+  if (!response.ok) {
+    throw new MemoryError({
+      code: ErrorCodes.AK_MEMORY_REMOTE_HTTP,
+      message: `weaviate ${response.status}: ${text.slice(0, 200)}`,
+      hint: `URL ${config.url}${path}. Check API key + class name "${config.className}".`
+    });
+  }
   return text.length > 0 ? JSON.parse(text) : {};
 }
 function weaviateVectorStore(config) {
@@ -961,8 +999,6 @@ function weaviateVectorStore(config) {
     }
   };
 }
-
-// src/vector/milvus.ts
 async function call6(config, path, body) {
   const fetchImpl = config.fetch ?? globalThis.fetch;
   const response = await fetchImpl(`${config.url}${path}`, {
@@ -974,7 +1010,13 @@ async function call6(config, path, body) {
     body: JSON.stringify(body)
   });
   const text = await response.text();
-  if (!response.ok) throw new Error(`milvus ${response.status}: ${text.slice(0, 200)}`);
+  if (!response.ok) {
+    throw new MemoryError({
+      code: ErrorCodes.AK_MEMORY_REMOTE_HTTP,
+      message: `milvus ${response.status}: ${text.slice(0, 200)}`,
+      hint: `URL ${config.url}${path}. Check token + collection "${config.collection}".`
+    });
+  }
   return text.length > 0 ? JSON.parse(text) : {};
 }
 function milvusVectorStore(config) {
@@ -1064,8 +1106,6 @@ function mongoAtlasVectorStore(config) {
     }
   };
 }
-
-// src/encrypted.ts
 function toBase64(bytes) {
   if (typeof Buffer !== "undefined") return Buffer.from(bytes).toString("base64");
   let binary = "";
@@ -1083,14 +1123,24 @@ async function resolveKey(subtle, material) {
   if ("type" in material && material.type === "secret") return material;
   const raw = material;
   if (raw.byteLength !== 32) {
-    throw new Error(`createEncryptedMemory: key must be 32 bytes (got ${raw.byteLength})`);
+    throw new ConfigError({
+      code: ErrorCodes.AK_CONFIG_INVALID,
+      message: `createEncryptedMemory: key must be 32 bytes (got ${raw.byteLength})`,
+      hint: "Generate a 32-byte key, e.g. crypto.getRandomValues(new Uint8Array(32))."
+    });
   }
   return subtle.importKey("raw", raw, { name: "AES-GCM" }, false, ["encrypt", "decrypt"]);
 }
 async function createEncryptedMemory(options) {
   const subtle = options.subtle ?? globalThis.crypto?.subtle;
   const random = options.getRandomValues ?? ((v) => globalThis.crypto.getRandomValues(v));
-  if (!subtle) throw new Error("createEncryptedMemory: SubtleCrypto not available");
+  if (!subtle) {
+    throw new MemoryError({
+      code: ErrorCodes.AK_MEMORY_LOAD_FAILED,
+      message: "createEncryptedMemory: SubtleCrypto not available",
+      hint: "Run on Node \u2265 20 / a modern browser, or pass options.subtle explicitly."
+    });
+  }
   const key = await resolveKey(subtle, options.key);
   const aad = options.aad;
   const encrypt = async (plain) => {