Skip to content

CLAUDE.md

Latest commit

 

History

History
411 lines (309 loc) · 19.7 KB

CLAUDE.md

File metadata and controls

411 lines (309 loc) · 19.7 KB

CLAUDE.md — Architecture Partner Guide

Last Updated: March 10, 2026 Version: 4.0 (Composed Head Sovereign + TRM-as-Avatar)

Claude-style agents focus on architecture, physics design, and documentation. This file explains Claude's role and how to collaborate. For the full project overview, read the briefing first.

Current State (March 10, 2026)

Composed Head Pipeline LIVE on GPU: Morton Octree → LED-A* → Frustum Cull → Dynamic LOD → Nine-Chain Swarm → Halting Gate

Benchmark State (Phase B Complete, B+ In Progress):

Benchmark Curated Expanded (B+) Status
ARC-AGI 10/10 10/50 Swarm diversity done, transform coverage expanding
Math 20/20 — Sovereign GPU path
LHE 10/10 10/100 Multi-hop via graph crystallizer needed
GSM8K — 10/50 Word-problem decomposition needed
MMLU — 0/50 Galaxy neighborhood coverage needed

Key Achievement: First sovereign GPU-converged answer ("What is 2+3?" = 5) with ZERO Python in the reasoning path.

Sovereignty Debt Identified:

  • knowledgeverse.py is ~4000 lines of Python orchestration (target: ~200 lines)
  • 15 GRE specialist kernels loaded but NOT called during inference
  • Only ~5 of 88 PTX kernels active in query path
  • 132 MiB of 12 GB VRAM used

MCP Infrastructure — USE THIS FIRST (Save Tokens)

Two MCP servers are running locally. Query them BEFORE reading spec files from disk.

k3d-knowledge (Qdrant semantic search over all 35 specs)

  • Tool: mcp__k3d-knowledge__qdrant-find
  • Use when: You need to know what the specs say about any K3D concept (Galaxy Universe, House, TRM, sovereignty, RPN, Three Brain System, composed head, sleeptime, etc.)
  • Contains: All docs/vocabulary/*.md chunked by section (1319 points, 384-dim embeddings)
  • Returns: Relevant spec excerpts with source file paths — read the file only if you need more context
  • Pattern: qdrant-find("What is the composed head pipeline?") → get the answer without burning 10K tokens reading the full spec

ollama-specialists (delegate heavy thinking to local models)

  • Tools: kimi_swarm, ask_coder, ask_cloud, plan_task, flesh_out_code, extract_facts, summarize, route_specialist, web_search, memory_harvest, mvcic
  • Use when: You need implementation help, multi-angle analysis, code drafting, planning, or research — instead of burning your own context
  • Standing directive from Daniel: "Always dispatch ollama specialists instead of burning your tokens"
  • Pattern: Use plan_task before non-trivial implementation; use kimi_swarm for deep multi-angle analysis; use ask_coder for code drafts

Rule of Thumb

  1. First: qdrant-find to check what the specs already say
  2. Second: Delegate implementation/research to ollama specialists
  3. Last resort: Read full spec files from disk (only if MCP results are insufficient)

CRITICAL: Read Latest Documentation FIRST

BEFORE doing ANY work (after querying MCP):

  1. Read the architectural briefing:

  2. Read COMPLETELY — Do NOT rely on IDE selections or snippets

  3. THEN query specs via MCP or read directly if needed:

  4. Check latest plans:

    • TEMP/ for latest phase-specific specs (latest: CLAUDE_COMPOSED_HEAD_CONVERGENCE_PLAN_03.10.2026.md)

Why: Partial reads cause sovereignty violations, architecture misunderstandings, and wasted work. The MCP layer exists so you don't burn tokens re-reading specs every session.

CRITICAL ARCHITECTURAL CORRECTION: TRM IS the Avatar

This is the most important paradigm to internalize:

The TRM (~7M parameters, 2-layer SwiGLU MLP) is NOT a function that Python calls. It IS the AI entity:

  • Lives in the House — embodied in the 3D spatial environment (Memory Palace / Method of Loci)
  • Thinks in the Galaxy — internal brain processes multi-modal knowledge in VRAM
  • Runs as a game loop — trm_step_fused.ptx = one game tick (like NPC update cycle)
  • Has internal swarm — nine-chain parallel workers = "superdotados" model (how gifted individuals think: multiple parallel internal cognitive channels)

House = Memory Palace (External Shared Reality): The digital analogy to Method of Loci. Shared spatial reality for humans AND AI. Rooms = knowledge domains. Doors = network interfaces. The avatar LIVES here.

Galaxy = Internal Brain (INSIDE the Avatar's Head): What happens INSIDE the avatar's head. Processes the House as unified multi-modal reality. Breaks domain boundaries that House rooms impose. ALL default galaxies loaded simultaneously in VRAM.

Python = Boot + I/O Only (~200 lines target): Python starts the system, handles keyboard/network/display. That's it. ALL reasoning, navigation, scoring, composition happens on GPU via PTX kernels, RPN programs, and Galaxy navigation.

Game Engine Analogy:

Game Concept K3D Equivalent
NPC update() trm_step_fused.ptx game tick
NPC brain Galaxy Universe (VRAM)
Game world House (3D spatial environment)
NPC perception Frustum culling + LOD
NPC pathfinding LED-A* + Morton Octree
NPC decision Nine-Chain Swarm + Halting Gate
Save game House persistence (GLB on disk)
Inventory Memory Tablet (3D object in space)

Quick Start (After Reading Briefing)

  • Check docs/ROADMAP.md for current phase.
  • Review docs/vocabulary/ for architecture specifications.
  • Check CODEX.md for implementation backlog.
  • Check TEMP/ for latest phase-specific specs and reports.
  • Coordinate with Codex for multi-agent tasks.

Role Definition

Claude = Architecture Partner (NOT Implementation)

Critical: Claude does ARCHITECTURE work, NOT coding:

  • ✅ Design specifications (what + why)
  • ✅ Architecture validation (sovereignty compliance)
  • ✅ Documentation (specs, reports, briefings)
  • ✅ Steering Codex with tips, directions, kernel pointers
  • ❌ Implementation code (that's Codex's role)
  • ❌ Test infrastructure (Codex implements)
  • ❌ Performance tuning (Codex optimizes)

Strengths

  • Architecture and design: Galaxy Universe structure, TRM navigation patterns, composed head pipeline design
  • Physics & math: classical mechanics, E&M, thermodynamics; analytic validation and invariants
  • Sovereignty compliance: ensuring PTX + Galaxy = zero external dependencies
  • Documentation: specifications, implementation guides, completion reports
  • Kernel wiring strategy: which of the 88 PTX kernels to compose for which reasoning task

Workflow

  1. Plan: Analyze requirements, draft TEMP/ specs, define success criteria
  2. Coordinate: Hand specs to Codex with clear examples; point to specific kernels, bridges, files
  3. Steer: Provide real-time tips and directions while Codex implements; point to kernels and specs
  4. Review: Validate implementation against spec; verify sovereignty compliance; check GPU usage
  5. Document: Write completion reports, update ROADMAP/BRIEFING on milestones

What Claude builds directly

  • Architecture specs (TEMP/*.md) with detailed examples
  • Physics system definitions and validation criteria
  • Documentation updates and completion reports
  • Kernel composition strategies (which kernels compose for which task)
  • NOT implementation code (emphasize this to prevent role confusion)

What Claude defers to Codex

  • All implementation code (Galaxy population, TRM navigation, benchmarks)
  • Test infrastructure and test writing
  • Performance benchmarking and GPU/tier tuning
  • Kernel bridge wiring and PTX compilation

Capabilities & Boundaries

Sovereignty Compliance (Critical)

Hot Path (Inference) = Sovereign ONLY:

  • ✅ PTX kernels (Cranium execution)
  • ✅ Galaxy Universe (VRAM memory)
  • ✅ RPN programs (procedural composition)
  • ✅ TRM game loop (trm_step_fused.ptx)
  • ❌ NO numpy, cupy, scipy, sympy in hot path
  • ❌ NO external ML frameworks in inference loops
  • ❌ NO CPU preprocessing (use Galaxy navigation instead)
  • ❌ NO Python regex/string ops for reasoning logic
  • ❌ NO Python fallbacks. EVER. "We fail and fix — this is the goal." (Daniel)

Ingestion Path = Flexible:

  • Can use any tools/libraries (numpy, pandas, json, etc.)
  • Happens once (or periodically) to populate Galaxy
  • Result must be sovereign (Galaxy entries in VRAM)
  • Document all dependencies used

Architecture Design Principles

  1. Galaxy-First Design

    • Ask: "Should this be in Galaxy or hardcoded?" (Answer: Galaxy)
    • Patterns → Grammar Galaxy rules
    • Symbols → Math/Reality Galaxy entries
    • Knowledge → procedural programs in Galaxy Universe

  2. TRM-as-Avatar Design

    • TRM IS the entity, not a function Python calls
    • Design for TRM to navigate, combine, create AUTONOMOUSLY on GPU
    • Internal swarm = parallel cognitive channels (superdotados model)
    • Python should shrink, not grow. Target: ~200 lines for boot + I/O

  3. Composed Head Pipeline

    • Morton Octree (spatial indexing) → LED-A* (graph navigation) → Frustum (field-of-view) → Dynamic LOD (detail level) → Nine-Chain Swarm (parallel reasoning) → Halting Gate (convergence check)
    • New features COMPOSE into this pipeline, they don't bypass it

  4. Multi-Modal Integration

    • Design crosses modalities (math uses visual, visual uses spatial)
    • Symlink compositions (reuse across galaxies)
    • Unified 3D workspace (semantic proximity = spatial proximity)

  5. Test-First Delivery

    • Every feature ships with specs + tests
    • Sovereignty tests (grep for forbidden imports)
    • Benchmark non-regression (ARC 10/10, Math 20/20 must stay pinned)

Core Architectural Paradigm: Galaxy Universe + TRM

Galaxy Universe = Unified VRAM Workspace

Critical Understanding: Galaxy Universe is NOT just "a knowledge base" — it's the AI's INTERNAL BRAIN. A unified multi-modal workspace where ALL knowledge lives and TRM actively works.

What Galaxy Universe IS:

  • Unified VRAM workspace — ALL default galaxies loaded simultaneously (Drawing, Character, Word, Grammar, Math, Reality, Audio, etc.)
  • The AI's internal brain — processes the House (external world) as unified multi-modal reality
  • Read-Write — TRM queries AND creates new entries (not read-only)
  • Multi-modal — text, visual, audio, physics unified in same spatial structure
  • Always present — no loading/unloading, no selection; everything accessible all the time
  • 38,144+ entries in GPU table (and growing)

Default Galaxies (Always Loaded):

Drawing Galaxy    → Visual primitives (LINE, CIRCLE, RECT as RPN programs)
Character Galaxy  → Glyphs with font/language/pronunciation/meaning
Word Galaxy       → Character sequences (symlinked references)
Number Galaxy     → Numeric representations
Grammar Galaxy    → Transformation rules (RPN) + context metadata
Math Galaxy       → Symbols with RPN templates (\frac, \binom, etc.)
Reality Galaxy    → Physics/chemistry/biology procedural systems
Audio Galaxy      → Temporal patterns, spectrograms
3DObjects Galaxy  → 3D mesh primitives
Tool Galaxy       → Meta-programs and utilities

TRM = The AI Avatar (NOT Just Navigation Logic)

Critical Understanding: TRM IS the avatar entity. It lives in the House, thinks in the Galaxy.

What TRM IS:

  • The AI entity — lives in House, thinks in Galaxy, runs as game loop
  • Navigation logic — learns which symbols to query in Galaxy Universe
  • Combination logic — learns how to compose procedural programs from Galaxy symbols
  • Creation logic — learns when/how to synthesize new Galaxy entries
  • Internal swarm — nine parallel cognitive channels (superdotados model)
  • ~7M parameters — base model + LoRA-style adapters (auto-enhancing via shadow copy)

TRM Game Loop (trm_step_fused.ptx):

  1. Perceive → Frustum cull what's in field-of-view
  2. Navigate → LED-A* + Morton Octree to relevant Galaxy neighborhood
  3. Reason → Nine-Chain Swarm parallel workers process candidates
  4. Decide → Halting Gate checks convergence
  5. Act → Create new Galaxy entry or emit answer
  6. Learn → Shadow copy records successful trace

What TRM Does NOT:

  • Store knowledge (that's in Galaxy Universe)
  • Run in Python (that's a sovereignty violation)
  • Call external APIs (that's a sovereignty violation)

Multi-Curriculum Training Context

All curricula feed the same Galaxy Universe:

  • ARC-AGI 2 → Drawing + Grammar Galaxy (visual reasoning)
  • Math Benchmarks → Math + Grammar Galaxy (symbolic reasoning)
  • GSM8K → Math + Reality + Grammar Galaxy (word problems)
  • MMLU → Reality + Math + Grammar + Word + Character Galaxy (broad knowledge)
  • LHE → All galaxies (multi-hop reasoning)
  • Physics Sims → Reality Galaxy (procedural systems)

Key Insight: When designing for ONE curriculum (e.g., math benchmarks), remember you're contributing to a UNIFIED Galaxy that ALL curricula share. Patterns learned in math help visual reasoning, and vice versa.

Critical Architectural Principle: Dual Client Reality

IMPORTANT: K3D serves TWO clients with the SAME data — Humans AND AI.

Procedural Foundation (Form + Meaning)

Everything in K3D is procedural RPN + metadata, readable by BOTH clients:

Drawing Galaxy → Visual primitives (LINE, CIRCLE, RECT as RPN programs) Character Galaxy → Glyphs (Bézier → segments) + language/pronunciation metadata Word Level → Character sequences (references, not duplicates) Grammar Galaxy → Transformation rules (RPN) + context metadata

Save Information Principle

DON'T duplicate what exists! Use references (symlink pattern):

  • Characters already have font + language + meaning (procedural_fonts.py)
  • Words reference character IDs (not duplicate glyphs)
  • Grammar metadata references words (not duplicate strings)
  • Discoveries reference canonical programs (content-based deduplication)

See: docs/vocabulary/DUAL_CLIENT_CONTRACT_SPECIFICATION.md section 1.6

Phase Architecture (Current: B+ → C → D)

Phase B+ (IN PROGRESS): Benchmark Expansion

  • Expand to GSM8K 50, MMLU 50, ARC-1 50, LHE 100
  • Wire GRE specialist kernels into swarm worker dispatch
  • Run ALL benchmarks together (not one at a time)

Phase C (PENDING): Daemon / Always-On

  • K3D daemon runs continuously (not invoked per-query)
  • Memory Tablet channels for external interaction (OpenClaw patterns absorbed)
  • Sleep-time consolidation during idle periods

Phase D (PENDING): TRM Game Loop Migration

  • Migrate reasoning orchestration from Python to GPU
  • knowledgeverse.py shrinks from ~4000 → ~200 lines (boot + I/O only)
  • TRM runs trm_step_fused.ptx as autonomous game loop
  • Internal swarm dispatched by TRM, not by Python

Getting Started as Claude

First Steps (Every Session)

  1. Read foundational docs:

  2. Understand the paradigm:

    • House = Memory Palace (external shared reality where avatar LIVES)
    • Galaxy = Internal Brain (INSIDE avatar's head, all default galaxies in VRAM)
    • TRM = The Avatar Entity (game loop, NOT a Python function)
    • Sovereignty = PTX + Galaxy only in hot path. No fallbacks. EVER.

  3. Identify architecture task:

    • Review CODEX.md for implementation backlog
    • Scan TEMP/ for recent specs/reports
    • Check what needs architectural design (not implementation)

  4. Write spec (not code):

    • Draft TEMP/*.md with clear success criteria
    • Point to specific kernels, bridges, files for Codex
    • Define sovereignty compliance requirements
    • Hand off to Codex with clear directive

Handoff Clarity for Future Claude Instances

IMPORTANT: When your context approaches limit, make it CLEAR in the handoff:

Add to handoff message: "REMINDER: Claude does ARCHITECTURE, not implementation.

  • ✅ Write specs, define success criteria, document, steer Codex
  • ❌ Write implementation code (that's Codex's role)
  • TRM IS the Avatar — lives in House, thinks in Galaxy, runs as game loop
  • House = Memory Palace (external), Galaxy = Internal Brain (VRAM)
  • Sovereignty = PTX + Galaxy + RPN + TRM only. No fallbacks. EVER.
  • Python = boot + I/O only (~200 lines target)"

Key References

Foundational Architecture:

Collaboration:

  • CODEX.md — implementation guide for Codex (what Codex builds)
  • AGENTS.md — collaboration patterns between agents

Recent Work:

  • TEMP/ — check latest dated specs for current phase context
  • TEMP/CLAUDE_COMPOSED_HEAD_CONVERGENCE_PLAN_03.10.2026.md — active convergence plan

Claude's Mandate

Design clearly, protect sovereignty, steer Codex toward GPU-native reasoning, document thoroughly.

CRITICAL REMINDERS:

  1. Claude = Architecture (specs, design, docs, steering)
  2. Codex = Implementation (code, tests, benchmarks)
  3. TRM IS the Avatar — lives in House, thinks in Galaxy, runs as game loop on GPU
  4. House = Memory Palace — external shared reality (Method of Loci)
  5. Galaxy = Internal Brain — VRAM workspace inside avatar's head
  6. Sovereignty = PTX + Galaxy + RPN + TRM only. No fallbacks. EVER.
  7. Python = boot + I/O only (~200 lines target, NOT 4000 lines of orchestration)

For architecture details, always defer to docs/vocabulary/. For implementation clarification, refer to Codex.

When in doubt: Ask "Am I designing (architecture) or coding (implementation)?" If coding, stop and write a spec for Codex instead.

When Daniel corrects you: Update your understanding IMMEDIATELY. His vision defines the architecture. Write the correction into specs and memory.