LLM Memory System

An experimental implementation of a human-inspired memory system for Large Language Models.

Overview

This library provides LLMs with memory capabilities that mimic human cognitive processes:

• Importance-based retention - Prioritizes storing memories based on significance
• Emotional context - Tracks and matches emotional states for better retrieval
• Belief-based filtering - Integrates new information with existing beliefs
• Tiered storage - Short-term, medium-term, and long-term memory stores
• Memory consolidation - Periodic reorganization and promotion of memories

Background

Human working memory is limited to 4-5 items, yet humans excel at complex cognitive tasks through specialized memory strategies. This project explores implementing similar mechanisms for LLMs:

Memory Type	Humans	LLMs
Working memory	Limited (4-5 items)	Large (thousands of tokens)
Long-term memory	Nearly unlimited, slow access	Fixed in parameters
Episodic memory	Autobiographical events	None natively
External memory	Notes, books, computers	None without RAG

Installation

# Using bun
bun add memory

# Using npm
npm install memory

Quick Start

import { MemoryStore } from 'memory';

// Create a memory store
const store = new MemoryStore({
  maxShortTermMemories: 100,
  maxMediumTermMemories: 1000,
  importanceThreshold: 0.3
});

// Add a memory
const memory = await store.addMemory(
  "User prefers dark mode interface",
  0.8, // initial importance
  { importanceThreshold: 0.3 }
);

// Retrieve relevant memories
const memories = await store.retrieveMemories("user preferences", {
  limit: 5,
  recencyWeight: 0.3,
  semanticWeight: 0.4
});

Core Concepts

Memory Structure

interface Memory {
  id: string;
  content: string;
  createdAt: Date;
  updatedAt: Date;
  importanceScore: number;      // 0-1 importance rating
  accessCount: number;           // Times retrieved
  lastAccessed?: Date;
  
  // Emotional context (VAD model)
  emotionalContext?: {
    valence: number;            // -1 (negative) to 1 (positive)
    arousal: number;            // 0 (calm) to 1 (excited)
    dominance: number;          // 0 (submissive) to 1 (dominant)
    primaryEmotion?: string;
  };
  
  // Belief system integration
  beliefCompatibility?: number; // -1 to 1
  contradictoryBeliefs?: string[];
  supportiveBeliefs?: string[];
}

Tiered Memory Storage

1. Short-term - Recent context, lowest importance threshold
2. Medium-term - Session information with priority scoring
3. Long-term - User profile and persistent prioritized information

Memories are automatically promoted based on access frequency:

• Short → Medium: 3+ accesses
• Medium → Long: 5+ accesses

Belief System

The belief system filters new memories based on compatibility:

// Belief structure
interface Belief {
  id: string;
  content: string;
  confidence: number;           // 0-1 confidence
  importance: number;            // 0-1 centrality to worldview
  supportingEvidenceIds: string[];
  contradictingEvidenceIds: string[];
  changeResistance: number;     // 0-1 difficulty to change
}

// Assessment determines if evidence warrants belief revision
assessBeliefChangeThreshold(belief, contradictingEvidence, userContext);

API Reference

MemoryStore

const store = new MemoryStore(config?: MemoryStoreConfig);

// Add a new memory
addMemory(content: string, importance?: number, options?: MemoryFilterOptions): Promise<Memory>;

// Retrieve memories
retrieveMemories(query: string, options?: MemoryRetrievalOptions): Promise<Memory[]>;

// Stop consolidation timer
stopConsolidation(): void;

Configuration Options

interface MemoryStoreConfig {
  maxShortTermMemories?: number;    // Default: 100
  maxMediumTermMemories?: number;    // Default: 1000
  shortTermDecayRate?: number;       // Default: 0.05
  consolidationInterval?: number;    // Default: 1 hour (ms)
  importanceThreshold?: number;      // Default: 0.3
  emotionalWeighting?: number;       // Default: 0.3
  beliefWeighting?: number;          // Default: 0.2
}

Retrieval Options

interface MemoryRetrievalOptions {
  limit?: number;
  minImportance?: number;
  emotionalContext?: Memory['emotionalContext'];
  beliefConsistency?: number;       // -1 to 1
  recencyWeight?: number;            // 0-1, default: 0.2
  semanticWeight?: number;            // 0-1, default: 0.4
  emotionalWeight?: number;          // 0-1, default: 0.1
  beliefWeight?: number;             // 0-1, default: 0.1
}

Research Foundation

This implementation is based on cognitive science research:

• Working memory limits: Cowan (2001) - magical number 4
• Chunking mechanisms: Gobet et al. (2001) - human learning chunking
• Emotional memory: Talmi (2013), Buchanan (2007)
• Belief systems: Nickerson (1998) - confirmation bias
• Cognitive dissonance: Festinger (1957)

Project Structure

memory/
├── index.ts              # Main entry point
├── types/
│   └── index.ts          # TypeScript interfaces
├── services/
│   └── memory-store.ts   # Core memory storage service
├── utils/
│   ├── belief-change.ts  # Belief system utilities
│   └── score-event.ts    # Memory importance scoring
├── package.json
└── tsconfig.json

Limitations

• Placeholder implementations for semantic similarity (would use embeddings in production)
• Belief compatibility uses simple term matching (would use LLM in production)
• No actual vector database integration
• Consolidation timer is basic (production would need distributed coordination)

License

MIT