@agentos/memory

Memory system with multiple backends for AgentOS.

Features

• Multi-tier Memory Architecture: Working, Conversation, Summary, Semantic, and Long-Term memory
• Multiple Storage Backends: In-memory, Redis, PostgreSQL, SQLite
• Automatic Tiering: Intelligent movement of memories between tiers
• Embedding Support: Semantic search with vector similarity
• Knowledge Graph: Relationship tracking between memories
• Eviction Strategies: LRU, LFU, FIFO, TTL, and Random
• Summarization: Automatic memory compression with extractive or LLM-based strategies

Installation

npm install @agentos/memory

Quick Start

import {
  createMemoryManager,
  createWorkingMemory,
  createConversationMemory,
} from '@agentos/memory';

// Create a memory manager with default configuration
const manager = createMemoryManager();

// Add a conversation message
await manager.addMessage('user', 'Hello, how are you?');
await manager.addMessage('assistant', 'I am doing well!');

// Get conversation history
const messages = await manager.getMessages();

// Store a memory item
await manager.store({
  id: 'my-memory-1',
  content: 'Important fact about the project',
  metadata: { source: 'user' },
  createdAt: new Date(),
});

// Search across all memory tiers
const results = await manager.search('project');

// Semantic search
const semanticResults = await manager.semanticSearch('machine learning');

Memory Tiers

Working Memory

Fast, ephemeral memory with automatic LRU eviction.

import { createWorkingMemory } from '@agentos/memory';

const working = createWorkingMemory({
  maxItems: 100,
  maxSizeBytes: 10 * 1024 * 1024, // 10MB
});

// Store items
await working.set({
  id: 'item-1',
  content: 'Quick access data',
  metadata: {},
  createdAt: new Date(),
});

// Get least recently used items
const lruItems = await working.getLeastRecentlyUsed(5);

Conversation Memory

Message history with automatic summarization.

import { createConversationMemory } from '@agentos/memory';

const conversation = createConversationMemory({
  maxMessages: 100,
  maxTokens: 32000,
  autoSummarize: true,
});

// Add messages
await conversation.addMessage('user', 'Tell me about AI');
await conversation.addMessage('assistant', 'AI is...');

// Get recent messages
const messages = await conversation.getMessages(10);

// Get conversation summary
const summary = await conversation.getSummary();

// Trigger manual summarization
await conversation.summarize();

Semantic Memory

Embedding-based storage with similarity search.

import { createSemanticMemory } from '@agentos/memory';

const semantic = createSemanticMemory({
  embeddingModel: 'text-embedding-3-small',
  embeddingDimensions: 1536,
  similarityThreshold: 0.7,
  embedFn: async (content) => {
    // Use your embedding provider here
    return await embedWithOpenAI(content);
  },
});

// Store items with embeddings
await semantic.set({
  id: 'doc-1',
  content: 'Machine learning is a subset of AI',
  metadata: {},
  createdAt: new Date(),
});

// Similarity search
const results = await semantic.similaritySearch('What is deep learning?', 5);

// Find similar items
const similar = await semantic.findSimilar('doc-1', 3);

Long-Term Memory

Persistent storage with knowledge graph support.

import { createLongTermMemory } from '@agentos/memory';

const longTerm = createLongTermMemory({
  enableKnowledgeGraph: true,
});

// Store knowledge
const einstein = await longTerm.storeKnowledge(
  'Albert Einstein was a physicist',
  { type: 'person', field: 'physics' }
);

const relativity = await longTerm.storeKnowledge(
  'Theory of relativity describes gravity',
  { type: 'theory', field: 'physics' }
);

// Create relationships
await longTerm.createRelationship(einstein.id, relativity.id, 'developed');

// Get related knowledge
const related = await longTerm.getRelated(einstein.id);

// Get items by type
const scientists = await longTerm.getByType('person');

// Access knowledge graph
const graph = longTerm.getKnowledgeGraph();
const nodes = graph.getNodes();
const edges = graph.getEdges();

Storage Adapters

In-Memory Adapter (Development)

import { createInMemoryAdapter } from '@agentos/memory';

const adapter = createInMemoryAdapter();

Redis Adapter (Production)

import { createRedisAdapter } from '@agentos/memory';

const adapter = createRedisAdapter({
  url: 'redis://localhost:6379',
  prefix: 'agentos:',
  ttl: 86400 * 30, // 30 days
});

await adapter.connect();
// ... use adapter
await adapter.disconnect();

PostgreSQL Adapter (Production)

import { createPostgresAdapter } from '@agentos/memory';

const adapter = createPostgresAdapter({
  connectionString: 'postgresql://user:pass@localhost:5432/agentos',
  tableName: 'memory_items',
});

await adapter.connect();

SQLite Adapter (Local/Embedded)

import { createSQLiteAdapter } from '@agentos/memory';

const adapter = createSQLiteAdapter({
  filePath: './data/memory.db',
  tableName: 'memory_items',
});

await adapter.connect();

Eviction Strategies

import {
  createEvictionStrategy,
  EvictionStrategyType,
} from '@agentos/memory';

// Least Recently Used
const lru = createEvictionStrategy(EvictionStrategyType.LRU);

// Least Frequently Used
const lfu = createEvictionStrategy(EvictionStrategyType.LFU);

// First In, First Out
const fifo = createEvictionStrategy(EvictionStrategyType.FIFO);

// Time To Live
const ttl = createEvictionStrategy(EvictionStrategyType.TTL, {
  ttl: 3600000, // 1 hour
});

// Random
const random = createEvictionStrategy(EvictionStrategyType.Random);

Summarization Strategies

Extractive (No LLM Required)

import { ExtractiveSummarizer } from '@agentos/memory';

const summarizer = new ExtractiveSummarizer();

const summary = await summarizer.summarize([
  'First sentence of text.',
  'Second sentence of text.',
]);

const facts = await summarizer.extractFacts('Text with 2023 and $100 values.');

LLM-Based (Higher Quality)

import { LLMSummarizer } from '@agentos/memory';

const summarizer = new LLMSummarizer(async (messages) => {
  // Call your LLM provider
  const response = await openai.chat.completions.create({
    model: 'gpt-4',
    messages,
  });
  return response.choices[0]?.message.content ?? '';
});

const summary = await summarizer.summarize(['Long content to summarize']);

Memory Manager

The MemoryManager coordinates all memory tiers and provides automatic tiering.

import { createMemoryManager, MemoryTier } from '@agentos/memory';

const manager = createMemoryManager({
  working: { maxItems: 100 },
  conversation: { maxMessages: 100 },
  semantic: { embeddingDimensions: 1536 },
  autoTiering: true,
  tieringThreshold: 0.8,
});

// Store with specific tier
await manager.store(item, MemoryTier.Working);

// Search across tiers
const results = await manager.search('query', {
  tiers: [MemoryTier.Working, MemoryTier.Semantic],
});

// Get tier statistics
const stats = manager.getAllStats();
console.log(stats.map(s => `${s.name}: ${s.itemCount}/${s.maxItems}`));

// Clear specific tiers
await manager.clear([MemoryTier.Working]);

API Reference

MemoryItem

interface MemoryItem {
  id: string;
  content: string;
  metadata: Record<string, unknown>;
  createdAt: Date;
  score?: number;
}

Memory Interface

interface Memory {
  get(id: string): Promise<MemoryItem | null>;
  set(item: MemoryItem): Promise<void>;
  delete(id: string): Promise<void>;
  search(query: string, limit?: number): Promise<MemoryItem[]>;
  clear(): Promise<void>;
}

ConversationMemory Interface

interface ConversationMemory extends Memory {
  addMessage(role: string, content: string): Promise<void>;
  getMessages(limit?: number): Promise<MemoryItem[]>;
  getSummary(): Promise<string>;
}

SemanticMemory Interface

interface SemanticMemory extends Memory {
  embed(content: string): Promise<number[]>;
  similaritySearch(query: string, limit?: number): Promise<MemoryItem[]>;
}

Error Handling

The package uses the Result pattern from @agentos/core for explicit error handling.

import { ok, err, isOk, isErr } from '@agentos/core';

const result = await manager.store(item);

if (isOk(result)) {
  console.log('Stored successfully');
} else {
  console.error('Failed:', result.error.message);
}

// Using tryCatch
import { tryCatchAsync } from '@agentos/core';

const result = await tryCatchAsync(
  () => adapter.get('item-id'),
  (error) => new MemoryError(MemoryErrorType.StorageError, 'Get failed', error)
);

License

MIT