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:

Operation	Symbol	Description
Bind	`a.bind(&b)`	Create association (dissimilar to inputs)
Bundle	`a.bundle(&b, β)`	Superpose (similar to inputs)
Unbind	`key.unbind(&trace)`	Retrieve associated value
Similarity	`a.similarity(&b)`	Measure closeness [-1, 1]

Available algebras:

Type	Dimensions	Use Case
`ProductCliffordAlgebra<K>`	8×K	General purpose, recommended
`Cl3`	8	Small/embedded systems
`FHRRAlgebra<D>`	D	Frequency domain operations
`MAPAlgebra<D>`	D	Binary/bipolar systems

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:

Store	Description
`SimpleStore`	Single trace, minimal overhead
`ShardedStore`	Hash-sharded across N traces for N× capacity

// 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:

Retriever	Description
`DirectRetriever`	Return raw result (no cleanup)
`ResonatorRetriever`	Iterative cleanup via resonator network

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:

Algebra	Dimensions	Approximate Capacity
`ProductCliffordAlgebra<16>`	128	~23 items
`ProductCliffordAlgebra<32>`	256	~46 items
`ProductCliffordAlgebra<64>`	512	~85 items
`ProductCliffordAlgebra<128>`	1024	~147 items

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:

Layer	Content	Portability
Semantic	Associations, relationships	Fully portable
Codebook	Symbol → seed mappings	Regenerable
Holograms	Binary patterns	Derived on demand
Calibration	T-matrix, learned patterns	Hardware-bound

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"] }

Feature	Description	Dependencies
`default`	Standard features	`std`
`std`	Standard library support	-
`parallel`	Rayon parallelism	`rayon`
`serde`	Serialization	`serde`, `bincode`
`persistence`	RocksDB storage	`rocksdb`, `serde`
`async`	Async support	`tokio`
`optical`	Optical backend	`serde`, `ordered-float`, `rand`
`full`	All features	all above

Documentation

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

Algebraic Guarantees

The underlying BindingAlgebra satisfies:

Identity: x.bind(&A::identity()) = x
Inverse: x.bind(&x.inverse()?) ≈ A::identity()
Dissimilarity: a.bind(&b) is dissimilar to both a and b
Bundle Similarity: a.bundle(&b, β)? is similar to both a and b
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

Domain	Application
Cognitive Agents	Working memory with associative recall
Knowledge Graphs	Relationship storage and analogical queries
Semantic Search	Content-addressable retrieval
Neurosymbolic AI	Symbol grounding with compositional generalization
Robotics	Motor primitive composition
Optical Computing	DMD/MMF-based memory systems

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.

minuet 0.2.0

Minuet

What's New in 0.2.0

What is Holographic Memory?

Quick Start

Basic Usage

Pipeline Composition

Optical Backend (New in 0.2.0)

Core Concepts

Binding Algebras

Memory Traces

Memory Stores

Codebooks

Retrievers

Capacity Management

Optical Backend (New in 0.2.0)

Architecture

Examples

Basic Examples

Optical Examples (requires optical feature)

Feature Flags

Documentation

Algebraic Guarantees

Performance Considerations

Use Cases

What Minuet Is Not

Testing

Minimum Supported Rust Version

License

References

Contributing

Optical Examples (requires `optical` feature)