agent-memory · packages

A class that provides a long-term memory layer for AI agents, combining LLM-powered extraction, semantic search, configurable storage (in-memory or PostgreSQL pgvector), and lifecycle management (decay, forgetting, contradiction resolution) into a single facade.

Canonical TypeScript types, enums, and utilities for the agent-memory ecosystem, providing the `Memory` data structure, lifecycle states, importance levels, contradiction strategies, and shared helpers like `cosineSimilarity` and `withRetry`. Exports interfaces, enums, and functions with zero runtime dependencies and dual ESM/CJS output.

An embedding provider abstraction that exposes a unified `EmbeddingProvider` interface with `embed()` and `embedBatch()` methods, shipping adapters for OpenAI, Cohere, and HuggingFace, plus an `InMemoryEmbeddingCache` with LRU eviction and TTL that wraps any provider via `CachedEmbeddingProvider`.

An event bus and typed event types for agent-memory lifecycle hooks, providing `InMemoryEventBus` (a class with `on`, `off`, `once`, and `emit` methods) and nine event type constants (`memory:stored`, `memory:retrieved`, etc.) for publishing and subscribing to memory creation, retrieval, contradiction, decay, and forgetting events.

An LLM-powered memory extraction engine that analyzes conversation turns to identify and classify memorable facts, preferences, decisions, and corrections, returning structured candidates with importance scores, confidence levels, and embeddings for semantic search. It provides a `MemoryExtractor` class that requires an `LLMProvider` and an `EmbeddingProvider` at runtime.

An `LLMProvider` interface and `OpenAILLMProvider` class that expose `complete()` for freeform text generation and `completeStructured<T>()` for JSON-schema-constrained structured output, designed for memory extraction and classification in agent systems.

A policy engine for memory lifecycle management that provides decay scoring, forgetting decisions, and contradiction resolution, exposed as a `PolicyEngine` class that composes `DecayEngine`, `ForgettingPolicy`, `ContradictionDetector`, and `ContradictionResolver` with pluggable rules.

A semantic memory retriever for LLM agents that combines embedding similarity with recency, importance, and topic diversification, exposing a `MemoryRetriever` class with pluggable ranking strategies and a `ContextInjector` for formatting results into prompts with token budgeting. Requires a memory storage backend and an embedding provider at runtime.

A `MemoryStorage` interface (class) with 14 methods for CRUD, batch operations, similarity search, metadata filtering, health checks, and backup/restore of agent memories, plus two implementations: a zero-dependency in-memory adapter for testing and a PostgreSQL pgvector adapter for production that requires the `pg` package.