chaotic_semantic_memory

chaotic_semantic_memory is a Rust crate for AI memory systems built on:

• 10240-bit hyperdimensional vectors with SIMD acceleration
• chaotic echo-state reservoirs for temporal processing
• libSQL persistence (local SQLite or remote Turso)

It targets both native and wasm32 builds with explicit threading guards.

Quick Links

Features

• Hyperdimensional Computing: 10240-bit binary hypervectors with SIMD-accelerated operations
• Chaotic Reservoirs: Configurable echo-state networks with spectral radius controls [0.9, 1.1]
• Semantic Memory: Concept graphs with weighted associations and similarity search
• Persistence: libSQL for local SQLite or remote Turso database
• WASM Support: Browser-compatible with memory-based import/export
• CLI: Full-featured command-line interface with shell completions
• Production-Ready: Structured logging, metrics, input validation, memory guardrails

Installation

cargo add chaotic_semantic_memory

Enable WASM bindings when needed:

[dependencies]
chaotic_semantic_memory = { version = "0.2", features = ["wasm"] }

Note: Using "0.1" ensures compatibility with the latest 0.1.x patch versions.

Core Components

• hyperdim: binary hypervector math (HVec10240) and similarity operations
• reservoir: sparse chaotic reservoir dynamics with spectral radius controls
• singularity: concept graph, associations, retrieval, and memory limits
• framework: high-level async orchestration API
• persistence: libSQL-backed storage (native only)
• wasm: JS-facing bindings for browser/runtime integration
• cli: Command-line interface (csm binary)

CLI Usage

The csm binary provides command-line access:

# Inject a concept
csm inject my-concept --database memory.db

# Find similar concepts
csm probe my-concept -k 10 --database memory.db

# Create associations
csm associate source-concept target-concept --strength 0.8

# Export memory state
csm export --output backup.json

# Import memory state
csm import backup.json --merge

# Generate shell completions
csm completions bash > ~/.local/share/bash-completion/completions/csm

CLI Commands

Quick Start

use chaotic_semantic_memory::prelude::*;

#[tokio::main]
async fn main() -> Result<()> {
    let framework = ChaoticSemanticFramework::builder()
        .without_persistence()
        .build()
        .await?;

    let concept = ConceptBuilder::new("cat".to_string()).build();
    framework.inject_concept("cat".to_string(), concept.vector.clone()).await?;

    let hits = framework.probe(concept.vector.clone(), 5).await?;
    println!("hits: {}", hits.len());
    Ok(())
}

See examples/proof_of_concept.rs for an end-to-end flow. See examples/basic_in_memory.rs for the minimal in-memory workflow.

Configuration

ChaoticSemanticFramework::builder() exposes runtime tuning knobs.

Tuning Guide

• Small workloads: disable persistence and use reservoir_size around 10_240.
• Mid-sized workloads: keep defaults and set max_concepts to enforce memory ceilings.
• Large workloads: keep persistence enabled, increase connection_pool_size, and tune max_probe_top_k to practical limits.

API Patterns

In-memory flow:

let framework = ChaoticSemanticFramework::builder()
    .without_persistence()
    .build()
    .await?;

Persistent flow:

let framework = ChaoticSemanticFramework::builder()
    .with_local_db("memory.db")
    .build()
    .await?;

Batch APIs for bulk workloads:

framework.inject_concepts(&concepts).await?;
framework.associate_many(&edges).await?;
let hits = framework.probe_batch(&queries, 10).await?;

Load semantics:

• load_replace(): clear in-memory state, then load persisted data.
• load_merge(): merge persisted state into current in-memory state.

WASM Build

rustup target add wasm32-unknown-unknown
cargo check --target wasm32-unknown-unknown

Notes:

• WASM threading-sensitive paths are guarded with #[cfg(not(target_arch = "wasm32"))].
• Persistence is intentionally unavailable on wasm32 in this crate build.
• WASM parity APIs include processSequence, exportToBytes, and importFromBytes.

Development Gates

cargo check --quiet
cargo test --all-features --quiet
cargo fmt --check --quiet
cargo clippy --quiet -- -D warnings

LOC policy: each source file in src/ must stay at or below 500 lines.

Mutation Testing

Install cargo-mutants once:

cargo install cargo-mutants

Run profiles:

scripts/mutation_test.sh fast
scripts/mutation_test.sh full

Reports are written under progress/mutation/.

Benchmark Gates

cargo bench --bench benchmark -- --save-baseline main
cargo bench --bench benchmark -- --baseline main

Primary perf gate: reservoir_step_50k < 100us.

License

MIT

Contributing

Contributions are welcome! Please read our Contributing Guide for:

• Code style and linting requirements
• Test and benchmark commands
• Pull request process
• ADR submission for architectural changes