Wave memory state library for Kerr-ODE architectures. Used by wave-server and the legacy kerr-server. Persistent harmonic band states that accumulate experience across conversations. The model reads and writes memory in its native coordinate system — no translation layer, no lossy conversion.
Pure Rust. Zero dependencies. ~920 lines.
A standard transformer has no concept of persistent experience. Every conversation starts from scratch. Fine-tuning changes the model itself — irreversible, opaque, expensive.
Wave memory is different. The model weights stay frozen (the "education"). A separate 1.5KB file stores accumulated harmonic band states (the "experience"). Each conversation shifts the Kerr-ODE's starting position on the unit circle — same model, different trajectory, different output.
The mechanism is native to the Kerr-ODE architecture. The model thinks in harmonic band oscillators. The memory stores harmonic band oscillators. No format conversion. No embedding lookup. The model resumes from where it was, not from a description of where it was.
| Experiment | Result | Finding |
|---|---|---|
| Injection sensitivity | PASS | Random noise at α=0.05 improves perplexity by 8.8% (stochastic resonance) |
| Accumulation stability | PASS | Converges over 20 conversations. Growth rate 280%→9.5%. β=0.99 recommended |
| Topic separation | NULL | Captures corpus texture, not topic at char-level 354K params. Bounded by model capacity |
| Memory reset | PASS | Bit-identical output after deletion. Zero residual effects |
| Anomaly detection | PASS | Spike at 50x energy caught immediately across all layers |
The mechanism works, is stable, is safe, and is inspectable. Semantic resolution depends on model capacity — word-level and BPE tokenization expected to enable topic separation.
# Build
cargo build --release
# See all commands
kerr-memory --help
# Create an empty memory file
kerr-memory create --n-bands 64 -o memory.kwmf
# Inspect a memory file
kerr-memory inspect memory.kwmf
# Full harmonic census with anomaly detection
kerr-memory census memory.kwmf
# Reset memory to zero (preserve config)
kerr-memory reset memory.kwmf
# Generate synthetic memory for testing
kerr-memory synth --type random --scale 0.1 -o test.kwmfAt conversation start, the server loads the .kwmf file and passes memory offsets to the engine's forward pass. The Kerr-ODE's initial conditions shift by α × M_k:
Z_k = input_k + α · memory_k
Additive injection — the memory nudges the starting position, the ODE dynamics amplify through nonlinear coupling. Small α (0.05) produces measurable effects because the Kerr self-phase modulation (α·|Z|²) amplifies bands where memory and input resonate.
During inference, each token's Kerr-ODE final state feeds an exponential moving average:
accumulator_k = decay · accumulator_k + (1 - decay) · ode_final_k
Bands that are consistently active across many tokens accumulate strongly. Bands that spike once and fade contribute almost nothing. At conversation end, the accumulator merges into the persistent memory:
memory_k = β · memory_k + (1 - β) · accumulator_k
The Kerr-ODE's dynamics do the memory processing without any special mechanism:
- Self-phase modulation (α·|Z_k|²): bands where memory and input BOTH have energy get amplified. Selective recall.
- Cross-phase modulation (β·neighbours): activating one band pulls related bands from memory. Associative recall.
- Damping (γ·Z_k): bands not reinforced by input decay toward zero. Natural forgetting. The trained γ values are the retention schedule.
Magic: "KWMF" (4 bytes)
Version: u32 (1)
n_layers: u32 (typically 3: blocks 1-3)
n_bands: u32 (typically 64 for 128-dim model)
alpha: f32 injection strength
decay: f32 within-conversation EMA
beta: f32 cross-conversation merge rate
n_convos: u32 conversations accumulated
Per layer (n_layers times):
r[n_bands]: f32[] real part of band oscillators
s[n_bands]: f32[] imaginary part of band oscillators
Default size: 32 header + 3 × 64 × 2 × 4 = 1,568 bytes.
| Parameter | Default | Range | Purpose |
|---|---|---|---|
| α (alpha) | 0.05 | 0.001 - 0.5 | How much memory influences ODE initial conditions |
| decay | 0.99 | 0.9 - 0.999 | Within-conversation EMA (higher = smoother) |
| β (beta) | 0.95 | 0.8 - 0.99 | Cross-conversation merge rate (higher = slower adaptation) |
Sweet spot from experiments: α=0.05, decay=0.99, β=0.99.
| Command | Purpose |
|---|---|
create |
Create an empty memory file with specified dimensions and config |
inspect |
Show header info, per-layer energy, peak bands |
census |
Full harmonic census: per-band energy, cross-layer correlation, anomaly detection |
reset |
Zero all band states (preserve config) |
synth |
Generate synthetic memory for testing (random, single-band, gradient) |
Run kerr-memory <command> --help for detailed options.
kerr-memory/src/
├── lib.rs Public API (re-exports all modules)
├── memory.rs Core structs: WaveMemory, MemoryLayer, MemoryConfig
├── file.rs KWMF binary format: save/load with validation
├── accumulator.rs EMA accumulator, energy-gated writing, merge
├── census.rs Harmonic census, cross-layer correlation, anomaly detection
└── main.rs CLI: create, inspect, census, reset, synth
~920 lines. 6 modules. 8 tests. Zero dependencies beyond std.
kerr-memory is a library crate imported by the inference servers:
# wave-server/Cargo.toml (or kerr-server/Cargo.toml)
[dependencies]
kerr-memory = { path = "../kerr-memory" }The server loads the .kwmf file at startup, passes memory offsets to the forward pass, updates the accumulator after each token, and saves the file after each conversation. The training engines don't import kerr-memory — they accept raw float offsets.
kerr-memory (zero deps) wave-engine (standalone)
↑ ↑
└───── wave-server ──────────┘
(imports both)
- Deletable: Remove the .kwmf file → model returns to trained baseline. Bit-identical (verified).
- Inspectable:
kerr-memory censusshows exactly what accumulated. Anomalies flagged before affecting output. - Bounded: Implicit regularisation (damping γ) prevents runaway. Accumulation converges (verified over 20 conversations).
- Separable: Model weights never change during inference. Memory is experience, not education.
- Resettable:
kerr-memory resetzeros all state, preserves config. Multiple memory files for different contexts.
The maintainer (Marco Da Cunha) is an IT systems administrator, not a programmer. This library was built through collaboration with AI (Claude Desktop for design, Claude Code for implementation). Stated openly.
- Main branch is protected. All changes through pull requests.
- Tests must pass.
cargo test— 8 tests covering round-trip file I/O, EMA accumulation, merge logic, energy gating, anomaly detection, cross-layer correlation.
- wave-engine — Training engine, successor to kerr-engine (public, Apache 2.0)
- wave-server — Inference server with
--memoryflag, successor to kerr-server (public, Apache 2.0) - kerr-engine — Original training engine, now parked (public, Apache 2.0)
- kerr-server — Original inference server, now parked (public, Apache 2.0)
- Wave Coherence — Research framework, Patterns 69-70 (public, MIT)
Apache 2.0. See LICENSE.
- Marco Da Cunha — Architecture, direction, wave memory concept
- Claude Desktop (Opus) — Mechanism design, physics analysis, documentation
- Claude Code — Implementation, testing, experiment execution
Part of the Wave Coherence as a Computational Primitive project.