Expand description
§Lucid Core
High-performance memory retrieval engine implementing ACT-R spreading activation and MINERVA 2’s reconstructive memory model.
§Why Reconstructive Memory?
Most AI memory systems treat memory as storage and retrieval—like a database. But human memory doesn’t work that way. Human memory is reconstructive:
- Memories evolve over time - They aren’t static records
- Context shapes retrieval - What surfaces depends on your current state
- Associations matter - Memories activate related memories
- Details fade, essence persists - Verbatim decays faster than gist
This library implements the computational mechanisms that make this possible.
§Core Concepts
§Activation
Every memory has an activation level that determines how likely it is to be retrieved. Activation comes from three sources:
-
Base-level activation - Recency and frequency of access
B(m) = ln[Σ(t_k)^(-d)] -
Probe-trace similarity - How well the current context matches
A(i) = S(i)³ (MINERVA 2's nonlinear function) -
Spreading activation - Activation from associated memories
A_j = Σ(W_i/n_i) × S_ij
§Retrieval
The retrieval pipeline combines these into a ranked set of candidates:
- Compute semantic similarity between probe and all memories
- Apply nonlinear activation (emphasizes strong matches)
- Compute base-level from access history
- Spread activation through the association graph
- Combine, rank, and filter by retrieval probability
§Example
use lucid_core::{
retrieval::{retrieve, RetrievalConfig, RetrievalInput},
spreading::Association,
};
// Your memory embeddings (from any embedding model)
let memories = vec![
vec![1.0, 0.0, 0.0],
vec![0.5, 0.5, 0.0],
vec![0.0, 1.0, 0.0],
];
// Probe embedding (what you're looking for)
let probe = vec![0.9, 0.1, 0.0];
let input = RetrievalInput {
probe_embedding: &probe,
memory_embeddings: &memories,
access_histories_ms: &[vec![1000.0], vec![500.0], vec![100.0]],
emotional_weights: &[0.5, 0.5, 0.5],
decay_rates: &[0.5, 0.5, 0.5],
working_memory_boosts: &[1.0, 1.0, 1.0], // 1.0 = no boost, up to 2.0
associations: &[], // Optional: links between memories
current_time_ms: 2000.0,
};
let config = RetrievalConfig::default();
let results = retrieve(&input, &config);
// Results are ranked by total activation
for candidate in results {
println!(
"Memory {} - activation: {:.3}, probability: {:.3}",
candidate.index,
candidate.total_activation,
candidate.probability
);
}§Performance
This library is designed for speed because memory should feel like remembering— not like a database query.
- Pure Rust implementation
- No heap allocations in hot paths where possible
- Batch operations for embedding comparisons
- Pre-computed norms for similarity calculations
§References
- Anderson, J. R. (1983). The Architecture of Cognition - ACT-R theory
- Hintzman, D. L. (1988). MINERVA 2: A simulation model of human memory - Reconstructive retrieval
- Kahana, M. J. (2012). Foundations of Human Memory - Memory models
Re-exports§
pub use activation::combine_activations;pub use activation::compute_association_decay;pub use activation::compute_base_level;pub use activation::compute_effective_thresholds;pub use activation::compute_encoding_strength;pub use activation::compute_instance_noise;pub use activation::compute_session_decay_rate;pub use activation::compute_session_decay_rate_batch;pub use activation::compute_working_memory_boost;pub use activation::compute_working_memory_boost_batch;pub use activation::cosine_similarity;pub use activation::get_decay_tau;pub use activation::nonlinear_activation;pub use activation::pe_zone;pub use activation::reconsolidation_probability;pub use activation::reinforce_association;pub use activation::retrieval_probability;pub use activation::should_prune_association;pub use activation::ActivationBreakdown;pub use activation::ActivationConfig;pub use activation::AssociationDecayConfig;pub use activation::AssociationState;pub use activation::InstanceNoiseConfig;pub use activation::ReconsolidationConfig;pub use activation::WorkingMemoryConfig;pub use activation::BETA_RECON;pub use activation::THETA_HIGH;pub use activation::THETA_LOW;pub use retrieval::retrieve;pub use retrieval::RetrievalCandidate;pub use retrieval::RetrievalConfig;pub use retrieval::RetrievalInput;pub use spreading::compute_temporal_link_strength;pub use spreading::create_episode_links;pub use spreading::find_temporal_neighbors;pub use spreading::spread_activation;pub use spreading::spread_temporal_activation;pub use spreading::spread_temporal_activation_multi;pub use spreading::Association;pub use spreading::SpreadingConfig;pub use spreading::SpreadingResult;pub use spreading::TemporalLink;pub use spreading::TemporalSpreadingConfig;pub use spreading::TemporalSpreadingResult;pub use location::compute_association_strength;pub use location::compute_batch_decay;pub use location::compute_decayed_familiarity;pub use location::compute_familiarity;pub use location::get_associated_locations;pub use location::infer_activity_type;pub use location::initial_familiarity;pub use location::is_well_known;pub use location::spread_location_activation;pub use location::ActivityInference;pub use location::ActivityType;pub use location::InferenceSource;pub use location::LocationAssociation;pub use location::LocationConfig;pub use location::LocationIntuition;pub use visual::compute_pruning_candidates;pub use visual::compute_tag_strength;pub use visual::prepare_frame_description_prompt;pub use visual::prepare_synthesis_prompt;pub use visual::retrieve_visual;pub use visual::select_frames_for_description;pub use visual::should_prune;pub use visual::should_tag;pub use visual::ConsolidationState;pub use visual::ConsolidationWindow;pub use visual::EmotionalContext;pub use visual::FrameCandidate;pub use visual::FrameDescriptionConfig;pub use visual::FrameDescriptionResult;pub use visual::PruningCandidate;pub use visual::PruningReason;pub use visual::TagReason;pub use visual::TranscriptSegment;pub use visual::VisualConfig;pub use visual::VisualConsolidationState;pub use visual::VisualMemory;pub use visual::VisualRetrievalCandidate;pub use visual::VisualRetrievalConfig;pub use visual::VisualRetrievalInput;pub use visual::VisualSource;pub use visual::VisualTag;
Modules§
- activation
- Activation Calculation
- location
- Location Intuitions
- retrieval
- Retrieval Pipeline
- spreading
- Spreading Activation
- visual
- Visual Memory
Constants§
- VERSION
- Library version
Functions§
- init
- Initialize the library (placeholder for future setup).