# KAI — AI WORKING MEMORY  (read this FIRST, in full, every session)

> This is the compact memory for AI assistants (Claude/Cowork). It is short ON PURPOSE so it
> survives a context-window compaction. The DEEP archive is `The KAI Codex.md` (multi-MB — GREP it,
> never read it whole, never recursive-grep the tree). Flow each session: (1) read THIS file fully,
> (2) `grep -a` the Codex for the feature you're touching, (3) confirm against the real file.
>
> **KEEP THIS FILE CURRENT.** When you finish a piece of work: add one line to "Recent work",
> update "Open issues", and (for code) bump the Codex + Cargo.toml. This file is only useful if the
> last AI updated it.

---

## Who / what / constraints
- **Owner:** solo dev ("k" / revry). One person built this whole stack.
- **Hardware:** ONE laptop — HP Victus, RTX 4050 **6 GB VRAM**, shared with Windows + the entire KAI
  fleet. Be conservative with GPU/CPU; prefer CPU/light options; account for other processes.
- **KAI engine memory (owner-stated design):** KAI's engine is built to hold ~**10 years** of chat/shared memory between the owner and KAI in **< 300 MB** total. It's a durable, compact lifelong-memory store (Rust brain: `[internal module]`, learned/durable weights survive restart) — retrieval per turn, NOT a context window that fills up. This is the model to respect: KAI already solves long-term memory; don't treat it like a stateless chatbot.
- **What the cloud AI CANNOT do** (so never claim a live-verified fix): run Windows processes, start
  the fleet, sign in to the dashboard, hear audio, use a GPU, drive two devices, reach [internal service]/LAN.
  → Ship changes **guarded behind a flag or with a fallback**, and have the owner verify.
- **Public site:** oraclekai.site, served from loopback :3001 behind a **Cloudflare tunnel**
  (cloudflared). Origin binds [internal service]. Real auth + 2FA + role gate + in-house guard modules exist.

## How to find things (memory-first)
1. Read this file. 2. `grep -ain "<feature>" "The KAI Codex.md"`. 3. Open the file the Codex names.
- **Do NOT** run `grep -r` / `find` over `[local path]` — huge tree, times out at 120 s.
- Large files trip grep's "binary" heuristic → always use `grep -a`.

## Feature → file map (where things ACTUALLY live)
| Feature | File |
|---|---|
| Finance page — bills, statements, cash forecast, month nav (`_calFin*`), Teller bank sync | `oracle-os/shell/desktop.js` |
| Oracle OS desktop + apps (Notes, Contacts, Calendar, Files, Finance); calendar/finance sync store `_cal` via `[internal endpoint]` | `oracle-os/shell/desktop.js` (served at `/oracle-os/`) |
| Dashboard core UI, account state sync (`_syncKeys`, `[internal endpoint]`), radio, Stripe billing | `oracle-core.js`, `oracle.html` |
| Server: `/api/*`, static-file allowlist, `/ws/games`, auth/role gate | `[internal module]` |
| Website voice pipeline (STT→LLM→TTS, logs `[GroqVoice/Leo]`); local-TTS hook at `LOCAL_TTS_URL` | `[internal module]` |
| Leo Discord bot (persona, voice turn, ack filler) | `[internal module]` |
| Local voice: Chatterbox server (:5111, cloned voice) / Kokoro read-aloud (:8123) | `[internal module]`, `[internal module]` |
| Arcade games (pool = `oracle-games-pool.js`) | `oracle-games-*.js` |
| Browser KAIVERSE 3D | `kaiverse.js`, `kaiverse-graphics.js` |
| Fleet launch / supervisor | `Start-KAI.ps1`, `ecosystem-manager.mjs` |
| Secrets + tuning env | `[internal module]` (NEVER print secret values) |

## Open issues / TODO (newest first)
- **FINANCE ANALYTICS TAB** — DONE v9.10.952 (Finance -> 'Reviews': Month/Week/Day, income/bills/other, savings register + weekly allowance, monthly statement records, SVG donut). Iterate with owner. File `oracle-os/shell/desktop.js`.
- **NEW-ITEM WIZARD** — DONE v9.10.951 (`_calWiz`/`_CAL_WIZ_FLOWS`, default for +Add, 'All fields (advanced)' escape). Iterate look/flows with owner.
- **Finance: 'past bill auto-marked paid'** — `_calFinPaidOn`/`_finPaid` treat any bill with date < today as PAID (`k<today`). Owner: 'its thinking when i pay them is when it is.' Want past-unpaid bills to show OVERDUE, not paid; keep the past=settled assumption ONLY for the cash forecast. Confirmed desired behavior, not yet coded.
- **Finance page: wrong statement/bill calendar dates** — unfixed. NEEDS a concrete example (which bill, on which day, should be which day) before touching it — base parsing (`_calD`) is confirmed correct, bug is in recurrence/statement logic; guessing risks corrupting financial data. File `oracle-os/shell/desktop.js`.
- **Finance page: add-a-bill** — DONE v9.10.949 (selected-day default + quick-day chips). Add card = `_calFinAddCard`, handler `osFinSetDate`/`osCalFinQuickAdd`.
- **Leo voice (Chatterbox):** wired into the REAL path v9.10.953 (`executeVocalSync` + `LEO_NO_GEMINI_LIVE=1` routes calls off Gemini Live). Owner MUST run `Start-KAI.ps1` to load it. Still open: record `leo-voice-ref.wav` (7-15s) for a true clone (default voice until then); confirm the STT-fallback call path still works + latency acceptable; revert = `LEO_NO_GEMINI_LIVE=0`.
- **Online pinball:** only 2-player sync built; 3–4 player sync not done.
- **Normal 2p online engine:** same shooter-authoritative pattern as pinball but WITHOUT the freeze-recovery (resync/watchdog) — should get the same mirror.
- **Provider quota:** Gemini 429 + Groq daily token cap were hitting; local models reduce this.

## KAI brain / BitNet — VERIFIED runtime state (2026-09-07, supersedes Codex §14.44 history)
- **Extraction WORKED (mechanically).** Full BitNet b1.58-2B-4T is on disk in KAI-native `KAI1` ternary format: `models/BitNet/Native/*.kai` = 30 blocks × 11 tensors + `token_embd` + `output_norm` (330 files). Forward pass runs: today's `overnight_pipeline.log` shows real `[BitNet] ...` generations.
- **Quality is the problem, not the extraction.** BitNet output loops hard ("X is a type of X is a type of X..."). The live teaching loop (`teaching/kai_language_teacher.py` → `teaching/teacher.log`) currently scores ~**0/8 (0%)** on Level-1 literacy; KAI often returns "(no reply)".
- **DEAD path:** the original sparse-vocab/WIAK `neural_weights.bin` (7.7GB) + `neural_structure.json` are ORPHANED (wrong schema, load always failed). Still sit in `data/`, `models/BitNet/`, backups. Do not revive without a new extractor+index+loader.
- **Architecture evolved to a HYBRID (not in Codex §14.44):** BitNet ternary brain + a fine-tuned **7B Dense Expert** `[internal module]` (candle quantized_llama, MoE-style routing, VRAM-managed/unload-when-idle). Flags: `has_native_transformer()`, `has_dense_expert()`, `hybrid_fully_wired`, `native_decode_count` — all in `[internal module]`; `[internal endpoint]` reports them.
- **"J-Space" is ALREADY a live KAI concept** (from the transformer causal-mediation "J-space" paper). KAI's analogue = the "silent ring" / `[internal module]` ("glass window into KAI's head") + `GET [internal endpoint]` (v9.10.556): what KAI considered but did NOT say, per-cell scores, branches not taken. Advantage over transformers: KAI's intermediate states are literal TEXT, not residual vectors — already verbalizable.
- **The "dissect the generative path" probe EXISTS + is TRAINED:** `[internal module]` = the Hyperdimensional Probe (Bronzini et al. arXiv [internal service].25045) — a learned 2-layer MLP pulling a transformer's residual stream into KAI's 16384-dim ternary VSA basis. Trained weights on disk: `[internal module]` (167MB), `[internal module]` (137MB). Training half = `[internal module]`; blend = `blend_mapper_with_state`. Looks OPT-IN (loaded via a path arg in `main.rs`), not blended into the live serving path by default — verify before claiming it's ON.
- **Key files:** brain = `[internal module]`, `bitnet_inference.rs`, `bitnet_llama.rs`; warehouse/dispatch = `language_warehouse.rs`; probe = `neural_mapper.rs` + `training.rs`; introspection = `mind_trace.rs`; data loop = `overnight_pipeline.py`, `teaching/kai_language_teacher.py`.

## Recent work (newest first — one line each; older detail is in the Codex)
- v9.10.982 — FIX Leo Radio button not showing: oracle.html loaded `oracle-core.js?v=12.10.901` (never bumped) → browser served cached old file. Bumped `?v`→12.10.902, moved button to a prominent full-width 'Listen to Leo Radio' under the Codex title (search-row spot was off-screen on mobile), sw→v43. LESSON: bump the `?v=` cache-bust in oracle.html when editing an oracle-*.js, not just the file.
- v9.10.981 — Added a **🎙 Leo Radio** button to the **KAI Codex reader** toolbar (`oracle-core.js`, next to the 📖 Read button — the Codex reader is in oracle-core.js, NOT desktop.js). Opens /leo-radio.html. Hard-refresh + sw v42.
- v9.10.979-980 — Leo Radio guest-accessible (added `[internal endpoint]` to GUEST_API_EXACT in [internal module]; needs dashboard restart) + an Oracle OS **app tile** (`leoradio` in OS_APPS + iframe render case in `osRenderAppBody`, desktop.js) that opens /leo-radio.html in a window with an 'Open full page' fallback (hard-refresh + sw v41 to apply).
- v9.10.978 — NEW **Leo Radio** (`/leo-radio.html` + POST `[internal endpoint]` in command-center-server.mjs): listen-only continuous Leo monologue, no mic. Uses `[internal module]` askGoogle (Gemini + google_search grounding on GEMINI_API_KEY_LEO) as brain+live-search, Kokoro (:8123) for voice; per-session rolling context in `globalThis.__leoRadio`; page prefetches next segment for seamless playback. APPLY = `.\Start-Dashboard.ps1` then open /leo-radio.html; needs Kokoro :8123 up + Gemini key.
- (voice) Re-enabled Gemini Live for Leo — set `LEO_NO_GEMINI_LIVE=0` in [internal module] (owner confirmed the Gemini key works again). Gemini Live is the all-in-one STT+LLM+TTS path (voice=Fenrir), bypassing the contended Groq pipeline + Chatterbox (6GB GPU) + skipped ElevenLabs (past_due). NEEDS full `.\Start-KAI.ps1` fleet restart to apply (bot env, no hot-reload). NOTE: this fixes the Discord voice Leo; the dashboard 'Oracle line' call still runs `[internal module]` (Groq-based) and would need Gemini wired in separately if that's the surface the owner means.
- v9.10.977 — Bounce House BR: switched to a third-person over-the-shoulder camera that TURNS with you (rotating projection `camA`/`proj2`, mouse-look yaw of `you.face`, W/S forward-back + A/D strafe relative to facing, forward aim reticle; floor drawn as a projected quad, zone as a projected polygon). File-only change, script ?v bumped to 977 → just hard-refresh. `oracle-games-bounce.js`.
- v9.10.976 — NEW arcade game **Bounce House Battle Royale** (`oracle-games-bounce.js`, id `bouncebr`): isometric ant-scale bounce-house battle royale, sky-drop spawn, bouncing pellets, parachute power-up crates that change pellet bounce, shrinking air-zone, AI bots. Registered via `GC.register`; script-tagged in oracle.html + allowlisted in `command-center-server.mjs`. APPLY = `.\Start-Dashboard.ps1` (server allowlist changed) THEN hard-refresh.
- v9.10.974-975 — Day popup: running Net projected/actual band moved up under the In/Out/Net tiles (occurred purchases now count in actual, not just verified). NEW Month overview popup (`_calMonthZoomHtml`, click the month title): month Income/Bills/Saved/Net tiles, in/out bars, projected end-of-month balance, per-pay-period budget meters, and a 'where it goes' category breakdown. `oracle-os/shell/desktop.js`.
- v9.10.972-973 — Day-popup balance: section now always shows when an account exists (was hidden at $0). Reworked into a RUNNING trajectory: Balance today + Net projected (cumulative plan through the day, carries prior pay-week savings forward) + Net actual (verified-only via `it.verified`; future = parenthesized estimate). `_flowTo(day,vo)` helper. Groundwork for paystub/bank-statement verification pipeline (owner's future automation). Owner still needs to set real Checking/Savings balances (currently $0). `oracle-os/shell/desktop.js`.
- v9.10.971 — Day popup: added Accounts + NET balance section (per-account balances, net worth, projected balance on selected day incl. delta; reads opts.accounts read-only + legacy fallback). Also fixed calendar 60s sync blinking: `_calSyncPull` re-rendered every tick; now gated by `_calSig` change + never rebuilds an open `_calZoom` popup. Owner says the blink is ALSO workspace-wide (other apps/settings/popups) = separate OS-level re-render to find next. `oracle-os/shell/desktop.js`.
- v9.10.970 — Month grid look modernized: rounded gradient day cells + `.calCell` hover-lift, today number in an accent pill (`.calTodayNum`), weekend tint, refined weekday header + pay-week card, more spacing. Visual-only, in `_calMonthView` + `calFxCss`. `oracle-os/shell/desktop.js`.
- v9.10.969 — Calendar day-analytics popup: added motion (pop-in `.calPop`, count-up stat tiles `_calFxCountUp`, animated meters `.calGrowI`, staggered side-pane/list reveal `.calRiseI` = the 'text effect' on day-click) + richer game-like info (status pill, pay-week budget meter = % of check to bills + free-to-save, next-paycheck & next-bill countdowns). CSS via one-time `_calFxEnsureCSS`. `oracle-os/shell/desktop.js`.
- v9.10.968 — Calendar UX pass: exact-cent finance math (new `_calMoneyC`; pay-week + day-cell + chips no longer round to whole $); day analytics POPUP `_calDayZoomHtml` (In/Out/Saved/Net tiles + bars + grouped item list) opened by 2nd-click on a selected day / side-pane Analytics btn / date header (`osCalZoom`); modernized `_calSidePane` (In/Out strip + buttons); mouse-wheel month nav (`osCalWheel`, Month grid only). NEXT: Week+Day view redesign (eyeball-iterate w/ owner). `oracle-os/shell/desktop.js`.
- (data) Reconciled owner finance store `state/os-appdata/usr_6e6932d1ec1fc7d3/calendar.json`: removed duplicate Rent (kept one, 1st-of-month $780 +5d grace), made $309.99 Consumers a one-time catch-up, Mortgage grace 15d, Internet 68.84→68.94. Pay-week totals now realistic (no more $0 weeks). Backups: `calendar.json.bak-cleanup-*`.
- v9.10.967 — Month calendar: pay-week save now a proper right-hand 'Pay week' COLUMN (In/Bills/Save breakdown per week, keyed to payday) instead of a cramped in-cell badge. `oracle-os/shell/desktop.js`.
- v9.10.966 — Pay weeks anchor to the DOMINANT paycheck (>=50% of biggest); a smaller partner income counts within the week instead of splitting it. Owner: Ryan Fri $1,055 (Mara, incl. $105 10%-cut to other acct), Kayla Wed $465. `oracle-os/shell/desktop.js`.
- v9.10.965 — Month calendar: day items now show icon+amount (not plain), and each PAYDAY cell shows a 'save +$X' pay-week leftover badge (payday-to-payday, not Mon-Fri). `oracle-os/shell/desktop.js`.
- v9.10.964 — Paycheck periods now anchored to RECURRING income (one-off/extra income no longer fragments periods; all income still counts within). `oracle-os/shell/desktop.js`.
- v9.10.963 — Fixed Leo Oracle-line voice hang (tts up to 37s): added AbortSignal.timeout to all TTS fetches in `groq-voice-session.mjs` so a dead/slow provider fails fast to the next voice. Applies on fleet restart.
- v9.10.962 — NEW Savings tracker: 'Savings' mode in This-month — total saved (net in/out), put-in/took-out this month, saved-per-week bars, 3/6/12-mo projection. Built from 'saving' items. 7/7 headless. `oracle-os/shell/desktop.js`.
- v9.10.961 — NEW Paycheck planner: 'Paycheck' mode in This-month segments money by pay period (payday->next payday) — per check: income, bills due before next check, what's left, and a 'short by X, split it' flag. 10/10 headless. `oracle-os/shell/desktop.js`.
- v9.10.960 — Finance analytics promoted: spending wheel + trends moved OUT of 'advanced' UP to a visible 'Where your money goes' zone under 'Where you stand', with a fill/reveal animation (finWheelIn). `oracle-os/shell/desktop.js`.
- v9.10.959 — Finance 'All details' reordered: Accounts moved UP to 'Where you stand' (this is what makes the forecast/safe-to-spend/cash actually work — they need balances set); Transactions moved up; Savings goals demoted to advanced. TODO: polish Transactions + What-is-due look/feel/function. `oracle-os/shell/desktop.js`.
- v9.10.957 — Finance 'All details' restructured into labeled zones (Where you stand / What's coming up / Accounts,recurring&savings / Transaction history) per finance-dashboard best practice. `oracle-os/shell/desktop.js`.
- v9.10.956 — Finance 'All details' decluttered: spending wheel/trends/budgets/advances moved under a remembered 'Show advanced' toggle; essentials (cash, safe-to-spend, due, forecast, accounts, recurring, transactions) up top. `oracle-os/shell/desktop.js`.
- v9.10.955 — Finance consolidated: opens on the monthly income/expenses view ('This month'); tabs renamed This month / All details / Add money. `oracle-os/shell/desktop.js`.
- v9.10.954 — Wizard date bug fixed: render-time sync was writing the amount into the date field (blanked mm/dd/yyyy); now keyed to the rendered step. Date seeds from the clicked day; tap opens the picker. `oracle-os/shell/desktop.js`.
- v9.10.953 — Leo voice root cause: his CALL uses Gemini Live native audio, not the Chatterbox path we wired. Wired Chatterbox into his real chokepoint `executeVocalSync` (PCM->WAV->ffmpeg) + `LEO_NO_GEMINI_LIVE` gate to route calls onto it. NEEDS fleet restart; ref wav still missing (default voice). `[internal module]`.
- v9.10.952 — NEW Finance 'Reviews' analytics tab: Month/Week/Day income vs bills vs other spending, left-to-save, savings register (weekly allowance), saved monthly statements. Custom SVG donut. 19/19 headless. `oracle-os/shell/desktop.js`.
- v9.10.951 — NEW guided New-item WIZARD (pick type -> only the right questions -> review -> add); default for +Add, full form kept as 'All fields (advanced)'. 16/16 headless. `oracle-os/shell/desktop.js`.
- v9.10.950 — Editor stopped reverting edits: background 60s sync no longer rebuilds the open 'New item' form and wipes typing (date/title/amount). `oracle-os/shell/desktop.js`.
- v9.10.949 — Finance: easy add-a-bill (selected-day default + Today/Tomorrow/1st/15th/Month-end chips). `oracle-os/shell/desktop.js`.
- v9.10.948 — Finance bills stopped vanishing on refresh: stabilized `_calUserKey` (no 'anon' regress) + anon-item rescue. `oracle-os/shell/desktop.js`.
- v9.10.947 — Chatterbox voice auto-starts with fleet (`Start-KAI.ps1` Stage 3.76, :5111).
- v9.10.946 — Chatterbox local TTS server for Leo's voice (`chatterbox-server.py`).
- v9.10.944 — Leo latency: 300 ms endpoint + gpt-oss-20b + instant ack filler.
- v9.10.943 — Online pinball mid-game freeze fix (seq state + resync + stuck-ball watchdog).
- v9.10.942 — Normal-mode AI blocked-path fix + pinball physics parity + speed slowdown.
- v9.10.941 — Map mode parity: cue stick, ghost/aim guide, 2-axis pan + zoom.
- v9.10.940 — 2-player online pinball sync (shooter-authoritative).
- v9.10.939 — Pinball made a standalone game mode (pool objective on the obstacle board).

## Hard gotchas (these have burned us)
- **LEO HAS THREE VOICE PATHS — this has caused huge confusion.** (1) Discord voice call = **Gemini Live** native audio (`leo.mjs` GeminiLiveSessionManager), unless `LEO_NO_GEMINI_LIVE=1` -> falls to (2) `leo.mjs` `executeVocalSync` (ElevenLabs->Kokoro->edge; Chatterbox wired in v9.10.953). (3) **Oracle-OS dashboard voice call ("the Oracle line", `[GroqVoice/Leo]`) = `[internal module]`** (Whisper->LLM->TTS), a SEPARATE path with its OWN Chatterbox wiring (`LEO_LOCAL_TTS=1` + `LOCAL_TTS_URL` -> POST -> streamPcm, then ElevenLabs/Orpheus). When the owner "calls Leo" on the dashboard, it's path 3. Fixing one path does NOT fix the others.
- **The Dashboard does NOT hot-reload TTS env.** The `.env` watcher only restarts specific BOTS for specific keys (e.g. LEO_NO_GEMINI_LIVE -> Gemini). The Dashboard/Oracle-voice process keeps whatever env it started with. So `LEO_LOCAL_TTS`, `LEO_TTS_SKIP_ELEVEN`, `LOCAL_TTS_URL` only take effect after a FULL `Start-KAI.ps1` restart. Symptom when stale (seen 2026-09-07 log): `[GroqVoice/Leo]` still hitting ElevenLabs with `tts=9000-37000ms` (ElevenLabs is past_due/401 -> slow retries) even though `.env` has the local-TTS keys set. FIX: full fleet restart + Chatterbox server (:5111) running.

- **Never** `open(f,'w').write(open(f).read()...)` inline — truncates before the read; emptied Cargo.toml once. Use safe read-then-write.
- **Never** wholesale-rewrite `oracle.html` / `oracle-core.js` / `oracle-os/**` / `kaiverse.js`. Surgical Python string-replace injections only.
- After code changes: bump Codex version + Last Updated + CHANGELOG (NAME the file), sync `Cargo.toml`, cache-bust served JS via `sw.js` SHELL_CACHE, and update THIS file.
- `.env` changes need a restart of whatever reads them; there is no auto `.env` watcher. The cloud AI can't restart — the owner runs `Start-Dashboard.ps1` (dashboard) or `Start-KAI.ps1` (fleet).
- **Standalone HTML pages served off oracle.html's dir (e.g. leo-radio.html, viseme-lab) with an inline `<script>` are BLOCKED by the dashboard's global CSP** (`script-src-elem 'self'` with NO `unsafe-inline`, set in command-center-server.mjs ~L8968). Symptom: the page renders but every button/handler is dead and NOTHING reaches the server (0 API hits) on ALL devices — easily misread as a mobile cache problem. The console shows `Executing inline script violates ... script-src-elem 'self'`. FIX: in that page's response handler, set a per-response `Content-Security-Policy` allowing `script-src-elem 'self' 'unsafe-inline'` + `media-src 'self' data:` (mirror the web-proxy handler ~L17771). Needs a dashboard restart. When building any new standalone inline-script page, add this CSP override at the same time as the route.