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

| Resource | Link | |----------|------| | Documentation | docs.rs/chaotic_semantic_memory | | Crates.io | crates.io/crates/chaotic_semantic_memory | | Issues | GitHub Issues | | Changelog | CHANGELOG.md |

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

For WASM targets, build with --target wasm32-unknown-unknown. No additional feature flag is needed; WASM support is enabled automatically when compiling for the wasm32 target architecture.

[dependencies]
chaotic_semantic_memory = { version = "0.2" }

Note: Using "0.2" ensures compatibility with the latest 0.2.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 (wasm32 target only)
• encoder: text and binary encoding utilities
• graph_traversal: graph walk and reachability utilities
• metadata_filter: metadata query and filtering
• bundle: snapshot and bundle helpers
• 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 --database memory.db

# 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

| Command | Description | |---------|-------------| | inject | Inject a new concept with a random or provided vector | | probe | Find similar concepts by concept ID | | associate | Create an association between two concepts | | export | Export memory state to JSON or binary | | import | Import memory state from file | | version | Show version information | | completions | Generate shell completions |

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.

| Parameter | Default | Valid Range | Effect | |---|---:|---|---| | reservoir_size | 50_000 | > 0 | Reservoir capacity and memory footprint | | reservoir_input_size | 10_240 | > 0 | Width of each sequence step | | chaos_strength | 0.1 | 0.0..=1.0 (recommended) | Noise amplitude in chaotic updates | | enable_persistence | true | boolean | Enables libSQL persistence setup | | max_concepts | None | optional positive | Evicts oldest concepts when reached | | max_associations_per_concept | None | optional positive | Keeps strongest associations only | | connection_pool_size | 10 | >= 1 | Turso/libSQL remote pool size | | max_probe_top_k | 10_000 | >= 1 | Input guard for probe and batch probes | | max_metadata_bytes | None | optional positive | Metadata payload size guard | | concept_cache_size | 1_000 | >= 1 | Similarity query cache capacity (set via with_concept_cache_size, stored separately from FrameworkConfig) |

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
cargo bench --bench persistence_benchmark -- --save-baseline main
cargo bench --bench persistence_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