@agentskit/memory 0.5.4 → 0.6.1

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ChatMemory, VectorMemory } from '@agentskit/core';
+import { ChatMemory, VectorMemory, Message } from '@agentskit/core';
 
 /**
  * ChatMemory backed by a JSON file on disk. Node-only.
@@ -70,4 +70,241 @@ interface FileVectorMemoryConfig {
 }
 declare function fileVectorMemory(config: FileVectorMemoryConfig): VectorMemory;
 
-export { type FileVectorMemoryConfig, type RedisChatMemoryConfig, type RedisClientAdapter, type RedisConnectionConfig, type RedisVectorMemoryConfig, type SqliteChatMemoryConfig, type VectorStore, type VectorStoreDocument, type VectorStoreResult, fileChatMemory, fileVectorMemory, redisChatMemory, redisVectorMemory, sqliteChatMemory };
+/**
+ * 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,
+ * relationships, derived beliefs. Designed to be backed by anything
+ * from an in-memory Map (tests, demos) to Neo4j / Memgraph / Neptune.
+ */
+interface GraphNode<TProps = Record<string, unknown>> {
+    id: string;
+    /** Type / label — 'person', 'company', 'topic'. */
+    kind: string;
+    properties?: TProps;
+    /** ISO timestamp when the node was first inserted. */
+    createdAt?: string;
+    /** ISO timestamp of the latest update. */
+    updatedAt?: string;
+}
+interface GraphEdge<TProps = Record<string, unknown>> {
+    id: string;
+    /** Verb / relation type — 'knows', 'works-at', 'cites'. */
+    label: string;
+    from: string;
+    to: string;
+    /** Optional weight — confidence, recency, or frequency. */
+    weight?: number;
+    properties?: TProps;
+}
+interface GraphQuery {
+    kind?: string;
+    label?: string;
+    from?: string;
+    to?: string;
+}
+interface GraphMemory {
+    upsertNode: <T>(node: GraphNode<T>) => Promise<GraphNode<T>>;
+    upsertEdge: <T>(edge: GraphEdge<T>) => Promise<GraphEdge<T>>;
+    getNode: <T>(id: string) => Promise<GraphNode<T> | null>;
+    findNodes: <T>(query?: GraphQuery) => Promise<GraphNode<T>[]>;
+    findEdges: <T>(query?: GraphQuery) => Promise<GraphEdge<T>[]>;
+    /** Breadth-first neighbors of `id` up to `depth`. Default 1. */
+    neighbors: <T>(id: string, options?: {
+        depth?: number;
+        label?: string;
+    }) => Promise<GraphNode<T>[]>;
+    deleteNode: (id: string) => Promise<void>;
+    deleteEdge: (id: string) => Promise<void>;
+    clear?: () => Promise<void>;
+}
+/**
+ * In-memory graph — fine for tests, single-process demos, and as
+ * reference for what a backing store needs to implement.
+ */
+declare function createInMemoryGraph(): GraphMemory;
+
+/**
+ * pgvector-backed VectorMemory. We accept a minimal async SQL runner
+ * so the caller picks the driver (`pg`, `postgres`, `@neondatabase/serverless`,
+ * `@supabase/postgres-js`, ...). Expects a table with columns
+ * `id text primary key`, `content text`, `embedding vector(N)`,
+ * `metadata jsonb`.
+ */
+interface PgVectorRunner {
+    query: <T = Record<string, unknown>>(sql: string, params: unknown[]) => Promise<{
+        rows: T[];
+    }>;
+}
+interface PgVectorConfig {
+    runner: PgVectorRunner;
+    /** Table name. Default 'agentskit_vectors'. */
+    table?: string;
+    /** Default topK for search. Default 10. */
+    topK?: number;
+}
+declare function pgvector(config: PgVectorConfig): VectorMemory;
+
+interface PineconeConfig {
+    /** Full index URL, e.g. `https://<idx>-<project>.svc.<region>.pinecone.io`. */
+    indexUrl: string;
+    apiKey: string;
+    /** Namespace. Default ''. */
+    namespace?: string;
+    /** Default topK for search. Default 10. */
+    topK?: number;
+    fetch?: typeof globalThis.fetch;
+}
+declare function pinecone(config: PineconeConfig): VectorMemory;
+
+interface QdrantConfig {
+    /** Base URL, e.g. `https://xxx.cluster-qdrant.io`. */
+    url: string;
+    apiKey?: string;
+    collection: string;
+    topK?: number;
+    fetch?: typeof globalThis.fetch;
+}
+declare function qdrant(config: QdrantConfig): VectorMemory;
+
+interface ChromaConfig {
+    /** Base URL of a running Chroma HTTP server. */
+    url: string;
+    collection: string;
+    topK?: number;
+    fetch?: typeof globalThis.fetch;
+}
+declare function chroma(config: ChromaConfig): VectorMemory;
+
+interface UpstashVectorConfig {
+    url: string;
+    token: string;
+    topK?: number;
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * Upstash Vector — HTTP-only serverless vector DB. The REST surface
+ * is tiny enough to implement directly without pulling the SDK.
+ */
+declare function upstashVector(config: UpstashVectorConfig): VectorMemory;
+
+/**
+ * Client-side encrypted ChatMemory wrapper. Keys never leave the
+ * caller — the backing store only ever sees an opaque
+ * `{ iv, ct }` payload stashed in `metadata.ciphertext` and
+ * `metadata.iv`; `content` becomes an empty string so rogue
+ * middleware can't peek at it either.
+ *
+ * Uses Web Crypto (AES-GCM, 256-bit). Available on Node 20+ and all
+ * modern browsers. BYO key material — typically generated per-user
+ * during onboarding and stored only on their device.
+ */
+interface EncryptedMemoryOptions {
+    backing: ChatMemory;
+    /** 32-byte raw key (e.g. `crypto.getRandomValues(new Uint8Array(32))`). */
+    key: Uint8Array | CryptoKey;
+    /** Override for tests. Defaults to `globalThis.crypto.subtle`. */
+    subtle?: SubtleCrypto;
+    /** Random source. Defaults to `globalThis.crypto.getRandomValues`. */
+    getRandomValues?: <T extends ArrayBufferView>(array: T) => T;
+    /** Optional AAD — content that binds ciphertext to context (user id, room). */
+    aad?: Uint8Array;
+}
+interface EncryptedEnvelope {
+    ciphertext: string;
+    iv: string;
+    /** Plaintext-length marker so the agent sees a non-empty content hint. */
+    length: number;
+}
+declare function createEncryptedMemory(options: EncryptedMemoryOptions): Promise<ChatMemory>;
+
+interface HierarchicalRecall {
+    /**
+     * Index a message for later retrieval. Called once per message as
+     * it moves from working → recall (usually: embed + store in a
+     * vector DB).
+     */
+    index: (message: Message) => void | Promise<void>;
+    /**
+     * Given the hot working window, return up to `topK` messages from
+     * the recall tier that are relevant to the current turn. The hub
+     * splices results chronologically alongside the working window.
+     */
+    query: (input: {
+        working: Message[];
+        topK: number;
+    }) => Message[] | Promise<Message[]>;
+}
+interface HierarchicalMemoryOptions {
+    /** Hot window — the messages always loaded in full. */
+    working: ChatMemory;
+    /** Cold storage — every message ever seen is written here. */
+    archival: ChatMemory;
+    /**
+     * Mid-term recall layer (usually a vector store). Optional;
+     * without it the hub behaves like virtualized memory with a hard
+     * backing store.
+     */
+    recall?: HierarchicalRecall;
+    /**
+     * Maximum messages to keep in `working`. Older messages spill
+     * into recall + archival. Default 50.
+     */
+    workingLimit?: number;
+    /**
+     * Max recalled messages to splice on each `load()`. Default 5.
+     */
+    recallTopK?: number;
+}
+interface HierarchicalMemory extends ChatMemory {
+    /** Full archival history. Always the source of truth. */
+    archival: () => Promise<Message[]>;
+    /** Current working-window snapshot. */
+    working: () => Promise<Message[]>;
+}
+/**
+ * MemGPT-style tiered memory. Three tiers:
+ *   - working: always-loaded hot window (bounded by `workingLimit`).
+ *   - recall: mid-term searchable layer (usually a vector store).
+ *   - archival: cold store that always holds the full conversation.
+ *
+ * On every `save`, new messages are appended to archival, messages
+ * that overflow the working window are indexed into recall, and the
+ * working tier is trimmed to `workingLimit`.
+ *
+ * On every `load`, the hub returns working + up to `recallTopK`
+ * messages surfaced by the recall tier, spliced chronologically.
+ */
+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 PersonalizationProfile, type PersonalizationStore, type PgVectorConfig, type PgVectorRunner, type PineconeConfig, type QdrantConfig, type RedisChatMemoryConfig, type RedisClientAdapter, type RedisConnectionConfig, type RedisVectorMemoryConfig, type SqliteChatMemoryConfig, type UpstashVectorConfig, type VectorStore, type VectorStoreDocument, type VectorStoreResult, chroma, createEncryptedMemory, createHierarchicalMemory, createInMemoryGraph, createInMemoryPersonalization, fileChatMemory, fileVectorMemory, pgvector, pinecone, qdrant, redisChatMemory, redisVectorMemory, renderProfileContext, sqliteChatMemory, upstashVector };