catalyst-brain 1.3.0

Catalyst Brain: O(1) Holographic Key-Value Cache, Quantum Attention, and Metacognitive Engine.

Catalyst Brain SDK

O(1) Holographic Memory, Grover-Amplified Attention, and Metacognitive Self-Improvement

---

catalyst-brain is a Rust+PyO3 SDK providing hyperdimensional computing (HDC) primitives for AI systems. Install from PyPI:

pip install catalyst-brain

Then import the SDK:

import catalyst_hdc as hdc

# Core HDC primitives
a = hdc.rand_bipolar(4096)
b = hdc.rand_bipolar(4096)
score = hdc.resonance(a, b)     # → ~0.5 for quasi-orthogonal vectors
bound = hdc.hdc_bind(a, b)      # XOR-like binding (self-inverse)
bundled = hdc.hdc_bundle(a, b)  # majority-vote superposition
shifted = hdc.hdc_permute(a, 3) # circular shift

# O(1) cognitive memory
from catalyst_hdc import PyHoloCPUScheduler
cpu = PyHoloCPUScheduler(dim=4096, quantum_capacity=8)
cpu.store_memory("user_pref_dark_mode")
assert cpu.recall("user_pref_dark_mode") == True
cpu.process_feedback(0.95)
print(cpu.feedback_strength())  # → 0.95

---

SDK Reference

Core HDC Primitives

Raw hypervector algebra. All other SDK classes are built on these.

Function	Signature	Description
rand_bipolar	(dim: int) → list[float]	Random {−1, +1} hypervector
resonance	(a, b) → float	Cosine similarity normalized to [0, 1]
hdc_bind	(a, b) → list[float]	XOR-like binding (self-inverse: bind(bind(a,b),b) == a)
hdc_bundle	(a, b) → list[float]	Majority-vote superposition
hdc_permute	(v, n) → list[float]	Circular shift by n positions
normalise_bipolar	(v) → list[float]	Normalize to bipolar range

a = hdc.rand_bipolar(4096)
b = hdc.rand_bipolar(4096)

# Self-inverse binding (XOR)
assert hdc.resonance(a, b) > 0.4          # quasi-orthogonal
bound = hdc.hdc_bind(a, b)
recovered = hdc.hdc_bind(bound, b)
assert hdc.resonance(a, recovered) > 0.99  # a ⊕ (a ⊕ b) = b (bit-exact)

# Bundle N vectors using reduce
from functools import reduce
vectors = [hdc.rand_bipolar(4096) for _ in range(4)]
superposition = reduce(hdc.hdc_bundle, vectors)

---

HoloCPU SDK — Cognitive Compute Engine

O(1) semantic memory with Grover-amplified attention routing.

from catalyst_hdc import PyHoloCPUScheduler
import catalyst_hdc as hdc

cpu = PyHoloCPUScheduler(dim=4096, quantum_capacity=8)

Memory

# Store and recall — O(1) regardless of how many memories exist
cpu.store_memory("user_preference_dark_mode")
cpu.store_memory("last_query")

assert cpu.recall("user_preference_dark_mode") == True
assert cpu.recall("nonexistent_key") == False

# Export entire cognitive state as a single 4096-float hypervector (16 KB constant)
state = cpu.export_holographic_state()
assert len(state) == 4096  # always 16 KB

Outcome Feedback

# Signal quality of an inference result (0.0 = bad, 1.0 = perfect)
cpu.process_feedback(0.95)   # positive outcome
print(cpu.feedback_strength())  # → 0.95 (elevated from baseline 0.5)

cpu.process_feedback(0.1)    # negative outcome
print(cpu.feedback_strength())  # → drops toward baseline

Grover-Amplified Attention

# quantum_grover_search takes a hypervector query + lists of key/value hypervectors
query = hdc.rand_bipolar(4096)
keys  = [hdc.rand_bipolar(4096) for _ in range(8)]
values = [hdc.rand_bipolar(4096) for _ in range(8)]

output = cpu.quantum_grover_search(query, keys, values)
# Returns a 4096-dim output vector from Grover-amplified routing
assert len(output) == 4096

Role Vectors

# Generate orthogonal role hypervectors for structured binding
agent   = cpu.generate_role("agent")
user    = cpu.generate_role("user")
system  = cpu.generate_role("system")

# Use for structured message encoding: message = bind(content, agent_role)

API Reference

Method	Signature	Description
dimension()	→ int	Hypervector dimensionality
quantum_capacity()	→ int	Qubit depth
store_memory(key)	(str) → None	Encode and store a semantic key
recall(key)	(str) → bool	O(1) key existence check
export_holographic_state()	→ list[float]	Full state as 4096 floats (16 KB)
process_feedback(signal)	(float) → None	Outcome feedback signal (0.0–1.0)
feedback_strength()	→ float	Current feedback strength
quantum_grover_search(query, keys, values)	(Vec, list[Vec], list[Vec]) → list[float]	Grover attention
run_audit_integrity_check()	→ bool	System health check
generate_role(label)	(str) → list[float]	Orthogonal role vector

---

HoloGen SDK — Geometric Hypervector Engine

Encode 3D geometry, materials, and photon states directly into hypervector space.

from catalyst_hdc import PyHoloGenEngine

engine = PyHoloGenEngine(dim=10_000)

Pixel Geometry

# Map screen coordinates to hypervector addresses
pixel_hv = engine.generate_pixel_geometry(64, 64)
# → list[int8], quasi-orthogonal per unique (x, y) pair

pixel_a = engine.generate_pixel_geometry(100, 200)
pixel_b = engine.generate_pixel_geometry(100, 201)  # adjacent pixel
# pixel_a and pixel_b are quasi-orthogonal — no hash collisions

Surface Materials

# A metallic surface at position (10, 0, 5) facing upward
surface_hv = engine.generate_material_mapping(
    position=[10.0, 0.0, 5.0],  # [f32; 3]
    normal=[0.0, 1.0, 0.0],     # surface normal [f32; 3]
    material_id=42
)

Photon State

# Form 1: encode photon color as a semantic hypervector
photon_hv = engine.generate_photon("blue")
# Supported: "violet"/"purple", "blue", "cyan", "green", "yellow",
# "amber"/"orange", "red", "white".

# Form 2: full geometric form
photon_hv = engine.generate_photon(
    [0.0, 5.0, 0.0],   # position [f32; 3]
    [1.0, 0.0, 0.0],   # direction [f32; 3]
    480.0,             # wavelength (nm)
)

BVH Nodes

# encode_bvh_node(min_bounds, max_bounds, left_hv, right_hv)
# left_hv and right_hv must be bipolar hypervectors as list[int8]
# Convert: [int(x) for x in hdc.rand_bipolar(dim)]

left_hv  = [int(x) for x in hdc.rand_bipolar(4096)]
right_hv = [int(x) for x in hdc.rand_bipolar(4096)]

bvh_node = engine.encode_bvh_node(
    [0.0, -10.0, 0.0],   # min_bounds [f32; 3]
    [10.0, 10.0, 10.0],  # max_bounds [f32; 3]
    left_hv,
    right_hv,
)

Counterfactual Physics

# Ask "what if this photon took a different path?"
# Inputs may be either bipolar i8 hypervectors or any object that stringifies
# (the latter is hashed deterministically into a hypervector of dim D).
actual_state = "jump→reward"
intervention = "crouch→reward"

alt_reality = engine.simulate_counterfactual(actual_state, intervention)
# Returns hypervector encoding hypothetical deviation (list[int8] of length D)

API Reference

Method	Signature	Description
structural_dimension()	→ int	Hypervector dimensionality
generate_pixel_geometry(x, y, frame_id=None)	(u32, u32, Optional[u64]) → list[int8]	Pixel coords → HDC address. frame_id defaults to 0.
generate_material_mapping(position, normal, material_id)	([f32;3], [f32;3], u32) → list[int8]	Surface → HDC
generate_photon(color)	(str) → list[int8]	Color string → HDC. Also accepts (position, direction, wavelength) as the geometric form.
encode_bvh_node(min_bounds, max_bounds, left_hv, right_hv)	([f32;3], [f32;3], Vec<i8>, Vec<i8>) → list[int8]	BVH node
simulate_counterfactual(state, intervention)	(Any, Any) → list[int8]	Counterfactual physics. Args are either bipolar i8 vectors or any stringifiable object (hashed to a vector).

---

Metacognition & Self-Audit

Self-improvement loop: observe → recommend → apply → audit.

from catalyst_hdc import PyMetacognition, PyOptimizer, PySelfAudit
import catalyst_hdc as hdc

meta = PyMetacognition(dim=4096)

Record Observations

# Record inference outcomes with resonance, coherence, accuracy
hv = hdc.rand_bipolar(4096)
meta.record(res=0.85, coh=0.90, acc=0.75, context=hv, hash=12345)
meta.record(res=0.92, coh=0.88, acc=0.81, context=hv, hash=12346)
meta.record(res=0.61, coh=0.72, acc=0.55, context=hv, hash=12347)

Query State

print(f"success_rate:  {meta.success_rate():.3f}")   # ratio of high-resonance successes
print(f"avg_resonance: {meta.avg_resonance():.3f}")  # mean resonance score
recs = meta.recommend()
# → [("momentum_increase", 0.05, "success rate > 80%, reinforce"), ...]

Apply Recommendations

opt = PyOptimizer()
opt.apply("momentum_increase", 0.05, "success rate above 80%")
params = opt.get_params()
# → {"learning_rate": 0.6, "momentum": 0.5, "attention_weight": 0.55, "identity_lr": 0.01}
opt.rollback()  # revert last parameter change

Audit Integrity

audit = PySelfAudit(dim=4096)
hv = hdc.rand_bipolar(4096)
score, passed, issues = audit.full_audit(hv)
# → score=1.0, passed=True, issues=[]

API Reference

Class	Method	Signature	Description
PyMetacognition	record(res, coh, acc, context, hash)	(float, float, float, Vec, u64)	Log observation
PyMetacognition	success_rate()	→ float	Ratio of high-res successes
PyMetacognition	avg_resonance()	→ float	Mean resonance
PyMetacognition	recommend()	→ list[tuple]	Parameter recommendations
PyOptimizer	apply(action, delta, reason)	(str, float, str)	Apply parameter delta
PyOptimizer	get_params()	→ dict	Current parameters
PyOptimizer	rollback()	→ None	Revert last change
PySelfAudit	full_audit(hv)	(Vec) → (float, bool, list)	Integrity check

---

Quantum Attention Head

Drop-in replacement for standard softmax attention using Grover-amplified routing.

from catalyst_hdc import PyQuantumAttentionHead
import catalyst_hdc as hdc

head = PyQuantumAttentionHead(dim=512, nqubits=40)

query  = hdc.rand_bipolar(512)
keys   = [hdc.rand_bipolar(512) for _ in range(10)]
values = [hdc.rand_bipolar(512) for _ in range(10)]

output = head.compute(query, keys, values)
# Returns 512-dim output vector

Method	Signature	Description
compute(query, keys, values)	(Vec, list[Vec], list[Vec]) → list[float]	Grover attention

Note: amplify() does not exist as a standalone method. Grover amplification for large memory stores is implemented inside PyHoloCPUScheduler.quantum_grover_search(). PyQuantumAttentionHead is for fine-grained per-layer attention.

---

HoloSwarm — Multi-Agent Spectral Synthesis

Superpose an arbitrary number of agents (Role ⊗ Policy ⊗ Skill) into a single hypervector and tune into any one of them at query time via iterative resonance decomposition.

from catalyst_hdc import PyHoloSwarm
import catalyst_hdc as hdc

swarm = PyHoloSwarm(dim=4096)

# Register agents — each compound is permuted before bundling
# to de-correlate overlapping roles.
swarm.add_agent(
    role="planner",   r_hv=hdc.rand_bipolar(4096),
    policy="explore", p_hv=hdc.rand_bipolar(4096),
    skill="search",   s_hv=hdc.rand_bipolar(4096),
)
swarm.add_agent(
    role="executor",  r_hv=hdc.rand_bipolar(4096),
    policy="exploit", p_hv=hdc.rand_bipolar(4096),
    skill="tool_use", s_hv=hdc.rand_bipolar(4096),
)

# Decompose: given a role key, recover policy + skill via iterative unbinding
role, policy, skill, confidence = swarm.resonate(
    role_key="planner",
    p_guess=hdc.rand_bipolar(4096),
    s_guess=hdc.rand_bipolar(4096),
    max_iter=10,
)

# Probe which agents are active in a semantic sector
active = swarm.materialize(probe=hdc.rand_bipolar(4096), threshold=0.6)
# → [("planner", 0.73), ...]

Method	Signature	Description
add_agent(role, r_hv, policy, p_hv, skill, s_hv)	(str, Vec, str, Vec, str, Vec) → None	Superpose Role ⊗ Policy ⊗ Skill into swarm
add_paradox_trap(names, roles, keys)	(list[str], list[Vec], list[Vec]) → None	Recursive causal-loop trap (HoloSec)
resonate(role_key, p_guess, s_guess, max_iter)	→ tuple[str,str,str,float]	Decompose swarm into (role, policy, skill, confidence)
materialize(probe, threshold)	(Vec, float) → list[tuple[str,float]]	Find agents resonating above threshold
get_swarm_vector()	→ list[float]	Raw composite hypervector

---

PyHKVC — Holographic Key-Value Cache

O(1) recency-unbiased KV cache using complex-domain phase accumulation. All entries contribute equal representational weight regardless of insertion order — no recency bias.

from catalyst_hdc import PyHKVC

cache = PyHKVC(dim=1024)

# Store key-value pairs at sequence positions
cache.store("question:capital_france", "Paris", position=0)
cache.store("question:capital_japan",  "Tokyo", position=1)
cache.store("question:capital_uk",     "London", position=2)

# O(1) retrieval: HashMap lookup → phase-domain resonance
value, score = cache.query("question:capital_france")
# → ("Paris", 0.94)

print(cache.count())  # → 3

Method	Signature	Description
store(key, value, position)	(str, str, int) → None	Insert key-value at position
query(query_key)	(str) → tuple[str, float]	Retrieve (value, confidence)
count()	→ int	Number of stored entries
position_score(position)	(int) → float	Recency-bias diagnostic (should be ≈constant)
accumulator_magnitude()	→ list[float]	Raw complex accumulator magnitudes

---

CausalMemory & MultiHopReasoner

Store causal relationships as hypervector triples and query them holographically.

from catalyst_hdc import PyCausalMemory, PyMultiHopReasoner
import catalyst_hdc as hdc

# CausalMemory: cause → effect temporal chains
mem = PyCausalMemory(dim=4096)

t0 = hdc.rand_bipolar(4096)   # time-role HV
cause  = hdc.rand_bipolar(4096)
effect = hdc.rand_bipolar(4096)

mem.store(cause, effect, t0)

recovered_effect = mem.recall_effect(cause)   # → list[float] or None
recovered_causes = mem.recall_cause(effect)   # → list[list[float]]
by_time          = mem.recall_by_time(t0)     # → list[float] or None

# MultiHopReasoner: traverse fact graphs up to N hops
reasoner = PyMultiHopReasoner(dim=4096)

f0 = reasoner.add_fact(hdc.rand_bipolar(4096))   # → index 0
f1 = reasoner.add_fact(hdc.rand_bipolar(4096))   # → index 1
reasoner.add_link(f0, f1)

query = hdc.rand_bipolar(4096)
results = reasoner.reason(query, hops=2)
# → [(fact_index, resonance_score), ...] sorted by resonance descending

Class	Method	Description
PyCausalMemory	store(cause, effect, time)	Record a causal triple
PyCausalMemory	recall_effect(cause)	Retrieve effect for a cause
PyCausalMemory	recall_cause(effect)	Retrieve all causes for an effect
PyCausalMemory	recall_by_time(time)	Retrieve effect at a time
PyMultiHopReasoner	add_fact(hv)	Register a fact, returns index
PyMultiHopReasoner	add_link(a, b)	Undirected association between facts
PyMultiHopReasoner	reason(query, hops)	Multi-hop resonance query

---

Rain Protocol — Stateless Agent State Transfer

Rain v2 is a binary-first wire protocol for transferring HDC agent state between serverless invocations. Instead of a database or JSON tokens, agents exchange compact .rain binaries carrying their holographic world vector, causal edges, and Hebbian weights.

Wire format (48-byte header + zlib payload):

[RAIN 4B][version u16 BE][flags u16 BE][dim u32 BE][n_edges u32 BE][sha256 32B][compressed body]

from catalyst_brain import RainPayload, rain_dumps, rain_loads
from catalyst_brain.rain import merge_digests, RainDigest, to_header, from_header
import catalyst_hdc as hdc

# Serialize agent state to .rain bytes
wv = hdc.rand_bipolar(10_000)
payload = RainPayload(
    agent_id="swarm-lead",
    dim=10_000,
    world_vector=wv,
)
blob = rain_dumps(payload)       # compact binary, SHA-256 verified
print(len(blob))                 # ≪ 100 KB even for 10k-dim vectors

# Round-trip
restored = rain_loads(blob)
assert restored.agent_id == "swarm-lead"
assert len(restored.world_vector) == 10_000

File I/O

from catalyst_brain.rain import dump, load

dump(payload, "checkpoint.rain")
restored = load("checkpoint.rain")

HTTP Header Transfer

Pass agent state between serverless functions without a database:

# Agent A — encode state into request header
header_value = to_header(payload)
# → base64 string, drop into X-Rain-State header

# Agent B — recover state on the other side
incoming = from_header(request.headers["X-Rain-State"])
resume_from(incoming.world_vector)

Holographic Digest Merge

Combine knowledge from N specialist agents into one vector without exposing underlying data:

digest_a = RainDigest(agent_id="specialist-A", vector=hdc.rand_bipolar(4096))
digest_b = RainDigest(agent_id="specialist-B", vector=hdc.rand_bipolar(4096))

merged = merge_digests([digest_a, digest_b])
# → RainDigest with bundled (majority-vote) world vector

Function	Signature	Description
rain_dumps(payload)	(RainPayload) → bytes	Serialize to .rain binary
rain_loads(data)	(bytes) → RainPayload	Deserialize from .rain binary
dump(payload, path)	(RainPayload, str|Path) → None	Write .rain file
load(path)	(str|Path) → RainPayload	Read .rain file
to_header(payload)	(RainPayload) → str	Base64 encode for X-Rain-State header
from_header(value)	(str) → RainPayload	Decode X-Rain-State header
merge_digests(digests)	(list[RainDigest]) → RainDigest	Algebraic knowledge merge

---

Benchmarks

Memory Footprint

Catalyst state is constant — it never grows with token count.

Tokens	Standard FP16 KV-Cache	Catalyst HKVC	Reduction
1,000	1,220.70 MB	0.15 MB	8,000x
5,000	6,103.52 MB	0.15 MB	40,000x
10,000	12,207.03 MB	0.15 MB	80,000x

Bit-Exact Recovery

Bind/unbind is provably lossless — XOR is its own inverse.

Operation	Fidelity	Tested depth
BCV bind/unbind	100.00% bit-exact	1,000 trials
Chained composition (depth 2–100)	100.00% bit-exact	6 depths
HMK serialization	100.00% bit-exact	100 trials

Multi-Item Superposition

Multi-item bundling maintains 98.4% constant bit accuracy regardless of item count (up to ~7,213 items at D=10,000).

Performance Benchmarks

All reproducible benchmarks are maintained in the open-source catalyst-benchmarks repository. See published results, methodology, and licensed-user instructions there.

---

Build from Source

# Requires Rust 1.75+ and Python 3.10+
git clone https://github.com/quantium-rock/catalyst-brain.git
cd catalyst-brain

# Install Python package (builds Rust extension via maturin)
pip install maturin
maturin develop --release

# Run tests (lib + integration + doc)
cargo test --workspace --all-targets

# Run lints
cargo clippy --workspace --all-targets --all-features -- -D warnings

# Build the WASM edge worker
rustup target add wasm32-unknown-unknown
cd demo/edge-worker && cargo check --target wasm32-unknown-unknown

---

Architecture

catalyst-brain/
├── src/
│   ├── lib.rs         # Core HDC: CausalMemory, bind/unbind, resonance,
│   │                  #   diagnostic_role, encode_system_state, bundle/extract
│   ├── py_api.rs      # PyO3 bindings: all Python-facing classes + functions
│   └── wasm_api.rs    # WASM bindings: WasmCausalMemory + free functions
├── catalyst_brain/    # Pure-Python companion package (shipped in the wheel)
│   ├── __init__.py    # Re-exports Rain API
│   └── rain.py        # Rain Protocol v2 — .rain binary state transfer
├── holocpu_sdk/       # O(1) scheduler + Grover search
├── hologen_sdk/       # Geometric encoding facade
├── quantum_heads/     # 26-gate quantum set + Grover attention head
├── metalearning/      # Metacognition, SelfAudit, Optimizer, LearningLog
├── hkvc_graphics/     # BVH, ray tracing, frame buffer, scheduler
├── demo/edge-worker/  # Cloudflare Worker (Rust → WASM) deployment
├── demo/dashboard/    # Vanilla HTML/CSS/JS monitoring dashboard
├── tests/             # Integration tests (diagnostic_role, etc.)
├── catalyst_hdc.pyi   # Python type stubs (PEP 561)
├── py.typed           # PEP 561 marker
├── CHANGELOG.md       # Release history
├── Cargo.toml         # Workspace manifest (version = "1.3.0")
└── pyproject.toml     # Python package config

---

Telemetry & Privacy

catalyst-brain collects anonymous usage data to help improve the SDK. No user data, vectors, labels, or model outputs are ever sent.

What is collected (all anonymous):

• SDK version, Python version, OS, CPU architecture
• A one-way hash of your machine's platform info (cannot be reversed)
• Which top-level feature was used and whether an exception occurred

Opt-out at any time:

export CATALYST_NO_TELEMETRY=1

Data is sent to a Cloudflare Worker endpoint over HTTPS in a background daemon thread and never blocks your code.

---

License

Research & Evaluation License v1.0 — see LICENSE file.

Use	Permitted?
Academic research	✅ Free
Personal experimentation	✅ Free
Benchmarking & evaluation	✅ Free
Publishing results (with attribution)	✅ Free
Production / commercial deployment	❌ Requires Commercial License
SaaS / hosted API	❌ Requires Commercial License

Patent: U.S. Provisional Patent Application CATALYST-2026-001 covers holographic key-value caching, BlockCodeVector binding, resonant superposition memory, and Grover-amplified attention routing.

Contact: [e-mail]

---

Copyright © 2026 Strategic Innovations AI. Built with Rust 🦀 + PyO3 🐍.