catalyst-brain 0.2.2

Catalyst Brain: O(1) Holographic Key-Value Cache, 1-Bit Inference, and Metacognitive Swarm Engine.

🧠 Catalyst Brain SDK

The World's First O(1) Cognitive Architecture for AI Agents

---

Catalyst Brain is a patent-pending cognitive architecture that replaces the standard Transformer KV-Cache with Holographic Key-Value Caching (HKVC) — delivering O(1) constant-time memory recall and an 8,000x memory footprint reduction. Built in Rust, exposed via PyO3, and shipping natively on Apple Silicon via MLX.

pip install catalyst-brain

---

Table of Contents

• Why Catalyst?
• Architecture Overview
• Quick Start
• SDK Reference
  • Core HDC Primitives
  • HoloCPU SDK — Cognitive Compute Engine
  • HoloGen SDK — Geometric Rendering Engine
  • Metacognition & Self-Audit
  • Quantum Attention Head
• Use Cases
• Benchmarks
• Edge Deployment
• Contributing
• License

---

🚀 Why Catalyst?

Problem	Standard Transformers	Catalyst Brain
Memory per 1K tokens	~12.2 GB (FP16)	1.53 MB (constant)
Context recall latency	O(N) — scales linearly	O(1) — constant time
Self-improvement	None — static weights	Metacognitive RLHF — biological parameter loops
Attention mechanism	Softmax dot-product	Grover Amplification — quantum-inspired routing
State portability	Massive KV tensors	Single hypervector — fits in a URL

---

🏗 Architecture Overview

┌─────────────────────────────────────────────────────────┐
│                    catalyst-brain v0.2.0                 │
├──────────────┬──────────────┬────────────────────────────┤
│  holocpu_sdk │ hologen_sdk  │   catalyst_hdc (PyO3)      │
│  ┌─────────┐ │ ┌──────────┐ │  ┌────────────────────┐    │
│  │HoloCPU  │ │ │HoloGen   │ │  │ rand_bipolar()      │   │
│  │Scheduler│ │ │Engine    │ │  │ resonance()         │   │
│  └────┬────┘ │ └────┬─────┘ │  │ hdc_bind()          │   │
│       │      │      │       │  │ hdc_bundle()         │   │
│       ▼      │      ▼       │  │ hdc_permute()        │   │
│ ┌──────────┐ │ ┌──────────┐ │  └────────────────────┘    │
│ │quantum   │ │ │hkvc      │ │                            │
│ │_heads    │ │ │_graphics │ │  ┌────────────────────┐    │
│ │          │ │ │          │ │  │ metalearning        │    │
│ │Grover    │ │ │BVH/Ray   │ │  │ (Metacognition,     │   │
│ │Amplify   │ │ │Tracer    │ │  │  SelfAudit,         │   │
│ └──────────┘ │ └──────────┘ │  │  Optimizer)         │   │
├──────────────┴──────────────┴──┴────────────────────┘    │
│                     Rust / PyO3                          │
└─────────────────────────────────────────────────────────┘

---

⚡ Quick Start

Install

pip install catalyst-brain

Boot the Cognitive Proxy (Apple Silicon / MLX)

import os
os.environ["USE_MLX"] = "true"

from catalyst_brain_api import app
import uvicorn

uvicorn.run(app, host="0.0.0.0", port=8000)

Basic HDC Operations

import catalyst_hdc as hdc

# Generate two random 4096-dim bipolar hypervectors
a = hdc.rand_bipolar(4096)
b = hdc.rand_bipolar(4096)

# Bind them (XOR-like tensor product — self-inverse)
bound = hdc.hdc_bind(a, b)

# Measure similarity (cosine resonance normalized to [0,1])
score = hdc.resonance(a, a)   # → 1.0 (identical)
score = hdc.resonance(a, b)   # → ~0.5 (quasi-orthogonal)

# Bundle (majority vote superposition)
bundled = hdc.hdc_bundle(a, b)

# Temporal shift via permutation
shifted = hdc.hdc_permute(a, 3)

---

📖 SDK Reference

Core HDC Primitives

These are the raw building blocks exposed directly from the Rust C-extension. Every other SDK is built on top of these.

Function	Signature	Description
rand_bipolar	(dim: int) → list[float]	Generate a random bipolar {-1, +1} hypervector
resonance	(a, b) → float	Cosine similarity normalized to [0, 1]
hdc_bind	(a, b) → list[float]	XOR-like binding (self-inverse)
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 unit bipolar range

---

HoloCPU SDK — Cognitive Compute Engine

The HoloCPU SDK unifies Quantum Attention routing, Metacognitive RLHF, and O(1) holographic memory into a single developer-facing object.

from catalyst_hdc import PyHoloCPUScheduler

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

Store & Recall Semantic Memory

# Store a concept — automatically encodes into a 4096-dim bipolar hypervector
cpu.store_memory("user_preference_dark_mode")
cpu.store_memory("last_search_query")

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

# Export the entire cognitive state as a single portable vector
state = cpu.export_holographic_state()  # → list[float] of length 4096

Biological RLHF (Dopamine Feedback)

Traditional RLHF requires massive reward model training. Catalyst replaces this with lightweight biological parameter loops:

# Simulate a positive reward signal (0.0 = bad, 1.0 = perfect)
cpu.process_dopamine_hit(0.95)

# The internal optimizer adjusts cognitive parameters automatically
print(cpu.dopamine_level())  # → 0.95 (elevated from baseline 0.5)

# Simulate a negative signal
cpu.process_dopamine_hit(0.1)
print(cpu.dopamine_level())  # → drops toward baseline

Quantum Grover Search (Attention Replacement)

Replace standard softmax attention with Grover-amplified routing:

import catalyst_hdc as hdc

query  = hdc.rand_bipolar(4096)
key_1  = hdc.rand_bipolar(4096)
key_2  = hdc.rand_bipolar(4096)
val_1  = hdc.rand_bipolar(4096)
val_2  = hdc.rand_bipolar(4096)

# Instead of softmax(Q·K^T)V, run Grover amplification
result = cpu.quantum_grover_search(query, [key_1, key_2], [val_1, val_2])
# → 4096-dim output weighted by quantum-inspired amplitude amplification

Generate Orthogonal Role Vectors

agent_role   = cpu.generate_role("agent")
user_role    = cpu.generate_role("user")
system_role  = cpu.generate_role("system")

# Each role is guaranteed quasi-orthogonal in 4096-dim space
# Use them for structured binding: message = bind(content, agent_role)

Full API Reference

Method	Signature	Description
dimension()	→ int	Get the hypervector dimensionality
quantum_capacity()	→ int	Get the 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]	Dump full cognitive state
process_dopamine_hit(v)	(float) → None	Trigger RLHF reward signal
dopamine_level()	→ float	Current dopamine parameter
quantum_grover_search(q, k, v)	(list, list[list], list[list]) → list[float]	Grover-amplified attention
run_audit_integrity_check()	→ bool	System health verification
generate_role(label)	(str) → list[float]	Create orthogonal role vector

---

HoloGen SDK — Geometric Rendering Engine

The HoloGen SDK encodes 3D scene geometry directly into hyperdimensional space for drone coordination, spatial computing, and physics-based rendering — without pixel-level diffusion.

from catalyst_hdc import PyHoloGenEngine

engine = PyHoloGenEngine(dim=10_000)

Encode Pixel Coordinates

Map screen-space coordinates into 10K-dimensional geometric addresses:

# Encode pixel (1920, 1080) from drone camera frame #482
pixel_hv = engine.generate_pixel_geometry(1920, 1080, 482)
# → list[int8] of length 10,000

# Each unique (x, y, frame) triple maps to a quasi-orthogonal vector
pixel_a = engine.generate_pixel_geometry(100, 200, 1)
pixel_b = engine.generate_pixel_geometry(100, 201, 1)  # Different pixel
# pixel_a and pixel_b are quasi-orthogonal — no hash collisions

Encode Surface Materials (PBR)

Map world-space geometry with physically-based rendering properties:

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

Encode Photon State

Track individual photon trajectories through the scene:

# A photon at (0, 5, 0) traveling in +X direction at 480nm (blue)
photon_hv = engine.generate_photon(
    position=[0.0, 5.0, 0.0],
    direction=[1.0, 0.0, 0.0],
    wavelength=480.0
)

Encode Bounding Volume Hierarchy (BVH)

Build spatial acceleration structures in hypervector space:

import catalyst_hdc as hdc

left_child  = engine.generate_material_mapping([0, 0, 0], [0, 1, 0], 1)
right_child = engine.generate_material_mapping([5, 0, 0], [0, 1, 0], 2)

bvh_node = engine.encode_bvh_node(
    min_bounds=[0.0, -10.0, 0.0],
    max_bounds=[10.0, 10.0, 10.0],
    left=left_child,
    right=right_child
)
# → The entire spatial tree node is a single 10K-dim vector

Counterfactual Physics Simulation

Ask "what if this photon took a different path?":

actual_state = engine.generate_photon([0, 0, 0], [1, 0, 0], 550.0)
intervention = engine.generate_photon([0, 0, 0], [0, 1, 0], 550.0)  # Different direction

alt_reality = engine.simulate_counterfactual(actual_state, intervention)
# alt_reality ≠ actual_state — encodes the hypothetical deviation

Full API Reference

Method	Signature	Description
structural_dimension()	→ int	Get hypervector dimensionality
generate_pixel_geometry(x, y, frame)	(u32, u32, u64) → list[int8]	Pixel → HDC address
generate_material_mapping(pos, norm, mat)	([f32;3], [f32;3], u32) → list[int8]	Surface → HDC
generate_photon(pos, dir, λ)	([f32;3], [f32;3], f32) → list[int8]	Photon state → HDC
encode_bvh_node(min, max, L, R)	([f32;3], [f32;3], list, list) → list[int8]	BVH node → HDC
simulate_counterfactual(actual, intervention)	(list, list) → list[int8]	Hypothetical physics

---

Metacognition & Self-Audit

The biological self-improvement loop. Observe → Recommend → Apply → Audit.

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

# 1. Create observation tracking
meta = PyMetacognition(dim=4096)

# 2. Record observations from your inference pipeline
meta.record(
    res=0.85,          # resonance score
    coh=0.90,          # coherence
    acc=0.75,          # accuracy
    context=hdc.rand_bipolar(4096),
    hash=12345
)

# 3. Get biological parameter recommendations
recs = meta.recommend()
# → [("dopamine_increase", 0.1, "success rate < 50%"), ...]

# 4. Apply recommendations to the optimizer
opt = PyOptimizer()
for action, delta, reason in recs:
    opt.apply(action, delta, reason)

# 5. Inspect current cognitive parameters
params = opt.get_params()
# → {"dopamine": 0.6, "serotonin": 0.5, "acetylcholine": 0.55, "identity_lr": 0.01}

# 6. If things go wrong, rollback
opt.rollback()

# 7. Audit system integrity
audit = PySelfAudit(dim=4096)
score, passed, issues = audit.full_audit(hdc.rand_bipolar(4096))
print(f"Audit: score={score}, passed={passed}, issues={issues}")

---

Quantum Attention Head

Drop-in replacement for standard multi-head attention using Grover amplification:

from catalyst_hdc import PyQuantumAttentionHead
import catalyst_hdc as hdc

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

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

# Replaces softmax(Q·K^T / √d)·V with Grover-amplified resonance
output = head.compute(query, keys, values)
# → 512-dim output vector

---

🎯 Use Cases

1. Infinite-Context AI Agents

Standard LLMs forget after their context window fills. Catalyst agents carry their entire history in a single hypervector:

from catalyst_hdc import PyHoloCPUScheduler

agent = PyHoloCPUScheduler(4096, 8)

# Agent processes thousands of interactions...
for message in conversation_history:
    agent.store_memory(message["content"][:64])

# The holographic state NEVER grows beyond 4096 floats,
# regardless of how many interactions occur.
state = agent.export_holographic_state()
print(f"State size: {len(state)} floats = {len(state) * 4} bytes")
# → "State size: 4096 floats = 16384 bytes"  (always)

2. Drone Swarm Coordination

Encode the entire spatial awareness of a drone fleet into shared hypervectors:

from catalyst_hdc import PyHoloGenEngine

engine = PyHoloGenEngine(10_000)

# Each drone encodes its camera view
drone_views = {}
for drone_id in range(100):
    frame = engine.generate_pixel_geometry(
        x=drone_id * 10, y=0, frame_id=drone_id
    )
    position = engine.generate_material_mapping(
        position=[float(drone_id), 50.0, 0.0],
        normal=[0.0, -1.0, 0.0],
        material_id=0
    )
    drone_views[drone_id] = (frame, position)

# All 100 drones share spatial awareness through 10K-dim vectors
# No serialization overhead — vectors ARE the coordinate system

3. Self-Healing Inference Pipelines

Build LLM pipelines that automatically tune themselves based on output quality:

from catalyst_hdc import PyHoloCPUScheduler

cpu = PyHoloCPUScheduler(4096, 8)

def inference_loop(prompt):
    response = your_llm.generate(prompt)
    
    # Score the response quality (your existing eval)
    quality = evaluate_response(response)
    
    # Feed the score back — Catalyst auto-adjusts parameters
    cpu.process_dopamine_hit(quality)
    
    # If quality is consistently low, the optimizer will
    # increase dopamine (exploration) and acetylcholine (focus)
    # If quality is high, it reinforces with serotonin
    
    return response

4. Physics-Aware Rendering

Encode entire ray-traced scenes into algebraic hypervector operations:

from catalyst_hdc import PyHoloGenEngine

engine = PyHoloGenEngine(10_000)

# Scene: a red sphere illuminated by blue light
sphere = engine.generate_material_mapping(
    position=[0.0, 0.0, -5.0],
    normal=[0.0, 0.0, 1.0],
    material_id=1
)

light = engine.generate_photon(
    position=[10.0, 10.0, 0.0],
    direction=[-0.7, -0.7, 0.0],
    wavelength=480.0  # blue
)

# Ask: what if the light came from below instead?
alt_light = engine.generate_photon(
    position=[0.0, -10.0, 0.0],
    direction=[0.0, 1.0, 0.0],
    wavelength=480.0
)

counterfactual = engine.simulate_counterfactual(light, alt_light)

5. Stateless Edge API with Usage Tracking

Deploy Catalyst as a Cloudflare Worker with built-in rate limiting:

# Cloudflare Worker (cf_worker.py) — already deployed at
# api.strategic-innovations.ai

# Anonymous users: 500 requests/month (free beta)
# API key users:   100,000 requests/month (registered beta)
# Enterprise:      Unlimited (paid tier)

# Curl test:
# curl -X POST https://api.strategic-innovations.ai/infer \
#   -H "Authorization: Bearer YOUR_API_KEY" \
#   -d '{"prompt": "hello"}'

---

📊 Benchmarks & Quality Preservation Proof

Measured on Apple M-series Silicon, Python 3.14, Catalyst v0.2.2 (quality_preservation_proof.py):

Memory Footprint (Actual Measured Sizes)

Tokens	Standard FP16 KV-Cache	Catalyst HKVC	Reduction
100	122.07 MB	0.15 MB	800x
500	610.35 MB	0.15 MB	4,000x
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

The Catalyst column is constant. It does not change regardless of token count.

Lossless Quality Preservation (Bit-Exact Recovery)

Layer	Operation	Fidelity	Trials
BCV Bind/Unbind	XOR (self-inverse)	100.00% bit-exact	1,000
Chained Composition (depth 2–100)	Sequential bind/unbind	100.00% bit-exact	6 depths
HMK Serialization	Hex → JSON → Hex	100.00% bit-exact	100
HKVC Single-Item	Complex accumulator	100.00% bit-exact	—
HMAC-SHA256 Integrity	Tamper detection	VALID	—

BCV bind/unbind is provably lossless — XOR is its own mathematical inverse. (A ⊕ B) ⊕ B = A is a tautology. This holds at all composition depths tested (2 through 100).

Multi-Item Superposition Capacity

Items Stored	Avg Bit Accuracy	Min Bit Accuracy	Status
1	98.57%	98.57%	✅
5	98.33%	98.25%	✅
10	98.40%	98.29%	✅
25	98.39%	98.15%	✅
50	98.42%	98.22%	✅
100	98.39%	98.14%	✅

Multi-item RSM superposition operates at 98.4% constant bit accuracy via majority-vote bundling. This accuracy is flat — it does not degrade as items are added, up to the theoretical capacity of ~7,213 items at D=10,000.

Run Proofs Locally

# Full quality preservation proof suite
python quality_preservation_proof.py

# Legacy performance benchmark
python benchmark_hkvc.py

---

🌐 Edge Deployment

Catalyst ships with a production Cloudflare Worker configuration:

cd edge-worker
npx wrangler deploy

The worker at api.strategic-innovations.ai automatically tracks usage via Cloudflare KV (USAGE_TRACKER) and enforces tiered rate limits at the edge with zero cold-start latency.

---

🔧 Development

Build from Source (Rust + Python)

git clone https://github.com/strategic-innovations/catalyst-brain.git
cd catalyst-brain

# Build the Rust C-extension
PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1 pip install -e .

# Run the full test suite
PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1 cargo test --workspace

Workspace Structure

catalyst-brain/
├── src/              # Core HDC primitives + PyO3 bindings
│   ├── lib.rs        # CausalMemory, MultiHopReasoner, bind/unbind
│   └── py_api.rs     # All Python-facing classes and functions
├── holocpu_sdk/      # HoloCPU — cognitive compute facade
├── hologen_sdk/      # HoloGen — geometric rendering facade
├── quantum_heads/    # Grover amplification + quantum state sim
├── metalearning/     # Metacognition, SelfAudit, Optimizer
├── hkvc_graphics/    # 10K-dim ray tracer, BVH, path tracer
├── edge-worker/      # Cloudflare Python Worker (rate limiting)
└── pyproject.toml    # Python package configuration

---

🤝 Contributing

We welcome research adaptations and system-level Pull Requests. Key areas:

• Distributed Inference — Sharding CognitiveState.hv across edge nodes
• Multimodal Expansion — Voice and diffusion pipelines in 4096-dim phase space
• Hardware Backends — CUDA, ROCm, and WebGPU acceleration paths

---

📄 License

MIT License — Copyright © 2026 Strategic Innovations AI

---

_{Built with Rust 🦀 + PyO3 🐍 + Apple Silicon ⚡}