/** * Memory adapter registry and factories. * * Port of `praisonaiagents/memory/adapters/registry.py`, * `memory/adapters/factories.py`, `memory/adapters/in_memory_adapter.py` and * the default registrations in `memory/adapters/__init__.py`. * * Backends: * - `in_memory` — {@link InMemoryAdapter}, ported. * - `chroma` — {@link ChromaMemory} over the existing * `integrations/vector/chroma.ts::ChromaVectorStore` (HTTP client). * - `sqlite`, `mem0`, `mongodb`, `dakera` — registered so the names resolve, * but their factories throw {@link BackendNotAvailableError} with an * explanatory message. Because the registry treats that error like * Python's `ImportError`, `getMemoryAdapter(name)` returns `null` for them * and preference lists fall through, exactly as Python does when the * optional dependency is missing. * * Python's registrations happen at import time; here they run lazily inside * {@link getDefaultMemoryRegistry} so importing the module has no side * effects (issue #4390). * * `safe_mem0_search` from `factories.py` is not ported: it patches a * mem0-specific upstream bug and has nothing to wrap without mem0. */ import { AdapterRegistry } from '../utils/adapter-registry'; import type { AdapterClass, AdapterFactory, AdapterKwargs } from '../utils/adapter-registry'; import { ChromaVectorStore } from '../integrations/vector/chroma'; import type { ChromaConfig } from '../integrations/vector/chroma'; export type MaybePromise = T | Promise; /** A stored memory entry as returned by search / list operations. */ export interface MemoryRecord { id: string; text: string; metadata: Record | null; score?: number; type?: string; [key: string]: unknown; } /** * Minimal contract for memory implementations * (Python `memory/protocols.py::MemoryProtocol`). Methods may be sync or * async because network-backed adapters (Chroma) cannot be synchronous in * JavaScript. */ export interface MemoryProtocol { storeShortTerm(text: string, metadata?: Record | null, kwargs?: AdapterKwargs): MaybePromise; searchShortTerm(query: string, limit?: number, kwargs?: AdapterKwargs): MaybePromise; storeLongTerm(text: string, metadata?: Record | null, kwargs?: AdapterKwargs): MaybePromise; searchLongTerm(query: string, limit?: number, kwargs?: AdapterKwargs): MaybePromise; getAllMemories(kwargs?: AdapterKwargs): MaybePromise; } /** * Registry for memory adapters (Python `MemoryAdapterRegistry`). */ export declare class MemoryAdapterRegistry extends AdapterRegistry { constructor(); } /** The default global registry, created (and populated) on first use (Python `get_default_memory_registry`). */ export declare function getDefaultMemoryRegistry(): MemoryAdapterRegistry; /** TypeScript-only test helper: drop the default registry so it is rebuilt on next use. */ export declare function resetDefaultMemoryRegistry(): void; /** Register a memory adapter class (Python `register_memory_adapter`). */ export declare function registerMemoryAdapter(name: string, adapterClass: AdapterClass): void; /** Register a memory adapter factory function (Python `register_memory_factory`). */ export declare function registerMemoryFactory(name: string, factoryFunc: AdapterFactory): void; /** Memory adapter instance by name, or `null` (Python `get_memory_adapter`). */ export declare function getMemoryAdapter(name: string, kwargs?: AdapterKwargs): MemoryProtocol | null; /** All registered memory adapter names, sorted (Python `list_memory_adapters`). */ export declare function listMemoryAdapters(): string[]; /** Canonical alias for {@link registerMemoryAdapter} (Python `add_memory_adapter`). */ export declare function addMemoryAdapter(name: string, adapterClass: AdapterClass): void; /** Canonical alias for {@link registerMemoryFactory} (Python `add_memory_factory`). */ export declare function addMemoryFactory(name: string, factoryFunc: AdapterFactory): void; /** True if an adapter or factory is registered under `name` (Python `has_memory_adapter`). */ export declare function hasMemoryAdapter(name: string): boolean; /** * Accepted spellings for a backend, mapped to the adapter that serves them * (Python `MEMORY_PROVIDER_ALIASES`). */ export declare const MEMORY_PROVIDER_ALIASES: Readonly>; /** Adapter name for `name`, or `null` if nothing is registered under it (Python `resolve_memory_adapter_name`). */ export declare function resolveMemoryAdapterName(name: string): string | null; /** * First available memory adapter from `preferences` (default * `["sqlite", "in_memory"]`), as `[name, instance]` or `null` * (Python `get_first_available_memory_adapter`). */ export declare function getFirstAvailableMemoryAdapter(preferences?: string[] | null, kwargs?: AdapterKwargs): [string, MemoryProtocol] | null; /** * Lightweight in-memory store for tests and development * (Python `InMemoryAdapter`). FIFO eviction above `maxSize` (default 10 000); * ids come from a monotonic counter so they never collide after eviction. */ export declare class InMemoryAdapter implements MemoryProtocol { private _data; private readonly _maxSize; private _nextId; constructor(kwargs?: AdapterKwargs); private _evictIfNeeded; private _store; private _search; storeShortTerm(text: string, metadata?: Record | null, kwargs?: AdapterKwargs): string; searchShortTerm(query: string, limit?: number, kwargs?: AdapterKwargs): MemoryRecord[]; storeLongTerm(text: string, metadata?: Record | null, kwargs?: AdapterKwargs): string; searchLongTerm(query: string, limit?: number, kwargs?: AdapterKwargs): MemoryRecord[]; /** Delete by id, optionally scoped to a tier (`"short"` | `"long"`); true if removed. */ deleteMemory(memoryId: string, tier?: string | null, kwargs?: AdapterKwargs): boolean; resetShortTerm(): void; resetLongTerm(): void; /** Defensive copies of every entry. */ getAllMemories(kwargs?: AdapterKwargs): MemoryRecord[]; } /** Sanitize metadata for Chroma: keep primitives, stringify the rest, drop null/undefined (Python `sanitize_chroma_metadata`). */ export declare function sanitizeChromaMetadata(metadata: Record): Record; /** Python `create_chroma_memory_adapter`: returns a {@link ChromaMemory}. */ export declare function createChromaMemoryAdapter(kwargs?: AdapterKwargs): MemoryProtocol; /** Python `create_mem0_memory_adapter`: mem0 has no TypeScript adapter yet. */ export declare function createMem0MemoryAdapter(kwargs?: AdapterKwargs): MemoryProtocol; /** Python `create_mongodb_memory_adapter`: MongoDB has no TypeScript adapter yet. */ export declare function createMongodbMemoryAdapter(kwargs?: AdapterKwargs): MemoryProtocol; /** Python `create_dakera_memory_adapter`: Dakera has no TypeScript adapter yet. */ export declare function createDakeraMemoryAdapter(kwargs?: AdapterKwargs): MemoryProtocol; /** * Python registers `SqliteMemoryAdapter` as a core class; the SQLite adapter * is not ported in this workstream, so the name resolves to `null` and * preference lists fall through to `in_memory`. */ export declare function createSqliteMemoryAdapter(kwargs?: AdapterKwargs): MemoryProtocol; /** Text → embedding vector. Defaults to `embeddings.embed(text, { model })`. */ export type MemoryEmbedder = (text: string, model: string) => MaybePromise; /** Configuration for {@link ChromaMemory}. Snake_case spellings from Python are accepted too. */ export interface ChromaMemoryConfig extends ChromaConfig { /** Python `rag_db_path`; accepted for parity — the TypeScript client talks HTTP, not a local directory. */ ragDbPath?: string; /** Collection (index) name. Default `"memory_store"`. */ collectionName?: string; /** Embedding model. Default `"text-embedding-3-small"`. */ embeddingModel?: string; /** Injectable vector store (defaults to a `ChromaVectorStore` built from `host`/`port`/`path`). */ store?: ChromaVectorStore; /** Injectable embedder (defaults to the `embeddings` module). */ embedder?: MemoryEmbedder; /** Injectable `fetch` for {@link ChromaMemory.getAllMemories}. Default `globalThis.fetch`. */ fetchImpl?: typeof fetch; [key: string]: unknown; } /** * Memory adapter over Chroma (Python `ChromaMemoryAdapter`), implemented on * the existing {@link ChromaVectorStore}. Short-term and long-term tiers * share one collection, exactly as in Python. * * Also exposes `add` / `search` aliases for callers that only want a plain * vector memory. */ export declare class ChromaMemory implements MemoryProtocol { readonly collectionName: string; readonly embeddingModel: string; readonly store: ChromaVectorStore; private readonly embedder; private readonly fetchImpl; private readonly baseUrl; private ready; constructor(config?: ChromaMemoryConfig); /** Get-or-create the collection once (Python `get_collection` / `create_collection`). */ private ensureCollection; private embedText; storeShortTerm(text: string, metadata?: Record | null, kwargs?: AdapterKwargs): Promise; searchShortTerm(query: string, limit?: number, kwargs?: AdapterKwargs): Promise; /** Store text with its embedding; resolves to the new id (Python `store_long_term`). */ storeLongTerm(text: string, metadata?: Record | null, kwargs?: AdapterKwargs): Promise; /** Vector-similarity search (Python `search_long_term`). */ searchLongTerm(query: string, limit?: number, kwargs?: AdapterKwargs): Promise; /** Alias for {@link storeLongTerm}. */ add(text: string, metadata?: Record | null, kwargs?: AdapterKwargs): Promise; /** Alias for {@link searchLongTerm}. */ search(query: string, limit?: number, kwargs?: AdapterKwargs): Promise; /** * Every stored memory (Python `get_all_memories`). `ChromaVectorStore` has * no list operation, so this calls Chroma's `collections//get` * endpoint directly. */ getAllMemories(kwargs?: AdapterKwargs): Promise; /** Drop and recreate the collection (Python `_reset_collection`). */ private resetCollection; resetShortTerm(): Promise; resetLongTerm(): Promise; /** No persistent client to close for the HTTP store (Python `close`). */ close(): void; }