Long-Term Memory

Consolidated knowledge extracted from episodic memories. Features natural decay based on access frequency and importance, inspired by human memory science.

What Is Long-Term Memory?

Long-term memory stores knowledge that has been distilled from episodic experiences. Rather than remembering every individual interaction, the consolidation process extracts patterns, insights, and key facts into durable memories that persist over time.

Like human memory, long-term memories decay naturally if not accessed. Frequently retrieved memories grow stronger, while unused memories gradually fade. This ensures that the most relevant knowledge remains readily available while stale information naturally expires.

When to Use

• •Storing distilled knowledge that should persist across sessions
• •Building a knowledge base from repeated interactions
• •Maintaining key facts that are accessed regularly
• •Allowing stale knowledge to naturally expire
• •Querying consolidated insights from past experiences

Quick Example

import Rekall from '@rekall/sdk';

const rekall = new Rekall({ apiKey: 'rk_your_api_key' });

// Create a long-term memory directly
const memory = await rekall.longTerm.create({
  content: 'Sarah prefers Python for backend services and TypeScript for frontend. She values type safety and comprehensive test coverage.',
  importance: 0.85,
  source: 'consolidation',  // or 'manual'
  tags: ['user:sarah', 'preferences', 'languages'],
});

// Search long-term memories
const results = await rekall.longTerm.search({
  query: 'What are Sarah\'s programming preferences?',
  limit: 5,
  minStrength: 0.3,
});

for (const mem of results) {
  console.log(mem.content, mem.strength, mem.lastAccessed);
}

Consolidation Process

Consolidation runs periodically (configurable, default every 6 hours) and processes recent episodic memories to extract patterns and insights. The process:

1. Identifies clusters of related episodic memories
2. Extracts common themes, facts, and patterns from each cluster
3. Checks for existing long-term memories that overlap
4. Creates new long-term memories or strengthens existing ones
5. Assigns importance scores based on frequency and source importance

// Trigger consolidation manually
const result = await rekall.longTerm.consolidate({
  since: '2025-01-01T00:00:00Z',  // Process memories since this date
  dryRun: false,                    // Set true to preview without saving
});

console.log(result.created, 'new long-term memories');
console.log(result.strengthened, 'existing memories updated');

Decay Formula

Memory strength decays according to an Ebbinghaus-inspired forgetting curve. The formula balances initial importance, time elapsed, and access frequency:

strength = importance * e^(-decay_rate * time_elapsed) + access_bonus

where:
  importance    = initial importance score (0.0 to 1.0)
  decay_rate    = base decay rate (default: 0.1, configurable per context)
  time_elapsed  = hours since creation or last consolidation
  access_bonus  = log(1 + access_count) * 0.1

A memory is considered "forgotten" when strength drops below the
threshold (default: 0.05). Forgotten memories are archived, not deleted.

Advanced Usage

Importance Scoring

Importance determines how quickly a memory decays and whether it survives consolidation. Several factors influence the score:

Retrieval Strengthening

Every time a long-term memory is retrieved (via search or direct access), its strength increases. This models the "testing effect" from cognitive science: retrieving information strengthens the memory trace.

// Get memory with strength info
const memory = await rekall.longTerm.get('mem_abc123');
console.log('Strength:', memory.strength);
console.log('Access count:', memory.accessCount);
console.log('Last accessed:', memory.lastAccessed);

// Manually boost a memory's strength
await rekall.longTerm.boost('mem_abc123', {
  amount: 0.2,  // Add to current strength
  reason: 'User confirmed this is still accurate',
});

Use Cases

Best Practices

• 1.Trust the consolidation process. Let episodic memories accumulate and let consolidation extract patterns. Avoid manually creating long-term memories for things that should emerge from experience.
• 2.Set appropriate importance on source episodic memories. High-importance episodes are more likely to be consolidated into long-term knowledge.
• 3.Monitor decay thresholds. If important knowledge is decaying too quickly, adjust the decay rate or boost specific memories.
• 4.Use minStrength in searches. Filter out weakened memories by setting a minimum strength threshold when searching.
• 5.Review archived memories. When memories drop below the threshold, they are archived rather than deleted. You can restore them if needed.