@agentskit/memory 0.8.1 → 0.9.0

package/dist/index.js

@@ -1,11 +1,8 @@
-import { serializeMessages, deserializeMessages } from '@agentskit/core';
+import { __require } from './chunk-G5S2A3MJ.js';
+export { createInMemoryPersonalization, renderProfileContext } from './chunk-G5S2A3MJ.js';
+import { serializeMessages, deserializeMessages, MemoryError, ErrorCodes, ConfigError } from '@agentskit/core';
+import { tokenize, createPIIRedactor } from '@agentskit/core/security';
 
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
 function fileChatMemory(path) {
   return {
     async load() {
@@ -19,7 +16,11 @@ function fileChatMemory(path) {
     },
     async save(messages) {
       const fs = await import('fs/promises');
-      await fs.writeFile(path, JSON.stringify(serializeMessages(messages), null, 2), "utf8");
+      await fs.writeFile(
+        path,
+        JSON.stringify(serializeMessages(messages), null, 2),
+        { encoding: "utf8", mode: 384 }
+      );
     },
     async clear() {
       try {
@@ -47,7 +48,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 +103,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 +168,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();
@@ -185,7 +196,7 @@ async function createRedisClientAdapter(url) {
       return await client.keys(pattern);
     },
     async disconnect() {
-      await client.disconnect();
+      await client.close();
     },
     async call(command, ...args) {
       return await client.sendCommand([command, ...args.map(String)]);
@@ -392,9 +403,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) {
@@ -411,16 +424,23 @@ function createVectraStore(dirPath) {
   return {
     async upsert(docs) {
       const idx = await getIndex();
-      for (const doc of docs) {
-        await idx.insertItem({
-          vector: doc.vector,
-          metadata: { _id: doc.id, ...doc.metadata }
-        });
+      await idx.beginUpdate();
+      try {
+        for (const doc of docs) {
+          await idx.insertItem({
+            vector: doc.vector,
+            metadata: { _id: doc.id, ...doc.metadata }
+          });
+        }
+        await idx.endUpdate();
+      } catch (err) {
+        idx.cancelUpdate();
+        throw err;
       }
     },
     async query(vector, topK) {
       const idx = await getIndex();
-      const results = await idx.queryItems(vector, topK);
+      const results = await idx.queryItems(vector, "", topK);
       return results.map((r) => ({
         id: String(r.item.metadata._id ?? ""),
         score: r.score,
@@ -471,44 +491,6 @@ function fileVectorMemory(config) {
   };
 }
 
-// src/personalization.ts
-function createInMemoryPersonalization() {
-  const profiles = /* @__PURE__ */ new Map();
-  return {
-    async get(subjectId) {
-      const hit = profiles.get(subjectId);
-      return hit ? { ...hit, traits: { ...hit.traits } } : null;
-    },
-    async set(profile) {
-      profiles.set(profile.subjectId, {
-        ...profile,
-        traits: { ...profile.traits },
-        updatedAt: profile.updatedAt || (/* @__PURE__ */ new Date()).toISOString()
-      });
-    },
-    async merge(subjectId, traits) {
-      const existing = profiles.get(subjectId);
-      const next = {
-        subjectId,
-        traits: { ...existing?.traits ?? {}, ...traits },
-        updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-      };
-      profiles.set(subjectId, next);
-      return { ...next, traits: { ...next.traits } };
-    },
-    async delete(subjectId) {
-      profiles.delete(subjectId);
-    }
-  };
-}
-function renderProfileContext(profile) {
-  if (!profile || Object.keys(profile.traits).length === 0) return "";
-  const lines = Object.entries(profile.traits).filter(([, value]) => value !== void 0 && value !== null && value !== "").map(([key, value]) => `- ${key}: ${typeof value === "string" ? value : JSON.stringify(value)}`);
-  if (lines.length === 0) return "";
-  return `## User profile
-${lines.join("\n")}`;
-}
-
 // src/graph.ts
 function createInMemoryGraph() {
   const nodes = /* @__PURE__ */ new Map();
@@ -632,8 +614,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 +625,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 +671,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 +682,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 +727,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 +735,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 +780,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 +791,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 +832,6 @@ function upstashVector(config) {
     }
   };
 }
-
-// src/vector/supabase.ts
 var cachedSdk2 = null;
 async function loadSdk2() {
   if (!cachedSdk2) {
@@ -847,9 +843,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 +857,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 +907,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 +918,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 +969,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 +980,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 +1076,6 @@ function mongoAtlasVectorStore(config) {
     }
   };
 }
-
-// src/encrypted.ts
 function toBase64(bytes) {
   if (typeof Buffer !== "undefined") return Buffer.from(bytes).toString("base64");
   let binary = "";
@@ -1083,14 +1093,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) => {
@@ -1207,6 +1227,102 @@ function createHierarchicalMemory(options) {
   };
 }
 
-export { chroma, createEncryptedMemory, createHierarchicalMemory, createInMemoryGraph, createInMemoryPersonalization, fileChatMemory, fileVectorMemory, matchesFilter, milvusVectorStore, mongoAtlasVectorStore, pgvector, pinecone, qdrant, redisChatMemory, redisVectorMemory, renderProfileContext, sqliteChatMemory, supabaseVectorStore, tursoChatMemory, upstashVector, weaviateVectorStore };
+// src/forget.ts
+function isForgettable(value) {
+  return !!value && typeof value === "object" && "forgetSubject" in value && typeof value.forgetSubject === "function";
+}
+async function hash(input) {
+  const encoded = new TextEncoder().encode(input);
+  const digest = await crypto.subtle.digest("SHA-256", encoded);
+  return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+async function forgetSubject(memories, subjectId) {
+  const reports = [];
+  for (const memory of memories) {
+    if (!isForgettable(memory)) continue;
+    reports.push(await memory.forgetSubject(subjectId));
+  }
+  const totalDeleted = reports.reduce((sum, r) => sum + r.deletedCount, 0);
+  const evidenceHash = await hash(
+    JSON.stringify({ subjectId, reports: reports.map((r) => ({ b: r.backend, n: r.deletedCount, at: r.at })) })
+  );
+  return { subjectId, reports, totalDeleted, evidenceHash };
+}
+function makeForgettable(memory, options) {
+  return Object.assign(memory, {
+    __agentskitBackend: options.backend,
+    forgetSubject: async (subjectId) => {
+      const ids = await options.listIds(subjectId);
+      const failures = [];
+      try {
+        await options.deleteIds(ids);
+      } catch (err) {
+        for (const id of ids) failures.push({ id, reason: err.message });
+      }
+      return {
+        backend: options.backend,
+        deletedCount: ids.length - failures.length,
+        at: (/* @__PURE__ */ new Date()).toISOString(),
+        failures: failures.length ? failures : void 0
+      };
+    }
+  });
+}
+async function transform(input, opts) {
+  if (opts.mode === "tokenize") {
+    if (!opts.vault) {
+      throw new ConfigError({
+        code: ErrorCodes.AK_CONFIG_INVALID,
+        message: 'wrapMemoryWithRedaction: vault is required when mode is "tokenize"'
+      });
+    }
+    if (!opts.allowedRoles) {
+      throw new ConfigError({
+        code: ErrorCodes.AK_CONFIG_INVALID,
+        message: 'wrapMemoryWithRedaction: allowedRoles is required when mode is "tokenize"'
+      });
+    }
+    const result = await tokenize(input, {
+      rules: opts.rules,
+      vault: opts.vault,
+      allowedRoles: opts.allowedRoles,
+      audit: opts.audit
+    });
+    return result.value;
+  }
+  return createPIIRedactor({ rules: opts.rules }).redact(input).value;
+}
+function wrapChatMemoryWithRedaction(inner, options) {
+  return {
+    load: () => inner.load(),
+    save: async (messages) => {
+      const redacted = await Promise.all(
+        messages.map(async (m) => ({
+          ...m,
+          content: await transform(m.content ?? "", options)
+        }))
+      );
+      await inner.save(redacted);
+    },
+    clear: inner.clear ? () => inner.clear() : void 0
+  };
+}
+function wrapVectorMemoryWithRedaction(inner, options) {
+  return {
+    store: async (docs) => {
+      const redacted = await Promise.all(
+        docs.map(async (d) => ({
+          ...d,
+          content: await transform(d.content, options)
+        }))
+      );
+      await inner.store(redacted);
+    },
+    search: (embedding, opts) => inner.search(embedding, opts),
+    delete: inner.delete ? (ids) => inner.delete(ids) : void 0
+  };
+}
+
+export { chroma, createEncryptedMemory, createHierarchicalMemory, createInMemoryGraph, fileChatMemory, fileVectorMemory, forgetSubject, makeForgettable, matchesFilter, milvusVectorStore, mongoAtlasVectorStore, pgvector, pinecone, qdrant, redisChatMemory, redisVectorMemory, sqliteChatMemory, supabaseVectorStore, tursoChatMemory, upstashVector, weaviateVectorStore, wrapChatMemoryWithRedaction, wrapVectorMemoryWithRedaction };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map