Recursive Memory Kernel v1 — Implementation Checklist

[abbudjoe]

Recursive Memory Kernel v1 — Implementation Checklist

Purpose: land the smallest tree-only v1 that is causally correct, observable, ablatable, and narrow enough to debug.

Rule of thumb: do not add side-memory bank, learned merge scheduling, routing early-stop, or dense fallback attention until this checklist is complete.

Status note: the implementation checklist below is complete through the current proving surface. This does not yet mean the architecture has been validated under learned training; the live ablation run so far is still an untrained baseline.

---

PR 1 — Scaffold v2 module boundaries

Title: scaffold fractal-v2 module boundaries

Deliverables

• Add LocalTrunk
• Add LeafSummarizer
• Add TreeMergeCell
• Add FractalRouterHead
• Add ReadFusion
• Add FractalV2Model

Requirements

• Do not disturb recursive-kernel-v1
• No side-memory bank
• No learned merge scheduling
• No routing early-stop
• No broad tournament integration beyond stub wiring

Merge criteria

• Workspace compiles
• Module ownership is explicit
• Public type boundaries are clear
• Existing v1 path still runs unchanged

---

PR 2 — Add typed v2 runtime state

Title: add typed recursive-memory-kernel v2 state surfaces

Deliverables

• Add multi-root recurrent state
• Add live leaf state
• Add sealed leaf summary store
• Add tree level summary stores
• Add exact leaf token cache
• Add retrieval policy surface

Requirements

• Prefer backend-friendly tensor layouts in hot paths
• Avoid pointer-heavy recursive state structures
• Separate conceptual ownership from runtime storage
• Sketch checkpoint/serialization boundary

Merge criteria

• State transitions are testable in isolation
• Shapes are explicit
• No hidden global state
• Types are stable enough for later model wiring

---

PR 3 — Multi-root local trunk baseline

Title: implement multi-root local trunk baseline

Deliverables

• Implement 2 to 4 root local processing
• Support leaf size 16
• Use a simple local recurrent/selective trunk
• Keep root outputs independently inspectable

Requirements

• Strict autoregressive behavior
• Same token stream reaches all roots
• No tree retrieval yet
• No exact leaf read yet

Diagnostics

• Root similarity / collapse metric
• Per-root norm tracking
• Per-root activation statistics

Merge criteria

• Forward pass works
• Training step works
• Single-root vs multi-root baseline is runnable
• Roots do not immediately collapse in smoke tests

---

PR 4 — Live leaf and sealed leaf mechanics

Title: add live leaf append and sealed leaf summary path

Deliverables

• Implement live leaf append path
• Seal leaves at fixed size 16
• Create sealed leaf summaries
• Populate token-level cache for sealed leaves

Requirements

• Only sealed leaves enter global memory
• Live leaf remains local-only
• Exact leaf read target is meaningful for later use

Tests

• Incremental append correctness
• Leaf sealing boundaries
• Correct sealed leaf spans
• No future-token leakage

Merge criteria

• Live/sealed split is stable
• Leaf summaries are deterministic
• Token cache contents are correct
• Causality is preserved

---

PR 5 — Regular dyadic summary tree

Title: implement regular causal dyadic summary tree

Deliverables

• Insert sealed leaves into level 0
• Add deterministic parent merge
• Store summaries level-major
• Track span metadata at each level

Requirements

• Regular dyadic tree only
• No learned merge gating
• Every sealed leaf participates
• Only prior sealed leaves are globally visible

Tests

• Incremental tree build matches reference recompute
• Span metadata is correct at all levels
• Causal visibility holds
• Parent and level counts are correct

Diagnostics

• Nodes per level
• Tree depth reached
• Dead / unused node detection

Merge criteria

• Tree construction is correct
• Incremental update path works
• No causal violations
• Summary tree is observable

---

PR 6 — Sparse routing over the sealed tree

Title: add sparse fractal router over sealed tree

Deliverables

• Add 4 routing heads
• Add beam width 2 routing
• Score candidates top-down
• Descend to selected sealed leaves

Requirements

• Candidate scoring is explicit
• Normalize only over surviving candidates
• No early-stop in first runnable version
• Routing stays inspectable per head

Diagnostics

• Routing depth histogram
• Candidate entropy per head
• Selected span distance histogram
• Head agreement / disagreement rate

Tests

• Routing touches sealed nodes only
• Beam width is enforced
• Behavior is deterministic under fixed seed

Merge criteria

• Routing is sparse
• Routing is query-dependent
• Heads do not all choose the same path by default
• Retrieval path is ablatable

---

PR 7 — Exact leaf read

Title: implement exact local read for selected sealed leaves

Deliverables

• Choose one exact-read mechanism:
  • local attention over token-level K/V inside the selected leaf
  • pointer-style read over cached token states
  • copy-distribution read over leaf token positions
• Wire exact read to selected routed leaves only

Requirements

• Keep the first mechanism simple
• No dense global token cache fallback
• Exact means token-level local access, not summary-only approximation

Diagnostics

• Fraction of steps using exact leaf read
• Selected token-position distribution
• Read concentration / entropy

Tests

• Exact reads target sealed leaves only
• Exact read span matches routed leaf
• Local token indices are correct

Merge criteria

• Exact read is real, not approximate
• Retrieval behavior changes when enabled
• Copy/retrieval probes improve relative to no-exact-read

---

PR 8 — Read fusion and LM head wiring

Title: wire read fusion into existing language model head

Deliverables

• Fuse per-root recurrent outputs
• Fuse routed tree values
• Fuse exact leaf read values
• Project fused output through LM head

Requirements

• Fusion logic is explicit and typed
• Do not bury routing usefulness inside an opaque mixer
• Keep all major sources easy to zero out for ablations

Tests

• Zeroing routed values changes behavior predictably
• Zeroing exact leaf read changes behavior predictably
• Zeroing extra roots changes behavior predictably

Merge criteria

• Full forward path works end-to-end
• Each source path is individually ablatable
• Logits are stable enough for smoke training

---

PR 8.5 — Causal Memory Auditor

Title: add causal memory auditor for counterfactual memory credit

Deliverables

• Add full forward reference path
• Add no-tree-read intervention
• Add no-exact-leaf-read intervention
• Add next-best-span substitution
• Add root-drop intervention
• Add structured reporting of utility deltas

Requirements

• Sampled, not always-on
• Cheap enough for evaluation runs
• Explicit intervention definitions
• No silent mutation of reference forward behavior

Diagnostics

• Loss delta
• Target-logit delta
• KL divergence from full forward
• Utility by root
• Utility by routing depth
• Utility by task family

Tests

• Each intervention preserves shape compatibility
• No-tree-read removes only tree-summary contributions
• No-exact-read removes only exact-read contributions
• Next-best substitution respects routing depth
• Root-drop removes only the selected root contribution

Merge criteria

• Tree retrieval utility is measurable
• Exact leaf read utility is measurable
• Root utility is measurable
• Dead-weight tree behavior is detectable if present

---

PR 9 — Synthetic task harness

Title: add synthetic retrieval and copy probes for v2

Deliverables

• Add copy task
• Add associative recall task
• Add induction task
• Add noisy retrieval task
• Add far-token comparison task

Requirements

• Tasks run quickly
• Metrics are comparable across ablations
• Do not wait for large LM training to evaluate architecture value

Merge criteria

• Each probe has a stable baseline
• Probes can compare:
  • no memory
  • tree only
  • tree + exact read
• Results are logged in a repeatable format

---

PR 10 — Benchmark and observability pass

Title: add scaling benchmarks and v2 observability suite

Deliverables

• Benchmark token append
• Benchmark leaf sealing
• Benchmark tree update
• Benchmark routing
• Benchmark exact leaf read
• Benchmark end-to-end forward pass

Sequence lengths

• 256
• 512
• 1k
• 2k
• 4k
• 8k

Metrics

• Tokens/sec
• Wall-clock per forward
• Peak memory
• Routing sparsity
• Root collapse metrics
• Exact-read usage
• Retrieval distance

Merge criteria

• Measured behavior trends toward intended scaling
• Hot paths are identifiable
• No accidental quadratic fallback is present

---

Required ablations before calling v1 “real”

Run at equal total state / parameter budget:

• single-root, no memory
• multi-root, no memory
• single-root, summaries only
• single-root, sparse retrieval
• single-root, sparse retrieval + exact leaf read
• multi-root, summaries only
• multi-root, sparse retrieval
• multi-root, sparse retrieval without exact leaf read
• multi-root, sparse retrieval + exact leaf read

Do not skip these.

---

Deferred until after this checklist

Do not add yet:

• side-memory bank
• learned eviction
• learned merge scheduling
• routing early-stop
• giant-scale training
• dense fallback attention
• complexity added only to rescue weak early results

---

Definition of done for first serious v1

The first serious v1 exists only when all of these are true:

• multi-root local trunk works
• leaf sealing is causal and correct
• dyadic tree is stable and incremental
• routing is sparse and query-dependent
• exact leaf read is implemented and ablatable
• causal memory auditing is implemented and reports useful deltas
• synthetic retrieval/copy tasks run
• scaling benchmarks exist
• diagnostics expose collapse and dead-weight behavior
• the architecture can be falsified cleanly

If these are not true yet, the work is still infrastructure, not a validated architecture.

[abbudjoe]

PR 1 is complete on codex/fractal-v2 at commit 223265f.

What landed:

• scaffolded fractal-core/src/v2/ module boundaries
• added explicit v2 boundary contracts for LocalTrunk, LeafSummarizer, TreeMergeCell, FractalRouterHead, ReadFusion, and FractalV2Model
• added FractalV2Components as the structural ownership bundle for model assembly
• re-exported the new v2 surfaces from fractal-core
• kept recursive-kernel-v1 runtime unchanged

Validation:

• cargo fmt --all
• cargo test -p fractal-core --quiet
• cargo clippy -p fractal-core --tests -- -D warnings
• cargo test -p fractal --quiet
• cargo test -p fractal --example tournament run_options_executes_tokenizer_backed_manifest_v2_and_persists_artifacts -- --nocapture

Note: there are still unrelated local worktree changes outside this commit that were intentionally left untouched.

[abbudjoe]

Follow-up review fix landed on codex/fractal-v2 at 12c52f9.

Addressed:

• hardened FractalV2Model::resolve_shape to reject zero-width dimensions across the v2 numeric contract
• added focused regression tests for zero-width root state, leaf summary, token-cache value, scale embedding, and fused readout dims
• kept the fix local to fractal-core/src/v2/model.rs

Validation rerun:

• cargo fmt --all
• cargo test -p fractal-core --quiet
• cargo clippy -p fractal-core --tests -- -D warnings
• cargo test -p fractal --quiet

[abbudjoe]

PR 3 is merged into codex/fractal-v2 at 47fb64d.

What landed:

• concrete BaselineLocalTrunk with typed step outputs and root-collapse diagnostics
• isolated FractalV2LocalBaselineModel for the PR 3 proving surface
• constructor-boundary validation for the baseline trunk and local baseline model
• local-baseline tests for causality, backprop, single-vs-multi-root runnability, and invalid config paths

Validation run on the merged PR state:

• cargo test -p fractal-core --quiet
• cargo clippy -p fractal-core --tests -- -D warnings
• cargo test -p fractal --quiet
• cargo test -p fractal --example tournament run_options_executes_tokenizer_backed_manifest_v2_and_persists_artifacts -- --nocapture

Next up: PR 4 for live leaf and sealed leaf mechanics.

[abbudjoe]

PR 4 is merged into codex/fractal-v2 at 8aace6f.

What landed:

• typed live-leaf append/seal flow
• baseline sealed-leaf summarizer
• typed sealed summary + token-cache materialization
• stricter fixed-leaf mutation contracts
• post-seal transition regressions, including cache population and fresh live-leaf restart after token 16

Validation for the final merged state:

• cargo fmt --all
• cargo test -p fractal-core --quiet
• cargo clippy -p fractal-core --tests -- -D warnings
• cargo test -p fractal --quiet
• cargo test -p fractal --example tournament run_options_executes_tokenizer_backed_manifest_v2_and_persists_artifacts -- --nocapture

Next up is PR 5: regular dyadic summary tree on a fresh checkout from codex/fractal-v2.

[abbudjoe]

PR 5 is merged into codex/fractal-v2 at f4e32a2.

What landed:

• typed tree merge surface with TreeNodeBatch / TreeMergeOutput
• baseline tree merge cell with scale-aware merge context
• regular dyadic tree state diagnostics
• incremental right-frontier tree update on sealed-leaf append
• tree regressions for reference recompute, odd-frontier carry, tree-required restoration, and merge-shape contract checks

Validation for the final merged state:

• cargo fmt --all
• cargo test -p fractal-core --quiet
• cargo clippy -p fractal-core --tests -- -D warnings
• cargo test -p fractal --quiet
• cargo test -p fractal --example tournament run_options_executes_tokenizer_backed_manifest_v2_and_persists_artifacts -- --nocapture

This gets us through PR 5. The next implementation step is PR 6: sparse routing over the sealed tree.

[abbudjoe]

PR 6 is merged into codex/fractal-v2.

What landed:

• baseline sparse fractal router with typed routed-leaf output
• explicit sealed-tree navigation helpers for top-down descent
• routing diagnostics for depth, entropy, span distance, and head agreement
• causal query-position filtering inside the router, plus a regression to prove future sealed spans cannot be selected for earlier queries

Validation run on the merged branch:

• cargo fmt --all
• cargo test -p fractal-core --quiet
• cargo clippy -p fractal-core --tests -- -D warnings
• cargo test -p fractal --quiet
• cargo test -p fractal --example tournament run_options_executes_tokenizer_backed_manifest_v2_and_persists_artifacts -- --nocapture

Next slice is PR 7: exact leaf read.

[abbudjoe]

PR 7 is merged into codex/fractal-v2 at e50ca43.

What landed:

• dedicated v2/exact_read.rs with a baseline exact leaf read over sealed leaf token-level K/V
• FractalV2Model now carries exact-read as an explicit validated contract surface
• typed FractalRouteOutput::from_parts(...) constructor for consuming routed leaf selections through explicit boundaries
• narrow model-level forward_retrieval_trace(...) path that exercises local_trunk -> state append -> router -> exact_read without pulling PR 8 fusion/logit work forward
• model-level no-exact-read ablation regression for the retrieval trace

Validation on the final state:

• cargo fmt --all
• cargo clippy -p fractal-core --tests -- -D warnings
• cargo test -p fractal-core --quiet
• cargo test -p fractal --quiet
• cargo test -p fractal --example tournament run_options_executes_tokenizer_backed_manifest_v2_and_persists_artifacts -- --nocapture

Reviewer loop:

• R1 found that exact read was still only isolated and not reachable from the model path
• follow-up wired the retrieval trace through the model surface
• R2 asked for a model-level no-exact-read ablation regression
• final reviewer pass came back with no findings

Next slice is PR 8: read fusion and LM head wiring.

[abbudjoe]

PR 8 is merged into codex/fractal-v2.

What landed:

• typed read fusion with separate root, routed-tree, and exact-read lanes
• first end-to-end v2 logits path through the LM head
• PR 8 ablation coverage for zero routed values, zero exact-read values, and zero extra roots
• direct state-level regression proving extra-root ablation narrows memory materialization before sealed leaf summary/tree/cache writes

Validation passed on the merged state:

• cargo fmt --all
• cargo test -p fractal-core --quiet
• cargo clippy -p fractal-core --tests -- -D warnings
• cargo test -p fractal --quiet
• cargo test -p fractal --example tournament run_options_executes_tokenizer_backed_manifest_v2_and_persists_artifacts -- --nocapture

Reviewer loop:

• R1 found extra-root ablation was only late-fusion and flagged retrieved-value double normalization plus missing end-to-end baseline regression
• follow-up fixed those issues
• R2 requested a direct state-materialization regression at the sealed-leaf seam
• R3 came back with no findings

Checkpoint result:

• PR 8 delivers the first real smoke-training / forward proving point for v2
• next step is PR 8.5 / PR 9 causal memory auditing before synthetic task evaluation

[abbudjoe]

PR 8.5 is merged into codex/fractal-v2. The causal memory auditor is now in place with explicit no-tree, no-exact-read, next-best-span-substitution, and root-drop interventions; structured utility reporting by intervention/component/root/depth/head/span/selected leaf/task family; retrieval-task accuracy deltas with explicit denominators on mixed-task aggregates; and model-level regressions pinning truthful next-best normalization, all-slot head-context tracking, and retrieval-task reporting. This completes the post-PR-8 audit checkpoint and sets up PR 9 synthetic-task proving work.

[abbudjoe]

PR 9 is merged into codex/fractal-v2 at d263bc4.

What landed:

• synthetic probe harness in fractal-eval-private for copy, associative recall, induction, noisy retrieval, and far-token comparison
• explicit runtime FractalV2MemoryMode path so probe comparisons use real execution modes instead of late fusion masks
• structural evidence-span contracts plus live-path proof on a controlled sparse v2 path
• public v2 extension seams for router/exact-read/local-trunk/leaf outputs where the traits were previously public but not externally constructible
• tighter route-output coherence checks and tensor-derived span auditing so the harness and core auditor use the same routed-span source of truth

Validation rerun before merge:

• cargo test -p fractal-core --quiet
• cargo clippy -p fractal-core --tests -- -D warnings
• cargo test -p fractal-eval-private --quiet
• cargo clippy -p fractal-eval-private --tests -- -D warnings
• cargo test -p fractal --quiet
• cargo test -p fractal --example tournament run_options_executes_tokenizer_backed_manifest_v2_and_persists_artifacts -- --nocapture

Next slice is PR 10: benchmark and observability pass.

[abbudjoe]

PR 10 runner slice is merged into codex/fractal-v2 at dd3f381.

What landed:

• shared baseline v2 synthetic fixture in fractal-eval-private/src/v2_fixture.rs
• real live runner at src/bin/v2-synthetic-probe.rs
• JSON-serializable synthetic probe reports plus fixture reuse in fractal-eval-private/src/v2_synthetic.rs
• explicit rejection for undersized synthetic fixture vocab configs

Validation stayed green:

• cargo test -p fractal-eval-private --quiet
• cargo test -p fractal --quiet --bin v2-synthetic-probe
• cargo clippy -p fractal-eval-private --tests -- -D warnings
• cargo clippy -p fractal --bin v2-synthetic-probe --tests -- -D warnings
• cargo test -p fractal --quiet
• live runs through the integrated binary in table and JSON modes

Reviewer subagent came back with no findings. Residual risk is intentional for this slice: the runner is still CPU Candle + random-init only, so it is a live integration surface, not yet the final checkpoint-driven benchmark entrypoint.