@agentskit/memory 0.8.1 → 0.9.0

package/dist/index.d.cts

@@ -1,4 +1,6 @@
 import { ChatMemory, VectorMemory, VectorFilter, Message } from '@agentskit/core';
+export { PersonalizationProfile, PersonalizationStore, createInMemoryPersonalization, renderProfileContext } from './personalization.cjs';
+import { PIIRule, RedactionVault, RedactionAuditSink } from '@agentskit/core/security';
 
 /**
  * ChatMemory backed by a JSON file on disk. Node-only.
@@ -86,37 +88,6 @@ interface FileVectorMemoryConfig {
 }
 declare function fileVectorMemory(config: FileVectorMemoryConfig): VectorMemory;
 
-/**
- * Personalization — a persisted profile per subject (user id,
- * account id, device). The agent reads it on every run to
- * condition responses; the runtime updates it when new facts
- * appear.
- */
-interface PersonalizationProfile {
-    subjectId: string;
-    /** Human-editable notes, facts, preferences. */
-    traits: Record<string, unknown>;
-    /** ISO timestamp of the latest update. */
-    updatedAt: string;
-}
-interface PersonalizationStore {
-    get: (subjectId: string) => Promise<PersonalizationProfile | null>;
-    set: (profile: PersonalizationProfile) => Promise<void>;
-    merge: (subjectId: string, traits: Record<string, unknown>) => Promise<PersonalizationProfile>;
-    delete?: (subjectId: string) => Promise<void>;
-}
-/**
- * In-memory personalization store — tests, single-process demos.
- * Bring your own for production (Postgres, Redis, DynamoDB).
- */
-declare function createInMemoryPersonalization(): PersonalizationStore;
-/**
- * Render a profile into a system-prompt fragment the runtime can
- * prepend. Kept intentionally short — full profile dumps bloat
- * context and leak unnecessary detail to the model.
- */
-declare function renderProfileContext(profile: PersonalizationProfile | null): string;
-
 /**
  * Non-linear memory: a typed knowledge graph. Use for facts the
  * agent should remember beyond a single conversation — entities,
@@ -412,4 +383,106 @@ interface HierarchicalMemory extends ChatMemory {
  */
 declare function createHierarchicalMemory(options: HierarchicalMemoryOptions): HierarchicalMemory;
 
-export { type ChromaConfig, type EncryptedEnvelope, type EncryptedMemoryOptions, type FileVectorMemoryConfig, type GraphEdge, type GraphMemory, type GraphNode, type GraphQuery, type HierarchicalMemory, type HierarchicalMemoryOptions, type HierarchicalRecall, type MilvusConfig, type MongoAtlasVectorConfig, type MongoCollectionLike, type PersonalizationProfile, type PersonalizationStore, type PgVectorConfig, type PgVectorRunner, type PineconeConfig, type QdrantConfig, type RedisChatMemoryConfig, type RedisClientAdapter, type RedisConnectionConfig, type RedisVectorMemoryConfig, type SqliteChatMemoryConfig, type SupabaseVectorStoreConfig, type TursoChatMemoryConfig, type UpstashVectorConfig, type VectorStore, type VectorStoreDocument, type VectorStoreResult, type WeaviateConfig, chroma, createEncryptedMemory, createHierarchicalMemory, createInMemoryGraph, createInMemoryPersonalization, fileChatMemory, fileVectorMemory, matchesFilter, milvusVectorStore, mongoAtlasVectorStore, pgvector, pinecone, qdrant, redisChatMemory, redisVectorMemory, renderProfileContext, sqliteChatMemory, supabaseVectorStore, tursoChatMemory, upstashVector, weaviateVectorStore };
+/**
+ * GDPR / LGPD / CCPA data-subject deletion. ADR-0003 deferred
+ * retention; this module is the "forget the user" half.
+ *
+ * Design: rather than mutate every memory contract (and break the
+ * public API freeze, RFC-0007), we attach `forgetSubject` as a
+ * **capability** on a memory instance. Backends that can implement it
+ * declare a `subjectFilter` (how to recognise records belonging to a
+ * subject) and `deleteFn` (how to remove them). `forgetSubject(memory,
+ * subjectId)` walks every backend the runtime is configured with and
+ * runs the deletion, returning a per-backend report you can sign into
+ * the audit log (#162).
+ *
+ * Closes issue #798.
+ */
+interface ForgettableMemory {
+    /**
+     * Backend identifier (`'pgvector'`, `'pinecone'`, `'sqlite'`, etc.).
+     * Used for the audit-log entry and for the per-backend report.
+     */
+    __agentskitBackend: string;
+    /** Delete every record where `metadata.subjectId === subjectId`. */
+    forgetSubject: (subjectId: string) => Promise<ForgetReport>;
+}
+interface ForgetReport {
+    backend: string;
+    deletedCount: number;
+    /** ISO timestamp of the deletion. */
+    at: string;
+    /** Records the deletion couldn't reach (offline replica, missing index). */
+    failures?: Array<{
+        id: string;
+        reason: string;
+    }>;
+}
+interface ForgetSubjectResult {
+    subjectId: string;
+    reports: ForgetReport[];
+    totalDeleted: number;
+    /** Hash you can sign into the audit log to prove the deletion ran. */
+    evidenceHash: string;
+}
+/**
+ * Walk every memory passed in and run `forgetSubject(subjectId)` on
+ * any that implement it. Memories that don't implement it are
+ * silently skipped — they hold no subject-scoped data, or you must
+ * delete out-of-band (e.g. log retention).
+ */
+declare function forgetSubject(memories: Array<ChatMemory | VectorMemory | unknown>, subjectId: string): Promise<ForgetSubjectResult>;
+/**
+ * Helper for backends that key records by `metadata.subjectId`. Wraps
+ * any `delete(ids)`-style API into a `ForgettableMemory`.
+ */
+declare function makeForgettable<M extends object>(memory: M, options: {
+    backend: string;
+    listIds: (subjectId: string) => Promise<string[]>;
+    deleteIds: (ids: string[]) => Promise<void>;
+}): M & ForgettableMemory;
+
+/**
+ * Wrap any `ChatMemory` so PII is redacted (or tokenized) on every
+ * `save()`. Works with the in-memory, file, sqlite, turso, and redis
+ * chat memories. `load()` and `clear()` are passthrough — reveal
+ * happens at read time via `@agentskit/core/security` `reveal()`,
+ * not inside the memory.
+ *
+ * `mode: 'redact'` (default) replaces matches with the rules' bracket
+ * markers — irreversible. `mode: 'tokenize'` replaces matches with
+ * opaque `<<piitoken:…>>` markers and stores originals in the vault
+ * so role-gated `reveal()` can recover them.
+ *
+ * Closes the memory-write half of issue #791.
+ */
+type RedactionMode = 'redact' | 'tokenize';
+interface ChatMemoryRedactionOptions {
+    /**
+     * Rules to apply. Pass `DEFAULT_PII_RULES` for the baseline set,
+     * `compilePIITaxonomy(json)` for a custom JSON taxonomy, or any
+     * hand-rolled `PIIRule[]`. Same shape as `createPIIRedactor`.
+     */
+    rules: PIIRule[];
+    mode?: RedactionMode;
+    /** Required when `mode === 'tokenize'`. */
+    vault?: RedactionVault;
+    /** Roles allowed to reveal — required when `mode === 'tokenize'`. */
+    allowedRoles?: string[];
+    /** Optional audit sink threaded into the vault `tokenize()` calls. */
+    audit?: RedactionAuditSink;
+}
+interface VectorMemoryRedactionOptions extends ChatMemoryRedactionOptions {
+}
+declare function wrapChatMemoryWithRedaction(inner: ChatMemory, options: ChatMemoryRedactionOptions): ChatMemory;
+/**
+ * Wrap any `VectorMemory` so each document's `content` is redacted (or
+ * tokenized) before `store()`. `search()` and `delete()` pass through.
+ *
+ * Note: embeddings pass through verbatim. Customers who embed
+ * plaintext PII separately (e.g. via a hosted embedding provider)
+ * must redact the input to their embedder, not just to this wrapper.
+ */
+declare function wrapVectorMemoryWithRedaction(inner: VectorMemory, options: VectorMemoryRedactionOptions): VectorMemory;
+
+export { type ChatMemoryRedactionOptions, type ChromaConfig, type EncryptedEnvelope, type EncryptedMemoryOptions, type FileVectorMemoryConfig, type ForgetReport, type ForgetSubjectResult, type ForgettableMemory, type GraphEdge, type GraphMemory, type GraphNode, type GraphQuery, type HierarchicalMemory, type HierarchicalMemoryOptions, type HierarchicalRecall, type MilvusConfig, type MongoAtlasVectorConfig, type MongoCollectionLike, type PgVectorConfig, type PgVectorRunner, type PineconeConfig, type QdrantConfig, type RedactionMode, type RedisChatMemoryConfig, type RedisClientAdapter, type RedisConnectionConfig, type RedisVectorMemoryConfig, type SqliteChatMemoryConfig, type SupabaseVectorStoreConfig, type TursoChatMemoryConfig, type UpstashVectorConfig, type VectorMemoryRedactionOptions, type VectorStore, type VectorStoreDocument, type VectorStoreResult, type WeaviateConfig, chroma, createEncryptedMemory, createHierarchicalMemory, createInMemoryGraph, fileChatMemory, fileVectorMemory, forgetSubject, makeForgettable, matchesFilter, milvusVectorStore, mongoAtlasVectorStore, pgvector, pinecone, qdrant, redisChatMemory, redisVectorMemory, sqliteChatMemory, supabaseVectorStore, tursoChatMemory, upstashVector, weaviateVectorStore, wrapChatMemoryWithRedaction, wrapVectorMemoryWithRedaction };

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 import { ChatMemory, VectorMemory, VectorFilter, Message } from '@agentskit/core';
+export { PersonalizationProfile, PersonalizationStore, createInMemoryPersonalization, renderProfileContext } from './personalization.js';
+import { PIIRule, RedactionVault, RedactionAuditSink } from '@agentskit/core/security';
 
 /**
  * ChatMemory backed by a JSON file on disk. Node-only.
@@ -86,37 +88,6 @@ interface FileVectorMemoryConfig {
 }
 declare function fileVectorMemory(config: FileVectorMemoryConfig): VectorMemory;
 
-/**
- * Personalization — a persisted profile per subject (user id,
- * account id, device). The agent reads it on every run to
- * condition responses; the runtime updates it when new facts
- * appear.
- */
-interface PersonalizationProfile {
-    subjectId: string;
-    /** Human-editable notes, facts, preferences. */
-    traits: Record<string, unknown>;
-    /** ISO timestamp of the latest update. */
-    updatedAt: string;
-}
-interface PersonalizationStore {
-    get: (subjectId: string) => Promise<PersonalizationProfile | null>;
-    set: (profile: PersonalizationProfile) => Promise<void>;
-    merge: (subjectId: string, traits: Record<string, unknown>) => Promise<PersonalizationProfile>;
-    delete?: (subjectId: string) => Promise<void>;
-}
-/**
- * In-memory personalization store — tests, single-process demos.
- * Bring your own for production (Postgres, Redis, DynamoDB).
- */
-declare function createInMemoryPersonalization(): PersonalizationStore;
-/**
- * Render a profile into a system-prompt fragment the runtime can
- * prepend. Kept intentionally short — full profile dumps bloat
- * context and leak unnecessary detail to the model.
- */
-declare function renderProfileContext(profile: PersonalizationProfile | null): string;
-
 /**
  * Non-linear memory: a typed knowledge graph. Use for facts the
  * agent should remember beyond a single conversation — entities,
@@ -412,4 +383,106 @@ interface HierarchicalMemory extends ChatMemory {
  */
 declare function createHierarchicalMemory(options: HierarchicalMemoryOptions): HierarchicalMemory;
 
-export { type ChromaConfig, type EncryptedEnvelope, type EncryptedMemoryOptions, type FileVectorMemoryConfig, type GraphEdge, type GraphMemory, type GraphNode, type GraphQuery, type HierarchicalMemory, type HierarchicalMemoryOptions, type HierarchicalRecall, type MilvusConfig, type MongoAtlasVectorConfig, type MongoCollectionLike, type PersonalizationProfile, type PersonalizationStore, type PgVectorConfig, type PgVectorRunner, type PineconeConfig, type QdrantConfig, type RedisChatMemoryConfig, type RedisClientAdapter, type RedisConnectionConfig, type RedisVectorMemoryConfig, type SqliteChatMemoryConfig, type SupabaseVectorStoreConfig, type TursoChatMemoryConfig, type UpstashVectorConfig, type VectorStore, type VectorStoreDocument, type VectorStoreResult, type WeaviateConfig, chroma, createEncryptedMemory, createHierarchicalMemory, createInMemoryGraph, createInMemoryPersonalization, fileChatMemory, fileVectorMemory, matchesFilter, milvusVectorStore, mongoAtlasVectorStore, pgvector, pinecone, qdrant, redisChatMemory, redisVectorMemory, renderProfileContext, sqliteChatMemory, supabaseVectorStore, tursoChatMemory, upstashVector, weaviateVectorStore };
+/**
+ * GDPR / LGPD / CCPA data-subject deletion. ADR-0003 deferred
+ * retention; this module is the "forget the user" half.
+ *
+ * Design: rather than mutate every memory contract (and break the
+ * public API freeze, RFC-0007), we attach `forgetSubject` as a
+ * **capability** on a memory instance. Backends that can implement it
+ * declare a `subjectFilter` (how to recognise records belonging to a
+ * subject) and `deleteFn` (how to remove them). `forgetSubject(memory,
+ * subjectId)` walks every backend the runtime is configured with and
+ * runs the deletion, returning a per-backend report you can sign into
+ * the audit log (#162).
+ *
+ * Closes issue #798.
+ */
+interface ForgettableMemory {
+    /**
+     * Backend identifier (`'pgvector'`, `'pinecone'`, `'sqlite'`, etc.).
+     * Used for the audit-log entry and for the per-backend report.
+     */
+    __agentskitBackend: string;
+    /** Delete every record where `metadata.subjectId === subjectId`. */
+    forgetSubject: (subjectId: string) => Promise<ForgetReport>;
+}
+interface ForgetReport {
+    backend: string;
+    deletedCount: number;
+    /** ISO timestamp of the deletion. */
+    at: string;
+    /** Records the deletion couldn't reach (offline replica, missing index). */
+    failures?: Array<{
+        id: string;
+        reason: string;
+    }>;
+}
+interface ForgetSubjectResult {
+    subjectId: string;
+    reports: ForgetReport[];
+    totalDeleted: number;
+    /** Hash you can sign into the audit log to prove the deletion ran. */
+    evidenceHash: string;
+}
+/**
+ * Walk every memory passed in and run `forgetSubject(subjectId)` on
+ * any that implement it. Memories that don't implement it are
+ * silently skipped — they hold no subject-scoped data, or you must
+ * delete out-of-band (e.g. log retention).
+ */
+declare function forgetSubject(memories: Array<ChatMemory | VectorMemory | unknown>, subjectId: string): Promise<ForgetSubjectResult>;
+/**
+ * Helper for backends that key records by `metadata.subjectId`. Wraps
+ * any `delete(ids)`-style API into a `ForgettableMemory`.
+ */
+declare function makeForgettable<M extends object>(memory: M, options: {
+    backend: string;
+    listIds: (subjectId: string) => Promise<string[]>;
+    deleteIds: (ids: string[]) => Promise<void>;
+}): M & ForgettableMemory;
+
+/**
+ * Wrap any `ChatMemory` so PII is redacted (or tokenized) on every
+ * `save()`. Works with the in-memory, file, sqlite, turso, and redis
+ * chat memories. `load()` and `clear()` are passthrough — reveal
+ * happens at read time via `@agentskit/core/security` `reveal()`,
+ * not inside the memory.
+ *
+ * `mode: 'redact'` (default) replaces matches with the rules' bracket
+ * markers — irreversible. `mode: 'tokenize'` replaces matches with
+ * opaque `<<piitoken:…>>` markers and stores originals in the vault
+ * so role-gated `reveal()` can recover them.
+ *
+ * Closes the memory-write half of issue #791.
+ */
+type RedactionMode = 'redact' | 'tokenize';
+interface ChatMemoryRedactionOptions {
+    /**
+     * Rules to apply. Pass `DEFAULT_PII_RULES` for the baseline set,
+     * `compilePIITaxonomy(json)` for a custom JSON taxonomy, or any
+     * hand-rolled `PIIRule[]`. Same shape as `createPIIRedactor`.
+     */
+    rules: PIIRule[];
+    mode?: RedactionMode;
+    /** Required when `mode === 'tokenize'`. */
+    vault?: RedactionVault;
+    /** Roles allowed to reveal — required when `mode === 'tokenize'`. */
+    allowedRoles?: string[];
+    /** Optional audit sink threaded into the vault `tokenize()` calls. */
+    audit?: RedactionAuditSink;
+}
+interface VectorMemoryRedactionOptions extends ChatMemoryRedactionOptions {
+}
+declare function wrapChatMemoryWithRedaction(inner: ChatMemory, options: ChatMemoryRedactionOptions): ChatMemory;
+/**
+ * Wrap any `VectorMemory` so each document's `content` is redacted (or
+ * tokenized) before `store()`. `search()` and `delete()` pass through.
+ *
+ * Note: embeddings pass through verbatim. Customers who embed
+ * plaintext PII separately (e.g. via a hosted embedding provider)
+ * must redact the input to their embedder, not just to this wrapper.
+ */
+declare function wrapVectorMemoryWithRedaction(inner: VectorMemory, options: VectorMemoryRedactionOptions): VectorMemory;
+
+export { type ChatMemoryRedactionOptions, type ChromaConfig, type EncryptedEnvelope, type EncryptedMemoryOptions, type FileVectorMemoryConfig, type ForgetReport, type ForgetSubjectResult, type ForgettableMemory, type GraphEdge, type GraphMemory, type GraphNode, type GraphQuery, type HierarchicalMemory, type HierarchicalMemoryOptions, type HierarchicalRecall, type MilvusConfig, type MongoAtlasVectorConfig, type MongoCollectionLike, type PgVectorConfig, type PgVectorRunner, type PineconeConfig, type QdrantConfig, type RedactionMode, type RedisChatMemoryConfig, type RedisClientAdapter, type RedisConnectionConfig, type RedisVectorMemoryConfig, type SqliteChatMemoryConfig, type SupabaseVectorStoreConfig, type TursoChatMemoryConfig, type UpstashVectorConfig, type VectorMemoryRedactionOptions, type VectorStore, type VectorStoreDocument, type VectorStoreResult, type WeaviateConfig, chroma, createEncryptedMemory, createHierarchicalMemory, createInMemoryGraph, fileChatMemory, fileVectorMemory, forgetSubject, makeForgettable, matchesFilter, milvusVectorStore, mongoAtlasVectorStore, pgvector, pinecone, qdrant, redisChatMemory, redisVectorMemory, sqliteChatMemory, supabaseVectorStore, tursoChatMemory, upstashVector, weaviateVectorStore, wrapChatMemoryWithRedaction, wrapVectorMemoryWithRedaction };