Skip to content
reaatechREAATECH
Book a conversation

@reaatech/agent-memory-extraction

npm v0.1.0

Extracts structured facts, preferences, and decisions from conversation logs using LLMs and generates corresponding vector embeddings. It provides a `MemoryExtractor` class that requires separate LLM and embedding provider implementations to process conversation turns.

npm →source →

@reaatech/agent-memory-extraction

npm version License: MIT CI

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

LLM-based memory extraction from conversations. Analyzes conversation turns to identify memorable facts, preferences, decisions, and corrections — assigning importance scores, types, confidence levels, and generating embeddings for semantic search.

Installation

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

Feature Overview

  • LLM-powered extraction — uses structured output to extract memories from conversations
  • Type classification — categorizes into facts, preferences, decisions, corrections, context, episodic
  • Importance scoring — assigns critical/high/medium/low/transient based on content analysis
  • Confidence scoring — each extraction includes a 0–1 confidence estimate
  • Batch processing — configurable batch size for handling long conversations
  • Automatic embedding generation — extracts and vectorizes in a single pass

Quick Start

typescript
import { MemoryExtractor } from '@reaatech/agent-memory-extraction';
import { MemoryType } from '@reaatech/agent-memory-core';
import { OpenAILLMProvider } from '@reaatech/agent-memory-llm';
import { OpenAIEmbeddingProvider } from '@reaatech/agent-memory-embedding';
 
const extractor = new MemoryExtractor(
  new OpenAILLMProvider({
    apiKey: process.env.OPENAI_API_KEY,
    model: 'gpt-4o-mini',
  }),
  new OpenAIEmbeddingProvider({
    apiKey: process.env.OPENAI_API_KEY,
    model: 'text-embedding-3-small',
  }),
  {
    batchSize: 10,
    confidenceThreshold: 0.7,
    enabledTypes: [
      MemoryType.FACT,
      MemoryType.PREFERENCE,
      MemoryType.DECISION,
      MemoryType.CORRECTION,
    ],
    tenantId: 'default',
  },
);
 
const conversation = [
  { speaker: 'user', content: 'I prefer dark mode interfaces', timestamp: new Date() },
  { speaker: 'agent', content: 'Noted! I will use dark mode.', timestamp: new Date() },
  { speaker: 'user', content: 'I live in Seattle and work as a software engineer', timestamp: new Date() },
];
 
const result = await extractor.extractFromConversation(conversation);
 
console.log(`Extracted ${result.candidates.length} memories`);
console.log(`Confidence: ${result.confidence}`);
console.log(`Rejected: ${result.rejected.length}`);
console.log(`Latency: ${result.latencyMs}ms`);

API Reference

MemoryExtractor (class)

The primary extraction engine:

typescript
const extractor = new MemoryExtractor(
  llmProvider,         // LLMProvider — for structured extraction
  embeddingProvider,   // EmbeddingProvider — for vector generation
  config,              // ExtractionConfig
);
MethodReturnsDescription
extractFromConversation(conversation)Promise<ExtractionResult>Analyze conversation and extract memories

ExtractionConfig

PropertyTypeDefaultDescription
batchSizenumber10Turns to process per extraction call
confidenceThresholdnumber0.7Minimum confidence to accept a candidate
enabledTypesMemoryType[](required)Which memory types to extract
tenantIdstringdefaultTenant identifier for extracted memories
ownerIdstringdefaultOwner identifier for extracted memories

ExtractionResult

typescript
interface ExtractionResult {
  candidates: Memory[];         // Memories that passed the confidence threshold
  rejected: MemoryCandidate[];  // Deduplicated or filtered candidates
  confidence: number;           // Overall extraction confidence (0–1)
  latencyMs: number;            // Extraction operation wall time
}

ConversationTurn (re-exported from core)

typescript
import type { ConversationTurn } from '@reaatech/agent-memory-extraction';
 
interface ConversationTurn {
  speaker: 'user' | 'agent';
  content: string;
  timestamp: Date;
}

How Extraction Works

  1. Chunking — splits long conversations into batches of batchSize turns
  2. LLM analysis — each batch is sent to the LLM with a structured output schema requesting:
    • Memory content (fact, preference, decision, correction)
    • Type classification
    • Importance level
    • Confidence score
    • Tags and category
  3. Filtering — candidates below confidenceThreshold are moved to rejected
  4. Embedding — accepted candidates are vectorized via the embedding provider
  5. Assembly — fully formed Memory objects with embeddings, timestamps, and metadata

Usage Patterns

Extracting Only High-Signal Memories

typescript
const extractor = new MemoryExtractor(llm, embedder, {
  batchSize: 5,
  confidenceThreshold: 0.85,   // stricter threshold
  enabledTypes: [
    MemoryType.FACT,
    MemoryType.PREFERENCE,
    MemoryType.CORRECTION,      // explicitly capture corrections
  ],
});

Multi-Tenant Extraction

typescript
const tenantExtractor = new MemoryExtractor(llm, embedder, {
  batchSize: 10,
  confidenceThreshold: 0.7,
  enabledTypes: [MemoryType.FACT, MemoryType.PREFERENCE],
  tenantId: 'tenant-42',
  ownerId: 'user-7',
});

Related Packages

License

MIT

All packagesagent-memory overview