@memstack/core 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,536 @@
+type MemoryType = "interaction" | "summary" | "observation" | "gossip";
+interface Memory {
+    id: string;
+    actorId: string;
+    memoryType: MemoryType;
+    content: string;
+    importance: number;
+    emotionalValence: number;
+    tags: string[];
+    embedding?: number[];
+    sourceId?: string;
+    metadata?: Record<string, unknown>;
+    expiresAt?: Date;
+    createdAt: Date;
+}
+interface CompiledContext {
+    systemPrompt: string;
+    recentMemories: Memory[];
+    importantMemories: Memory[];
+    tokenEstimate: number;
+}
+interface ProcessResult {
+    memory: Memory;
+    summaryCreated?: Memory;
+}
+interface MemStackSnapshot {
+    version: 1;
+    memories: Memory[];
+    exportedAt: string;
+}
+interface HealthStatus {
+    storage: boolean;
+    llm: boolean;
+    embedding: boolean;
+}
+
+interface MemoryStoreInput {
+    actorId: string;
+    content: string;
+    memoryType?: MemoryType;
+    importance?: number;
+    emotionalValence?: number;
+    tags?: string[];
+    embedding?: number[];
+    sourceId?: string;
+    metadata?: Record<string, unknown>;
+    expiresAt?: Date;
+    onConflict?: "append";
+    /** Pre-assigned ID. When set, the storage adapter uses it instead of generating one. */
+    id?: string;
+}
+interface MemoryCountFilter {
+    actorId?: string;
+    memoryType?: MemoryType;
+    minImportance?: number;
+}
+interface MemoryRetrieveQuery {
+    actorId?: string;
+    query?: string;
+    memoryTypes?: MemoryType[];
+    tags?: string[];
+    limit?: number;
+    strategy?: "semantic" | "hybrid" | "recent" | "important";
+}
+interface ContextOptions {
+    actorId: string;
+    maxTokens?: number;
+    memoryTypes?: MemoryType[];
+}
+interface SummarizeOptions {
+    actorId?: string;
+    olderThan?: Date;
+    skipMostRecent?: number;
+    targetCount?: number;
+    memoryTypes?: MemoryType[];
+    keepOriginals?: boolean;
+}
+interface PruneStrategy {
+    type: "byAge" | "byImportance" | "byCount" | "byType" | "custom";
+    maxAge?: number;
+    minImportance?: number;
+    maxPerActor?: number;
+    memoryTypes?: MemoryType[];
+    /** Custom predicate: return true for memories that should be REMOVED. */
+    shouldRemove?: (memory: Memory) => boolean;
+}
+interface LLMProvider {
+    complete(request: {
+        system: string;
+        user: string;
+        model?: string;
+        temperature?: number;
+        maxTokens?: number;
+    }): Promise<{
+        text: string;
+        tokens: {
+            prompt: number;
+            completion: number;
+            total: number;
+        };
+    }>;
+    /** Optional streaming variant. Returns an async iterable of text chunks. */
+    completeStream?(request: {
+        system: string;
+        user: string;
+        model?: string;
+        temperature?: number;
+        maxTokens?: number;
+    }): AsyncIterable<{
+        text: string;
+        tokens: {
+            prompt: number;
+            completion: number;
+            total: number;
+        };
+    }>;
+}
+interface EmbeddingProvider {
+    embed(texts: string[]): Promise<number[][]>;
+    dimensions: number;
+}
+interface StorageProvider {
+    initialize(): Promise<void>;
+    store(memory: MemoryStoreInput): Promise<Memory>;
+    storeBatch(memories: MemoryStoreInput[]): Promise<Memory[]>;
+    get(id: string): Promise<Memory | null>;
+    delete(id: string): Promise<void>;
+    deleteMany(ids: string[]): Promise<number>;
+    /** Update the last-accessed timestamp for a memory without changing its content, id, or createdAt. */
+    touch?(id: string): Promise<void>;
+    retrieve(query: MemoryRetrieveQuery, embedding?: number[]): Promise<Memory[]>;
+    count(filter?: MemoryCountFilter): Promise<number>;
+    close(): Promise<void>;
+}
+interface MemStackConfig {
+    llm: LLMProvider;
+    embedding?: EmbeddingProvider;
+    storage?: StorageProvider;
+    defaults?: {
+        summarizationThreshold?: number;
+        embedOnStore?: boolean;
+        pruneStrategy?: PruneStrategy;
+        pruneInterval?: number;
+        autoImportance?: boolean;
+        autoTags?: boolean;
+        summarizationPrompt?: string;
+    };
+    hooks?: {
+        onMemoryStored?: (memory: Memory) => void;
+        onMemoryPruned?: (ids: string[]) => void;
+        onSummaryCreated?: (summary: Memory, deletedCount: number) => void;
+        onError?: (error: Error, context: string) => void;
+    };
+}
+interface ProcessInput {
+    actorId: string;
+    content: string;
+    memoryType?: MemoryType;
+    importance?: number;
+    emotionalValence?: number;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+    expiresAt?: Date;
+    onConflict?: "append";
+}
+
+interface MemoryStoreConfig {
+    storage: StorageProvider;
+    embedding?: EmbeddingProvider;
+    llm?: LLMProvider;
+    embedOnStore?: boolean;
+    summarizationPrompt?: string;
+}
+declare class MemoryStore {
+    private storage;
+    private embedding?;
+    private summarizer?;
+    private pruner;
+    private compiler;
+    private embedOnStore;
+    constructor(config: MemoryStoreConfig);
+    store(input: MemoryStoreInput): Promise<Memory>;
+    storeBatch(inputs: MemoryStoreInput[]): Promise<Memory[]>;
+    get(id: string): Promise<Memory | null>;
+    delete(id: string): Promise<void>;
+    deleteMany(ids: string[]): Promise<number>;
+    touch(id: string): Promise<void>;
+    count(filter?: MemoryCountFilter): Promise<number>;
+    retrieve(query: MemoryRetrieveQuery): Promise<Memory[]>;
+    compileContext(options: ContextOptions): Promise<CompiledContext>;
+    summarize(options: SummarizeOptions, onError?: (err: Error) => void): Promise<{
+        summary: Memory;
+        deletedCount: number;
+    }>;
+    prune(strategy: PruneStrategy): Promise<{
+        pruned: string[];
+        count: number;
+    }>;
+    dryRunPrune(strategy: PruneStrategy): Promise<{
+        wouldPrune: string[];
+        count: number;
+    }>;
+    export(): Promise<Memory[]>;
+    private _hashContent;
+}
+
+declare class MemStack {
+    readonly memory: MemoryStore;
+    private config;
+    private storage;
+    private processCount;
+    constructor(config: MemStackConfig);
+    process(input: ProcessInput): Promise<ProcessResult>;
+    export(): Promise<MemStackSnapshot>;
+    import(snapshot: MemStackSnapshot): Promise<void>;
+    health(): Promise<HealthStatus>;
+    close(): Promise<void>;
+    private _parseEnrichmentJson;
+    private _parseTagsJson;
+    /** Strip markdown code fences and extract the JSON payload from LLM output. */
+    private _extractJson;
+}
+
+type MemStackErrorCode = "STORAGE_ERROR" | "EMBEDDING_ERROR" | "LLM_ERROR" | "VALIDATION_ERROR" | "NOT_FOUND" | "CONFIG_ERROR";
+declare class MemStackError extends Error {
+    code: MemStackErrorCode;
+    retryable: boolean;
+    details?: Record<string, unknown>;
+    constructor(code: MemStackErrorCode, message: string, options?: {
+        retryable?: boolean;
+        details?: Record<string, unknown>;
+    });
+}
+declare function notFound(entity: string, id: string): MemStackError;
+declare function validationError(message: string, details?: Record<string, unknown>): MemStackError;
+declare function storageError(message: string, cause?: unknown): MemStackError;
+declare function configError(message: string): MemStackError;
+
+declare class InMemoryStorage implements StorageProvider {
+    private memories;
+    initialize(): Promise<void>;
+    generateId(): string;
+    store(input: MemoryStoreInput): Promise<Memory>;
+    storeBatch(inputs: MemoryStoreInput[]): Promise<Memory[]>;
+    get(id: string): Promise<Memory | null>;
+    delete(id: string): Promise<void>;
+    deleteMany(ids: string[]): Promise<number>;
+    retrieve(query: MemoryRetrieveQuery, _embedding?: number[]): Promise<Memory[]>;
+    count(filter?: MemoryCountFilter): Promise<number>;
+    touch(id: string): Promise<void>;
+    close(): Promise<void>;
+    getAllMemories(): Memory[];
+}
+
+interface DiskStorageConfig {
+    /** Directory to store memory files. Default: "./memstack-data" */
+    storageDir?: string;
+}
+declare class DiskStorage implements StorageProvider {
+    private dir;
+    private _writeLocks;
+    constructor(config?: DiskStorageConfig);
+    initialize(): Promise<void>;
+    generateId(): string;
+    store(input: MemoryStoreInput): Promise<Memory>;
+    storeBatch(inputs: MemoryStoreInput[]): Promise<Memory[]>;
+    get(id: string): Promise<Memory | null>;
+    delete(id: string): Promise<void>;
+    deleteMany(ids: string[]): Promise<number>;
+    retrieve(query: MemoryRetrieveQuery, _embedding?: number[]): Promise<Memory[]>;
+    count(filter?: MemoryCountFilter): Promise<number>;
+    touch(id: string): Promise<void>;
+    close(): Promise<void>;
+    private _filePath;
+    private _readFile;
+    private _writeFile;
+    private _withWriteLock;
+    private _listActors;
+    private _toExternal;
+}
+
+type RedisClient = {
+    set(key: string, value: string): Promise<unknown>;
+    get(key: string): Promise<string | null>;
+    mget(...keys: string[]): Promise<(string | null)[]>;
+    del(key: string | string[]): Promise<number>;
+    sadd(key: string, ...members: string[]): Promise<number>;
+    srem(key: string, ...members: string[]): Promise<number>;
+    smembers(key: string): Promise<string[]>;
+};
+interface RedisStorageConfig {
+    /** An active ioredis client instance (or compatible) */
+    redis: RedisClient;
+    /** Key prefix. Default: "memstack" */
+    keyPrefix?: string;
+}
+declare class RedisStorage implements StorageProvider {
+    private redis;
+    private prefix;
+    constructor(config: RedisStorageConfig);
+    initialize(): Promise<void>;
+    generateId(): string;
+    store(input: MemoryStoreInput): Promise<Memory>;
+    storeBatch(inputs: MemoryStoreInput[]): Promise<Memory[]>;
+    get(id: string): Promise<Memory | null>;
+    delete(id: string): Promise<void>;
+    deleteMany(ids: string[]): Promise<number>;
+    retrieve(query: MemoryRetrieveQuery, _embedding?: number[]): Promise<Memory[]>;
+    count(filter?: MemoryCountFilter): Promise<number>;
+    close(): Promise<void>;
+    private _actorsSetKey;
+    private _actorKey;
+    private _memKey;
+    private _getActorRecords;
+    private _listActors;
+    private _toExternal;
+}
+
+type PgPool = {
+    query(text: string, params?: unknown[]): Promise<{
+        rows: unknown[];
+    }>;
+};
+interface PostgresStorageConfig {
+    /** An active pg Pool instance */
+    pool: PgPool;
+    /** Table name. Default: "memstack_memories" */
+    tableName?: string;
+    /** Automatically run CREATE TABLE IF NOT EXISTS on init. Default: true */
+    autoMigrate?: boolean;
+}
+declare class PostgresStorage implements StorageProvider {
+    private pool;
+    private table;
+    private autoMigrate;
+    constructor(config: PostgresStorageConfig);
+    initialize(): Promise<void>;
+    generateId(): string;
+    store(input: MemoryStoreInput): Promise<Memory>;
+    storeBatch(inputs: MemoryStoreInput[]): Promise<Memory[]>;
+    get(id: string): Promise<Memory | null>;
+    delete(id: string): Promise<void>;
+    deleteMany(ids: string[]): Promise<number>;
+    retrieve(query: MemoryRetrieveQuery, embedding?: number[]): Promise<Memory[]>;
+    count(filter?: MemoryCountFilter): Promise<number>;
+    close(): Promise<void>;
+    private _semanticRetrieve;
+    private _rowToMemory;
+}
+
+interface OpenAILLMConfig {
+    apiKey: string;
+    baseURL?: string;
+    defaultModel?: string;
+    defaultTemperature?: number;
+    defaultMaxTokens?: number;
+}
+declare class OpenAILLMAdapter implements LLMProvider {
+    private apiKey;
+    private baseURL;
+    private defaultModel;
+    private defaultTemperature;
+    private defaultMaxTokens;
+    constructor(config: OpenAILLMConfig);
+    complete(request: {
+        system: string;
+        user: string;
+        model?: string;
+        temperature?: number;
+        maxTokens?: number;
+    }): Promise<{
+        text: string;
+        tokens: {
+            prompt: number;
+            completion: number;
+            total: number;
+        };
+    }>;
+    completeStream(request: {
+        system: string;
+        user: string;
+        model?: string;
+        temperature?: number;
+        maxTokens?: number;
+    }): AsyncIterable<{
+        text: string;
+        tokens: {
+            prompt: number;
+            completion: number;
+            total: number;
+        };
+    }>;
+}
+
+interface AnthropicLLMConfig {
+    apiKey: string;
+    baseURL?: string;
+    defaultModel?: string;
+    defaultMaxTokens?: number;
+}
+declare class AnthropicLLMAdapter implements LLMProvider {
+    private apiKey;
+    private baseURL;
+    private defaultModel;
+    private defaultMaxTokens;
+    private sdk;
+    constructor(config: AnthropicLLMConfig);
+    complete(request: {
+        system: string;
+        user: string;
+        model?: string;
+        temperature?: number;
+        maxTokens?: number;
+    }): Promise<{
+        text: string;
+        tokens: {
+            prompt: number;
+            completion: number;
+            total: number;
+        };
+    }>;
+}
+
+interface OpenAIEmbeddingConfig {
+    apiKey: string;
+    baseURL?: string;
+    model?: string;
+}
+declare class OpenAIEmbeddingAdapter implements EmbeddingProvider {
+    private apiKey;
+    private baseURL;
+    private model;
+    readonly dimensions: number;
+    constructor(config: OpenAIEmbeddingConfig);
+    embed(texts: string[]): Promise<number[][]>;
+}
+
+interface CohereEmbeddingConfig {
+    /** Cohere API key */
+    apiKey: string;
+    /** Model name. Default: "embed-english-v3.0" (1024 dims) */
+    model?: string;
+    /** Base URL. Default: "https://api.cohere.ai/v1" */
+    baseURL?: string;
+}
+declare class CohereEmbeddingAdapter implements EmbeddingProvider {
+    private apiKey;
+    private baseURL;
+    private model;
+    readonly dimensions: number;
+    constructor(config: CohereEmbeddingConfig);
+    embed(texts: string[]): Promise<number[][]>;
+}
+
+interface OllamaLLMConfig {
+    /** Ollama server URL. Default: "http://localhost:11434" */
+    baseURL?: string;
+    /** Default model name. Default: "llama3.2" */
+    defaultModel?: string;
+    /** Default temperature. Default: 0.7 */
+    defaultTemperature?: number;
+    /** Default max tokens. Default: 1024 */
+    defaultMaxTokens?: number;
+}
+declare class OllamaLLMAdapter implements LLMProvider {
+    private baseURL;
+    private defaultModel;
+    private defaultTemperature;
+    private defaultMaxTokens;
+    constructor(config?: OllamaLLMConfig);
+    complete(request: {
+        system: string;
+        user: string;
+        model?: string;
+        temperature?: number;
+        maxTokens?: number;
+    }): Promise<{
+        text: string;
+        tokens: {
+            prompt: number;
+            completion: number;
+            total: number;
+        };
+    }>;
+}
+
+interface GroqLLMConfig {
+    /** Groq API key */
+    apiKey: string;
+    /** Base URL. Default: "https://api.groq.com/openai/v1" */
+    baseURL?: string;
+    /** Default model. Default: "llama-3.3-70b-versatile" */
+    defaultModel?: string;
+    /** Default temperature. Default: 0.7 */
+    defaultTemperature?: number;
+    /** Default max tokens. Default: 1024 */
+    defaultMaxTokens?: number;
+}
+declare class GroqLLMAdapter implements LLMProvider {
+    private apiKey;
+    private baseURL;
+    private defaultModel;
+    private defaultTemperature;
+    private defaultMaxTokens;
+    constructor(config: GroqLLMConfig);
+    complete(request: {
+        system: string;
+        user: string;
+        model?: string;
+        temperature?: number;
+        maxTokens?: number;
+    }): Promise<{
+        text: string;
+        tokens: {
+            prompt: number;
+            completion: number;
+            total: number;
+        };
+    }>;
+    completeStream(request: {
+        system: string;
+        user: string;
+        model?: string;
+        temperature?: number;
+        maxTokens?: number;
+    }): AsyncIterable<{
+        text: string;
+        tokens: {
+            prompt: number;
+            completion: number;
+            total: number;
+        };
+    }>;
+}
+
+export { AnthropicLLMAdapter, type AnthropicLLMConfig, CohereEmbeddingAdapter, type CohereEmbeddingConfig, type CompiledContext, type ContextOptions, DiskStorage, type DiskStorageConfig, type EmbeddingProvider, GroqLLMAdapter, type GroqLLMConfig, type HealthStatus, InMemoryStorage, type LLMProvider, MemStack, type MemStackConfig, MemStackError, type MemStackErrorCode, type MemStackSnapshot, type Memory, type MemoryCountFilter, type MemoryRetrieveQuery, type MemoryStoreInput, type MemoryType, OllamaLLMAdapter, type OllamaLLMConfig, OpenAIEmbeddingAdapter, type OpenAIEmbeddingConfig, OpenAILLMAdapter, type OpenAILLMConfig, PostgresStorage, type PostgresStorageConfig, type ProcessInput, type ProcessResult, type PruneStrategy, RedisStorage, type RedisStorageConfig, type StorageProvider, type SummarizeOptions, configError, notFound, storageError, validationError };