Skip to content
reaatechREAATECH
Book a conversation

@reaatech/agent-memory

npm v0.1.0

Provides a unified interface for managing AI agent long-term memory, including automated fact extraction, semantic retrieval, and lifecycle policies. It exposes an `AgentMemory` class that integrates storage backends, embedding providers, and LLM-based extraction logic.

npm →source →

@reaatech/agent-memory

npm version License: MIT CI

Status: Pre-1.0 — APIs may change in minor versions. Pin to a specific version in production.

Long-term memory layer for AI agents. The @reaatech/agent-memory package is the main facade that wires together all component packages — extraction, storage, retrieval, policies, events, embedding, and LLM — into a single, batteries-included entry point.

Installation

terminal
npm install @reaatech/agent-memory
# or
pnpm add @reaatech/agent-memory

Feature Overview

  • LLM-powered extraction — automatically identify facts, preferences, and decisions from conversations
  • Semantic search — find relevant memories using embedding-based similarity
  • Configurable storage — swap between in-memory (dev/test) and PostgreSQL pgvector (production)
  • Lifecycle management — automatic decay, forgetting, and contradiction resolution
  • Event hooks — subscribe to memory lifecycle events for audit logging and metrics
  • Multi-provider embedding — OpenAI, Cohere, HuggingFace with transparent caching
  • Dual ESM/CJS output — works with import and require

Quick Start

typescript
import {
  AgentMemory,
  OpenAILLMProvider,
  MemoryType,
} from '@reaatech/agent-memory';
 
const memory = new AgentMemory({
  // Storage: 'memory' (ephemeral) or 'postgres' (persistent)
  storage: { provider: 'memory' },
 
  // Embedding provider for semantic search
  embedding: {
    provider: 'openai',
    model: 'text-embedding-3-small',
    apiKey: process.env.OPENAI_API_KEY,
  },
 
  // LLM for memory extraction
  extraction: {
    llmProvider: new OpenAILLMProvider({
      apiKey: process.env.OPENAI_API_KEY,
      model: 'gpt-4o-mini',
    }),
    enabledTypes: [
      MemoryType.FACT,
      MemoryType.PREFERENCE,
      MemoryType.CORRECTION,
    ],
    batchSize: 10,
    confidenceThreshold: 0.7,
  },
});
 
// Extract and store memories from a conversation
const conversation = [
  { speaker: 'user', content: 'I prefer dark mode', timestamp: new Date() },
  { speaker: 'agent', content: 'Got it!', timestamp: new Date() },
  { speaker: 'user', content: 'I live in Seattle', timestamp: new Date() },
];
 
const stored = await memory.extractAndStore(conversation);
console.log(`Stored ${stored.length} memories`);
 
// Retrieve relevant memories
const relevant = await memory.retrieve('Where does the user live?', {
  limit: 5,
});
console.log(relevant.map((m) => m.content));
 
// Run maintenance (decay + forgetting policies)
await memory.runMaintenance();
 
// Subscribe to events
memory.events.on('memory:stored', (event) => {
  console.log('Memory stored:', event.payload);
});
 
// Cleanup
await memory.close();

API Reference

AgentMemory (class)

The main facade class:

typescript
class AgentMemory {
  constructor(config: AgentMemoryConfig);
 
  // Core operations
  extractAndStore(conversation: ConversationTurn[]): Promise<Memory[]>;
  retrieve(context: string, options?: Partial<RetrievalOptions>): Promise<Memory[]>;
  runMaintenance(tenantId?: string): Promise<void>;
 
  // Accessors
  getStorage(): MemoryStorage;
  readonly events: MemoryEventBus;
 
  // Lifecycle
  close(): Promise<void>;
}

AgentMemoryConfig

PropertyTypeDescription
storageMemoryStorage | StorageConfigStorage backend instance or config
embeddingEmbeddingProvider | EmbeddingConfigEmbedding provider instance or config
extractionExtractionConfig & { llmProvider, enabledTypes }Extraction configuration
tenantIdstringTenant identifier (default: default)
ownerIdstringOwner identifier (default: default)
retrievalPartial<RetrievalConfig>Retrieval tuning (optional)
policies{ decay?, forgetting?, contradiction?, rules? }Policy configuration (optional)
eventsMemoryEventBusCustom event bus (default: InMemoryEventBus)
embeddingCacheEmbeddingCacheCustom embedding cache (default: InMemoryEmbeddingCache)

StorageConfig

typescript
type StorageConfig =
  | { provider: 'memory' }
  | { provider: 'postgres'; connection: PostgresConfig };

EmbeddingConfig

typescript
type EmbeddingConfig =
  | { provider: 'openai'; model: string; apiKey: string; dimensions?: number; baseUrl?: string }
  | { provider: 'cohere'; model: string; apiKey: string; dimensions?: number }
  | { provider: 'huggingface'; model: string; apiKey: string };

Package Architecture

@reaatech/agent-memory is the facade for 8 specialized packages:

PackageDescription
@reaatech/agent-memory-coreCore types, enums, and utilities
@reaatech/agent-memory-storageStorage abstraction (In-Memory, PostgreSQL pgvector)
@reaatech/agent-memory-embeddingEmbedding providers (OpenAI, Cohere, HuggingFace)
@reaatech/agent-memory-llmLLM provider abstraction
@reaatech/agent-memory-retrievalSemantic retrieval with ranking strategies
@reaatech/agent-memory-policiesDecay, forgetting, and contradiction resolution
@reaatech/agent-memory-extractionLLM-based memory extraction
@reaatech/agent-memory-eventsEvent bus for lifecycle hooks

Advanced Usage

PostgreSQL Storage

typescript
const memory = new AgentMemory({
  storage: {
    provider: 'postgres',
    connection: {
      host: 'localhost',
      database: 'agent_memory',
      user: 'postgres',
      password: process.env.DB_PASSWORD,
    },
  },
  embedding: {
    provider: 'openai',
    model: 'text-embedding-3-small',
    apiKey: process.env.OPENAI_API_KEY,
  },
  extraction: {
    llmProvider: new OpenAILLMProvider({
      apiKey: process.env.OPENAI_API_KEY,
      model: 'gpt-4o-mini',
    }),
    enabledTypes: [MemoryType.FACT, MemoryType.PREFERENCE],
    batchSize: 10,
    confidenceThreshold: 0.7,
  },
});

Custom Policy Rules

typescript
const memory = new AgentMemory({
  // ... base config
  policies: {
    rules: [
      {
        id: 'never-forget-medical',
        priority: 100,
        condition: { type: 'tag_matches', pattern: 'medical:*' },
        action: { type: 'freeze_decay' },
        override: true,
      },
      {
        id: 'archive-old-transient',
        priority: 50,
        condition: { type: 'importance_equals', value: 'transient' },
        action: { type: 'forget_after', days: 7 },
      },
    ],
  },
});

Event Hooks for Observability

typescript
import { AgentMemory } from '@reaatech/agent-memory';
import { Counter, Histogram } from 'prom-client';
 
const materializedCount = new Counter({
  name: 'agent_memory_stored_total',
  help: 'Total stored memories',
  labelNames: ['tenant', 'type'],
});
 
const retrieveLatency = new Histogram({
  name: 'agent_memory_retrieve_duration_ms',
  help: 'Retrieval latency',
});
 
const memory = new AgentMemory({
  // ... config
  events: bus,
});
 
memory.events.on('memory:stored', (event) => {
  materializedCount.inc({
    tenant: event.tenantId,
    type: event.payload.memory.type,
  });
});
 
memory.events.on('memory:retrieved', (event) => {
  retrieveLatency.observe(Date.now() - event.timestamp.getTime());
});

License

MIT

All packagesagent-memory overview