Minuet

"The optical table for holographic computing."

Minuet is a Rust toolkit for building holographic memory systems, extending amari-holographic with higher-level abstractions for cognitive memory architectures.

Named after Star Trek's first sentient hologram, Minuet provides memory that participates in cognition rather than merely serving it.

What's New in 0.2.0

• Optical Backend: Hardware abstraction for optical holographic computing (DMD + MMF systems)
• Checkpoint Persistence: Journal-based state persistence portable across hardware
• T-Matrix Fingerprinting: Fast hardware validation without full recalibration
• Symbolic Expressions: Hardware-independent memory representation (symbols, bindings, bundles)

See the CHANGELOG for full details.

What is Holographic Memory?

Holographic memory stores information in superposition using high-dimensional algebraic representations. Unlike traditional key-value stores:

• Retrieval is algebraic: Queries are pattern completions in the same representational space as stored knowledge
• Relationships are first-class: Associations are stored as algebraic bindings, enabling analogical queries
• Graceful degradation: Memory degrades smoothly under capacity pressure rather than failing catastrophically
• Compositional: Complex structures are built from simple binding and bundling operations

Quick Start

Add to your Cargo.toml:

[dependencies]
minuet = "0.2"
amari-holographic = "0.15"

Basic Usage

use minuet::prelude::*;

// Choose an algebra - ProductCliffordAlgebra<K> has 8*K dimensions
type Algebra = ProductCliffordAlgebra<64>; // 512 dimensions, ~85 item capacity

fn main() -> MinuetResult<()> {
    // Create a simple memory (combines store + codebook)
    let memory = SimpleMemory::<Algebra>::new();

    // Store associations between symbols
    memory.store_symbols("paris", "france")?;
    memory.store_symbols("berlin", "germany")?;
    memory.store_symbols("rome", "italy")?;

    // Recall: given a key, find the associated value
    if let Some((value, confidence)) = memory.recall("paris")? {
        println!("paris -> {} (confidence: {:.2})", value, confidence);
    }

    // Direct algebra operations
    let dog = memory.symbol("dog");
    let bark = memory.symbol("bark");
    memory.store(&dog, &bark)?;

    Ok(())
}

Pipeline Composition

For more control, compose custom pipelines:

use minuet::prelude::*;
use minuet::capacity::RejectPolicy;

type Algebra = ProductCliffordAlgebra<32>; // 256 dimensions

fn main() -> MinuetResult<()> {
    // Build a custom pipeline
    let pipeline = PipelineBuilder::<Algebra>::new()
        .with_store(ShardedStore::with_shards(4))      // 4 shards for ~4x capacity
        .with_retriever(ResonatorRetriever::new())     // Cleanup via resonator network
        .with_codebook(HashMapCodebook::new())         // Symbol vocabulary
        .with_capacity_policy(RejectPolicy::with_threshold(0.9))
        .build()?;

    // Use the pipeline
    let key = pipeline.symbol("query");
    let value = pipeline.symbol("result");
    pipeline.store(&key, &value)?;

    let result = pipeline.retrieve(&key)?;
    println!("Retrieved with confidence: {:.2}", result.confidence);

    Ok(())
}

Optical Backend (New in 0.2.0)

For optical holographic computing systems:

use minuet::optical::{
    CheckpointConfig, CheckpointedOpticalMemory,
    MockOpticalHardware, SymbolicExpression,
};
use std::path::PathBuf;
use std::time::Duration;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create optical memory with mock hardware
    let hardware = MockOpticalHardware::new(42);
    let config = CheckpointConfig {
        journal_path: PathBuf::from("/tmp/memory.bin"),
        interval: Duration::from_secs(300),
        ..Default::default()
    };

    let mut memory = CheckpointedOpticalMemory::new(
        hardware, encoder_config, codebook_config, config,
    )?;

    // Store using symbolic expressions
    memory.store(
        SymbolicExpression::role_filler("AGENT", "John"),
        SymbolicExpression::role_filler("ACTION", "run"),
    )?;

    // Retrieve
    if let Some(result) = memory.retrieve(
        &SymbolicExpression::role_filler("AGENT", "John")
    )? {
        println!("John's action: {:?}", result.value);
    }

    // Checkpoint (saves to journal)
    memory.checkpoint()?;

    // Restore on any hardware (same or different)
    let new_hardware = MockOpticalHardware::new(999);
    let restored = CheckpointedOpticalMemory::restore(new_hardware, config)?;

    Ok(())
}

Core Concepts

Binding Algebras

Minuet is generic over any BindingAlgebra from amari-holographic. The algebra provides:

Available algebras:

Memory Traces

A trace stores items in superposition:

use minuet::store::DenseTrace;

let mut trace = DenseTrace::<Algebra>::new();

// Add items (they superpose)
trace.add(&item1, 1.0);  // weight = 1.0
trace.add(&item2, 1.0);

// Query similarity
let sim = trace.similarity(&item1);  // High similarity

// Unbind to retrieve
let retrieved = trace.unbind(&key);

Memory Stores

Stores manage one or more traces:

// Simple store for small workloads
let simple = SimpleStore::<Algebra>::new();

// Sharded store for larger capacity
let sharded = ShardedStore::<Algebra>::with_shards(8);

Codebooks

Codebooks provide consistent symbol-to-vector mappings:

use minuet::encoding::HashMapCodebook;

let codebook = HashMapCodebook::<Algebra>::new();

// Same name always returns same vector
let v1 = codebook.symbol("hello");
let v2 = codebook.symbol("hello");
assert!(v1.similarity(&v2) > 0.99);

// Find closest symbol to a vector
if let Some((name, similarity)) = codebook.closest(&query) {
    println!("Closest: {} ({:.2})", name, similarity);
}

Retrievers

Retrievers clean up noisy retrieval results:

use minuet::retrieval::ResonatorRetriever;

// Resonator with custom settings
let retriever = ResonatorRetriever::<Algebra>::new()
    .initial_temperature(1.0)   // Start soft
    .final_temperature(100.0)   // End hard
    .max_iterations(50);

Capacity Management

Holographic memory has finite capacity based on dimensions:

Capacity scales as O(D / ln D) where D is dimension.

For larger workloads, use ShardedStore:

// 8 shards × 85 items ≈ 680 item capacity
let store = ShardedStore::<ProductCliffordAlgebra<64>>::with_shards(8);

Optical Backend (New in 0.2.0)

The optical module provides hardware abstraction for optical holographic computing:

┌─────────────────────────────────────────────────────────┐
│                 CheckpointedOpticalMemory               │
│  • store() / retrieve() - optical hot paths             │
│  • checkpoint() - periodic persistence                  │
│  • restore() - hardware-independent recovery            │
├─────────────────────────────────────────────────────────┤
│     MemoryJournal     TMatrixFingerprint   OpticalHardware │
│      (portable)         (validation)         (backend)    │
└─────────────────────────────────────────────────────────┘

Key Concepts:

• Hardware as Accelerator: Optical hardware computes, but doesn't store. State is persisted independently.
• Portable Checkpoints: Save on one device, restore on another.
• T-Matrix Fingerprinting: Detect hardware drift or replacement without full recalibration.
• Symbolic Expressions: Hardware-independent representation using symbols, bindings, and bundles.

Persistence Model:

Architecture

minuet/
├── src/
│   ├── lib.rs           # Re-exports and prelude
│   ├── traits.rs        # Core trait definitions
│   ├── error.rs         # Error types
│   ├── store/           # Memory storage
│   │   ├── trace.rs     # DenseTrace - fundamental storage unit
│   │   ├── simple.rs    # SimpleStore - single-trace store
│   │   └── sharded.rs   # ShardedStore - hash-sharded store
│   ├── encoding/        # Symbol encoding
│   │   └── codebook.rs  # HashMapCodebook
│   ├── retrieval/       # Cleanup strategies
│   │   ├── direct.rs    # DirectRetriever
│   │   └── resonator_retriever.rs
│   ├── capacity/        # Capacity management
│   │   └── mod.rs       # RejectPolicy, AcceptAllPolicy
│   ├── pipeline/        # Composition
│   │   └── builder.rs   # PipelineBuilder
│   ├── reference/       # Reference implementations
│   │   └── simple_memory.rs  # SimpleMemory
│   └── optical/         # Optical backend (feature-gated)
│       ├── mod.rs       # Module exports
│       ├── symbolic.rs  # SymbolicExpression types
│       ├── journal.rs   # MemoryJournal, MemoryOp
│       ├── fingerprint.rs # TMatrixFingerprint
│       ├── hardware.rs  # OpticalHardware trait
│       ├── mock_hardware.rs # MockOpticalHardware
│       └── checkpoint.rs # CheckpointedOpticalMemory
├── docs/
│   └── API.md           # Complete API reference
├── examples/
│   ├── simple_memory.rs           # Basic usage
│   ├── compose_pipeline.rs        # Pipeline composition
│   ├── optical_memory_demo.rs     # Optical backend demo
│   ├── optical_fingerprint_demo.rs # T-matrix fingerprinting
│   └── optical_expressions_demo.rs # Symbolic expressions
└── tests/

Examples

Basic Examples

# Simple memory operations
cargo run --example simple_memory

# Pipeline composition with sharding
cargo run --example compose_pipeline

Optical Examples (requires optical feature)

# Full optical memory demo with checkpoint/restore
cargo run --example optical_memory_demo --features optical

# T-matrix fingerprinting for hardware validation
cargo run --example optical_fingerprint_demo --features optical

# Symbolic expressions (symbols, bindings, bundles)
cargo run --example optical_expressions_demo --features optical

Feature Flags

[dependencies]
minuet = { version = "0.2", features = ["optical"] }

Documentation

• API Reference - Complete API documentation
• docs.rs - Generated rustdoc

Algebraic Guarantees

The underlying BindingAlgebra satisfies:

1. Identity: x.bind(&A::identity()) = x
2. Inverse: x.bind(&x.inverse()?) ≈ A::identity()
3. Dissimilarity: a.bind(&b) is dissimilar to both a and b
4. Bundle Similarity: a.bundle(&b, β)? is similar to both a and b
5. Distributivity: a.bind(&b.bundle(&c, β)?) ≈ a.bind(&b).bundle(&a.bind(&c), β)?

Performance Considerations

• Dimension Choice: Higher dimensions = more capacity but slower operations
• Sharding: Use ShardedStore when single-trace capacity is insufficient
• Retriever: DirectRetriever is fastest; ResonatorRetriever improves accuracy
• Bundling Temperature: β=1.0 (soft) preserves more information; β=∞ (hard) is faster

Use Cases

What Minuet Is Not

• A replacement for vector databases at scale (millions of items)
• A general-purpose key-value store
• An embedding similarity search engine

Minuet excels at small-to-medium associative memories where algebraic structure matters.

Testing

# Run all tests
cargo test

# Run with all features
cargo test --all-features

# Run optical tests
cargo test --features optical

# Run examples
cargo run --example simple_memory
cargo run --example optical_memory_demo --features optical

Minimum Supported Rust Version

Rust nightly is required. This enables compatibility with amari-gpu for future GPU-accelerated implementations.

License

MIT OR Apache-2.0

References

• amari-holographic - Core binding algebras
• Holographic Reduced Representations (Plate, 1995)
• Hyperdimensional Computing (Kanerva, 2009)
• Vector Symbolic Architectures (Gayler, 2003)

Contributing

Contributions welcome! Please see the GitHub repository for issues and pull requests.