← all documents · raw markdown · 10 KB

KAI — Systems Architecture Brief for Reinforcement-Learning Alignment

*Prepared so an external AI assistant can write RL scripts that match KAI's exact types, ports, and patterns. Repo root: C:\KAI. Crate version 9.8.7. Rust engine in src/, Node fleet in tools/oracle-discord/, Python at root.*

> Read this first: KAI has two distinct ternary systems — do not conflate them. (A) sparse ternary VSA memory vectors (the lattice), and (B) BitNet-1.58 LLM weights (the language decoder). They use different representations.

---

1. Ternary Implementation

A. Sparse ternary VSA vectors — the memory/lattice core (i8 primitives)

File: src/core/sparse_vec.rs

pub struct SparseVec {
    pub nz: Vec<u16>,    // sorted indices of active dimensions
    pub vals: Vec<i8>,   // parallel values, each -1 or +1 (0 = absent from nz)
    cached_norm: f32,    // sqrt(nnz)
}

B. BitNet-1.58 LLM weights — 2-bit packed, zero-multiply matmul

Files: src/cognition/ternary_math.rs, src/cognition/bitnet_brain.rs

---

2. State & Action Space

Hybrid: a continuous 16384-dim ternary vector substrate, but every action is discrete selection + graph update — not emitting a continuous action vector.

1. Candidate selection (discrete) — geometric top-N cell retrieval (NeuralBus::query_associative → universe.query_in_regions).

2. Synaptic propagation — boost associated cells.

3. Hebbian write (LTP) — record_co_firing wires the fired set together.

---

3. Language Boundaries (definitive)

All cross-language communication is plain HTTP/REST over localhost TCP + child_process spawning. There is NO PyO3, NO napi-rs, NO WebAssembly, NO gRPC, NO active file-IPC. (Confirmed: Cargo.toml has no pyo3/napi/tonic/axum/actix/hyper; package.json has no napi/neon/ffi.)

Implication for RL scripts: the cleanest integration is HTTP to :3334 (any language). A Python RL loop posts goal/query vectors and reads back hits + field metrics — no FFI needed.

---

4. Existing Core Code (verbatim patterns to match)

(a) Structs — sparse_vec.rs:

#[derive(Clone, Debug)]
pub struct SparseVec { pub nz: Vec<u16>, pub vals: Vec<i8>, cached_norm: f32 }

universe.rs Cell: { label: String, region: Arc<str>, claim: Claim /* holds vec: SparseVec */, last_fired: u64, convergence_score: f32, activation_heat: f32, resonance_signature: u64, children: Vec<u32>, parent: Option<u32> }.

(b) Core loop — lattice_attention.rs::lattice_attend:

let hits = universe.query_vec(query, ATTENTION_TOP_K);
let scores: Vec<f32> = hits.iter().map(|h| h.1).collect();
let weights = softmax(&scores, ATTENTION_TEMPERATURE);   // 0.5
let pairs = hits.iter().zip(&weights).map(|(h,&w)| (&h.0.claim.vec, w)).collect();
let attended_vec = SparseVec::weighted_superpose(&pairs, 0.0);

(c) HTTP handler pattern — oracle_server.rs::handle_rshl_query:

#[derive(Deserialize)]
struct QueryReq { query: String, n: Option<usize>,
    #[serde(default)] dense_vec: Option<Vec<f32>> }
let req: QueryReq = serde_json::from_slice(body)?;
let hits = /* lock universe+synaptic; */ NeuralBus::query_associative(&u, &sl, field.phi_g, &req.query, limit, &[], "");
write_json(stream, 200, "OK", &serde_json::to_value(hits).unwrap())

Important hook: dense_vec: Option<Vec<f32>> ("The Crusher") — an external policy can POST a continuous f32 vector which is projected into the 16384-dim ternary space via SparseVec::from_dense_floats. This is the front door for an RL policy's output vector.

---

5. Existing Reward / RL Hooks (what to plug into) + THE OPEN QUESTION

KAI already has the scalar signals an RL loop needs — you don't build reward from scratch:

Recommended RL surface: reward = w1*phi_g + w2*rpe - w3*chi; policy acts by either (a) POSTing a goal/query vector to /api/rshl/query dense_vec (the Crusher) or feeding Drive::feed_goal, or (b) setting dopamine/phi_g/surprise to steer record_co_firing.

>> THE ONE THING ONLY RYAN CAN ANSWER (Section 5 of the request): the RL GOAL/TASK

The codebase gives the reward signals and the action surface, but what task do you want the RL script to train KAI to solve right now? Pick one so the external AI has a target:

*Hand sections 1–4 + the reward hooks in 5 to the external AI as-is; tell it which of (a)–(d) is the target.*