Decay & Consolidation

How memory strength changes over time. Rekall uses an Ebbinghaus-inspired decay curve and periodic consolidation to model realistic memory behavior.

Overview

Human memory does not persist uniformly. Frequently accessed information stays strong while unused knowledge fades. Rekall models this through two complementary mechanisms:

• •Decay: Memory strength decreases over time following an exponential curve. More important memories decay more slowly.
• •Consolidation: Periodic process that extracts patterns from episodic memories and creates durable long-term memories.

Together, these mechanisms ensure that your agent's memory stays relevant and manageable, retaining important knowledge while naturally pruning stale information.

The Decay Curve

Rekall uses an Ebbinghaus-inspired forgetting curve. Memory strength starts at its initial importance value and decays exponentially over time:

S(t) = I * e^(-lambda * t) + B(a)

where:
  S(t)     = memory strength at time t
  I        = initial importance (0.0 to 1.0)
  lambda   = decay rate (default: 0.1 per day)
  t        = time elapsed since creation (in days)
  B(a)     = access bonus = min(0.5, log(1 + a) * 0.1)
  a        = number of times the memory has been accessed

When S(t) < threshold (default: 0.05), the memory is considered
"forgotten" and is archived.

Decay Parameters

Access Frequency Boost

Every time a memory is retrieved via search or direct access, its access count increments. The access bonus follows a logarithmic curve that rewards early retrievals more than later ones (diminishing returns). This models the "testing effect" from cognitive science.

Accesses | Bonus  | Effective strength (importance=0.8, day 7)
---------|--------|-------------------------------------------
0        | 0.000  | 0.398
1        | 0.069  | 0.467
3        | 0.139  | 0.537
5        | 0.179  | 0.577
10       | 0.240  | 0.638
20       | 0.300  | 0.698
50       | 0.391  | 0.789
100+     | 0.500  | 0.898  (capped at max_access_bonus)

The Consolidation Process

How It Works

Consolidation runs periodically (default: every 6 hours) and processes recent episodic memories to extract durable knowledge. The process follows these steps:

1. 1.Cluster related memories. Group episodic memories by semantic similarity using the vector embeddings.
2. 2.Extract patterns. For each cluster, identify common themes, repeated facts, and consistent patterns.
3. 3.Check for duplicates. Compare extracted patterns against existing long-term memories to avoid redundancy.
4. 4.Create or strengthen. Create new long-term memories for novel patterns. Strengthen existing ones that receive confirming evidence.
5. 5.Score importance. Assign importance based on source frequency, recency, episodic importance, and uniqueness.

Triggering Consolidation

Consolidation runs automatically on schedule, but you can also trigger it manually.

// Trigger consolidation for a specific time range
const result = await rekall.consolidation.run({
  since: '2025-01-01T00:00:00Z',
  until: '2025-01-31T23:59:59Z',
  dryRun: true,  // Preview changes without saving
});

console.log('Would create:', result.wouldCreate, 'new memories');
console.log('Would strengthen:', result.wouldStrengthen, 'existing');

// Run for real
const applied = await rekall.consolidation.run({
  since: '2025-01-01T00:00:00Z',
  dryRun: false,
});

// Check consolidation status and history
const status = await rekall.consolidation.status();
console.log('Last run:', status.lastRun);
console.log('Next scheduled:', status.nextScheduled);
console.log('Memories processed:', status.memoriesProcessed);

Importance Thresholds

Not all episodic memories are candidates for consolidation. The system uses importance thresholds to filter which memories are processed:

Configuration

Decay and consolidation parameters can be configured per memory context.

// Configure decay parameters
await rekall.config.setDecay({
  decayRate: 0.05,         // Slower decay (memories last longer)
  threshold: 0.1,          // Higher archive threshold
  accessWeight: 0.15,      // Stronger access boost
  maxAccessBonus: 0.6,     // Higher access bonus cap
});

// Configure consolidation schedule
await rekall.config.setConsolidation({
  intervalHours: 12,       // Run every 12 hours
  minClusterSize: 2,       // Minimum memories to form a cluster
  similarityThreshold: 0.8, // How similar memories must be to cluster
  minImportance: 0.3,      // Skip low-importance memories
});

// Disable decay entirely (memories persist forever)
await rekall.config.setDecay({ decayRate: 0 });

Best Practices

• 1.Start with defaults. The default decay rate and consolidation schedule work well for most use cases. Tune only after observing behavior.
• 2.Use dry runs. Always preview consolidation with dry_run=true before running on production data.
• 3.Monitor archived memories. Check what is being archived. If important knowledge is decaying too fast, lower the decay rate or increase importance scores.
• 4.Set importance deliberately. Importance is the primary lever for decay speed. A well-calibrated importance score is more effective than tuning global decay parameters.
• 5.Trust the system. Decay and consolidation are designed to manage memory naturally. Resist the urge to set decay_rate to 0 unless you have a specific reason.