@agentskit/memory 0.5.4 → 0.6.1

package/README.md

@@ -4,8 +4,8 @@ Persist conversations and add vector search to your agents — swap backends wit
 
 [![npm version](https://img.shields.io/npm/v/@agentskit/memory?color=blue)](https://www.npmjs.com/package/@agentskit/memory)
 [![npm downloads](https://img.shields.io/npm/dm/@agentskit/memory)](https://www.npmjs.com/package/@agentskit/memory)
-[![bundle size](https://img.shields.io/bundlephobia/minzip/@agentskit/memory)](https://bundlephobia.com/package/@agentskit/memory)
-[![license](https://img.shields.io/npm/l/@agentskit/memory)](../../LICENSE)
+[![bundle size](https://img.shields.io/bundlejs/size/@agentskit/memory?label=bundle)](https://bundlejs.com/?q=@agentskit/memory)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE)
 [![stability](https://img.shields.io/badge/stability-stable-brightgreen)](../../docs/STABILITY.md)
 [![GitHub stars](https://img.shields.io/github/stars/AgentsKit-io/agentskit?style=social)](https://github.com/AgentsKit-io/agentskit)
 
@@ -49,10 +49,38 @@ Use a **vector** backend with [`@agentskit/rag`](https://www.npmjs.com/package/@
 
 ## Features
 
-- Chat memory: `inMemoryChatMemory`, `sqliteChatMemory`, `redisChatMemory`, `fileChatMemory`
-- Vector memory: `fileVectorMemory` (pure JS), `redisVectorMemory`
-- `VectorMemory` interface — 3 methods, bring any custom store
-- Memory contract v1 (ADR 0003) — substitutable across `runtime`, `useChat`, and `@agentskit/ink`
+### Chat memory (3)
+
+- `fileChatMemory({ path })` — JSON on disk; zero infra.
+- `sqliteChatMemory({ path })` — WAL-mode SQLite; indexed by session.
+- `redisChatMemory({ client, keyPrefix })` — distributed, serverless-friendly.
+
+All on top of `createInMemoryMemory` / `createLocalStorageMemory` from
+`@agentskit/core`.
+
+### Vector memory (7)
+
+- `fileVectorMemory` — pure-JS, file-persisted (good to ~10k vectors).
+- `redisVectorMemory` — Redis Stack / Redis 8+ HNSW.
+- `pgvector` — BYO SQL runner (`postgres.js`, `pg`, Drizzle, Prisma, Neon).
+- `pinecone` — managed; namespaces + metadata filters.
+- `qdrant` — self-hosted or cloud via HTTP.
+- `chroma` — HTTP collection client.
+- `upstashVector` — serverless HTTP.
+
+Same 3-method `VectorStore` contract — swap without touching agent code.
+
+### Higher-order wrappers (6)
+
+- `createHierarchicalMemory` — MemGPT-style tiers: working / recall / archival. [Recipe](https://www.agentskit.io/docs/recipes/hierarchical-memory).
+- `createVirtualizedMemory` — hot window + cold retriever for long sessions. [Recipe](https://www.agentskit.io/docs/recipes/virtualized-memory).
+- `createAutoSummarizingMemory` *(via `@agentskit/core/auto-summarize`)* — fold oldest turns into a running summary. [Recipe](https://www.agentskit.io/docs/recipes/auto-summarize).
+- `createEncryptedMemory` — AES-GCM-256 envelope over any `ChatMemory`; keys never leave the caller. [Recipe](https://www.agentskit.io/docs/recipes/encrypted-memory).
+- `createInMemoryGraph` — knowledge graph (nodes + edges + BFS). [Recipe](https://www.agentskit.io/docs/recipes/graph-memory).
+- `createInMemoryPersonalization` + `renderProfileContext` — per-user trait profile. [Recipe](https://www.agentskit.io/docs/recipes/personalization).
+
+Memory contract v1 (ADR 0003) — substitutable across `runtime`,
+`useChat`, and every framework binding.
 
 ## Ecosystem
 

package/dist/index.cjs

@@ -366,10 +366,526 @@ 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();
+  const edges = /* @__PURE__ */ new Map();
+  const matchesNode = (node, query) => {
+    if (!query) return true;
+    if (query.kind && node.kind !== query.kind) return false;
+    return true;
+  };
+  const matchesEdge = (edge, query) => {
+    if (!query) return true;
+    if (query.label && edge.label !== query.label) return false;
+    if (query.from && edge.from !== query.from) return false;
+    if (query.to && edge.to !== query.to) return false;
+    return true;
+  };
+  return {
+    async upsertNode(node) {
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const existing = nodes.get(node.id);
+      const merged = {
+        ...existing ?? {},
+        ...node,
+        createdAt: existing?.createdAt ?? now,
+        updatedAt: now
+      };
+      nodes.set(node.id, merged);
+      return merged;
+    },
+    async upsertEdge(edge) {
+      edges.set(edge.id, edge);
+      return edge;
+    },
+    async getNode(id) {
+      const hit = nodes.get(id);
+      return hit ? { ...hit } : null;
+    },
+    async findNodes(query) {
+      return Array.from(nodes.values()).filter((n) => matchesNode(n, query)).map((n) => ({ ...n }));
+    },
+    async findEdges(query) {
+      return Array.from(edges.values()).filter((e) => matchesEdge(e, query)).map((e) => ({ ...e }));
+    },
+    async neighbors(id, options = {}) {
+      const depth = Math.max(1, options.depth ?? 1);
+      const visited = /* @__PURE__ */ new Set([id]);
+      let frontier = /* @__PURE__ */ new Set([id]);
+      for (let i = 0; i < depth; i++) {
+        const next = /* @__PURE__ */ new Set();
+        for (const edge of edges.values()) {
+          if (options.label && edge.label !== options.label) continue;
+          if (frontier.has(edge.from) && !visited.has(edge.to)) next.add(edge.to);
+          if (frontier.has(edge.to) && !visited.has(edge.from)) next.add(edge.from);
+        }
+        for (const n of next) visited.add(n);
+        frontier = next;
+        if (next.size === 0) break;
+      }
+      visited.delete(id);
+      return Array.from(visited, (nid) => nodes.get(nid)).filter((n) => Boolean(n)).map((n) => ({ ...n }));
+    },
+    async deleteNode(id) {
+      nodes.delete(id);
+      for (const [eid, edge] of edges) {
+        if (edge.from === id || edge.to === id) edges.delete(eid);
+      }
+    },
+    async deleteEdge(id) {
+      edges.delete(id);
+    },
+    async clear() {
+      nodes.clear();
+      edges.clear();
+    }
+  };
+}
+
+// src/vector/pgvector.ts
+function formatVector(embedding) {
+  return `[${embedding.join(",")}]`;
+}
+function pgvector(config) {
+  const table = config.table ?? "agentskit_vectors";
+  const defaultTopK = Math.max(1, config.topK ?? 10);
+  return {
+    async store(docs) {
+      if (docs.length === 0) return;
+      const values = [];
+      const placeholders = docs.map((doc, i) => {
+        const base = i * 4;
+        values.push(doc.id, doc.content, formatVector(doc.embedding), JSON.stringify(doc.metadata ?? {}));
+        return `($${base + 1}, $${base + 2}, $${base + 3}::vector, $${base + 4}::jsonb)`;
+      }).join(", ");
+      await config.runner.query(
+        `INSERT INTO ${table} (id, content, embedding, metadata) VALUES ${placeholders}
+         ON CONFLICT (id) DO UPDATE SET content = EXCLUDED.content, embedding = EXCLUDED.embedding, metadata = EXCLUDED.metadata`,
+        values
+      );
+    },
+    async search(embedding, options = {}) {
+      const topK = options.topK ?? defaultTopK;
+      const threshold = options.threshold ?? 0;
+      const { rows } = await config.runner.query(
+        `SELECT id, content, metadata, (embedding <=> $1::vector) AS distance
+         FROM ${table}
+         ORDER BY embedding <=> $1::vector
+         LIMIT $2`,
+        [formatVector(embedding), topK]
+      );
+      return rows.map((r) => ({
+        id: r.id,
+        content: r.content,
+        metadata: r.metadata ?? void 0,
+        score: 1 - r.distance
+      })).filter((r) => (r.score ?? 0) >= threshold);
+    },
+    async delete(ids) {
+      if (ids.length === 0) return;
+      const placeholders = ids.map((_, i) => `$${i + 1}`).join(",");
+      await config.runner.query(`DELETE FROM ${table} WHERE id IN (${placeholders})`, ids);
+    }
+  };
+}
+
+// src/vector/pinecone.ts
+async function call(config, path, body) {
+  const fetchImpl = config.fetch ?? globalThis.fetch;
+  const response = await fetchImpl(`${config.indexUrl}${path}`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "api-key": config.apiKey
+    },
+    body: JSON.stringify(body)
+  });
+  const text = await response.text();
+  if (!response.ok) throw new Error(`pinecone ${response.status}: ${text.slice(0, 200)}`);
+  return text.length > 0 ? JSON.parse(text) : {};
+}
+function pinecone(config) {
+  const defaultTopK = Math.max(1, config.topK ?? 10);
+  const namespace = config.namespace ?? "";
+  return {
+    async store(docs) {
+      if (docs.length === 0) return;
+      await call(config, "/vectors/upsert", {
+        namespace,
+        vectors: docs.map((d) => ({
+          id: d.id,
+          values: d.embedding,
+          metadata: { content: d.content, ...d.metadata ?? {} }
+        }))
+      });
+    },
+    async search(embedding, options = {}) {
+      const topK = options.topK ?? defaultTopK;
+      const threshold = options.threshold ?? 0;
+      const result = await call(config, "/query", {
+        namespace,
+        topK,
+        vector: embedding,
+        includeMetadata: true
+      });
+      return (result.matches ?? []).filter((m) => m.score >= threshold).map((m) => ({
+        id: m.id,
+        content: String((m.metadata ?? {}).content ?? ""),
+        metadata: m.metadata,
+        score: m.score
+      }));
+    },
+    async delete(ids) {
+      if (ids.length === 0) return;
+      await call(config, "/vectors/delete", { namespace, ids });
+    }
+  };
+}
+
+// src/vector/qdrant.ts
+async function call2(config, method, path, body) {
+  const fetchImpl = config.fetch ?? globalThis.fetch;
+  const response = await fetchImpl(`${config.url}${path}`, {
+    method,
+    headers: {
+      "content-type": "application/json",
+      ...config.apiKey ? { "api-key": config.apiKey } : {}
+    },
+    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)}`);
+  return text.length > 0 ? JSON.parse(text) : {};
+}
+function qdrant(config) {
+  const defaultTopK = Math.max(1, config.topK ?? 10);
+  return {
+    async store(docs) {
+      if (docs.length === 0) return;
+      await call2(config, "PUT", `/collections/${config.collection}/points`, {
+        points: docs.map((d) => ({
+          id: d.id,
+          vector: d.embedding,
+          payload: { content: d.content, ...d.metadata ?? {} }
+        }))
+      });
+    },
+    async search(embedding, options = {}) {
+      const topK = options.topK ?? defaultTopK;
+      const threshold = options.threshold ?? 0;
+      const result = await call2(config, "POST", `/collections/${config.collection}/points/search`, {
+        vector: embedding,
+        limit: topK,
+        with_payload: true
+      });
+      return (result.result ?? []).filter((m) => m.score >= threshold).map((m) => ({
+        id: String(m.id),
+        content: String((m.payload ?? {}).content ?? ""),
+        metadata: m.payload,
+        score: m.score
+      }));
+    },
+    async delete(ids) {
+      if (ids.length === 0) return;
+      await call2(config, "POST", `/collections/${config.collection}/points/delete`, {
+        points: ids
+      });
+    }
+  };
+}
+
+// src/vector/chroma.ts
+async function call3(config, method, path, body) {
+  const fetchImpl = config.fetch ?? globalThis.fetch;
+  const response = await fetchImpl(`${config.url}${path}`, {
+    method,
+    headers: { "content-type": "application/json" },
+    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)}`);
+  return text.length > 0 ? JSON.parse(text) : {};
+}
+function chroma(config) {
+  const defaultTopK = Math.max(1, config.topK ?? 10);
+  return {
+    async store(docs) {
+      if (docs.length === 0) return;
+      await call3(config, "POST", `/api/v1/collections/${config.collection}/upsert`, {
+        ids: docs.map((d) => d.id),
+        embeddings: docs.map((d) => d.embedding),
+        documents: docs.map((d) => d.content),
+        metadatas: docs.map((d) => d.metadata ?? {})
+      });
+    },
+    async search(embedding, options = {}) {
+      const topK = options.topK ?? defaultTopK;
+      const threshold = options.threshold ?? 0;
+      const result = await call3(config, "POST", `/api/v1/collections/${config.collection}/query`, {
+        query_embeddings: [embedding],
+        n_results: topK
+      });
+      const ids = result.ids?.[0] ?? [];
+      const documents = result.documents?.[0] ?? [];
+      const metadatas = result.metadatas?.[0] ?? [];
+      const distances = result.distances?.[0] ?? [];
+      return ids.map((id, i) => ({
+        id,
+        content: documents[i] ?? "",
+        metadata: metadatas[i],
+        score: distances[i] !== void 0 ? 1 - distances[i] : 0
+      })).filter((r) => (r.score ?? 0) >= threshold);
+    },
+    async delete(ids) {
+      if (ids.length === 0) return;
+      await call3(config, "POST", `/api/v1/collections/${config.collection}/delete`, { ids });
+    }
+  };
+}
+
+// src/vector/upstash.ts
+async function call4(config, path, body) {
+  const fetchImpl = config.fetch ?? globalThis.fetch;
+  const response = await fetchImpl(`${config.url}${path}`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      authorization: `Bearer ${config.token}`
+    },
+    body: JSON.stringify(body)
+  });
+  const text = await response.text();
+  if (!response.ok) throw new Error(`upstash-vector ${response.status}: ${text.slice(0, 200)}`);
+  return text.length > 0 ? JSON.parse(text) : {};
+}
+function upstashVector(config) {
+  const defaultTopK = Math.max(1, config.topK ?? 10);
+  return {
+    async store(docs) {
+      if (docs.length === 0) return;
+      await call4(
+        config,
+        "/upsert",
+        docs.map((d) => ({
+          id: d.id,
+          vector: d.embedding,
+          metadata: { content: d.content, ...d.metadata ?? {} }
+        }))
+      );
+    },
+    async search(embedding, options = {}) {
+      const topK = options.topK ?? defaultTopK;
+      const threshold = options.threshold ?? 0;
+      const result = await call4(config, "/query", { vector: embedding, topK, includeMetadata: true });
+      return (result.result ?? []).filter((m) => m.score >= threshold).map((m) => ({
+        id: m.id,
+        content: String((m.metadata ?? {}).content ?? ""),
+        metadata: m.metadata,
+        score: m.score
+      }));
+    },
+    async delete(ids) {
+      if (ids.length === 0) return;
+      await call4(config, "/delete", { ids });
+    }
+  };
+}
+
+// src/encrypted.ts
+function toBase64(bytes) {
+  if (typeof Buffer !== "undefined") return Buffer.from(bytes).toString("base64");
+  let binary = "";
+  for (const b of bytes) binary += String.fromCharCode(b);
+  return btoa(binary);
+}
+function fromBase64(value) {
+  if (typeof Buffer !== "undefined") return new Uint8Array(Buffer.from(value, "base64"));
+  const binary = atob(value);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+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})`);
+  }
+  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");
+  const key = await resolveKey(subtle, options.key);
+  const aad = options.aad;
+  const encrypt = async (plain) => {
+    const iv = random(new Uint8Array(12));
+    const data = new TextEncoder().encode(plain);
+    const params = aad ? { name: "AES-GCM", iv, additionalData: aad } : { name: "AES-GCM", iv };
+    const cipher = await subtle.encrypt(params, key, data);
+    return {
+      ciphertext: toBase64(new Uint8Array(cipher)),
+      iv: toBase64(iv),
+      length: plain.length
+    };
+  };
+  const decrypt = async (envelope) => {
+    const iv = fromBase64(envelope.iv);
+    const params = aad ? { name: "AES-GCM", iv, additionalData: aad } : { name: "AES-GCM", iv };
+    const plain = await subtle.decrypt(params, key, fromBase64(envelope.ciphertext));
+    return new TextDecoder().decode(plain);
+  };
+  const encryptMessage = async (m) => {
+    if (m.metadata?.agentskitEncrypted) return m;
+    const envelope = await encrypt(m.content ?? "");
+    return {
+      ...m,
+      content: "",
+      metadata: {
+        ...m.metadata ?? {},
+        agentskitEncrypted: true,
+        ciphertext: envelope.ciphertext,
+        iv: envelope.iv,
+        length: envelope.length
+      }
+    };
+  };
+  const decryptMessage = async (m) => {
+    if (!m.metadata?.agentskitEncrypted) return m;
+    const envelope = {
+      ciphertext: String(m.metadata.ciphertext),
+      iv: String(m.metadata.iv),
+      length: Number(m.metadata.length ?? 0)
+    };
+    const content = await decrypt(envelope);
+    const { agentskitEncrypted: _, ciphertext: __, iv: ___, length: ____, ...rest } = m.metadata;
+    return { ...m, content, metadata: Object.keys(rest).length > 0 ? rest : void 0 };
+  };
+  return {
+    async load() {
+      const stored = await options.backing.load();
+      return Promise.all(stored.map(decryptMessage));
+    },
+    async save(messages) {
+      const encrypted = await Promise.all(messages.map(encryptMessage));
+      await options.backing.save(encrypted);
+    },
+    async clear() {
+      await options.backing.clear?.();
+    }
+  };
+}
+
+// src/hierarchical.ts
+function mergeChronological(a, b) {
+  const out = [...a, ...b];
+  out.sort((x, y) => x.createdAt.getTime() - y.createdAt.getTime());
+  return out;
+}
+function createHierarchicalMemory(options) {
+  const workingLimit = Math.max(1, options.workingLimit ?? 50);
+  const recallTopK = Math.max(0, options.recallTopK ?? 5);
+  const loadAll = async (source) => [...await source.load()];
+  return {
+    async load() {
+      const hot = await loadAll(options.working);
+      if (!options.recall || recallTopK === 0) return hot;
+      let recalled = [];
+      try {
+        recalled = [...await options.recall.query({ working: hot, topK: recallTopK })];
+      } catch {
+        recalled = [];
+      }
+      const hotIds = new Set(hot.map((m) => m.id));
+      return mergeChronological(
+        recalled.filter((m) => !hotIds.has(m.id)),
+        hot
+      );
+    },
+    async save(messages) {
+      const knownArchival = await loadAll(options.archival);
+      const archivalIds = new Set(knownArchival.map((m) => m.id));
+      const fresh = messages.filter((m) => !archivalIds.has(m.id));
+      if (fresh.length > 0) {
+        await options.archival.save(mergeChronological(knownArchival, fresh));
+      }
+      const tail = messages.slice(Math.max(0, messages.length - workingLimit));
+      const overflow = messages.slice(0, Math.max(0, messages.length - workingLimit));
+      await options.working.save(tail);
+      if (options.recall) {
+        const knownOverflow = overflow.filter((m) => fresh.some((f) => f.id === m.id));
+        for (const m of knownOverflow) await options.recall.index(m);
+        const appended = fresh.filter((m) => !tail.some((t) => t.id === m.id));
+        for (const m of appended) await options.recall.index(m);
+      }
+    },
+    async clear() {
+      await options.working.clear?.();
+      await options.archival.clear?.();
+    },
+    async archival() {
+      return loadAll(options.archival);
+    },
+    async working() {
+      return loadAll(options.working);
+    }
+  };
+}
+
+exports.chroma = chroma;
+exports.createEncryptedMemory = createEncryptedMemory;
+exports.createHierarchicalMemory = createHierarchicalMemory;
+exports.createInMemoryGraph = createInMemoryGraph;
+exports.createInMemoryPersonalization = createInMemoryPersonalization;
 exports.fileChatMemory = fileChatMemory;
 exports.fileVectorMemory = fileVectorMemory;
+exports.pgvector = pgvector;
+exports.pinecone = pinecone;
+exports.qdrant = qdrant;
 exports.redisChatMemory = redisChatMemory;
 exports.redisVectorMemory = redisVectorMemory;
+exports.renderProfileContext = renderProfileContext;
 exports.sqliteChatMemory = sqliteChatMemory;
+exports.upstashVector = upstashVector;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map