Temporal Awareness

Time-weighted memory retrieval

Temporal awareness allows memories to naturally decay in relevance over time, ensuring that recent context is prioritized while older information remains accessible when needed.

How It Works

When you query memories, temporal awareness combines semantic similarity with time-based decay to produce a final relevance score. This mimics how human memory works—recent events are easier to recall, but important old memories remain accessible.

// Query with temporal weighting
const memories = await memory.query({
  text: "user preferences",

  // How much time should influence the score (0-1)
  temporalWeight: 0.7,

  // How quickly memories decay (half-life)
  decayHalfLife: "7d",  // 7 days

  // Optional: custom decay function
  decayFunction: "exponential",

  limit: 10
});

// Each result includes:
// - semanticScore: similarity to query (0-1)
// - temporalScore: recency score (0-1)
// - finalScore: combined score

Temporal Weight

The temporalWeight parameter controls how much time affects the final relevance score, from 0 (time doesn't matter) to 1 (time is everything).

finalScore = (1 - temporalWeight) × semanticScore + temporalWeight × temporalScore

0.0

Pure semantic search. Time is ignored.

0.5

Balanced. Good default for most cases.

1.0

Most recent wins. Semantic match secondary.

Decay Half-Life

The decayHalfLife parameter defines how quickly memories lose relevance. After one half-life, a memory's temporal score is reduced by 50%.

// Supported formats
"30m"    // 30 minutes
"6h"     // 6 hours
"7d"     // 7 days
"2w"     // 2 weeks
"3mo"    // 3 months
"1y"     // 1 year

// Examples
{ decayHalfLife: "1h" }   // Fast decay for chat
{ decayHalfLife: "30d" }  // Slow decay for preferences
{ decayHalfLife: "6mo" }  // Very slow for knowledge base

Half-Life	After 1 HL	After 2 HL	After 3 HL
1 day	50% relevance	25% relevance	12.5% relevance
7 days	50% @ 1 week	25% @ 2 weeks	12.5% @ 3 weeks

Decay Functions

Choose a decay function that matches your use case. Exponential decay is the default and works well for most scenarios.

exponential

Memory relevance decays exponentially over time. Best for most use cases.

Formula: score × e^(-λt)Usage: decayFunction: "exponential"

linear

Memory relevance decreases linearly. Useful for fixed time windows.

Formula: score × (1 - t/T)Usage: decayFunction: "linear"

step

Full relevance until threshold, then zero. Good for strict time boundaries.

Formula: score if t < T, else 0Usage: decayFunction: "step"

gaussian

Bell curve decay centered on optimal time. For periodic patterns.

Formula: score × e^(-(t-μ)²/2σ²)Usage: decayFunction: "gaussian"

Use Case Examples

Conversational AI

Recent conversation context is more relevant than old exchanges.

halfLife: "1h", temporalWeight: 0.9

User Preferences

Preferences change slowly, so longer decay is appropriate.

halfLife: "30d", temporalWeight: 0.3

News & Events

Current events become stale quickly.

halfLife: "6h", temporalWeight: 0.95

Knowledge Base

Reference knowledge stays relevant longer.

halfLife: "90d", temporalWeight: 0.2

Advanced Example

// Combining temporal awareness with other features
const memories = await memory.query({
  text: "What does the user prefer for notifications?",

  // Temporal configuration
  temporalWeight: 0.6,
  decayHalfLife: "14d",
  decayFunction: "exponential",

  // Filter to specific entity
  entityId: "user_123",

  // Include relationship context
  includeRelationships: true,

  // Time range filter (optional)
  createdAfter: "2024-01-01",

  limit: 5
});

// Process results
memories.forEach(mem => {
  console.log(`[${mem.finalScore.toFixed(2)}] ${mem.content}`);
  console.log(`  Semantic: ${mem.semanticScore.toFixed(2)}`);
  console.log(`  Temporal: ${mem.temporalScore.toFixed(2)}`);
  console.log(`  Created: ${mem.createdAt}`);
});

Best Practices

✓Start with temporalWeight: 0.5 and adjust based on results
✓Use shorter half-lives for rapidly changing context (conversations, sessions)
✓Use longer half-lives for stable information (user profiles, preferences)
✓Combine temporal filtering with entity filtering for focused results
✓Monitor semanticScore vs temporalScore to tune your weights

Next Steps

Relationship Mapping Cost Optimization