exo-temporal

Temporal memory coordinator with causal structure for the EXO-AI 2025 cognitive substrate.

Overview

This crate implements a biologically-inspired temporal memory system with:

Short-term buffer: Volatile memory for recent patterns
Long-term store: Consolidated memory with strategic forgetting
Causal graph: Tracks antecedent relationships between patterns
Memory consolidation: Salience-based filtering (frequency, recency, causal importance, surprise)
Predictive anticipation: Pre-fetching based on sequential patterns, temporal cycles, and causal chains

Architecture

┌─────────────────────────────────────────────────────────┐
│                  TemporalMemory                         │
├─────────────────────────────────────────────────────────┤
│ ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │
│ │ Short-Term  │  │ Long-Term   │  │   Causal    │      │
│ │   Buffer    │→ │    Store    │  │    Graph    │      │
│ └─────────────┘  └─────────────┘  └─────────────┘      │
│        ↓                ↑                 ↑             │
│ ┌─────────────────────────────────────────────┐         │
│ │          Consolidation Engine               │         │
│ │  (Salience computation & filtering)         │         │
│ └─────────────────────────────────────────────┘         │
│        ↓                                                │
│ ┌─────────────────────────────────────────────┐         │
│ │       Anticipation & Prefetch               │         │
│ └─────────────────────────────────────────────┘         │
└─────────────────────────────────────────────────────────┘

Modules

types: Core type definitions (Pattern, Query, SubstrateTime, etc.)
causal: Causal graph for tracking antecedent relationships
short_term: Volatile short-term memory buffer
long_term: Consolidated long-term memory store
consolidation: Memory consolidation with salience computation
anticipation: Predictive pre-fetching and query anticipation

Key Algorithms

Causal Cone Query (Pseudocode 3.1)

Retrieves patterns within causal light-cone constraints:

let results = memory.causal_query(
    &query,
    reference_time,
    CausalConeType::Past,
);

Filters by time range (Past, Future, or LightCone)
Computes causal distance via graph traversal
Ranks by combined similarity, temporal, and causal relevance

Memory Consolidation (Pseudocode 3.2)

Transfers patterns from short-term to long-term based on salience:

let result = memory.consolidate();

Salience factors:

Frequency: Access count (logarithmic scaling)
Recency: Exponential decay from last access
Causal importance: Out-degree in causal graph
Surprise: Novelty compared to existing patterns

Predictive Anticipation (Pseudocode 3.3)

Pre-fetches likely future queries:

memory.anticipate(&[
    AnticipationHint::SequentialPattern { recent: vec![id1, id2] },
    AnticipationHint::CausalChain { context: id3 },
]);

Strategies:

Sequential patterns: If A then B learned sequences
Temporal cycles: Time-of-day / day-of-week patterns
Causal chains: Downstream effects in causal graph

Usage Example

use exo_temporal::{TemporalMemory, TemporalConfig, Pattern, Metadata};

// Create temporal memory
let memory = TemporalMemory::new(TemporalConfig::default());

// Store pattern with causal context
let pattern = Pattern::new(vec![1.0, 2.0, 3.0], Metadata::new());
let id = memory.store(pattern, &[]).unwrap();

// Retrieve pattern
let retrieved = memory.get(&id).unwrap();

// Causal query
let query = Query::from_embedding(vec![1.0, 2.0, 3.0])
    .with_origin(id)
    .with_k(10);

let results = memory.causal_query(
    &query,
    SubstrateTime::now(),
    CausalConeType::Past,
);

// Trigger consolidation
let consolidation_result = memory.consolidate();

// Strategic forgetting
memory.forget();

// Get statistics
let stats = memory.stats();
println!("Short-term: {} patterns", stats.short_term.size);
println!("Long-term: {} patterns", stats.long_term.size);
println!("Causal edges: {}", stats.causal_graph.num_edges);

Implementation Notes

Pseudocode Alignment

This implementation follows the pseudocode in PSEUDOCODE.md:

Section 3.1: causal_query method implements causal cone filtering
Section 3.2: consolidate function implements salience-based consolidation
Section 3.3: anticipate function implements predictive pre-fetching

Concurrency

Uses DashMap for concurrent access to patterns and indices
parking_lot::RwLock for read-heavy workloads
Thread-safe throughout for multi-threaded substrate operations

Performance

O(log n) temporal range queries via binary search on sorted index
O(k × d) similarity search where k = results, d = embedding dimension
O(n²) worst-case for causal distance via Dijkstra's algorithm
O(1) prefetch cache lookup

Dependencies

exo-core: Core traits and types (to be implemented)
dashmap: Concurrent hash maps
parking_lot: Efficient synchronization primitives
chrono: Temporal handling
petgraph: Graph algorithms for causal distance
serde: Serialization support

Future Enhancements

Temporal Knowledge Graph (TKG) integration (mentioned in ARCHITECTURE.md)
Relativistic light cone with spatial distance
Advanced consolidation policies (sleep-inspired replay)
Distributed temporal memory via CRDT synchronization
GPU-accelerated similarity search

References

ARCHITECTURE.md: Section 2.5 (Temporal Memory Coordinator)
PSEUDOCODE.md: Section 3 (Temporal Memory Coordinator)
Research: Zep-inspired temporal knowledge graphs, IIT consciousness metrics

License

MIT OR Apache-2.0

exo-temporal 0.1.0