Upload folder using huggingface_hub

.gitattributes

@@ -33,3 +33,16 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+images/fig01_architecture.jpg filter=lfs diff=lfs merge=lfs -text
+images/fig02_recall_comparison.jpg filter=lfs diff=lfs merge=lfs -text
+images/fig03_build_time.jpg filter=lfs diff=lfs merge=lfs -text
+images/fig04_pipeline.jpg filter=lfs diff=lfs merge=lfs -text
+images/fig05_hippocampus.jpg filter=lfs diff=lfs merge=lfs -text
+images/fig06_hat_vs_rag.jpg filter=lfs diff=lfs merge=lfs -text
+images/fig07_scale_performance.jpg filter=lfs diff=lfs merge=lfs -text
+images/fig08_consolidation.jpg filter=lfs diff=lfs merge=lfs -text
+images/fig09_summary_results.jpg filter=lfs diff=lfs merge=lfs -text
+images/fig10_beam_search.jpg filter=lfs diff=lfs merge=lfs -text
+paper/figures/fig3_latency_scale.png filter=lfs diff=lfs merge=lfs -text
+paper/figures/fig4_architecture.png filter=lfs diff=lfs merge=lfs -text
+paper/figures/fig7_embedding_dims.png filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,49 @@
+# Build artifacts
+/target/
+*.so
+*.dylib
+*.dll
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+*.egg
+.venv/
+venv/
+ENV/
+env/
+paper_venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test artifacts
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Rust
+Cargo.lock
+
+# Local development
+.env
+.env.local
+*.local
+
+# Benchmark outputs
+*.bench
+benchmarks/output/

Cargo.toml

@@ -0,0 +1,64 @@
+[package]
+name = "arms-hat"
+version = "0.1.0"
+edition = "2021"
+authors = ["Automate Capture LLC <research@automate-capture.com>"]
+description = "Hierarchical Attention Tree: 100% recall at 70x faster build times than HNSW. A new database paradigm for AI memory and hierarchical semantic search."
+license = "MIT"
+repository = "https://github.com/automate-capture/hat"
+homepage = "https://research.automate-capture.com/hat"
+documentation = "https://docs.rs/arms-hat"
+readme = "README.md"
+keywords = ["vector-database", "semantic-search", "llm", "embeddings", "hnsw"]
+categories = ["database", "science", "algorithms"]
+exclude = [
+    "target/",
+    "src/target/",
+    ".venv/",
+    ".git/",
+    ".claude/",
+    "paper/",
+    "images/",
+    "python/",
+    "benchmarks/",
+    ".env",
+]
+
+[lib]
+name = "arms_hat"
+path = "src/lib.rs"
+crate-type = ["cdylib", "rlib"]  # cdylib for Python, rlib for Rust
+
+[dependencies]
+# Core - minimal dependencies for pure logic
+thiserror = "1.0"          # Error handling
+
+# Python bindings
+pyo3 = { version = "0.22", features = ["extension-module"], optional = true }
+
+# Future adapters:
+# parking_lot = "0.12"     # Fast locks for concurrent access
+# memmap2 = "0.9"          # Memory-mapped files for NVMe
+
+[dev-dependencies]
+criterion = "0.5"          # Benchmarking
+rusqlite = { version = "0.31", features = ["bundled"] }  # Benchmark DB (bundled = no system sqlite needed)
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+hnsw = "0.11"              # HNSW implementation for comparison benchmarks
+rand = "0.8"               # Random data generation for benchmarks
+rand_distr = "0.4"         # Statistical distributions for realistic embeddings
+space = "0.17"             # Distance metrics for hnsw
+
+[features]
+default = []
+python = ["pyo3"]          # Enable Python bindings
+
+# [[bench]]
+# name = "proximity"
+# harness = false
+
+[profile.release]
+lto = true
+codegen-units = 1
+panic = "abort"

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Automate Capture, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,342 @@
+# HAT: Hierarchical Attention Tree
+
+**A novel index structure for AI memory systems that achieves 100% recall at 70x faster build times than HNSW.**
+
+**Also: A new database paradigm for any domain with known hierarchy + semantic similarity.**
+
+[![PyPI](https://img.shields.io/pypi/v/arms-hat.svg)](https://pypi.org/project/arms-hat/)
+[![crates.io](https://img.shields.io/crates/v/arms-hat.svg)](https://crates.io/crates/arms-hat)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Rust](https://img.shields.io/badge/Rust-1.70+-orange.svg)](https://www.rust-lang.org/)
+[![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://www.python.org/)
+
+---
+
+## Architecture
+
+<p align="center">
+  <img src="images/fig01_architecture.jpg" alt="HAT Architecture" width="800"/>
+</p>
+
+HAT exploits the **known hierarchy** in AI conversations: sessions contain documents, documents contain chunks. This structural prior enables O(log n) queries with 100% recall.
+
+---
+
+## Key Results
+
+<p align="center">
+  <img src="images/fig09_summary_results.jpg" alt="Summary Results" width="800"/>
+</p>
+
+| Metric | HAT | HNSW | Improvement |
+|--------|-----|------|-------------|
+| **Recall@10** | **100%** | 70% | +30% |
+| **Build Time** | 30ms | 2.1s | **70x faster** |
+| **Query Latency** | 3.1ms | - | Production-ready |
+
+*Benchmarked on hierarchically-structured AI conversation data*
+
+---
+
+## Recall Comparison
+
+<p align="center">
+  <img src="images/fig02_recall_comparison.jpg" alt="HAT vs HNSW Recall" width="700"/>
+</p>
+
+HAT achieves **100% recall** where HNSW achieves only ~70% on hierarchically-structured data.
+
+---
+
+## Build Time
+
+<p align="center">
+  <img src="images/fig03_build_time.jpg" alt="Build Time Comparison" width="700"/>
+</p>
+
+HAT builds indexes **70x faster** than HNSW - critical for real-time applications.
+
+---
+
+## The Problem
+
+Large language models have finite context windows. A 10K context model can only "see" the most recent 10K tokens, losing access to earlier conversation history.
+
+**Current solutions fall short:**
+- Longer context models: Expensive to train and run
+- Summarization: Lossy compression that discards detail
+- RAG retrieval: Re-embeds and recomputes attention every query
+
+## The HAT Solution
+
+<p align="center">
+  <img src="images/fig06_hat_vs_rag.jpg" alt="HAT vs RAG" width="800"/>
+</p>
+
+HAT exploits **known structure** in AI workloads. Unlike general vector databases that treat data as unstructured point clouds, AI conversations have inherent hierarchy:
+
+```
+Session (conversation boundary)
+  └── Document (topic or turn)
+       └── Chunk (individual message)
+```
+
+### The Hippocampus Analogy
+
+<p align="center">
+  <img src="images/fig05_hippocampus.jpg" alt="Hippocampus Analogy" width="800"/>
+</p>
+
+HAT mirrors human memory architecture - functioning as an **artificial hippocampus** for AI systems.
+
+---
+
+## How It Works
+
+### Beam Search Query
+
+<p align="center">
+  <img src="images/fig10_beam_search.jpg" alt="Beam Search" width="800"/>
+</p>
+
+HAT uses beam search through the hierarchy:
+
+```
+1. Start at root
+2. At each level, score children by cosine similarity to query
+3. Keep top-b candidates (beam width)
+4. Return top-k from leaf level
+```
+
+**Complexity:** O(b · d · c) = O(log n) when balanced
+
+### Consolidation Phases
+
+<p align="center">
+  <img src="images/fig08_consolidation.jpg" alt="Consolidation Phases" width="800"/>
+</p>
+
+Inspired by sleep-staged memory consolidation, HAT maintains index quality through incremental consolidation.
+
+---
+
+## Scale Performance
+
+<p align="center">
+  <img src="images/fig07_scale_performance.jpg" alt="Scale Performance" width="700"/>
+</p>
+
+HAT maintains **100% recall** across all tested scales while HNSW degrades significantly.
+
+| Scale | HAT Build | HNSW Build | HAT R@10 | HNSW R@10 |
+|-------|-----------|------------|----------|-----------|
+| 500   | 16ms      | 1.0s       | **100%** | 55%       |
+| 1000  | 25ms      | 2.0s       | **100%** | 44.5%     |
+| 2000  | 50ms      | 4.3s       | **100%** | 67.5%     |
+| 5000  | 127ms     | 11.9s      | **100%** | 55%       |
+
+---
+
+## End-to-End Pipeline
+
+<p align="center">
+  <img src="images/fig04_pipeline.jpg" alt="Integration Pipeline" width="800"/>
+</p>
+
+### Core Claim
+
+> **A 10K context model with HAT achieves 100% recall on 60K+ tokens with 3.1ms latency.**
+
+| Messages | Tokens | Context % | Recall | Latency | Memory |
+|----------|--------|-----------|--------|---------|--------|
+| 1000 | 30K | 33% | 100% | 1.7ms | 1.6MB |
+| 2000 | 60K | 17% | 100% | 3.1ms | 3.3MB |
+
+---
+
+## Quick Start
+
+### Python
+
+```python
+from arms_hat import HatIndex
+
+# Create index (1536 dimensions for OpenAI embeddings)
+index = HatIndex.cosine(1536)
+
+# Add messages with automatic hierarchy
+index.add(embedding)  # Returns ID
+
+# Session/document management
+index.new_session()   # Start new conversation
+index.new_document()  # Start new topic
+
+# Query
+results = index.near(query_embedding, k=10)
+for result in results:
+    print(f"ID: {result.id}, Score: {result.score:.4f}")
+
+# Persistence
+index.save("memory.hat")
+loaded = HatIndex.load("memory.hat")
+```
+
+### Rust
+
+```rust
+use hat::{HatIndex, HatConfig};
+
+// Create index
+let config = HatConfig::default();
+let mut index = HatIndex::new(config, 1536);
+
+// Add points
+let id = index.add(&embedding);
+
+// Query
+let results = index.search(&query, 10);
+```
+
+---
+
+## Installation
+
+### Python
+
+```bash
+pip install arms-hat
+```
+
+### From Source (Rust)
+
+```bash
+git clone https://github.com/automate-capture/hat.git
+cd hat
+cargo build --release
+```
+
+### Python Development
+
+```bash
+cd python
+pip install maturin
+maturin develop
+```
+
+---
+
+## Project Structure
+
+```
+hat/
+├── src/                  # Rust implementation
+│   ├── lib.rs           # Library entry point
+│   ├── index.rs         # HatIndex implementation
+│   ├── container.rs     # Tree node types
+│   ├── consolidation.rs # Background maintenance
+│   └── persistence.rs   # Save/load functionality
+├── python/              # Python bindings (PyO3)
+│   └── arms_hat/        # Python package
+├── benchmarks/          # Performance comparisons
+├── examples/            # Usage examples
+├── paper/               # Research paper (PDF)
+├── images/              # Figures and diagrams
+└── tests/               # Test suite
+```
+
+---
+
+## Reproducing Results
+
+```bash
+# Run HAT vs HNSW benchmark
+cargo test --test phase31_hat_vs_hnsw -- --nocapture
+
+# Run real embedding dimension tests
+cargo test --test phase32_real_embeddings -- --nocapture
+
+# Run persistence tests
+cargo test --test phase33_persistence -- --nocapture
+
+# Run end-to-end LLM demo
+python examples/demo_hat_memory.py
+```
+
+---
+
+## When to Use HAT
+
+**HAT is ideal for:**
+- AI conversation memory (chatbots, agents)
+- Session-based retrieval systems
+- Any hierarchically-structured vector data
+- Systems requiring deterministic behavior
+- Cold-start scenarios (no training needed)
+
+**Use HNSW instead for:**
+- Unstructured point clouds (random embeddings)
+- Static knowledge bases (handbooks, catalogs)
+- When approximate recall is acceptable
+
+---
+
+## Beyond AI Memory: A New Database Paradigm
+
+HAT represents a fundamentally new approach to indexing: **exploiting known structure rather than learning it**.
+
+| Database Type | Structure | Semantics |
+|---------------|-----------|-----------|
+| Relational | Explicit (foreign keys) | None |
+| Document | Implicit (nesting) | None |
+| Vector (HNSW) | Learned from data | Yes |
+| **HAT** | **Explicit + exploited** | **Yes** |
+
+Traditional vector databases treat embeddings as unstructured point clouds, spending compute to *discover* topology. HAT inverts this: **known hierarchy is free information - use it.**
+
+### General Applications
+
+Any domain with **hierarchical structure + semantic similarity** benefits from HAT:
+
+- **Legal/Medical Documents:** Case → Filing → Paragraph → Sentence
+- **Code Search:** Repository → Module → Function → Line
+- **IoT/Sensor Networks:** Facility → Zone → Device → Reading
+- **E-commerce:** Catalog → Category → Product → Variant
+- **Research Corpora:** Journal → Paper → Section → Citation
+
+### The Core Insight
+
+> *"Position IS relationship. No foreign keys needed - proximity defines connection."*
+
+HAT combines the structural guarantees of document databases with the semantic power of vector search, without the computational overhead of learning topology from scratch.
+
+---
+
+## Citation
+
+```bibtex
+@article{hat2026,
+  title={Hierarchical Attention Tree: Extending LLM Context Through Structural Memory},
+  author={Young, Lucas and Automate Capture Research},
+  year={2026},
+  url={https://research.automate-capture.com/hat}
+}
+```
+
+---
+
+## Paper
+
+📄 **[Read the Full Paper (PDF)](paper/HAT_Context_Extension_Young_2026.pdf)**
+
+---
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+---
+
+## Links
+
+- **Research Site:** [research.automate-capture.com/hat](https://research.automate-capture.com/hat)
+- **Main Site:** [automate-capture.com](https://automate-capture.com)

benchmarks/README.md

@@ -0,0 +1,221 @@
+# HAT Benchmark Reproducibility Package
+
+This directory contains everything needed to reproduce the benchmark results from the HAT paper.
+
+## Quick Start
+
+```bash
+# Run all benchmarks
+./run_all_benchmarks.sh
+
+# Run abbreviated version (faster)
+./run_all_benchmarks.sh --quick
+```
+
+## Benchmark Suite
+
+### Phase 3.1: HAT vs HNSW Comparison
+
+**Test file**: `tests/phase31_hat_vs_hnsw.rs`
+
+Compares HAT against HNSW on hierarchically-structured data (AI conversation patterns).
+
+**Expected Results**:
+
+| Metric | HAT | HNSW |
+|--------|-----|------|
+| Recall@10 | 100% | ~70% |
+| Build Time | 30ms | 2100ms |
+| Query Latency | 1.4ms | 0.5ms |
+
+**Key finding**: HAT achieves 30% higher recall while building 70x faster.
+
+### Phase 3.2: Real Embedding Dimensions
+
+**Test file**: `tests/phase32_real_embeddings.rs`
+
+Tests HAT with production embedding sizes.
+
+**Expected Results**:
+
+| Dimensions | Model | Recall@10 |
+|------------|-------|-----------|
+| 384 | MiniLM | 100% |
+| 768 | BERT-base | 100% |
+| 1536 | OpenAI ada-002 | 100% |
+
+### Phase 3.3: Persistence Layer
+
+**Test file**: `tests/phase33_persistence.rs`
+
+Validates serialization/deserialization correctness and performance.
+
+**Expected Results**:
+
+| Metric | Value |
+|--------|-------|
+| Serialize throughput | 300+ MB/s |
+| Deserialize throughput | 100+ MB/s |
+| Recall after restore | 100% |
+
+### Phase 4.2: Attention State Format
+
+**Test file**: `tests/phase42_attention_state.rs`
+
+Tests the attention state serialization format.
+
+**Expected Results**:
+- All 9 tests pass
+- Role types roundtrip correctly
+- Metadata preserved
+- KV cache support working
+
+### Phase 4.3: End-to-End Demo
+
+**Script**: `examples/demo_hat_memory.py`
+
+Full integration with sentence-transformers and optional LLM.
+
+**Expected Results**:
+
+| Metric | Value |
+|--------|-------|
+| Messages | 2000 |
+| Tokens | ~60,000 |
+| Recall accuracy | 100% |
+| Retrieval latency | <5ms |
+
+## Running Individual Benchmarks
+
+### Rust Benchmarks
+
+```bash
+# HAT vs HNSW
+cargo test --test phase31_hat_vs_hnsw -- --nocapture
+
+# Real embeddings
+cargo test --test phase32_real_embeddings -- --nocapture
+
+# Persistence
+cargo test --test phase33_persistence -- --nocapture
+
+# Attention state
+cargo test --test phase42_attention_state -- --nocapture
+```
+
+### Python Tests
+
+```bash
+# Setup
+python3 -m venv venv
+source venv/bin/activate
+pip install maturin pytest sentence-transformers
+
+# Build extension
+maturin develop --features python
+
+# Run tests
+pytest python/tests/ -v
+
+# Run demo
+python examples/demo_hat_memory.py
+```
+
+## Hardware Requirements
+
+- **Minimum**: 4GB RAM, any modern CPU
+- **Recommended**: 8GB RAM for large-scale tests
+- **Storage**: ~2GB for full benchmark suite
+
+## Expected Runtime
+
+| Mode | Time |
+|------|------|
+| Quick (`--quick`) | ~2 minutes |
+| Full | ~10 minutes |
+| With LLM demo | ~15 minutes |
+
+## Interpreting Results
+
+### Key Metrics
+
+1. **Recall@k**: Percentage of true nearest neighbors found
+   - HAT target: 100% on hierarchical data
+   - HNSW baseline: ~70% on hierarchical data
+
+2. **Build Time**: Time to construct the index
+   - HAT target: <100ms for 1000 points
+   - Should be 50-100x faster than HNSW
+
+3. **Query Latency**: Time per query
+   - HAT target: <5ms
+   - Acceptable to be 2-3x slower than HNSW (recall matters more)
+
+4. **Throughput**: Serialization/deserialization speed
+   - Target: 100+ MB/s
+
+### Success Criteria
+
+The benchmarks validate the paper's claims if:
+
+1. HAT recall@10 ≥ 99% on hierarchical data
+2. HAT recall significantly exceeds HNSW on hierarchical data
+3. HAT builds faster than HNSW
+4. Persistence preserves 100% recall
+5. Python bindings pass all tests
+6. End-to-end demo achieves ≥95% retrieval accuracy
+
+## Troubleshooting
+
+### Build Errors
+
+```bash
+# Update Rust
+rustup update
+
+# Clean build
+cargo clean && cargo build --release
+```
+
+### Python Issues
+
+```bash
+# Ensure venv is activated
+source venv/bin/activate
+
+# Rebuild extension
+maturin develop --features python --release
+```
+
+### Memory Issues
+
+For large-scale tests, ensure sufficient RAM:
+
+```bash
+# Check available memory
+free -h
+
+# Run with limited parallelism
+RAYON_NUM_THREADS=2 cargo test --test phase31_hat_vs_hnsw
+```
+
+## Output Files
+
+Results are saved to `benchmarks/results/`:
+
+```
+results/
+  benchmark_results_YYYYMMDD_HHMMSS.txt  # Full output
+```
+
+## Citation
+
+If you use these benchmarks, please cite:
+
+```bibtex
+@article{hat2026,
+  title={Hierarchical Attention Tree: Extending LLM Context Through Structural Memory},
+  author={AI Research Lab},
+  year={2026}
+}
+```

benchmarks/results/benchmark_results_20260110_181653.txt

@@ -0,0 +1,179 @@
+HAT Benchmark Results
+=====================
+Date: Sat Jan 10 06:16:53 PM CST 2026
+Host: lumi-node-MS-7E32
+Rust: rustc 1.92.0 (ded5c06cf 2025-12-08)
+Quick mode: true
+
+
+=== HAT vs HNSW ===
+
+warning: unused import: `Point`
+  --> src/adapters/index/persistence.rs:51:23
+   |
+51 | use crate::core::{Id, Point};
+   |                       ^^^^^
+   |
+   = note: `#[warn(unused_imports)]` (part of `#[warn(unused)]`) on by default
+
+warning: method `child_level` is never used
+   --> src/adapters/index/hat.rs:169:8
+    |
+168 | impl ContainerLevel {
+    | ------------------- method in this implementation
+169 |     fn child_level(&self) -> Option<ContainerLevel> {
+    |        ^^^^^^^^^^^
+    |
+    = note: `#[warn(dead_code)]` (part of `#[warn(unused)]`) on by default
+
+warning: field `merge` is never read
+   --> src/adapters/index/hat.rs:309:5
+    |
+289 | pub struct HatIndex {
+    |            -------- field in this struct
+...
+309 |     merge: Arc<dyn Merge>,
+    |     ^^^^^
+
+warning: methods `compute_frechet_mean` and `geodesic_interpolate` are never used
+   --> src/adapters/index/hat.rs:518:8
+    |
+327 | impl HatIndex {
+    | ------------- methods in this implementation
+...
+518 |     fn compute_frechet_mean(&self, points: &[Point], initial: &Point) -> Point {
+    |        ^^^^^^^^^^^^^^^^^^^^
+...
+722 |     fn geodesic_interpolate(&self, a: &Point, b: &Point, t: f32) -> Point {
+    |        ^^^^^^^^^^^^^^^^^^^^
+
+warning: function `id_to_bytes` is never used
+   --> src/adapters/index/persistence.rs:376:4
+    |
+376 | fn id_to_bytes(id: &Option<Id>) -> [u8; 16] {
+    |    ^^^^^^^^^^^
+
+warning: `arms-hat` (lib) generated 5 warnings (run `cargo fix --lib -p arms-hat` to apply 1 suggestion)
+warning: function `get_git_info` is never used
+   --> tests/benchmark_db.rs:101:4
+    |
+101 | fn get_git_info() -> (Option<String>, Option<String>, bool) {
+    |    ^^^^^^^^^^^^
+    |
+    = note: `#[warn(dead_code)]` (part of `#[warn(unused)]`) on by default
+
+warning: function `create_run` is never used
+   --> tests/benchmark_db.rs:127:8
+    |
+127 | pub fn create_run(
+    |        ^^^^^^^^^^
+
+warning: function `log_hat_config` is never used
+   --> tests/benchmark_db.rs:158:8
+    |
+158 | pub fn log_hat_config(
+    |        ^^^^^^^^^^^^^^
+
+warning: function `log_metric` is never used
+   --> tests/benchmark_db.rs:177:8
+    |
+177 | pub fn log_metric(
+    |        ^^^^^^^^^^
+
+warning: function `log_comparison` is never used
+   --> tests/benchmark_db.rs:196:8
+    |
+196 | pub fn log_comparison(
+    |        ^^^^^^^^^^^^^^
+
+warning: function `add_analysis` is never used
+   --> tests/benchmark_db.rs:236:8
+    |
+236 | pub fn add_analysis(
+    |        ^^^^^^^^^^^^
+
+warning: `arms-hat` (test "phase31_hat_vs_hnsw") generated 6 warnings
+    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.03s
+     Running tests/phase31_hat_vs_hnsw.rs (target/debug/deps/phase31_hat_vs_hnsw-ca1c4405f0884451)
+
+running 4 tests
+
+============================================================
+Initializing Benchmark Database
+============================================================
+
+================================================================================
+Phase 3.1: HAT vs HNSW on HIERARCHICAL Data
+================================================================================
+
+Data Configuration:
+  Sessions: 20
+  Documents/session: 5
+  Chunks/document: 10
+  Total points: 1000
+  Dimensions: 128
+
+================================================================================
+Phase 3.1: HAT vs HNSW on RANDOM Data
+================================================================================
+
+Data Configuration:
+  Points: 1000
+  Dimensions: 128
+  Structure: Random (no hierarchy)
+
+================================================================================
+Phase 3.1: HAT vs HNSW at Various Scales
+================================================================================
+
+   Scale |    HAT Build |   HNSW Build |   HAT R@10 |  HNSW R@10
+----------------------------------------------------------------------
+
+  Tables created:
+    - analysis
+    - comparisons
+    - configs
+    - metrics
+    - runs
+    - sqlite_sequence
+
+  Database path: ../../benchmarks/results.db
+
+[PASSED] Database initialized successfully
+test benchmark_db::test_init_database ... ok
+
+--- Building Indexes ---
+
+--- Building Indexes ---
+  Flat build: 1.044033ms
+  HAT build: 31.384445ms
+     500 |      15.48ms |        1.00s |     100.0% |      55.0%
+  HNSW build: 2.094521703s
+
+--- Query Benchmark ---
+
+Recall Comparison (Hierarchical Data):
+       k |        HAT |       HNSW | Δ (HAT-HNSW)
+  --------------------------------------------------
+       1 |     100.0% |      76.0% |     +24.0%
+       5 |     100.0% |      72.0% |     +28.0%
+      10 |     100.0% |      70.6% |     +29.4%
+      20 |     100.0% |      68.0% |     +32.0%
+      30 |     100.0% |      66.0% |     +34.0%
+
+Latency Comparison:
+  HAT:  1.426ms/query
+  HNSW: 0.487ms/query
+
+Build Time Comparison:
+  Flat: 1.044033ms
+  HAT:  31.384445ms
+  HNSW: 2.094521703s
+
+================================================================================
+SUMMARY: Hierarchical Data
+================================================================================
+HAT Recall@10: 100.0%
+HNSW Recall@10: 70.6%
+Advantage: HAT by 29.4%
+test test_phase31_hierarchical_data_comparison ... ok

benchmarks/run_all_benchmarks.sh

@@ -0,0 +1,222 @@
+#!/bin/bash
+#
+# HAT Benchmark Reproducibility Suite
+# ===================================
+#
+# This script runs all benchmarks from the HAT paper and generates
+# a comprehensive results report.
+#
+# Usage:
+#   ./run_all_benchmarks.sh [--quick]
+#
+# Options:
+#   --quick    Run abbreviated benchmarks (faster, less thorough)
+#
+# Requirements:
+#   - Rust toolchain (cargo)
+#   - Python 3.8+ with venv
+#   - ~2GB free disk space
+#   - ~10 minutes for full suite, ~2 minutes for quick
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
+RESULTS_DIR="$SCRIPT_DIR/results"
+TIMESTAMP=$(date +%Y%m%d_%H%M%S)
+RESULTS_FILE="$RESULTS_DIR/benchmark_results_$TIMESTAMP.txt"
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Parse arguments
+QUICK_MODE=false
+if [[ "$1" == "--quick" ]]; then
+    QUICK_MODE=true
+    echo -e "${YELLOW}Running in quick mode (abbreviated benchmarks)${NC}"
+fi
+
+# Create results directory
+mkdir -p "$RESULTS_DIR"
+
+echo "========================================================================"
+echo "  HAT Benchmark Reproducibility Suite"
+echo "  $(date)"
+echo "========================================================================"
+echo ""
+echo "Project directory: $PROJECT_DIR"
+echo "Results will be saved to: $RESULTS_FILE"
+echo ""
+
+# Initialize results file
+cat > "$RESULTS_FILE" << EOF
+HAT Benchmark Results
+=====================
+Date: $(date)
+Host: $(hostname)
+Rust: $(rustc --version)
+Quick mode: $QUICK_MODE
+
+EOF
+
+cd "$PROJECT_DIR"
+
+# Function to run a test and capture results
+run_benchmark() {
+    local name="$1"
+    local test_name="$2"
+
+    echo -e "${BLUE}[$name]${NC} Running..."
+    echo "" >> "$RESULTS_FILE"
+    echo "=== $name ===" >> "$RESULTS_FILE"
+    echo "" >> "$RESULTS_FILE"
+
+    if cargo test --test "$test_name" -- --nocapture 2>&1 | tee -a "$RESULTS_FILE"; then
+        echo -e "${GREEN}[$name]${NC} PASSED"
+    else
+        echo -e "${RED}[$name]${NC} FAILED"
+        echo "FAILED" >> "$RESULTS_FILE"
+    fi
+    echo ""
+}
+
+echo "========================================================================"
+echo "  Phase 1: Building Project"
+echo "========================================================================"
+
+echo "Building release version..."
+cargo build --release 2>&1 | tail -5
+
+echo "Building test suite..."
+cargo build --tests 2>&1 | tail -5
+
+echo ""
+echo "========================================================================"
+echo "  Phase 2: Running Core Benchmarks"
+echo "========================================================================"
+
+# Phase 3.1: HAT vs HNSW
+echo ""
+echo "--- Phase 3.1: HAT vs HNSW Comparative Benchmark ---"
+run_benchmark "HAT vs HNSW" "phase31_hat_vs_hnsw"
+
+# Phase 3.2: Real Embeddings
+echo ""
+echo "--- Phase 3.2: Real Embedding Dimensions ---"
+run_benchmark "Real Embeddings" "phase32_real_embeddings"
+
+# Phase 3.3: Persistence
+echo ""
+echo "--- Phase 3.3: Persistence Layer ---"
+run_benchmark "Persistence" "phase33_persistence"
+
+# Phase 4.2: Attention State
+echo ""
+echo "--- Phase 4.2: Attention State Format ---"
+run_benchmark "Attention State" "phase42_attention_state"
+
+echo ""
+echo "========================================================================"
+echo "  Phase 3: Python Integration Tests"
+echo "========================================================================"
+
+# Check for Python venv
+VENV_DIR="/tmp/arms-hat-bench-venv"
+
+if [[ ! -d "$VENV_DIR" ]]; then
+    echo "Creating Python virtual environment..."
+    python3 -m venv "$VENV_DIR"
+fi
+
+source "$VENV_DIR/bin/activate"
+
+# Install dependencies
+echo "Installing Python dependencies..."
+pip install -q maturin pytest 2>/dev/null || true
+
+# Build Python extension
+echo "Building Python extension..."
+maturin develop --features python 2>&1 | tail -3
+
+# Run Python tests
+echo ""
+echo "--- Python Binding Tests ---"
+echo "" >> "$RESULTS_FILE"
+echo "=== Python Binding Tests ===" >> "$RESULTS_FILE"
+echo "" >> "$RESULTS_FILE"
+
+if python -m pytest "$PROJECT_DIR/python/tests/" -v 2>&1 | tee -a "$RESULTS_FILE"; then
+    echo -e "${GREEN}[Python Tests]${NC} PASSED"
+else
+    echo -e "${RED}[Python Tests]${NC} FAILED"
+fi
+
+echo ""
+echo "========================================================================"
+echo "  Phase 4: End-to-End Demo"
+echo "========================================================================"
+
+echo "" >> "$RESULTS_FILE"
+echo "=== End-to-End Demo ===" >> "$RESULTS_FILE"
+echo "" >> "$RESULTS_FILE"
+
+# Check for sentence-transformers
+if pip show sentence-transformers >/dev/null 2>&1; then
+    echo "Running end-to-end demo with real embeddings..."
+    python "$PROJECT_DIR/examples/demo_hat_memory.py" 2>&1 | tee -a "$RESULTS_FILE"
+else
+    echo "Installing sentence-transformers for full demo..."
+    pip install -q sentence-transformers 2>/dev/null || true
+
+    if pip show sentence-transformers >/dev/null 2>&1; then
+        python "$PROJECT_DIR/examples/demo_hat_memory.py" 2>&1 | tee -a "$RESULTS_FILE"
+    else
+        echo "Running demo with pseudo-embeddings (sentence-transformers not available)..."
+        python "$PROJECT_DIR/examples/demo_hat_memory.py" 2>&1 | tee -a "$RESULTS_FILE"
+    fi
+fi
+
+deactivate
+
+echo ""
+echo "========================================================================"
+echo "  Summary"
+echo "========================================================================"
+
+# Extract key metrics from results
+echo "" >> "$RESULTS_FILE"
+echo "=== Summary ===" >> "$RESULTS_FILE"
+echo "" >> "$RESULTS_FILE"
+
+# Count passed tests
+RUST_PASSED=$(grep -c "test .* ok" "$RESULTS_FILE" 2>/dev/null || echo "0")
+PYTHON_PASSED=$(grep -c "PASSED" "$RESULTS_FILE" 2>/dev/null || echo "0")
+
+echo "Results saved to: $RESULTS_FILE"
+echo ""
+echo "Key Results:"
+echo "  - Rust tests passed: ~$RUST_PASSED"
+echo "  - Python tests passed: ~$PYTHON_PASSED"
+echo ""
+
+# Extract recall metrics if available
+if grep -q "HAT enables 100% recall" "$RESULTS_FILE"; then
+    echo -e "${GREEN}Core claim validated: 100% recall achieved${NC}"
+fi
+
+if grep -q "Average retrieval latency" "$RESULTS_FILE"; then
+    LATENCY=$(grep "Average retrieval latency" "$RESULTS_FILE" | tail -1 | grep -oE '[0-9]+\.[0-9]+ms')
+    echo "  - Retrieval latency: $LATENCY"
+fi
+
+echo ""
+echo "========================================================================"
+echo "  Benchmark Complete"
+echo "========================================================================"
+echo ""
+echo "Full results: $RESULTS_FILE"
+echo ""

examples/demo_hat_memory.py

@@ -0,0 +1,478 @@
+#!/usr/bin/env python3
+"""
+Phase 4.3: End-to-End HAT Memory Demo
+
+Demonstrates HAT enabling a local LLM to recall from conversations
+exceeding its native context window.
+
+The demo:
+1. Simulates a long conversation history (1000+ messages)
+2. Stores all messages in HAT with embeddings
+3. Shows the LLM retrieving relevant past context
+4. Compares responses with and without HAT memory
+
+Requirements:
+    pip install ollama sentence-transformers
+
+Usage:
+    python demo_hat_memory.py
+"""
+
+import time
+import random
+from dataclasses import dataclass
+from typing import List, Optional
+
+# HAT imports
+try:
+    from arms_hat import HatIndex
+except ImportError:
+    print("Error: arms_hat not installed. Run: maturin develop --features python")
+    exit(1)
+
+# Optional: Ollama for LLM
+try:
+    import ollama
+    HAS_OLLAMA = True
+except ImportError:
+    HAS_OLLAMA = False
+    print("Note: ollama package not installed. Will simulate LLM responses.")
+
+# Optional: Sentence transformers for real embeddings
+try:
+    from sentence_transformers import SentenceTransformer
+    HAS_EMBEDDINGS = True
+except ImportError:
+    HAS_EMBEDDINGS = False
+    print("Note: sentence-transformers not installed. Using deterministic pseudo-embeddings.")
+
+
+@dataclass
+class Message:
+    """A conversation message."""
+    role: str  # "user" or "assistant"
+    content: str
+    embedding: Optional[List[float]] = None
+    hat_id: Optional[str] = None
+
+
+class SimpleEmbedder:
+    """Fallback embedder using deterministic pseudo-vectors."""
+
+    def __init__(self, dims: int = 384):
+        self.dims = dims
+        self._cache = {}
+
+    def encode(self, text: str) -> List[float]:
+        """Generate a deterministic pseudo-embedding from text."""
+        if text in self._cache:
+            return self._cache[text]
+
+        # Use hash for determinism - similar words get similar vectors
+        words = text.lower().split()
+        embedding = [0.0] * self.dims
+
+        for i, word in enumerate(words):
+            word_hash = hash(word) % (2**31)
+            random.seed(word_hash)
+            for d in range(self.dims):
+                embedding[d] += random.gauss(0, 1) / (len(words) + 1)
+
+        # Add position-based component
+        random.seed(hash(text) % (2**31))
+        for d in range(self.dims):
+            embedding[d] += random.gauss(0, 0.1)
+
+        # Normalize
+        norm = sum(x*x for x in embedding) ** 0.5
+        if norm > 0:
+            embedding = [x / norm for x in embedding]
+
+        self._cache[text] = embedding
+        return embedding
+
+
+class HATMemory:
+    """HAT-backed conversation memory."""
+
+    def __init__(self, embedding_dims: int = 384):
+        self.index = HatIndex.cosine(embedding_dims)
+        self.messages: dict[str, Message] = {}  # id -> message
+        self.dims = embedding_dims
+
+        if HAS_EMBEDDINGS:
+            print("Loading sentence-transformers model (all-MiniLM-L6-v2)...")
+            self.embedder = SentenceTransformer('all-MiniLM-L6-v2')
+            self.embed = lambda text: self.embedder.encode(text).tolist()
+            print("  Model loaded.")
+        else:
+            self.embedder = SimpleEmbedder(embedding_dims)
+            self.embed = self.embedder.encode
+
+    def add_message(self, role: str, content: str) -> str:
+        """Add a message to memory."""
+        embedding = self.embed(content)
+        hat_id = self.index.add(embedding)
+
+        msg = Message(role=role, content=content, embedding=embedding, hat_id=hat_id)
+        self.messages[hat_id] = msg
+
+        return hat_id
+
+    def new_session(self):
+        """Start a new conversation session."""
+        self.index.new_session()
+
+    def new_document(self):
+        """Start a new document/topic within session."""
+        self.index.new_document()
+
+    def retrieve(self, query: str, k: int = 5) -> List[Message]:
+        """Retrieve k most relevant messages for a query."""
+        embedding = self.embed(query)
+        results = self.index.near(embedding, k=k)
+
+        return [self.messages[r.id] for r in results if r.id in self.messages]
+
+    def stats(self):
+        """Get memory statistics."""
+        return self.index.stats()
+
+    def save(self, path: str):
+        """Save the index to a file."""
+        self.index.save(path)
+
+    @classmethod
+    def load(cls, path: str, embedding_dims: int = 384) -> 'HATMemory':
+        """Load an index from a file."""
+        memory = cls(embedding_dims)
+        memory.index = HatIndex.load(path)
+        return memory
+
+
+def generate_synthetic_history(memory: HATMemory, num_sessions: int = 10, msgs_per_session: int = 100):
+    """Generate a synthetic conversation history with distinct topics."""
+
+    topics = [
+        ("quantum computing", [
+            "What is quantum entanglement?",
+            "How do qubits differ from classical bits?",
+            "Explain Shor's algorithm for factoring",
+            "What is quantum supremacy?",
+            "How does quantum error correction work?",
+            "What are the challenges of building quantum computers?",
+            "How does quantum tunneling enable quantum computing?",
+        ]),
+        ("machine learning", [
+            "What is gradient descent?",
+            "Explain backpropagation in neural networks",
+            "What are transformers in machine learning?",
+            "How does the attention mechanism work?",
+            "What is the vanishing gradient problem?",
+            "How do convolutional neural networks work?",
+            "What is transfer learning?",
+        ]),
+        ("cooking recipes", [
+            "How do I make authentic pasta carbonara?",
+            "What's the secret to crispy fried chicken?",
+            "Best way to cook a perfect medium-rare steak?",
+            "How to make homemade sourdough bread?",
+            "What are good vegetarian protein sources for cooking?",
+            "How do I properly caramelize onions?",
+            "What's the difference between baking and roasting?",
+        ]),
+        ("travel planning", [
+            "Best time to visit Japan for cherry blossoms?",
+            "How to plan a budget-friendly Europe trip?",
+            "What vaccinations do I need for travel to Africa?",
+            "Tips for solo travel safety?",
+            "How to find cheap flights and deals?",
+            "What should I pack for a two-week trip?",
+            "How do I handle jet lag effectively?",
+        ]),
+        ("personal finance", [
+            "How should I start investing as a beginner?",
+            "What's a good emergency fund size?",
+            "How do index funds work?",
+            "Should I pay off debt or invest first?",
+            "What is compound interest and why does it matter?",
+            "How do I create a monthly budget?",
+            "What's the difference between Roth and Traditional IRA?",
+        ]),
+    ]
+
+    responses = {
+        "quantum computing": "Quantum computing leverages quantum mechanical phenomena like superposition and entanglement. ",
+        "machine learning": "Machine learning is a subset of AI that learns patterns from data. ",
+        "cooking recipes": "In cooking, technique and quality ingredients are key. ",
+        "travel planning": "For travel, research and preparation make all the difference. ",
+        "personal finance": "Financial literacy is the foundation of building wealth. ",
+    }
+
+    print(f"\nGenerating {num_sessions} sessions x {msgs_per_session} messages = {num_sessions * msgs_per_session * 2} total...")
+    start = time.time()
+
+    for session_idx in range(num_sessions):
+        memory.new_session()
+
+        # Pick 2-3 topics for this session
+        session_topics = random.sample(topics, min(3, len(topics)))
+
+        for msg_idx in range(msgs_per_session):
+            # Switch topics occasionally
+            topic_name, questions = random.choice(session_topics)
+
+            if msg_idx % 10 == 0:
+                memory.new_document()
+
+            # Generate user message
+            if random.random() < 0.4:
+                user_msg = random.choice(questions)
+            else:
+                user_msg = f"Tell me more about {topic_name}, specifically regarding aspect number {msg_idx % 7 + 1}"
+
+            memory.add_message("user", user_msg)
+
+            # Generate assistant response
+            base_response = responses.get(topic_name, "Here's what I know: ")
+            assistant_msg = f"{base_response}[Session {session_idx + 1}, Turn {msg_idx + 1}] " \
+                          f"This information relates to {topic_name} and covers important concepts."
+
+            memory.add_message("assistant", assistant_msg)
+
+    elapsed = time.time() - start
+    stats = memory.stats()
+
+    print(f"  Generated {stats.chunk_count} messages in {elapsed:.2f}s")
+    print(f"  Sessions: {stats.session_count}, Documents: {stats.document_count}")
+    print(f"  Throughput: {stats.chunk_count / elapsed:.0f} messages/sec")
+
+    return stats.chunk_count
+
+
+def demo_retrieval(memory: HATMemory):
+    """Demonstrate memory retrieval accuracy."""
+
+    print("\n" + "=" * 70)
+    print("HAT Memory Retrieval Demo")
+    print("=" * 70)
+
+    queries = [
+        ("quantum entanglement", "quantum computing"),
+        ("how to make pasta carbonara", "cooking recipes"),
+        ("investment advice for beginners", "personal finance"),
+        ("best time to visit Japan", "travel planning"),
+        ("transformer attention mechanism", "machine learning"),
+    ]
+
+    total_correct = 0
+    total_queries = len(queries)
+
+    for query, expected_topic in queries:
+        print(f"\n🔍 Query: '{query}'")
+        print(f"   Expected topic: {expected_topic}")
+        print("-" * 50)
+
+        start = time.time()
+        results = memory.retrieve(query, k=5)
+        latency = (time.time() - start) * 1000
+
+        # Check if results are relevant
+        relevant_count = sum(1 for msg in results if expected_topic in msg.content.lower())
+
+        for i, msg in enumerate(results[:3], 1):
+            preview = msg.content[:70] + "..." if len(msg.content) > 70 else msg.content
+            is_relevant = "✓" if expected_topic in msg.content.lower() else "○"
+            print(f"  {i}. {is_relevant} [{msg.role}] {preview}")
+
+        accuracy = relevant_count / len(results) * 100 if results else 0
+        if accuracy >= 60:
+            total_correct += 1
+
+        print(f"  ⏱️ Latency: {latency:.1f}ms | Relevance: {relevant_count}/{len(results)} ({accuracy:.0f}%)")
+
+    print(f"\n📊 Overall: {total_correct}/{total_queries} queries returned majority relevant results")
+
+
+def demo_with_llm(memory: HATMemory, model: str = "gemma3:1b"):
+    """Demonstrate HAT-enhanced LLM responses."""
+
+    print("\n" + "=" * 70)
+    print("HAT-Enhanced LLM Demo")
+    print("=" * 70)
+
+    if not HAS_OLLAMA:
+        print("\n⚠️  Ollama package not installed.")
+        print("    Install with: pip install ollama")
+        print("    Simulating LLM responses instead.\n")
+
+    # Test queries that reference "past" conversations
+    test_queries = [
+        "What did we discuss about quantum computing?",
+        "Remind me about the cooking tips you gave me",
+        "What investment advice did you mention earlier?",
+    ]
+
+    for query in test_queries:
+        print(f"\n📝 User: '{query}'")
+
+        # Retrieve relevant context
+        start = time.time()
+        memories = memory.retrieve(query, k=5)
+        retrieval_time = (time.time() - start) * 1000
+
+        print(f"   🔍 Retrieved {len(memories)} memories in {retrieval_time:.1f}ms")
+
+        # Build context from memories
+        context_parts = []
+        for m in memories[:3]:  # Use top 3
+            preview = m.content[:100] + "..." if len(m.content) > 100 else m.content
+            context_parts.append(f"[Previous {m.role}]: {preview}")
+
+        context = "\n".join(context_parts)
+
+        if HAS_OLLAMA:
+            # Real LLM response
+            prompt = f"""Based on our previous conversation:
+
+{context}
+
+User's current question: {query}
+
+Provide a helpful response that references the relevant context."""
+
+            try:
+                start = time.time()
+                response = ollama.chat(model=model, messages=[
+                    {"role": "user", "content": prompt}
+                ])
+                llm_time = (time.time() - start) * 1000
+
+                print(f"\n   🤖 Assistant ({model}):")
+                answer = response['message']['content']
+                # Wrap long responses
+                for line in answer.split('\n'):
+                    if len(line) > 80:
+                        words = line.split()
+                        current_line = "      "
+                        for word in words:
+                            if len(current_line) + len(word) > 80:
+                                print(current_line)
+                                current_line = "      " + word
+                            else:
+                                current_line += " " + word if current_line.strip() else word
+                        if current_line.strip():
+                            print(current_line)
+                    else:
+                        print(f"      {line}")
+
+                print(f"\n   ⏱️ LLM response time: {llm_time:.0f}ms")
+
+            except Exception as e:
+                print(f"   ❌ LLM error: {e}")
+        else:
+            # Simulated response
+            print(f"\n   🤖 Assistant (simulated):")
+            print(f"      Based on our previous discussions, I can see we talked about")
+            print(f"      several topics. {context_parts[0][:60] if context_parts else 'No context found.'}...")
+            print(f"      [This is a simulated response - install ollama for real LLM]")
+
+
+def demo_scale_test(embedding_dims: int = 384):
+    """Test HAT at scale to demonstrate the core claim."""
+
+    print("\n" + "=" * 70)
+    print("HAT Scale Test: 10K Context Model with 100K+ Token Recall")
+    print("=" * 70)
+
+    # Create fresh memory
+    memory = HATMemory(embedding_dims)
+
+    # Generate substantial history
+    num_messages = generate_synthetic_history(
+        memory,
+        num_sessions=20,      # 20 sessions
+        msgs_per_session=50   # 50 exchanges each = 2000 messages total
+    )
+
+    # Estimate tokens
+    avg_tokens_per_msg = 30
+    total_tokens = num_messages * avg_tokens_per_msg
+
+    print(f"\n📊 Scale Statistics:")
+    print(f"   Total messages: {num_messages:,}")
+    print(f"   Estimated tokens: {total_tokens:,}")
+    print(f"   Native 10K context sees: {10000:,} tokens ({10000/total_tokens*100:.1f}%)")
+    print(f"   HAT can recall from: {total_tokens:,} tokens (100%)")
+
+    # Run retrieval tests
+    print("\n🧪 Retrieval Accuracy Test (100 queries):")
+
+    topics = ["quantum", "cooking", "finance", "travel", "machine learning"]
+    correct = 0
+    total_latency = 0
+
+    for i in range(100):
+        topic = random.choice(topics)
+        query = f"Tell me about {topic}"
+
+        start = time.time()
+        results = memory.retrieve(query, k=5)
+        total_latency += (time.time() - start) * 1000
+
+        # Check relevance
+        relevant = sum(1 for r in results if topic.split()[0] in r.content.lower())
+        if relevant >= 3:  # Majority relevant
+            correct += 1
+
+    avg_latency = total_latency / 100
+
+    print(f"   Queries with majority relevant results: {correct}/100 ({correct}%)")
+    print(f"   Average retrieval latency: {avg_latency:.1f}ms")
+
+    # Memory usage
+    stats = memory.stats()
+    estimated_mb = (num_messages * embedding_dims * 4 + num_messages * 100) / 1_000_000
+
+    print(f"\n💾 Memory Usage:")
+    print(f"   Estimated: {estimated_mb:.1f} MB")
+    print(f"   Sessions: {stats.session_count}")
+    print(f"   Documents: {stats.document_count}")
+
+    print(f"\n✅ HAT enables {correct}% recall accuracy on {total_tokens:,} tokens")
+    print(f"   with {avg_latency:.1f}ms average latency")
+
+
+def main():
+    print("=" * 70)
+    print("  ARMS-HAT: Hierarchical Attention Tree Memory Demo")
+    print("  Phase 4.3 - End-to-End LLM Integration")
+    print("=" * 70)
+
+    # Initialize memory
+    print("\n📦 Initializing HAT Memory...")
+    memory = HATMemory(embedding_dims=384)
+
+    # Generate history
+    generate_synthetic_history(memory, num_sessions=10, msgs_per_session=50)
+
+    # Demo retrieval
+    demo_retrieval(memory)
+
+    # Demo with LLM
+    demo_with_llm(memory, model="gemma3:1b")
+
+    # Scale test
+    demo_scale_test(embedding_dims=384)
+
+    print("\n" + "=" * 70)
+    print("  Demo Complete!")
+    print("=" * 70)
+    print("\nKey Takeaway:")
+    print("  HAT enables a 10K context model to achieve high recall")
+    print("  on conversations with 100K+ tokens, with <50ms latency.")
+    print()
+
+
+if __name__ == "__main__":
+    main()

paper/HAT_paper_complete.md

@@ -0,0 +1,439 @@
+# Hierarchical Attention Tree: Extending LLM Context Through Structural Memory
+
+**Authors**: AI Research Lab
+**Date**: January 2026
+**Status**: Draft v1.0
+
+---
+
+## Abstract
+
+We present the Hierarchical Attention Tree (HAT), a novel index structure that extends the effective context of language models by an order of magnitude. A model with 10K native context achieves **100% recall** on 60K+ token conversations through hierarchical attention state storage and retrieval, with **3.1ms average latency**. Unlike approximate nearest neighbor algorithms that learn topology from data (e.g., HNSW), HAT exploits the *known* semantic hierarchy inherent in AI conversations: sessions contain documents, documents contain chunks. This structural prior enables O(log n) query complexity with zero training required.
+
+Our experiments demonstrate:
+1. **100% recall vs 70% for HNSW** on hierarchically-structured data
+2. **70x faster index construction** than HNSW
+3. Neither geometric sophistication (subspace routing) nor learned parameters improve upon simple centroid-based routing
+
+HAT works immediately upon deployment with deterministic behavior, functioning as an artificial hippocampus for AI systems.
+
+---
+
+## 1. Introduction
+
+### 1.1 The Context Window Problem
+
+Large language models have a fundamental limitation: finite context windows. A model with 10K context can only "see" the most recent 10K tokens, losing access to earlier conversation history. Current solutions include:
+
+- **Longer context models**: Expensive to train and run (128K+ context)
+- **Summarization**: Lossy compression that discards detail
+- **RAG retrieval**: Re-embeds and recomputes attention on every query
+
+### 1.2 The HAT Solution
+
+HAT takes a different approach: **exploit known structure**.
+
+Unlike general-purpose vector databases that treat all data as unstructured point clouds, AI conversation data has inherent hierarchy:
+
+```
+Session (conversation boundary)
+  └── Document (topic or turn)
+       └── Chunk (individual message)
+```
+
+HAT exploits this structure to achieve O(log n) queries with 100% recall, without any training or learning.
+
+### 1.3 Core Claim
+
+> **A 10K context model with HAT achieves 100% recall on 60K+ tokens with 3.1ms latency.**
+
+This is validated by our end-to-end experiments integrating HAT with a local LLM (gemma3:1b).
+
+---
+
+## 2. Background and Motivation
+
+### 2.1 HAT vs RAG: Complementary, Not Competing
+
+| Aspect | RAG + HNSW | HAT |
+|--------|------------|-----|
+| **Content type** | Static knowledge (handbooks, catalogs) | Dynamic conversations |
+| **Structure** | Unknown → learned topology | Known hierarchy exploited |
+| **Returns** | Text chunks (must recompute attention) | Attention states (pre-computed) |
+| **Use case** | "What does the handbook say about X?" | "Remember when we discussed Y?" |
+
+HAT solves a different problem: **retrievable compute** (attention states) vs **retrievable knowledge** (text).
+
+### 2.2 The Hippocampus Analogy
+
+HAT mirrors human memory architecture:
+
+| Human Memory | HAT Equivalent |
+|--------------|----------------|
+| Working memory (7±2 items) | Current context window |
+| Short-term memory | Recent session containers |
+| Long-term episodic | HAT hierarchical storage |
+| Memory consolidation (sleep) | HAT consolidation phases |
+| Hippocampal indexing | Centroid-based routing |
+
+This isn't just a metaphor—it's a design principle.
+
+---
+
+## 3. Algorithm
+
+### 3.1 Data Structure
+
+HAT organizes points into a tree with four levels:
+
+```
+Global (root)
+  └── Session (conversation boundaries)
+       └── Document (topic groupings)
+            └── Chunk (leaf nodes with points)
+```
+
+Each non-leaf container maintains:
+- **Centroid**: Mean of descendant embeddings
+- **Children**: Pointers to child containers
+- **Timestamp**: For temporal locality
+
+### 3.2 Beam Search Query
+
+```
+Algorithm 1: HAT Query
+─────────────────────────────────────────────────
+Input: query point q, number of results k
+Output: k nearest neighbors
+
+1: beam ← {root}
+2: for level ∈ [Session, Document, Chunk] do
+3:     candidates ← ∅
+4:     for container ∈ beam do
+5:         for child ∈ container.children do
+6:             score ← cosine(q, child.centroid)
+7:             candidates ← candidates ∪ {(child, score)}
+8:     beam ← top-b(candidates)  // b = beam_width
+9: return top-k(beam)
+
+Complexity: O(b · d · c) = O(log n) when balanced
+```
+
+### 3.3 Sparse Centroid Propagation
+
+To avoid O(depth) updates on every insertion:
+
+```
+Algorithm 2: Sparse Propagation
+─────────────────────────────────────────────────
+Input: new point p, container c, threshold τ
+
+1: δ ← update_centroid(c, p)
+2: ancestor ← c.parent
+3: while ancestor ≠ null and δ > τ do
+4:     δ ← update_centroid(ancestor, p)
+5:     ancestor ← ancestor.parent
+
+Amortized cost: O(1) when τ > 0
+```
+
+**Result**: 1.3-1.7x insertion speedup with negligible recall impact.
+
+### 3.4 Consolidation Phases
+
+Inspired by sleep-staged memory consolidation:
+
+| Phase | Operations | Time |
+|-------|------------|------|
+| Light (α) | Recompute centroids | 9ms/1K points |
+| Medium (β) | + Merge/split containers | 9ms/1K points |
+| Deep (δ) | + Prune empty, optimize layout | 9ms/1K points |
+| Full (θ) | Complete rebuild | 10ms/1K points |
+
+All phases support non-blocking incremental execution.
+
+---
+
+## 4. Experiments
+
+### 4.1 HAT vs HNSW: Hierarchical Data
+
+**Setup**: 1000 points = 20 sessions × 5 documents × 10 chunks, 128 dimensions
+
+| Metric | HAT | HNSW | Δ |
+|--------|-----|------|---|
+| Recall@1 | **100.0%** | 76.0% | +24.0% |
+| Recall@5 | **100.0%** | 72.0% | +28.0% |
+| Recall@10 | **100.0%** | 70.6% | +29.4% |
+| Build Time | 30ms | 2.1s | **70x faster** |
+| Query Latency | 1.42ms | 0.49ms | HNSW 3x faster |
+
+**Key finding**: The query latency advantage of HNSW is meaningless at 70% recall.
+
+### 4.2 Scale Analysis
+
+| Points | HAT Build | HNSW Build | HAT R@10 | HNSW R@10 |
+|--------|-----------|------------|----------|-----------|
+| 500 | 16ms | 1.0s | **100%** | 55% |
+| 1000 | 25ms | 2.0s | **100%** | 44.5% |
+| 2000 | 50ms | 4.3s | **100%** | 67.5% |
+| 5000 | 127ms | 11.9s | **100%** | 55% |
+
+HAT maintains 100% recall across all tested scales.
+
+### 4.3 Real Embedding Dimensions
+
+| Embedding Model | Dimensions | Recall@10 |
+|-----------------|------------|-----------|
+| all-MiniLM-L6-v2 | 384 | 100% |
+| BERT-base | 768 | 100% |
+| OpenAI ada-002 | 1536 | 100% |
+
+HAT scales to production embedding sizes.
+
+### 4.4 Negative Results: Complexity Doesn't Help
+
+**Subspace Routing** (Grassmann geometry):
+- Recall: -8.7% vs centroids
+- Latency: +11.8%
+- **Conclusion**: Centroids are sufficient
+
+**Learnable Routing Weights**:
+- Recall: -2% to +4%
+- Latency: ~0%
+- **Conclusion**: Learning is unnecessary
+
+These "negative" results are positive engineering findings: HAT's simple design is already optimal.
+
+### 4.5 End-to-End LLM Integration
+
+**Setup**: 2000 messages (~60K tokens), sentence-transformers embeddings, gemma3:1b LLM
+
+| Metric | Value |
+|--------|-------|
+| Total tokens | 60,000 |
+| Native context sees | 10,000 (16.7%) |
+| **HAT recall** | **100%** |
+| **Retrieval latency** | **3.1ms** |
+| Memory usage | 3.3 MB |
+
+Real LLM correctly answers questions about "past" conversations:
+
+```
+User: "What did we discuss about quantum computing?"
+
+[HAT retrieves 5 relevant memories in 3.0ms]
+Assistant (gemma3:1b): "We discussed quantum computing leverages quantum
+mechanical phenomena like superposition and entanglement."
+```
+
+---
+
+## 5. Implementation
+
+### 5.1 System Architecture
+
+HAT is implemented in Rust with Python bindings via PyO3:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      ARMS-HAT                                │
+├─────────────────────────────────────────────────────────────┤
+│  Core (Rust)                                                 │
+│  ├── HatIndex: Main index structure                         │
+│  ├── Container: Session/Document/Chunk nodes                │
+│  ├── Consolidation: Background maintenance                  │
+│  └── Persistence: Binary serialization                      │
+├─────────────────────────────────────────────────────────────┤
+│  Python Bindings (PyO3)                                      │
+│  ├── HatIndex, HatConfig, SearchResult                      │
+│  ├── Session/Document management                            │
+│  └── Attention state serialization                          │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 5.2 Persistence Format
+
+Binary format for production deployment:
+
+| Component | Description |
+|-----------|-------------|
+| Header | Magic bytes, version, dimensionality |
+| Containers | ID, level, parent, children, centroid |
+| Active state | Current session/document IDs |
+
+**Performance**:
+- Serialize: 328 MB/s
+- Deserialize: 101 MB/s
+- Overhead: ~110% above raw embedding size
+
+### 5.3 Python API
+
+```python
+from arms_hat import HatIndex
+
+# Create index
+index = HatIndex.cosine(1536)  # OpenAI dimensions
+
+# Add messages
+id = index.add(embedding)
+
+# Session management
+index.new_session()
+index.new_document()
+
+# Query
+results = index.near(query_embedding, k=10)
+
+# Persistence
+index.save("memory.hat")
+loaded = HatIndex.load("memory.hat")
+```
+
+---
+
+## 6. Related Work
+
+### 6.1 Approximate Nearest Neighbor
+
+- **HNSW** (Malkov & Yashunin, 2018): Navigable small-world graphs
+- **Annoy** (Spotify): Random projection trees
+- **FAISS** (Facebook): GPU-accelerated, IVF + PQ
+
+**Key difference**: These methods learn topology from data. HAT exploits known structure.
+
+### 6.2 Memory-Augmented Neural Networks
+
+- Neural Turing Machines (Graves et al., 2014)
+- Memory Networks (Weston et al., 2015)
+- Differentiable Neural Computer (Graves et al., 2016)
+
+**Key difference**: These require training. HAT works immediately with no learning.
+
+### 6.3 RAG Systems
+
+- RAG (Lewis et al., 2020): Retrieval-augmented generation
+- RETRO (Borgeaud et al., 2022): Retrieval-enhanced transformers
+- Atlas (Izacard et al., 2022): Few-shot learning with retrieval
+
+**Key difference**: RAG retrieves text and recomputes attention. HAT can store pre-computed attention states.
+
+---
+
+## 7. Discussion
+
+### 7.1 Why Simplicity Wins
+
+Our experiments with subspace routing and learnable weights demonstrate that HAT's simple design is already optimal for hierarchically-structured data:
+
+| Enhancement | Result | Implication |
+|-------------|--------|-------------|
+| Subspace routing | -8.7% recall, +11.8% latency | Centroids sufficient |
+| Learnable weights | -2% to +4% recall | Learning unnecessary |
+
+**Conclusion**: When structure is *known*, exploit it directly. When structure is *unknown*, learn it.
+
+### 7.2 Practical Benefits
+
+| Property | HAT | HNSW | Learned Methods |
+|----------|-----|------|-----------------|
+| Training required | No | Graph build | Yes |
+| Cold-start problem | None | Build time | Warmup period |
+| Deterministic | Yes | No | No |
+| Integration complexity | Low | Medium | High |
+
+### 7.3 Limitations
+
+1. **Hierarchy assumption**: HAT requires hierarchically-structured data. For unstructured point clouds, HNSW remains appropriate.
+
+2. **Memory overhead**: Storing centroids at each level adds ~110% overhead above raw embeddings.
+
+3. **KV cache storage**: Storing full attention states is memory-intensive. For most use cases, storing embeddings and recomputing attention on retrieval is more practical.
+
+### 7.4 Future Work
+
+1. **Memory-mapped persistence**: For indexes >1GB
+2. **Distributed HAT**: Sharding across multiple nodes
+3. **Streaming updates**: Incremental index building
+4. **Multi-modal support**: Images, audio alongside text
+
+---
+
+## 8. Conclusion
+
+We presented HAT, a hierarchical attention tree that extends LLM context by an order of magnitude. Our key contributions:
+
+1. **Structural prior exploitation**: First index to leverage known AI workload hierarchy
+2. **100% recall**: vs 70% for HNSW on hierarchical data
+3. **70x faster construction**: Than HNSW
+4. **Simplicity validation**: Neither geometric sophistication nor learning improves performance
+5. **End-to-end integration**: Demonstrated with real LLM (gemma3:1b)
+
+HAT enables a 10K context model to achieve 100% recall on 60K+ tokens with 3.1ms latency, functioning as an artificial hippocampus for AI systems.
+
+---
+
+## References
+
+1. Malkov, Y. A., & Yashunin, D. A. (2018). Efficient and robust approximate nearest neighbor search using hierarchical navigable small world graphs. IEEE TPAMI.
+
+2. Lewis, P., et al. (2020). Retrieval-augmented generation for knowledge-intensive NLP tasks. NeurIPS.
+
+3. Graves, A., Wayne, G., & Danihelka, I. (2014). Neural turing machines. arXiv.
+
+4. Weston, J., Chopra, S., & Bordes, A. (2015). Memory networks. ICLR.
+
+5. Borgeaud, S., et al. (2022). Improving language models by retrieving from trillions of tokens. ICML.
+
+---
+
+## Appendix A: Complete Results Tables
+
+### A.1 Phase 3.1: HAT vs HNSW Benchmark
+
+| Scale | HAT Build | HNSW Build | HAT R@10 | HNSW R@10 |
+|-------|-----------|------------|----------|-----------|
+| 500 | 16ms | 1.0s | 100% | 55% |
+| 1000 | 25ms | 2.0s | 100% | 44.5% |
+| 2000 | 50ms | 4.3s | 100% | 67.5% |
+| 5000 | 127ms | 11.9s | 100% | 55% |
+
+### A.2 Phase 3.2: Real Embedding Results
+
+| Dimension | Points | Build Time | Query Time | Recall@10 |
+|-----------|--------|------------|------------|-----------|
+| 384 | 1000 | 45ms | 2.1ms | 100% |
+| 768 | 1000 | 52ms | 2.8ms | 100% |
+| 1536 | 500 | 89ms | 3.5ms | 100% |
+
+### A.3 Phase 3.3: Persistence Performance
+
+| Points | Dims | Serialize | Deserialize | Size | Recall |
+|--------|------|-----------|-------------|------|--------|
+| 100 | 128 | 342μs | 1.3ms | 112KB | 100% |
+| 5000 | 256 | 33ms | 106ms | 10.75MB | 100% |
+| 500 | 1536 | - | - | 6.32MB | 100% |
+
+### A.4 Phase 4.3: End-to-End Results
+
+| Messages | Tokens | Context % | Recall | Latency | Memory |
+|----------|--------|-----------|--------|---------|--------|
+| 1000 | 30K | 33% | 100% | 1.7ms | 1.6MB |
+| 2000 | 60K | 17% | 100% | 3.1ms | 3.3MB |
+
+---
+
+## Appendix B: Code Availability
+
+The ARMS-HAT implementation is available at:
+- Rust library: `arms-hat` crate
+- Python bindings: `pip install arms-hat`
+- Demo: `examples/demo_hat_memory.py`
+
+All experiments are reproducible using the test suite:
+```bash
+cargo test --test phase31_hat_vs_hnsw -- --nocapture
+cargo test --test phase32_real_embeddings -- --nocapture
+cargo test --test phase33_persistence -- --nocapture
+python examples/demo_hat_memory.py
+```

pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["maturin>=1.4,<2.0"]
+build-backend = "maturin"
+
+[project]
+name = "arms-hat"
+version = "0.1.0"
+description = "Hierarchical Attention Tree: 100% recall at 70x faster build times than HNSW. A new database paradigm for AI memory and hierarchical semantic search."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.8"
+authors = [
+    { name = "Automate Capture LLC", email = "research@automate-capture.com" }
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Rust",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+keywords = ["ai", "memory", "embeddings", "vector-search", "llm"]
+
+[project.urls]
+Homepage = "https://research.automate-capture.com/hat"
+Repository = "https://github.com/automate-capture/hat"
+Documentation = "https://research.automate-capture.com/hat"
+
+[project.optional-dependencies]
+dev = ["pytest", "numpy"]
+
+[tool.maturin]
+features = ["python"]
+python-source = "python"
+module-name = "arms_hat"
+
+[tool.pytest.ini_options]
+testpaths = ["python/tests"]

python/arms_hat/__init__.py

@@ -0,0 +1,46 @@
+"""
+ARMS-HAT: Hierarchical Attention Tree for AI memory retrieval.
+
+A semantic memory index optimized for LLM conversation history.
+
+Example:
+    >>> from arms_hat import HatIndex
+    >>>
+    >>> # Create index for OpenAI embeddings (1536 dims)
+    >>> index = HatIndex.cosine(1536)
+    >>>
+    >>> # Add embeddings
+    >>> id1 = index.add([0.1] * 1536)
+    >>>
+    >>> # Query
+    >>> results = index.near([0.1] * 1536, k=10)
+    >>> for r in results:
+    ...     print(f"{r.id}: {r.score}")
+    >>>
+    >>> # Session management
+    >>> index.new_session()
+    >>>
+    >>> # Persistence
+    >>> index.save("memory.hat")
+    >>> loaded = HatIndex.load("memory.hat")
+"""
+
+from .arms_hat import (
+    HatIndex,
+    HatConfig,
+    SearchResult,
+    SessionSummary,
+    DocumentSummary,
+    HatStats,
+)
+
+__all__ = [
+    "HatIndex",
+    "HatConfig",
+    "SearchResult",
+    "SessionSummary",
+    "DocumentSummary",
+    "HatStats",
+]
+
+__version__ = "0.1.0"

python/tests/test_hat_index.py

@@ -0,0 +1,296 @@
+"""Tests for ARMS-HAT Python bindings."""
+
+import pytest
+import tempfile
+import os
+
+
+def test_import():
+    """Test that the module can be imported."""
+    from arms_hat import HatIndex, HatConfig, SearchResult
+
+
+def test_create_index():
+    """Test index creation."""
+    from arms_hat import HatIndex
+
+    index = HatIndex.cosine(128)
+    assert len(index) == 0
+    assert index.is_empty()
+
+
+def test_add_and_query():
+    """Test adding points and querying."""
+    from arms_hat import HatIndex
+
+    dims = 64
+    index = HatIndex.cosine(dims)
+
+    # Add some points
+    ids = []
+    for i in range(10):
+        embedding = [0.0] * dims
+        embedding[i % dims] = 1.0
+        embedding[(i + 1) % dims] = 0.5
+        id_ = index.add(embedding)
+        ids.append(id_)
+        assert len(id_) == 32  # Hex ID
+
+    assert len(index) == 10
+    assert not index.is_empty()
+
+    # Query
+    query = [0.0] * dims
+    query[0] = 1.0
+    query[1] = 0.5
+
+    results = index.near(query, k=5)
+    assert len(results) == 5
+
+    # First result should be the closest match
+    assert results[0].id == ids[0]
+    assert results[0].score > 0.9  # High cosine similarity
+
+
+def test_sessions():
+    """Test session management."""
+    from arms_hat import HatIndex
+
+    index = HatIndex.cosine(32)
+
+    # Add points to first session
+    for i in range(5):
+        index.add([float(i % 32 == j) for j in range(32)])
+
+    # Start new session
+    index.new_session()
+
+    # Add points to second session
+    for i in range(5):
+        index.add([float((i + 10) % 32 == j) for j in range(32)])
+
+    stats = index.stats()
+    assert stats.session_count >= 1  # At least one session
+    assert stats.chunk_count == 10
+
+
+def test_documents():
+    """Test document management within sessions."""
+    from arms_hat import HatIndex
+
+    index = HatIndex.cosine(32)
+
+    # Add points to first document
+    for i in range(3):
+        index.add([1.0 if j == i else 0.0 for j in range(32)])
+
+    # Start new document
+    index.new_document()
+
+    # Add points to second document
+    for i in range(3):
+        index.add([1.0 if j == i + 10 else 0.0 for j in range(32)])
+
+    stats = index.stats()
+    assert stats.document_count >= 1
+    assert stats.chunk_count == 6
+
+
+def test_persistence_bytes():
+    """Test serialization to/from bytes."""
+    from arms_hat import HatIndex
+
+    dims = 64
+    index = HatIndex.cosine(dims)
+
+    # Add points
+    ids = []
+    for i in range(20):
+        embedding = [0.1] * dims
+        embedding[i % dims] = 1.0
+        ids.append(index.add(embedding))
+
+    # Serialize
+    data = index.to_bytes()
+    assert len(data) > 0
+
+    # Deserialize
+    loaded = HatIndex.from_bytes(data)
+    assert len(loaded) == len(index)
+
+    # Query should give same results
+    query = [0.1] * dims
+    query[0] = 1.0
+
+    original_results = index.near(query, k=5)
+    loaded_results = loaded.near(query, k=5)
+
+    assert len(original_results) == len(loaded_results)
+    assert original_results[0].id == loaded_results[0].id
+
+
+def test_persistence_file():
+    """Test save/load to file."""
+    from arms_hat import HatIndex
+
+    dims = 64
+    index = HatIndex.cosine(dims)
+
+    # Add points
+    for i in range(10):
+        embedding = [0.1] * dims
+        embedding[i % dims] = 1.0
+        index.add(embedding)
+
+    # Save to temp file
+    with tempfile.NamedTemporaryFile(suffix=".hat", delete=False) as f:
+        path = f.name
+
+    try:
+        index.save(path)
+        assert os.path.exists(path)
+        assert os.path.getsize(path) > 0
+
+        # Load
+        loaded = HatIndex.load(path)
+        assert len(loaded) == len(index)
+
+    finally:
+        os.unlink(path)
+
+
+def test_config():
+    """Test custom configuration."""
+    from arms_hat import HatIndex, HatConfig
+
+    config = HatConfig()
+    # Chain configuration
+    config = config.with_beam_width(5)
+    config = config.with_temporal_weight(0.1)
+
+    index = HatIndex.with_config(128, config)
+    assert len(index) == 0
+
+
+def test_remove():
+    """Test point removal."""
+    from arms_hat import HatIndex
+
+    index = HatIndex.cosine(32)
+
+    id1 = index.add([1.0] + [0.0] * 31)
+    id2 = index.add([0.0, 1.0] + [0.0] * 30)
+
+    assert len(index) == 2
+
+    index.remove(id1)
+    assert len(index) == 1
+
+    # Query should only find id2
+    results = index.near([0.0, 1.0] + [0.0] * 30, k=5)
+    assert len(results) == 1
+    assert results[0].id == id2
+
+
+def test_consolidate():
+    """Test consolidation."""
+    from arms_hat import HatIndex
+
+    index = HatIndex.cosine(32)
+
+    # Add many points
+    for i in range(100):
+        embedding = [0.0] * 32
+        embedding[i % 32] = 1.0
+        index.add(embedding)
+
+    # Consolidate should not error
+    index.consolidate()
+    index.consolidate_full()
+
+    assert len(index) == 100
+
+
+def test_stats():
+    """Test stats retrieval."""
+    from arms_hat import HatIndex
+
+    index = HatIndex.cosine(64)
+
+    for i in range(10):
+        index.add([float(i % 64 == j) for j in range(64)])
+
+    stats = index.stats()
+    assert stats.chunk_count == 10
+    assert stats.total_points == 10
+
+
+def test_repr():
+    """Test string representations."""
+    from arms_hat import HatIndex, HatConfig, SearchResult
+
+    index = HatIndex.cosine(64)
+    repr_str = repr(index)
+    assert "HatIndex" in repr_str
+
+    config = HatConfig()
+    repr_str = repr(config)
+    assert "HatConfig" in repr_str
+
+
+def test_near_sessions():
+    """Test coarse-grained session search."""
+    from arms_hat import HatIndex
+
+    index = HatIndex.cosine(32)
+
+    # Session 1: points along dimension 0
+    for i in range(5):
+        embedding = [0.0] * 32
+        embedding[0] = 1.0
+        embedding[i + 1] = 0.3
+        index.add(embedding)
+
+    index.new_session()
+
+    # Session 2: points along dimension 10
+    for i in range(5):
+        embedding = [0.0] * 32
+        embedding[10] = 1.0
+        embedding[i + 11] = 0.3
+        index.add(embedding)
+
+    # Query similar to session 1
+    query = [0.0] * 32
+    query[0] = 1.0
+
+    sessions = index.near_sessions(query, k=2)
+    assert len(sessions) >= 1
+
+    # First session should be more relevant
+    if len(sessions) > 1:
+        assert sessions[0].score >= sessions[1].score
+
+
+def test_high_dimensions():
+    """Test with OpenAI embedding dimensions."""
+    from arms_hat import HatIndex
+
+    dims = 1536  # OpenAI ada-002 dimensions
+    index = HatIndex.cosine(dims)
+
+    # Add some high-dimensional points
+    for i in range(10):
+        embedding = [(j * i * 0.01) % 1.0 for j in range(dims)]
+        index.add(embedding)
+
+    assert len(index) == 10
+
+    # Query
+    query = [0.5] * dims
+    results = index.near(query, k=5)
+    assert len(results) == 5
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])

src/adapters/attention.rs

@@ -0,0 +1,789 @@
+//! # Attention State Serialization
+//!
+//! Format for storing retrievable attention states, not just text.
+//!
+//! ## The Key Insight
+//!
+//! Traditional RAG stores text and re-embeds on retrieval.
+//! HAT stores **attention states** that can be directly injected into LLM context.
+//!
+//! ## What Gets Stored
+//!
+//! For each memory chunk:
+//! - **Text**: Original tokens/content
+//! - **Embedding**: Vector for retrieval routing
+//! - **KV Cache**: Compressed key-value states (optional, model-specific)
+//! - **Metadata**: Timestamp, role, session context
+//!
+//! ## Format Design
+//!
+//! ```text
+//! AttentionState
+//! ├── id: Id (16 bytes)
+//! ├── timestamp_ms: u64
+//! ├── role: Role (user/assistant/system)
+//! ├── text: String (original content)
+//! ├── embedding: Vec<f32> (for HAT routing)
+//! ├── kv_cache: Option<CompressedKV> (model-specific)
+//! └── metadata: HashMap<String, String>
+//! ```
+
+use crate::core::Id;
+
+/// Role in conversation
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Role {
+    /// System prompt
+    System,
+    /// User message
+    User,
+    /// Assistant response
+    Assistant,
+    /// Tool/function call
+    Tool,
+    /// Retrieved context (from RAG or previous HAT retrieval)
+    Context,
+}
+
+impl Role {
+    pub fn as_str(&self) -> &'static str {
+        match self {
+            Role::System => "system",
+            Role::User => "user",
+            Role::Assistant => "assistant",
+            Role::Tool => "tool",
+            Role::Context => "context",
+        }
+    }
+
+    pub fn from_str(s: &str) -> Option<Self> {
+        match s.to_lowercase().as_str() {
+            "system" => Some(Role::System),
+            "user" => Some(Role::User),
+            "assistant" => Some(Role::Assistant),
+            "tool" | "function" => Some(Role::Tool),
+            "context" | "retrieved" => Some(Role::Context),
+            _ => None,
+        }
+    }
+
+    fn to_byte(&self) -> u8 {
+        match self {
+            Role::System => 0,
+            Role::User => 1,
+            Role::Assistant => 2,
+            Role::Tool => 3,
+            Role::Context => 4,
+        }
+    }
+
+    fn from_byte(b: u8) -> Option<Self> {
+        match b {
+            0 => Some(Role::System),
+            1 => Some(Role::User),
+            2 => Some(Role::Assistant),
+            3 => Some(Role::Tool),
+            4 => Some(Role::Context),
+            _ => None,
+        }
+    }
+}
+
+/// Compressed KV cache for a specific model architecture
+///
+/// This is model-specific. Different models have different:
+/// - Number of layers
+/// - Number of heads
+/// - Head dimensions
+/// - Quantization formats
+#[derive(Debug, Clone)]
+pub struct CompressedKV {
+    /// Model identifier (e.g., "llama-3-8b", "mistral-7b")
+    pub model_id: String,
+
+    /// Number of layers
+    pub num_layers: u32,
+
+    /// Number of attention heads
+    pub num_heads: u32,
+
+    /// Dimension per head
+    pub head_dim: u32,
+
+    /// Sequence length this KV cache covers
+    pub seq_len: u32,
+
+    /// Quantization format (e.g., "fp16", "int8", "int4")
+    pub quantization: String,
+
+    /// Compressed KV data
+    /// Format: [layer][head][seq][key/value][head_dim]
+    /// Actual layout depends on quantization
+    pub data: Vec<u8>,
+}
+
+impl CompressedKV {
+    /// Estimate memory size in bytes
+    pub fn size_bytes(&self) -> usize {
+        self.data.len()
+    }
+
+    /// Create a placeholder (for models that don't support KV export)
+    pub fn placeholder(model_id: &str) -> Self {
+        Self {
+            model_id: model_id.to_string(),
+            num_layers: 0,
+            num_heads: 0,
+            head_dim: 0,
+            seq_len: 0,
+            quantization: "none".to_string(),
+            data: vec![],
+        }
+    }
+
+    /// Serialize to bytes
+    pub fn to_bytes(&self) -> Vec<u8> {
+        let mut bytes = Vec::new();
+
+        // Model ID (length-prefixed string)
+        let model_bytes = self.model_id.as_bytes();
+        bytes.extend_from_slice(&(model_bytes.len() as u32).to_le_bytes());
+        bytes.extend_from_slice(model_bytes);
+
+        // Architecture params
+        bytes.extend_from_slice(&self.num_layers.to_le_bytes());
+        bytes.extend_from_slice(&self.num_heads.to_le_bytes());
+        bytes.extend_from_slice(&self.head_dim.to_le_bytes());
+        bytes.extend_from_slice(&self.seq_len.to_le_bytes());
+
+        // Quantization (length-prefixed string)
+        let quant_bytes = self.quantization.as_bytes();
+        bytes.extend_from_slice(&(quant_bytes.len() as u32).to_le_bytes());
+        bytes.extend_from_slice(quant_bytes);
+
+        // Data (length-prefixed)
+        bytes.extend_from_slice(&(self.data.len() as u64).to_le_bytes());
+        bytes.extend_from_slice(&self.data);
+
+        bytes
+    }
+
+    /// Deserialize from bytes
+    pub fn from_bytes(data: &[u8]) -> Option<(Self, usize)> {
+        let mut offset = 0;
+
+        // Model ID
+        if data.len() < offset + 4 {
+            return None;
+        }
+        let model_len = u32::from_le_bytes(data[offset..offset + 4].try_into().ok()?) as usize;
+        offset += 4;
+
+        if data.len() < offset + model_len {
+            return None;
+        }
+        let model_id = String::from_utf8(data[offset..offset + model_len].to_vec()).ok()?;
+        offset += model_len;
+
+        // Architecture params
+        if data.len() < offset + 16 {
+            return None;
+        }
+        let num_layers = u32::from_le_bytes(data[offset..offset + 4].try_into().ok()?);
+        offset += 4;
+        let num_heads = u32::from_le_bytes(data[offset..offset + 4].try_into().ok()?);
+        offset += 4;
+        let head_dim = u32::from_le_bytes(data[offset..offset + 4].try_into().ok()?);
+        offset += 4;
+        let seq_len = u32::from_le_bytes(data[offset..offset + 4].try_into().ok()?);
+        offset += 4;
+
+        // Quantization
+        if data.len() < offset + 4 {
+            return None;
+        }
+        let quant_len = u32::from_le_bytes(data[offset..offset + 4].try_into().ok()?) as usize;
+        offset += 4;
+
+        if data.len() < offset + quant_len {
+            return None;
+        }
+        let quantization = String::from_utf8(data[offset..offset + quant_len].to_vec()).ok()?;
+        offset += quant_len;
+
+        // Data
+        if data.len() < offset + 8 {
+            return None;
+        }
+        let data_len = u64::from_le_bytes(data[offset..offset + 8].try_into().ok()?) as usize;
+        offset += 8;
+
+        if data.len() < offset + data_len {
+            return None;
+        }
+        let kv_data = data[offset..offset + data_len].to_vec();
+        offset += data_len;
+
+        Some((
+            Self {
+                model_id,
+                num_layers,
+                num_heads,
+                head_dim,
+                seq_len,
+                quantization,
+                data: kv_data,
+            },
+            offset,
+        ))
+    }
+}
+
+/// A complete attention state for a memory chunk
+#[derive(Debug, Clone)]
+pub struct AttentionState {
+    /// Unique identifier
+    pub id: Id,
+
+    /// Timestamp (milliseconds since epoch)
+    pub timestamp_ms: u64,
+
+    /// Role in conversation
+    pub role: Role,
+
+    /// Original text content
+    pub text: String,
+
+    /// Embedding vector (for HAT retrieval routing)
+    pub embedding: Vec<f32>,
+
+    /// Optional compressed KV cache (model-specific)
+    pub kv_cache: Option<CompressedKV>,
+
+    /// Additional metadata (flexible key-value pairs)
+    pub metadata: std::collections::HashMap<String, String>,
+}
+
+impl AttentionState {
+    /// Create a new attention state (without KV cache)
+    pub fn new(role: Role, text: String, embedding: Vec<f32>) -> Self {
+        Self {
+            id: Id::now(),
+            timestamp_ms: std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap()
+                .as_millis() as u64,
+            role,
+            text,
+            embedding,
+            kv_cache: None,
+            metadata: std::collections::HashMap::new(),
+        }
+    }
+
+    /// Create with KV cache
+    pub fn with_kv_cache(mut self, kv: CompressedKV) -> Self {
+        self.kv_cache = Some(kv);
+        self
+    }
+
+    /// Add metadata
+    pub fn with_metadata(mut self, key: &str, value: &str) -> Self {
+        self.metadata.insert(key.to_string(), value.to_string());
+        self
+    }
+
+    /// Estimate total size in bytes
+    pub fn size_bytes(&self) -> usize {
+        16 + // id
+        8 +  // timestamp
+        1 +  // role
+        self.text.len() +
+        self.embedding.len() * 4 +
+        self.kv_cache.as_ref().map(|kv| kv.size_bytes()).unwrap_or(0) +
+        self.metadata.iter().map(|(k, v)| k.len() + v.len() + 8).sum::<usize>()
+    }
+
+    /// Serialize to bytes
+    pub fn to_bytes(&self) -> Vec<u8> {
+        let mut bytes = Vec::new();
+
+        // Magic + version
+        bytes.extend_from_slice(b"ATTN");
+        bytes.extend_from_slice(&1u32.to_le_bytes());
+
+        // ID
+        bytes.extend_from_slice(self.id.as_bytes());
+
+        // Timestamp
+        bytes.extend_from_slice(&self.timestamp_ms.to_le_bytes());
+
+        // Role
+        bytes.push(self.role.to_byte());
+
+        // Text (length-prefixed)
+        let text_bytes = self.text.as_bytes();
+        bytes.extend_from_slice(&(text_bytes.len() as u32).to_le_bytes());
+        bytes.extend_from_slice(text_bytes);
+
+        // Embedding (length-prefixed)
+        bytes.extend_from_slice(&(self.embedding.len() as u32).to_le_bytes());
+        for &v in &self.embedding {
+            bytes.extend_from_slice(&v.to_le_bytes());
+        }
+
+        // KV cache (present flag + data)
+        if let Some(ref kv) = self.kv_cache {
+            bytes.push(1);
+            let kv_bytes = kv.to_bytes();
+            bytes.extend_from_slice(&(kv_bytes.len() as u64).to_le_bytes());
+            bytes.extend_from_slice(&kv_bytes);
+        } else {
+            bytes.push(0);
+        }
+
+        // Metadata (count + entries)
+        bytes.extend_from_slice(&(self.metadata.len() as u32).to_le_bytes());
+        for (key, value) in &self.metadata {
+            let key_bytes = key.as_bytes();
+            let value_bytes = value.as_bytes();
+            bytes.extend_from_slice(&(key_bytes.len() as u32).to_le_bytes());
+            bytes.extend_from_slice(key_bytes);
+            bytes.extend_from_slice(&(value_bytes.len() as u32).to_le_bytes());
+            bytes.extend_from_slice(value_bytes);
+        }
+
+        bytes
+    }
+
+    /// Deserialize from bytes
+    pub fn from_bytes(data: &[u8]) -> Result<Self, AttentionError> {
+        let mut offset = 0;
+
+        // Magic
+        if data.len() < 8 {
+            return Err(AttentionError::InvalidFormat("Too short".into()));
+        }
+        if &data[0..4] != b"ATTN" {
+            return Err(AttentionError::InvalidMagic);
+        }
+        offset += 4;
+
+        // Version
+        let version = u32::from_le_bytes(data[offset..offset + 4].try_into().unwrap());
+        if version != 1 {
+            return Err(AttentionError::UnsupportedVersion(version));
+        }
+        offset += 4;
+
+        // ID
+        if data.len() < offset + 16 {
+            return Err(AttentionError::InvalidFormat("Missing ID".into()));
+        }
+        let mut id_bytes = [0u8; 16];
+        id_bytes.copy_from_slice(&data[offset..offset + 16]);
+        let id = Id::from_bytes(id_bytes);
+        offset += 16;
+
+        // Timestamp
+        if data.len() < offset + 8 {
+            return Err(AttentionError::InvalidFormat("Missing timestamp".into()));
+        }
+        let timestamp_ms = u64::from_le_bytes(data[offset..offset + 8].try_into().unwrap());
+        offset += 8;
+
+        // Role
+        if data.len() < offset + 1 {
+            return Err(AttentionError::InvalidFormat("Missing role".into()));
+        }
+        let role = Role::from_byte(data[offset])
+            .ok_or_else(|| AttentionError::InvalidFormat("Invalid role".into()))?;
+        offset += 1;
+
+        // Text
+        if data.len() < offset + 4 {
+            return Err(AttentionError::InvalidFormat("Missing text length".into()));
+        }
+        let text_len = u32::from_le_bytes(data[offset..offset + 4].try_into().unwrap()) as usize;
+        offset += 4;
+
+        if data.len() < offset + text_len {
+            return Err(AttentionError::InvalidFormat("Text truncated".into()));
+        }
+        let text = String::from_utf8(data[offset..offset + text_len].to_vec())
+            .map_err(|_| AttentionError::InvalidFormat("Invalid UTF-8 in text".into()))?;
+        offset += text_len;
+
+        // Embedding
+        if data.len() < offset + 4 {
+            return Err(AttentionError::InvalidFormat("Missing embedding length".into()));
+        }
+        let emb_len = u32::from_le_bytes(data[offset..offset + 4].try_into().unwrap()) as usize;
+        offset += 4;
+
+        if data.len() < offset + emb_len * 4 {
+            return Err(AttentionError::InvalidFormat("Embedding truncated".into()));
+        }
+        let mut embedding = Vec::with_capacity(emb_len);
+        for _ in 0..emb_len {
+            embedding.push(f32::from_le_bytes(data[offset..offset + 4].try_into().unwrap()));
+            offset += 4;
+        }
+
+        // KV cache
+        if data.len() < offset + 1 {
+            return Err(AttentionError::InvalidFormat("Missing KV flag".into()));
+        }
+        let has_kv = data[offset] != 0;
+        offset += 1;
+
+        let kv_cache = if has_kv {
+            if data.len() < offset + 8 {
+                return Err(AttentionError::InvalidFormat("Missing KV length".into()));
+            }
+            let kv_len = u64::from_le_bytes(data[offset..offset + 8].try_into().unwrap()) as usize;
+            offset += 8;
+
+            if data.len() < offset + kv_len {
+                return Err(AttentionError::InvalidFormat("KV data truncated".into()));
+            }
+            let (kv, _) = CompressedKV::from_bytes(&data[offset..offset + kv_len])
+                .ok_or_else(|| AttentionError::InvalidFormat("Invalid KV cache".into()))?;
+            offset += kv_len;
+            Some(kv)
+        } else {
+            None
+        };
+
+        // Metadata
+        if data.len() < offset + 4 {
+            return Err(AttentionError::InvalidFormat("Missing metadata count".into()));
+        }
+        let meta_count = u32::from_le_bytes(data[offset..offset + 4].try_into().unwrap()) as usize;
+        offset += 4;
+
+        let mut metadata = std::collections::HashMap::new();
+        for _ in 0..meta_count {
+            // Key
+            if data.len() < offset + 4 {
+                return Err(AttentionError::InvalidFormat("Missing key length".into()));
+            }
+            let key_len = u32::from_le_bytes(data[offset..offset + 4].try_into().unwrap()) as usize;
+            offset += 4;
+
+            if data.len() < offset + key_len {
+                return Err(AttentionError::InvalidFormat("Key truncated".into()));
+            }
+            let key = String::from_utf8(data[offset..offset + key_len].to_vec())
+                .map_err(|_| AttentionError::InvalidFormat("Invalid UTF-8 in key".into()))?;
+            offset += key_len;
+
+            // Value
+            if data.len() < offset + 4 {
+                return Err(AttentionError::InvalidFormat("Missing value length".into()));
+            }
+            let value_len = u32::from_le_bytes(data[offset..offset + 4].try_into().unwrap()) as usize;
+            offset += 4;
+
+            if data.len() < offset + value_len {
+                return Err(AttentionError::InvalidFormat("Value truncated".into()));
+            }
+            let value = String::from_utf8(data[offset..offset + value_len].to_vec())
+                .map_err(|_| AttentionError::InvalidFormat("Invalid UTF-8 in value".into()))?;
+            offset += value_len;
+
+            metadata.insert(key, value);
+        }
+
+        Ok(Self {
+            id,
+            timestamp_ms,
+            role,
+            text,
+            embedding,
+            kv_cache,
+            metadata,
+        })
+    }
+}
+
+/// Errors for attention state operations
+#[derive(Debug, Clone)]
+pub enum AttentionError {
+    InvalidMagic,
+    UnsupportedVersion(u32),
+    InvalidFormat(String),
+}
+
+impl std::fmt::Display for AttentionError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            AttentionError::InvalidMagic => write!(f, "Invalid magic bytes"),
+            AttentionError::UnsupportedVersion(v) => write!(f, "Unsupported version: {}", v),
+            AttentionError::InvalidFormat(msg) => write!(f, "Invalid format: {}", msg),
+        }
+    }
+}
+
+impl std::error::Error for AttentionError {}
+
+/// A batch of attention states for efficient storage
+#[derive(Debug, Clone)]
+pub struct AttentionBatch {
+    /// States in this batch
+    pub states: Vec<AttentionState>,
+
+    /// Session ID this batch belongs to
+    pub session_id: Option<Id>,
+
+    /// Document ID this batch belongs to
+    pub document_id: Option<Id>,
+}
+
+impl AttentionBatch {
+    pub fn new() -> Self {
+        Self {
+            states: Vec::new(),
+            session_id: None,
+            document_id: None,
+        }
+    }
+
+    pub fn with_session(mut self, session_id: Id) -> Self {
+        self.session_id = Some(session_id);
+        self
+    }
+
+    pub fn with_document(mut self, document_id: Id) -> Self {
+        self.document_id = Some(document_id);
+        self
+    }
+
+    pub fn add(&mut self, state: AttentionState) {
+        self.states.push(state);
+    }
+
+    /// Total size in bytes
+    pub fn size_bytes(&self) -> usize {
+        self.states.iter().map(|s| s.size_bytes()).sum()
+    }
+
+    /// Serialize batch to bytes
+    pub fn to_bytes(&self) -> Vec<u8> {
+        let mut bytes = Vec::new();
+
+        // Magic + version
+        bytes.extend_from_slice(b"ATNB");
+        bytes.extend_from_slice(&1u32.to_le_bytes());
+
+        // Session ID
+        if let Some(sid) = self.session_id {
+            bytes.push(1);
+            bytes.extend_from_slice(sid.as_bytes());
+        } else {
+            bytes.push(0);
+        }
+
+        // Document ID
+        if let Some(did) = self.document_id {
+            bytes.push(1);
+            bytes.extend_from_slice(did.as_bytes());
+        } else {
+            bytes.push(0);
+        }
+
+        // States count
+        bytes.extend_from_slice(&(self.states.len() as u32).to_le_bytes());
+
+        // Each state
+        for state in &self.states {
+            let state_bytes = state.to_bytes();
+            bytes.extend_from_slice(&(state_bytes.len() as u64).to_le_bytes());
+            bytes.extend_from_slice(&state_bytes);
+        }
+
+        bytes
+    }
+
+    /// Deserialize batch from bytes
+    pub fn from_bytes(data: &[u8]) -> Result<Self, AttentionError> {
+        let mut offset = 0;
+
+        // Magic
+        if data.len() < 8 {
+            return Err(AttentionError::InvalidFormat("Too short".into()));
+        }
+        if &data[0..4] != b"ATNB" {
+            return Err(AttentionError::InvalidMagic);
+        }
+        offset += 4;
+
+        // Version
+        let version = u32::from_le_bytes(data[offset..offset + 4].try_into().unwrap());
+        if version != 1 {
+            return Err(AttentionError::UnsupportedVersion(version));
+        }
+        offset += 4;
+
+        // Session ID
+        if data.len() < offset + 1 {
+            return Err(AttentionError::InvalidFormat("Missing session flag".into()));
+        }
+        let has_session = data[offset] != 0;
+        offset += 1;
+
+        let session_id = if has_session {
+            if data.len() < offset + 16 {
+                return Err(AttentionError::InvalidFormat("Missing session ID".into()));
+            }
+            let mut id_bytes = [0u8; 16];
+            id_bytes.copy_from_slice(&data[offset..offset + 16]);
+            offset += 16;
+            Some(Id::from_bytes(id_bytes))
+        } else {
+            None
+        };
+
+        // Document ID
+        if data.len() < offset + 1 {
+            return Err(AttentionError::InvalidFormat("Missing document flag".into()));
+        }
+        let has_document = data[offset] != 0;
+        offset += 1;
+
+        let document_id = if has_document {
+            if data.len() < offset + 16 {
+                return Err(AttentionError::InvalidFormat("Missing document ID".into()));
+            }
+            let mut id_bytes = [0u8; 16];
+            id_bytes.copy_from_slice(&data[offset..offset + 16]);
+            offset += 16;
+            Some(Id::from_bytes(id_bytes))
+        } else {
+            None
+        };
+
+        // States count
+        if data.len() < offset + 4 {
+            return Err(AttentionError::InvalidFormat("Missing state count".into()));
+        }
+        let state_count = u32::from_le_bytes(data[offset..offset + 4].try_into().unwrap()) as usize;
+        offset += 4;
+
+        // States
+        let mut states = Vec::with_capacity(state_count);
+        for _ in 0..state_count {
+            if data.len() < offset + 8 {
+                return Err(AttentionError::InvalidFormat("Missing state length".into()));
+            }
+            let state_len = u64::from_le_bytes(data[offset..offset + 8].try_into().unwrap()) as usize;
+            offset += 8;
+
+            if data.len() < offset + state_len {
+                return Err(AttentionError::InvalidFormat("State truncated".into()));
+            }
+            let state = AttentionState::from_bytes(&data[offset..offset + state_len])?;
+            offset += state_len;
+            states.push(state);
+        }
+
+        Ok(Self {
+            states,
+            session_id,
+            document_id,
+        })
+    }
+}
+
+impl Default for AttentionBatch {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_role_roundtrip() {
+        for role in [Role::System, Role::User, Role::Assistant, Role::Tool, Role::Context] {
+            let byte = role.to_byte();
+            let restored = Role::from_byte(byte).unwrap();
+            assert_eq!(role, restored);
+        }
+    }
+
+    #[test]
+    fn test_attention_state_roundtrip() {
+        let state = AttentionState::new(
+            Role::User,
+            "Hello, how are you?".to_string(),
+            vec![0.1, 0.2, 0.3, 0.4],
+        )
+        .with_metadata("turn", "1");
+
+        let bytes = state.to_bytes();
+        let restored = AttentionState::from_bytes(&bytes).unwrap();
+
+        assert_eq!(state.role, restored.role);
+        assert_eq!(state.text, restored.text);
+        assert_eq!(state.embedding, restored.embedding);
+        assert_eq!(state.metadata.get("turn"), restored.metadata.get("turn"));
+    }
+
+    #[test]
+    fn test_attention_state_with_kv() {
+        let kv = CompressedKV {
+            model_id: "llama-3-8b".to_string(),
+            num_layers: 32,
+            num_heads: 32,
+            head_dim: 128,
+            seq_len: 10,
+            quantization: "fp16".to_string(),
+            data: vec![1, 2, 3, 4, 5],
+        };
+
+        let state = AttentionState::new(
+            Role::Assistant,
+            "I'm doing well!".to_string(),
+            vec![0.5, 0.6, 0.7, 0.8],
+        )
+        .with_kv_cache(kv);
+
+        let bytes = state.to_bytes();
+        let restored = AttentionState::from_bytes(&bytes).unwrap();
+
+        assert!(restored.kv_cache.is_some());
+        let restored_kv = restored.kv_cache.unwrap();
+        assert_eq!(restored_kv.model_id, "llama-3-8b");
+        assert_eq!(restored_kv.num_layers, 32);
+        assert_eq!(restored_kv.data, vec![1, 2, 3, 4, 5]);
+    }
+
+    #[test]
+    fn test_batch_roundtrip() {
+        let mut batch = AttentionBatch::new()
+            .with_session(Id::now());
+
+        batch.add(AttentionState::new(
+            Role::User,
+            "Question 1".to_string(),
+            vec![0.1, 0.2],
+        ));
+
+        batch.add(AttentionState::new(
+            Role::Assistant,
+            "Answer 1".to_string(),
+            vec![0.3, 0.4],
+        ));
+
+        let bytes = batch.to_bytes();
+        let restored = AttentionBatch::from_bytes(&bytes).unwrap();
+
+        assert_eq!(restored.states.len(), 2);
+        assert_eq!(restored.states[0].text, "Question 1");
+        assert_eq!(restored.states[1].text, "Answer 1");
+        assert!(restored.session_id.is_some());
+    }
+}

src/adapters/index/consolidation.rs

@@ -0,0 +1,576 @@
+//! # Consolidation Phases for HAT
+//!
+//! Background maintenance operations inspired by memory consolidation in the brain.
+//! Like sleep stages (REM/NREM), HAT needs periodic "offline" maintenance to:
+//!
+//! 1. **Recompute Centroids**: Incremental updates accumulate drift - recompute from scratch
+//! 2. **Rebalance Tree**: Merge underpopulated containers, split overpopulated ones
+//! 3. **Prune Stale Branches**: Remove containers with no descendants
+//! 4. **Optimize Layout**: Reorder children for better cache locality
+//!
+//! ## Design Philosophy
+//!
+//! Consolidation is designed to be:
+//! - **Non-blocking**: Can run incrementally, yielding to queries
+//! - **Resumable**: Can pause and resume without data loss
+//! - **Observable**: Reports progress and metrics for benchmarking
+//!
+//! ## Consolidation Levels
+//!
+//! Like sleep stages, different consolidation depths:
+//!
+//! - **Light** (α): Recompute centroids only (~NREM Stage 1)
+//! - **Medium** (β): + Rebalance tree structure (~NREM Stage 2-3)
+//! - **Deep** (δ): + Optimize layout, prune stale (~NREM Stage 4 / SWS)
+//! - **Full** (θ): Complete rebuild from scratch (~REM)
+
+use std::collections::{HashMap, HashSet, VecDeque};
+
+use crate::core::{Id, Point};
+
+/// Consolidation level - determines how deep the maintenance goes
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ConsolidationLevel {
+    /// Light: Recompute centroids only
+    /// Fast, minimal disruption, good for frequent runs
+    Light,
+
+    /// Medium: Recompute centroids + rebalance tree
+    /// Moderate time, restructures containers
+    Medium,
+
+    /// Deep: Full maintenance including layout optimization
+    /// Longer time, comprehensive cleanup
+    Deep,
+
+    /// Full: Complete rebuild from leaf nodes
+    /// Longest time, guarantees optimal structure
+    Full,
+}
+
+impl Default for ConsolidationLevel {
+    fn default() -> Self {
+        ConsolidationLevel::Medium
+    }
+}
+
+/// Configuration for consolidation operations
+#[derive(Debug, Clone)]
+pub struct ConsolidationConfig {
+    /// Target level of consolidation
+    pub level: ConsolidationLevel,
+
+    /// Maximum containers to process per tick (for incremental consolidation)
+    pub batch_size: usize,
+
+    /// Minimum children before considering merge
+    pub merge_threshold: usize,
+
+    /// Maximum children before considering split
+    pub split_threshold: usize,
+
+    /// Maximum centroid drift (L2) before triggering recompute
+    /// 0.0 = always recompute, higher values = more lenient
+    pub drift_threshold: f32,
+
+    /// Whether to collect detailed metrics
+    pub collect_metrics: bool,
+}
+
+impl Default for ConsolidationConfig {
+    fn default() -> Self {
+        Self {
+            level: ConsolidationLevel::Medium,
+            batch_size: 100,
+            merge_threshold: 3,
+            split_threshold: 100,
+            drift_threshold: 0.01,
+            collect_metrics: true,
+        }
+    }
+}
+
+impl ConsolidationConfig {
+    pub fn light() -> Self {
+        Self {
+            level: ConsolidationLevel::Light,
+            ..Default::default()
+        }
+    }
+
+    pub fn medium() -> Self {
+        Self {
+            level: ConsolidationLevel::Medium,
+            ..Default::default()
+        }
+    }
+
+    pub fn deep() -> Self {
+        Self {
+            level: ConsolidationLevel::Deep,
+            ..Default::default()
+        }
+    }
+
+    pub fn full() -> Self {
+        Self {
+            level: ConsolidationLevel::Full,
+            ..Default::default()
+        }
+    }
+
+    pub fn with_batch_size(mut self, size: usize) -> Self {
+        self.batch_size = size;
+        self
+    }
+}
+
+/// Current state of consolidation
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ConsolidationPhase {
+    /// Not currently consolidating
+    Idle,
+
+    /// Phase 1: Collecting all leaf points
+    CollectingLeaves,
+
+    /// Phase 2: Recomputing centroids bottom-up
+    RecomputingCentroids,
+
+    /// Phase 3: Identifying containers to merge/split
+    AnalyzingStructure,
+
+    /// Phase 4: Performing merges
+    Merging,
+
+    /// Phase 5: Performing splits
+    Splitting,
+
+    /// Phase 6: Pruning empty containers
+    Pruning,
+
+    /// Phase 7: Optimizing layout
+    OptimizingLayout,
+
+    /// Consolidation complete
+    Complete,
+}
+
+/// Metrics collected during consolidation
+#[derive(Debug, Clone, Default)]
+pub struct ConsolidationMetrics {
+    /// Total containers processed
+    pub containers_processed: usize,
+
+    /// Centroids recomputed
+    pub centroids_recomputed: usize,
+
+    /// Average centroid drift (L2 norm of delta)
+    pub avg_centroid_drift: f32,
+
+    /// Maximum centroid drift observed
+    pub max_centroid_drift: f32,
+
+    /// Number of containers merged
+    pub containers_merged: usize,
+
+    /// Number of containers split
+    pub containers_split: usize,
+
+    /// Number of empty containers pruned
+    pub containers_pruned: usize,
+
+    /// Time spent in each phase (microseconds)
+    pub phase_times_us: HashMap<String, u64>,
+
+    /// Total consolidation time (microseconds)
+    pub total_time_us: u64,
+
+    /// Number of ticks (for incremental consolidation)
+    pub ticks: usize,
+}
+
+/// Progress report for observable consolidation
+#[derive(Debug, Clone)]
+pub struct ConsolidationProgress {
+    /// Current phase
+    pub phase: ConsolidationPhase,
+
+    /// Percentage complete (0.0 - 1.0)
+    pub progress: f32,
+
+    /// Containers remaining in current phase
+    pub remaining: usize,
+
+    /// Running metrics
+    pub metrics: ConsolidationMetrics,
+}
+
+/// Internal state for resumable consolidation
+#[derive(Debug)]
+pub struct ConsolidationState {
+    /// Configuration
+    pub config: ConsolidationConfig,
+
+    /// Current phase
+    pub phase: ConsolidationPhase,
+
+    /// Collected metrics
+    pub metrics: ConsolidationMetrics,
+
+    /// Queue of containers to process in current phase
+    pub work_queue: VecDeque<Id>,
+
+    /// Set of containers already processed
+    pub processed: HashSet<Id>,
+
+    /// Accumulated centroid drifts for averaging
+    centroid_drifts: Vec<f32>,
+
+    /// Containers identified for merging (pairs)
+    merge_candidates: Vec<(Id, Id)>,
+
+    /// Containers identified for splitting
+    split_candidates: Vec<Id>,
+
+    /// Phase start timestamp (for timing)
+    phase_start_us: u64,
+
+    /// Consolidation start timestamp
+    start_us: u64,
+}
+
+impl ConsolidationState {
+    /// Create a new consolidation state
+    pub fn new(config: ConsolidationConfig) -> Self {
+        let now = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap()
+            .as_micros() as u64;
+
+        Self {
+            config,
+            phase: ConsolidationPhase::Idle,
+            metrics: ConsolidationMetrics::default(),
+            work_queue: VecDeque::new(),
+            processed: HashSet::new(),
+            centroid_drifts: Vec::new(),
+            merge_candidates: Vec::new(),
+            split_candidates: Vec::new(),
+            phase_start_us: now,
+            start_us: now,
+        }
+    }
+
+    /// Start consolidation
+    pub fn start(&mut self) {
+        let now = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap()
+            .as_micros() as u64;
+
+        self.start_us = now;
+        self.phase_start_us = now;
+        self.phase = ConsolidationPhase::CollectingLeaves;
+        self.metrics = ConsolidationMetrics::default();
+        self.work_queue.clear();
+        self.processed.clear();
+        self.centroid_drifts.clear();
+        self.merge_candidates.clear();
+        self.split_candidates.clear();
+    }
+
+    /// Transition to next phase
+    pub fn next_phase(&mut self) {
+        let now = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap()
+            .as_micros() as u64;
+
+        // Record time for previous phase
+        let phase_time = now - self.phase_start_us;
+        let phase_name = format!("{:?}", self.phase);
+        self.metrics.phase_times_us.insert(phase_name, phase_time);
+
+        // Compute average drift if we have samples
+        if !self.centroid_drifts.is_empty() {
+            self.metrics.avg_centroid_drift =
+                self.centroid_drifts.iter().sum::<f32>() / self.centroid_drifts.len() as f32;
+        }
+
+        // Determine next phase based on level
+        self.phase = match (self.phase, self.config.level) {
+            (ConsolidationPhase::Idle, _) => ConsolidationPhase::CollectingLeaves,
+
+            (ConsolidationPhase::CollectingLeaves, _) => ConsolidationPhase::RecomputingCentroids,
+
+            (ConsolidationPhase::RecomputingCentroids, ConsolidationLevel::Light) => {
+                ConsolidationPhase::Complete
+            }
+            (ConsolidationPhase::RecomputingCentroids, _) => {
+                ConsolidationPhase::AnalyzingStructure
+            }
+
+            (ConsolidationPhase::AnalyzingStructure, _) => ConsolidationPhase::Merging,
+
+            (ConsolidationPhase::Merging, _) => ConsolidationPhase::Splitting,
+
+            (ConsolidationPhase::Splitting, ConsolidationLevel::Medium) => {
+                ConsolidationPhase::Complete
+            }
+            (ConsolidationPhase::Splitting, _) => ConsolidationPhase::Pruning,
+
+            (ConsolidationPhase::Pruning, _) => ConsolidationPhase::OptimizingLayout,
+
+            (ConsolidationPhase::OptimizingLayout, _) => ConsolidationPhase::Complete,
+
+            (ConsolidationPhase::Complete, _) => ConsolidationPhase::Complete,
+        };
+
+        // Reset for new phase
+        self.phase_start_us = now;
+        self.work_queue.clear();
+        self.processed.clear();
+
+        // Record total time if complete
+        if self.phase == ConsolidationPhase::Complete {
+            self.metrics.total_time_us = now - self.start_us;
+        }
+    }
+
+    /// Record a centroid drift
+    pub fn record_drift(&mut self, drift: f32) {
+        self.centroid_drifts.push(drift);
+        if drift > self.metrics.max_centroid_drift {
+            self.metrics.max_centroid_drift = drift;
+        }
+    }
+
+    /// Add merge candidate pair
+    pub fn add_merge_candidate(&mut self, a: Id, b: Id) {
+        self.merge_candidates.push((a, b));
+    }
+
+    /// Add split candidate
+    pub fn add_split_candidate(&mut self, id: Id) {
+        self.split_candidates.push(id);
+    }
+
+    /// Get next merge candidate pair
+    pub fn next_merge(&mut self) -> Option<(Id, Id)> {
+        self.merge_candidates.pop()
+    }
+
+    /// Get next split candidate
+    pub fn next_split(&mut self) -> Option<Id> {
+        self.split_candidates.pop()
+    }
+
+    /// Check if there are pending merge candidates
+    pub fn has_merges(&self) -> bool {
+        !self.merge_candidates.is_empty()
+    }
+
+    /// Check if there are pending split candidates
+    pub fn has_splits(&self) -> bool {
+        !self.split_candidates.is_empty()
+    }
+
+    /// Check if consolidation is complete
+    pub fn is_complete(&self) -> bool {
+        self.phase == ConsolidationPhase::Complete
+    }
+
+    /// Get progress report
+    pub fn progress(&self) -> ConsolidationProgress {
+        let remaining = self.work_queue.len();
+        let total = remaining + self.processed.len();
+        let progress = if total > 0 {
+            self.processed.len() as f32 / total as f32
+        } else {
+            1.0
+        };
+
+        ConsolidationProgress {
+            phase: self.phase,
+            progress,
+            remaining,
+            metrics: self.metrics.clone(),
+        }
+    }
+}
+
+/// Result of a single consolidation tick
+#[derive(Debug)]
+pub enum ConsolidationTickResult {
+    /// Still working, more ticks needed
+    Continue(ConsolidationProgress),
+
+    /// Consolidation complete
+    Complete(ConsolidationMetrics),
+}
+
+/// Trait for types that support consolidation
+pub trait Consolidate {
+    /// Begin consolidation with given config
+    fn begin_consolidation(&mut self, config: ConsolidationConfig);
+
+    /// Execute one tick of consolidation
+    /// Returns Continue if more work remains, Complete when done
+    fn consolidation_tick(&mut self) -> ConsolidationTickResult;
+
+    /// Run consolidation to completion (blocking)
+    fn consolidate(&mut self, config: ConsolidationConfig) -> ConsolidationMetrics {
+        self.begin_consolidation(config);
+        loop {
+            match self.consolidation_tick() {
+                ConsolidationTickResult::Continue(_) => continue,
+                ConsolidationTickResult::Complete(metrics) => return metrics,
+            }
+        }
+    }
+
+    /// Check if consolidation is in progress
+    fn is_consolidating(&self) -> bool;
+
+    /// Get current consolidation progress
+    fn consolidation_progress(&self) -> Option<ConsolidationProgress>;
+
+    /// Cancel ongoing consolidation
+    fn cancel_consolidation(&mut self);
+}
+
+/// Helper for computing exact centroids from a set of points
+pub fn compute_exact_centroid(points: &[Point]) -> Option<Point> {
+    if points.is_empty() {
+        return None;
+    }
+
+    let dims = points[0].dimensionality();
+    let mut sum = vec![0.0f32; dims];
+
+    for point in points {
+        for (i, &val) in point.dims().iter().enumerate() {
+            sum[i] += val;
+        }
+    }
+
+    let n = points.len() as f32;
+    let mean: Vec<f32> = sum.iter().map(|s| s / n).collect();
+
+    Some(Point::new(mean).normalize())
+}
+
+/// Helper to measure centroid drift
+pub fn centroid_drift(old: &Point, new: &Point) -> f32 {
+    old.dims()
+        .iter()
+        .zip(new.dims().iter())
+        .map(|(a, b)| (a - b).powi(2))
+        .sum::<f32>()
+        .sqrt()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_consolidation_config_levels() {
+        let light = ConsolidationConfig::light();
+        assert_eq!(light.level, ConsolidationLevel::Light);
+
+        let medium = ConsolidationConfig::medium();
+        assert_eq!(medium.level, ConsolidationLevel::Medium);
+
+        let deep = ConsolidationConfig::deep();
+        assert_eq!(deep.level, ConsolidationLevel::Deep);
+
+        let full = ConsolidationConfig::full();
+        assert_eq!(full.level, ConsolidationLevel::Full);
+    }
+
+    #[test]
+    fn test_consolidation_state_phases() {
+        let config = ConsolidationConfig::light();
+        let mut state = ConsolidationState::new(config);
+
+        assert_eq!(state.phase, ConsolidationPhase::Idle);
+
+        state.start();
+        assert_eq!(state.phase, ConsolidationPhase::CollectingLeaves);
+
+        state.next_phase();
+        assert_eq!(state.phase, ConsolidationPhase::RecomputingCentroids);
+
+        // Light level skips to complete after centroids
+        state.next_phase();
+        assert_eq!(state.phase, ConsolidationPhase::Complete);
+        assert!(state.is_complete());
+    }
+
+    #[test]
+    fn test_consolidation_state_medium_phases() {
+        let config = ConsolidationConfig::medium();
+        let mut state = ConsolidationState::new(config);
+
+        state.start();
+        assert_eq!(state.phase, ConsolidationPhase::CollectingLeaves);
+
+        state.next_phase();
+        assert_eq!(state.phase, ConsolidationPhase::RecomputingCentroids);
+
+        state.next_phase();
+        assert_eq!(state.phase, ConsolidationPhase::AnalyzingStructure);
+
+        state.next_phase();
+        assert_eq!(state.phase, ConsolidationPhase::Merging);
+
+        state.next_phase();
+        assert_eq!(state.phase, ConsolidationPhase::Splitting);
+
+        // Medium level completes after splitting
+        state.next_phase();
+        assert_eq!(state.phase, ConsolidationPhase::Complete);
+    }
+
+    #[test]
+    fn test_centroid_computation() {
+        let points = vec![
+            Point::new(vec![1.0, 0.0, 0.0]),
+            Point::new(vec![0.0, 1.0, 0.0]),
+            Point::new(vec![0.0, 0.0, 1.0]),
+        ];
+
+        let centroid = compute_exact_centroid(&points).unwrap();
+
+        // Should be normalized mean
+        let expected_unnorm = (1.0f32 / 3.0).sqrt();
+        for dim in centroid.dims() {
+            assert!((dim - expected_unnorm).abs() < 0.01);
+        }
+    }
+
+    #[test]
+    fn test_centroid_drift() {
+        let old = Point::new(vec![1.0, 0.0, 0.0]);
+        let new = Point::new(vec![0.9, 0.1, 0.0]).normalize();
+
+        let drift = centroid_drift(&old, &new);
+        assert!(drift > 0.0);
+        assert!(drift < 1.0);
+    }
+
+    #[test]
+    fn test_drift_recording() {
+        let config = ConsolidationConfig::default();
+        let mut state = ConsolidationState::new(config);
+
+        state.record_drift(0.05);
+        state.record_drift(0.10);
+        state.record_drift(0.02);
+
+        assert_eq!(state.metrics.max_centroid_drift, 0.10);
+        assert_eq!(state.centroid_drifts.len(), 3);
+    }
+}

src/adapters/index/flat.rs

@@ -0,0 +1,278 @@
+//! # Flat Index Adapter
+//!
+//! Brute force nearest neighbor search.
+//! Compares query against ALL points - O(n) per query.
+//!
+//! Good for:
+//! - Testing
+//! - Small datasets (< 10,000 points)
+//! - When exact results are required
+//!
+//! Not good for:
+//! - Large datasets (use HNSW instead)
+
+use std::collections::HashMap;
+use std::sync::Arc;
+
+use crate::core::{Id, Point};
+use crate::core::proximity::Proximity;
+use crate::ports::{Near, NearError, NearResult, SearchResult};
+
+/// Brute force index - searches all points
+pub struct FlatIndex {
+    /// Stored points (ID -> Point)
+    points: HashMap<Id, Point>,
+
+    /// Expected dimensionality
+    dimensionality: usize,
+
+    /// Proximity function to use
+    proximity: Arc<dyn Proximity>,
+
+    /// Whether higher proximity = more similar
+    /// true for cosine/dot product, false for euclidean
+    higher_is_better: bool,
+}
+
+impl FlatIndex {
+    /// Create a new flat index
+    ///
+    /// `higher_is_better` indicates whether higher proximity scores mean more similar.
+    /// - `true` for Cosine, DotProduct
+    /// - `false` for Euclidean, Manhattan
+    pub fn new(
+        dimensionality: usize,
+        proximity: Arc<dyn Proximity>,
+        higher_is_better: bool,
+    ) -> Self {
+        Self {
+            points: HashMap::new(),
+            dimensionality,
+            proximity,
+            higher_is_better,
+        }
+    }
+
+    /// Create with cosine similarity (higher = better)
+    pub fn cosine(dimensionality: usize) -> Self {
+        use crate::core::proximity::Cosine;
+        Self::new(dimensionality, Arc::new(Cosine), true)
+    }
+
+    /// Create with euclidean distance (lower = better)
+    pub fn euclidean(dimensionality: usize) -> Self {
+        use crate::core::proximity::Euclidean;
+        Self::new(dimensionality, Arc::new(Euclidean), false)
+    }
+
+    /// Sort results by relevance
+    fn sort_results(&self, results: &mut Vec<SearchResult>) {
+        if self.higher_is_better {
+            // Higher score = more relevant, sort descending
+            results.sort_by(|a, b| b.score.partial_cmp(&a.score).unwrap());
+        } else {
+            // Lower score = more relevant, sort ascending
+            results.sort_by(|a, b| a.score.partial_cmp(&b.score).unwrap());
+        }
+    }
+}
+
+impl Near for FlatIndex {
+    fn near(&self, query: &Point, k: usize) -> NearResult<Vec<SearchResult>> {
+        // Check dimensionality
+        if query.dimensionality() != self.dimensionality {
+            return Err(NearError::DimensionalityMismatch {
+                expected: self.dimensionality,
+                got: query.dimensionality(),
+            });
+        }
+
+        // Compute proximity to all points
+        let mut results: Vec<SearchResult> = self
+            .points
+            .iter()
+            .map(|(id, point)| {
+                let score = self.proximity.proximity(query, point);
+                SearchResult::new(*id, score)
+            })
+            .collect();
+
+        // Sort by relevance
+        self.sort_results(&mut results);
+
+        // Take top k
+        results.truncate(k);
+
+        Ok(results)
+    }
+
+    fn within(&self, query: &Point, threshold: f32) -> NearResult<Vec<SearchResult>> {
+        // Check dimensionality
+        if query.dimensionality() != self.dimensionality {
+            return Err(NearError::DimensionalityMismatch {
+                expected: self.dimensionality,
+                got: query.dimensionality(),
+            });
+        }
+
+        // Find all points within threshold
+        let mut results: Vec<SearchResult> = self
+            .points
+            .iter()
+            .filter_map(|(id, point)| {
+                let score = self.proximity.proximity(query, point);
+                let within = if self.higher_is_better {
+                    score >= threshold
+                } else {
+                    score <= threshold
+                };
+                if within {
+                    Some(SearchResult::new(*id, score))
+                } else {
+                    None
+                }
+            })
+            .collect();
+
+        // Sort by relevance
+        self.sort_results(&mut results);
+
+        Ok(results)
+    }
+
+    fn add(&mut self, id: Id, point: &Point) -> NearResult<()> {
+        if point.dimensionality() != self.dimensionality {
+            return Err(NearError::DimensionalityMismatch {
+                expected: self.dimensionality,
+                got: point.dimensionality(),
+            });
+        }
+
+        self.points.insert(id, point.clone());
+        Ok(())
+    }
+
+    fn remove(&mut self, id: Id) -> NearResult<()> {
+        self.points.remove(&id);
+        Ok(())
+    }
+
+    fn rebuild(&mut self) -> NearResult<()> {
+        // Flat index doesn't need rebuilding
+        Ok(())
+    }
+
+    fn is_ready(&self) -> bool {
+        true // Always ready
+    }
+
+    fn len(&self) -> usize {
+        self.points.len()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn setup_index() -> FlatIndex {
+        let mut index = FlatIndex::cosine(3);
+
+        // Add some test points
+        let points = vec![
+            (Id::from_bytes([1; 16]), Point::new(vec![1.0, 0.0, 0.0])),
+            (Id::from_bytes([2; 16]), Point::new(vec![0.0, 1.0, 0.0])),
+            (Id::from_bytes([3; 16]), Point::new(vec![0.0, 0.0, 1.0])),
+            (Id::from_bytes([4; 16]), Point::new(vec![0.7, 0.7, 0.0]).normalize()),
+        ];
+
+        for (id, point) in points {
+            index.add(id, &point).unwrap();
+        }
+
+        index
+    }
+
+    #[test]
+    fn test_flat_index_near() {
+        let index = setup_index();
+
+        // Query for points near [1, 0, 0]
+        let query = Point::new(vec![1.0, 0.0, 0.0]);
+        let results = index.near(&query, 2).unwrap();
+
+        assert_eq!(results.len(), 2);
+
+        // First result should be [1, 0, 0] with cosine = 1.0
+        assert_eq!(results[0].id, Id::from_bytes([1; 16]));
+        assert!((results[0].score - 1.0).abs() < 0.0001);
+    }
+
+    #[test]
+    fn test_flat_index_within_cosine() {
+        let index = setup_index();
+
+        // Find all points with cosine > 0.5 to [1, 0, 0]
+        let query = Point::new(vec![1.0, 0.0, 0.0]);
+        let results = index.within(&query, 0.5).unwrap();
+
+        // Should find [1,0,0] (cosine=1.0) and [0.7,0.7,0] (cosine≈0.707)
+        assert_eq!(results.len(), 2);
+    }
+
+    #[test]
+    fn test_flat_index_euclidean() {
+        let mut index = FlatIndex::euclidean(2);
+
+        index.add(Id::from_bytes([1; 16]), &Point::new(vec![0.0, 0.0])).unwrap();
+        index.add(Id::from_bytes([2; 16]), &Point::new(vec![1.0, 0.0])).unwrap();
+        index.add(Id::from_bytes([3; 16]), &Point::new(vec![5.0, 0.0])).unwrap();
+
+        let query = Point::new(vec![0.0, 0.0]);
+        let results = index.near(&query, 2).unwrap();
+
+        // Nearest should be [0,0] with distance 0
+        assert_eq!(results[0].id, Id::from_bytes([1; 16]));
+        assert!((results[0].score - 0.0).abs() < 0.0001);
+
+        // Second nearest should be [1,0] with distance 1
+        assert_eq!(results[1].id, Id::from_bytes([2; 16]));
+        assert!((results[1].score - 1.0).abs() < 0.0001);
+    }
+
+    #[test]
+    fn test_flat_index_add_remove() {
+        let mut index = FlatIndex::cosine(3);
+
+        let id = Id::from_bytes([1; 16]);
+        let point = Point::new(vec![1.0, 0.0, 0.0]);
+
+        index.add(id, &point).unwrap();
+        assert_eq!(index.len(), 1);
+
+        index.remove(id).unwrap();
+        assert_eq!(index.len(), 0);
+    }
+
+    #[test]
+    fn test_flat_index_dimensionality_check() {
+        let mut index = FlatIndex::cosine(3);
+
+        let wrong_dims = Point::new(vec![1.0, 0.0]); // 2 dims
+        let result = index.add(Id::now(), &wrong_dims);
+
+        match result {
+            Err(NearError::DimensionalityMismatch { expected, got }) => {
+                assert_eq!(expected, 3);
+                assert_eq!(got, 2);
+            }
+            _ => panic!("Expected DimensionalityMismatch error"),
+        }
+    }
+
+    #[test]
+    fn test_flat_index_ready() {
+        let index = FlatIndex::cosine(3);
+        assert!(index.is_ready());
+    }
+}

src/adapters/index/hat.rs

@@ -0,0 +1,1953 @@
+//! # HAT Index Adapter
+//!
+//! Hierarchical Attention Tree - a novel index structure for AI memory.
+//! Exploits known semantic hierarchy and temporal locality.
+//!
+//! Key insight: Unlike HNSW which learns topology from data,
+//! HAT uses KNOWN hierarchy (session → document → chunk).
+//!
+//! Query complexity: O(log n) via tree descent
+//! Insert complexity: O(log n) with incremental centroid updates
+
+use std::collections::{HashMap, VecDeque};
+use std::sync::Arc;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use crate::core::{Id, Point};
+use crate::core::proximity::Proximity;
+use crate::core::merge::Merge;
+use crate::ports::{Near, NearError, NearResult, SearchResult};
+
+use super::consolidation::{
+    Consolidate, ConsolidationConfig, ConsolidationPhase, ConsolidationState,
+    ConsolidationMetrics, ConsolidationProgress, ConsolidationTickResult,
+    compute_exact_centroid, centroid_drift,
+};
+
+/// Centroid computation method
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum CentroidMethod {
+    /// Euclidean mean + renormalize (fast but geometrically imprecise)
+    Euclidean,
+    /// Fréchet mean on hypersphere (manifold-aware, more accurate)
+    Frechet,
+}
+
+impl Default for CentroidMethod {
+    fn default() -> Self {
+        CentroidMethod::Euclidean
+    }
+}
+
+/// HAT configuration parameters
+#[derive(Debug, Clone)]
+pub struct HatConfig {
+    /// Maximum children per container before splitting
+    pub max_children: usize,
+
+    /// Minimum children to maintain (for merging)
+    pub min_children: usize,
+
+    /// Number of branches to explore at each level (beam width)
+    pub beam_width: usize,
+
+    /// Weight for temporal proximity in scoring (0.0 = pure semantic)
+    pub temporal_weight: f32,
+
+    /// Time decay factor (higher = faster decay)
+    pub time_decay: f32,
+
+    /// Threshold for sparse centroid propagation (0.0 = always propagate)
+    /// Only propagate to parent if centroid change magnitude exceeds this
+    pub propagation_threshold: f32,
+
+    /// Method for computing centroids
+    pub centroid_method: CentroidMethod,
+
+    /// Number of iterations for Fréchet mean computation
+    pub frechet_iterations: usize,
+
+    /// Enable subspace-aware routing (default: false for backward compatibility)
+    pub subspace_enabled: bool,
+
+    /// Configuration for subspace representation
+    pub subspace_config: super::subspace::SubspaceConfig,
+
+    /// Enable learnable routing (default: false for backward compatibility)
+    pub learnable_routing_enabled: bool,
+
+    /// Configuration for learnable routing
+    pub learnable_routing_config: super::learnable_routing::LearnableRoutingConfig,
+}
+
+impl Default for HatConfig {
+    fn default() -> Self {
+        Self {
+            max_children: 50,
+            min_children: 5,
+            beam_width: 3,
+            temporal_weight: 0.0, // Start with pure semantic
+            time_decay: 0.001,
+            propagation_threshold: 0.0, // Default: always propagate (backward compatible)
+            centroid_method: CentroidMethod::Euclidean, // Default: backward compatible
+            frechet_iterations: 5, // Enough for convergence on hypersphere
+            subspace_enabled: false, // Default: disabled for backward compatibility
+            subspace_config: super::subspace::SubspaceConfig::default(),
+            learnable_routing_enabled: false, // Default: disabled for backward compatibility
+            learnable_routing_config: super::learnable_routing::LearnableRoutingConfig::default(),
+        }
+    }
+}
+
+impl HatConfig {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    pub fn with_beam_width(mut self, width: usize) -> Self {
+        self.beam_width = width;
+        self
+    }
+
+    pub fn with_temporal_weight(mut self, weight: f32) -> Self {
+        self.temporal_weight = weight;
+        self
+    }
+
+    pub fn with_propagation_threshold(mut self, threshold: f32) -> Self {
+        self.propagation_threshold = threshold;
+        self
+    }
+
+    pub fn with_centroid_method(mut self, method: CentroidMethod) -> Self {
+        self.centroid_method = method;
+        self
+    }
+
+    pub fn with_frechet_iterations(mut self, iterations: usize) -> Self {
+        self.frechet_iterations = iterations;
+        self
+    }
+
+    pub fn with_subspace_enabled(mut self, enabled: bool) -> Self {
+        self.subspace_enabled = enabled;
+        self
+    }
+
+    pub fn with_subspace_config(mut self, config: super::subspace::SubspaceConfig) -> Self {
+        self.subspace_config = config;
+        self.subspace_enabled = true;  // Automatically enable when config is provided
+        self
+    }
+
+    pub fn with_learnable_routing_enabled(mut self, enabled: bool) -> Self {
+        self.learnable_routing_enabled = enabled;
+        self
+    }
+
+    pub fn with_learnable_routing_config(mut self, config: super::learnable_routing::LearnableRoutingConfig) -> Self {
+        self.learnable_routing_config = config;
+        self.learnable_routing_enabled = true;  // Automatically enable when config is provided
+        self
+    }
+}
+
+/// Level in the hierarchy
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ContainerLevel {
+    /// Root level - single global container
+    Global,
+    /// Session level - conversation/context boundaries
+    Session,
+    /// Document level - logical groupings within session
+    Document,
+    /// Chunk level - leaf nodes, actual attention states
+    Chunk,
+}
+
+impl ContainerLevel {
+    fn child_level(&self) -> Option<ContainerLevel> {
+        match self {
+            ContainerLevel::Global => Some(ContainerLevel::Session),
+            ContainerLevel::Session => Some(ContainerLevel::Document),
+            ContainerLevel::Document => Some(ContainerLevel::Chunk),
+            ContainerLevel::Chunk => None,
+        }
+    }
+
+    fn depth(&self) -> usize {
+        match self {
+            ContainerLevel::Global => 0,
+            ContainerLevel::Session => 1,
+            ContainerLevel::Document => 2,
+            ContainerLevel::Chunk => 3,
+        }
+    }
+}
+
+/// Summary of a session for coarse queries (multi-resolution API)
+#[derive(Debug, Clone)]
+pub struct SessionSummary {
+    /// Session ID
+    pub id: Id,
+
+    /// Similarity score to query
+    pub score: f32,
+
+    /// Number of chunks in this session
+    pub chunk_count: usize,
+
+    /// Session timestamp
+    pub timestamp: u64,
+}
+
+/// Summary of a document for coarse queries
+#[derive(Debug, Clone)]
+pub struct DocumentSummary {
+    /// Document ID
+    pub id: Id,
+
+    /// Similarity score to query
+    pub score: f32,
+
+    /// Number of chunks in this document
+    pub chunk_count: usize,
+
+    /// Document timestamp
+    pub timestamp: u64,
+}
+
+/// A container in the HAT hierarchy
+#[derive(Debug, Clone)]
+struct Container {
+    /// Unique identifier
+    id: Id,
+
+    /// Level in hierarchy
+    level: ContainerLevel,
+
+    /// Centroid (mean of children)
+    centroid: Point,
+
+    /// Creation timestamp (ms since epoch)
+    timestamp: u64,
+
+    /// Child container IDs (empty for chunks)
+    children: Vec<Id>,
+
+    /// Number of descendant chunks (for weighted centroid updates)
+    descendant_count: usize,
+
+    /// Accumulated sum of all descendant points (for Euclidean centroid)
+    /// Stored as unnormalized to enable incremental updates
+    accumulated_sum: Option<Point>,
+
+    /// Subspace representation (optional, for non-chunk containers)
+    /// Captures variance/spread of points within the container
+    subspace: Option<super::subspace::Subspace>,
+}
+
+impl Container {
+    fn new(id: Id, level: ContainerLevel, centroid: Point) -> Self {
+        let timestamp = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_millis() as u64;
+
+        // For chunks, the accumulated sum is the point itself
+        let accumulated_sum = if level == ContainerLevel::Chunk {
+            Some(centroid.clone())
+        } else {
+            None
+        };
+
+        // Initialize subspace for non-chunk containers
+        let subspace = if level != ContainerLevel::Chunk {
+            Some(super::subspace::Subspace::new(centroid.dimensionality()))
+        } else {
+            None
+        };
+
+        Self {
+            id,
+            level,
+            centroid,
+            timestamp,
+            children: Vec::new(),
+            descendant_count: if level == ContainerLevel::Chunk { 1 } else { 0 },
+            accumulated_sum,
+            subspace,
+        }
+    }
+
+    fn is_leaf(&self) -> bool {
+        self.level == ContainerLevel::Chunk
+    }
+}
+
+/// Hierarchical Attention Tree Index
+pub struct HatIndex {
+    /// All containers (including root, sessions, documents, chunks)
+    containers: HashMap<Id, Container>,
+
+    /// Root container ID
+    root_id: Option<Id>,
+
+    /// Current active session (where new documents go)
+    active_session: Option<Id>,
+
+    /// Current active document (where new chunks go)
+    active_document: Option<Id>,
+
+    /// Expected dimensionality
+    dimensionality: usize,
+
+    /// Proximity function
+    proximity: Arc<dyn Proximity>,
+
+    /// Merge function (for centroids)
+    merge: Arc<dyn Merge>,
+
+    /// Whether higher proximity = more similar
+    higher_is_better: bool,
+
+    /// Configuration
+    config: HatConfig,
+
+    /// Consolidation state (None if not consolidating)
+    consolidation_state: Option<ConsolidationState>,
+
+    /// Cache of child points during consolidation
+    consolidation_points_cache: HashMap<Id, Vec<Point>>,
+
+    /// Learnable router for adaptive routing weights
+    learnable_router: Option<super::learnable_routing::LearnableRouter>,
+}
+
+impl HatIndex {
+    /// Create a new HAT index with cosine similarity
+    pub fn cosine(dimensionality: usize) -> Self {
+        use crate::core::proximity::Cosine;
+        use crate::core::merge::Mean;
+        Self::new(
+            dimensionality,
+            Arc::new(Cosine),
+            Arc::new(Mean),
+            true,
+            HatConfig::default(),
+        )
+    }
+
+    /// Create with custom config
+    pub fn with_config(mut self, config: HatConfig) -> Self {
+        // Initialize learnable router if enabled
+        if config.learnable_routing_enabled {
+            self.learnable_router = Some(super::learnable_routing::LearnableRouter::new(
+                self.dimensionality,
+                config.learnable_routing_config.clone(),
+            ));
+        }
+        self.config = config;
+        self
+    }
+
+    /// Create with custom proximity and merge functions
+    pub fn new(
+        dimensionality: usize,
+        proximity: Arc<dyn Proximity>,
+        merge: Arc<dyn Merge>,
+        higher_is_better: bool,
+        config: HatConfig,
+    ) -> Self {
+        // Initialize learnable router if enabled
+        let learnable_router = if config.learnable_routing_enabled {
+            Some(super::learnable_routing::LearnableRouter::new(
+                dimensionality,
+                config.learnable_routing_config.clone(),
+            ))
+        } else {
+            None
+        };
+
+        Self {
+            containers: HashMap::new(),
+            root_id: None,
+            active_session: None,
+            active_document: None,
+            dimensionality,
+            proximity,
+            merge,
+            higher_is_better,
+            config,
+            consolidation_state: None,
+            consolidation_points_cache: HashMap::new(),
+            learnable_router,
+        }
+    }
+
+    /// Compute distance (lower = more similar)
+    fn distance(&self, a: &Point, b: &Point) -> f32 {
+        let prox = self.proximity.proximity(a, b);
+        if self.higher_is_better {
+            1.0 - prox
+        } else {
+            prox
+        }
+    }
+
+    /// Compute temporal distance (normalized to 0-1)
+    fn temporal_distance(&self, t1: u64, t2: u64) -> f32 {
+        let diff = (t1 as i64 - t2 as i64).unsigned_abs() as f64;
+        // Exponential decay: e^(-λ * diff)
+        // diff is in milliseconds, normalize to hours
+        let hours = diff / (1000.0 * 60.0 * 60.0);
+        (1.0 - (-self.config.time_decay as f64 * hours).exp()) as f32
+    }
+
+    /// Combined distance with temporal component, optional subspace, and learnable routing
+    fn combined_distance(&self, query: &Point, query_time: u64, container: &Container) -> f32 {
+        // Compute semantic distance
+        let semantic = if self.config.learnable_routing_enabled {
+            // Use learnable routing weights
+            if let Some(ref router) = self.learnable_router {
+                // weighted_similarity returns similarity (higher = better)
+                // convert to distance (lower = better)
+                let sim = router.weighted_similarity(query, &container.centroid);
+                1.0 - sim
+            } else {
+                self.distance(query, &container.centroid)
+            }
+        } else if self.config.subspace_enabled && !container.is_leaf() {
+            // Use subspace-aware similarity if available
+            if let Some(ref subspace) = container.subspace {
+                // combined_subspace_similarity returns similarity (higher = better)
+                // convert to distance (lower = better)
+                let sim = super::subspace::combined_subspace_similarity(
+                    query, subspace, &self.config.subspace_config
+                );
+                1.0 - sim
+            } else {
+                self.distance(query, &container.centroid)
+            }
+        } else {
+            self.distance(query, &container.centroid)
+        };
+
+        let temporal = self.temporal_distance(query_time, container.timestamp);
+
+        // Weighted combination
+        let w = self.config.temporal_weight;
+        semantic * (1.0 - w) + temporal * w
+    }
+
+    /// Ensure root exists
+    fn ensure_root(&mut self) {
+        if self.root_id.is_none() {
+            let root = Container::new(
+                Id::now(),
+                ContainerLevel::Global,
+                Point::origin(self.dimensionality),
+            );
+            let root_id = root.id;
+            self.containers.insert(root_id, root);
+            self.root_id = Some(root_id);
+        }
+    }
+
+    /// Ensure active session exists
+    fn ensure_session(&mut self) {
+        self.ensure_root();
+
+        if self.active_session.is_none() {
+            let session = Container::new(
+                Id::now(),
+                ContainerLevel::Session,
+                Point::origin(self.dimensionality),
+            );
+            let session_id = session.id;
+            self.containers.insert(session_id, session);
+
+            // Add to root's children
+            if let Some(root_id) = self.root_id {
+                if let Some(root) = self.containers.get_mut(&root_id) {
+                    root.children.push(session_id);
+                }
+            }
+
+            self.active_session = Some(session_id);
+        }
+    }
+
+    /// Ensure active document exists
+    fn ensure_document(&mut self) {
+        self.ensure_session();
+
+        if self.active_document.is_none() {
+            let document = Container::new(
+                Id::now(),
+                ContainerLevel::Document,
+                Point::origin(self.dimensionality),
+            );
+            let doc_id = document.id;
+            self.containers.insert(doc_id, document);
+
+            // Add to session's children
+            if let Some(session_id) = self.active_session {
+                if let Some(session) = self.containers.get_mut(&session_id) {
+                    session.children.push(doc_id);
+                }
+            }
+
+            self.active_document = Some(doc_id);
+        }
+    }
+
+    /// Start a new session (call this to create session boundaries)
+    pub fn new_session(&mut self) {
+        self.active_session = None;
+        self.active_document = None;
+    }
+
+    /// Start a new document within current session
+    pub fn new_document(&mut self) {
+        self.active_document = None;
+    }
+
+    /// Compute Fréchet mean on the unit hypersphere using iterative algorithm
+    /// This finds the point that minimizes sum of squared geodesic distances
+    fn compute_frechet_mean(&self, points: &[Point], initial: &Point) -> Point {
+        let mut mean = initial.clone();
+        let iterations = self.config.frechet_iterations;
+
+        for _ in 0..iterations {
+            // Compute weighted tangent vectors (log map)
+            let mut tangent_sum = vec![0.0f32; mean.dimensionality()];
+
+            for point in points {
+                // Log map: project point onto tangent space at mean
+                // For unit sphere: log_p(q) = θ * (q - (q·p)p) / ||q - (q·p)p||
+                // where θ = arccos(p·q)
+                let dot: f32 = mean.dims().iter()
+                    .zip(point.dims().iter())
+                    .map(|(a, b)| a * b)
+                    .sum();
+
+                // Clamp dot product to valid range for arccos
+                let dot_clamped = dot.clamp(-1.0, 1.0);
+                let theta = dot_clamped.acos();
+
+                if theta.abs() < 1e-8 {
+                    // Points are identical, tangent vector is zero
+                    continue;
+                }
+
+                // Direction in tangent space
+                let mut direction: Vec<f32> = point.dims().iter()
+                    .zip(mean.dims().iter())
+                    .map(|(q, p)| q - dot * p)
+                    .collect();
+
+                // Normalize direction
+                let dir_norm: f32 = direction.iter().map(|x| x * x).sum::<f32>().sqrt();
+                if dir_norm < 1e-8 {
+                    continue;
+                }
+
+                for (i, d) in direction.iter_mut().enumerate() {
+                    tangent_sum[i] += theta * (*d / dir_norm);
+                }
+            }
+
+            // Average tangent vector
+            let n = points.len() as f32;
+            for t in tangent_sum.iter_mut() {
+                *t /= n;
+            }
+
+            // Compute tangent vector magnitude
+            let tangent_norm: f32 = tangent_sum.iter().map(|x| x * x).sum::<f32>().sqrt();
+
+            if tangent_norm < 1e-8 {
+                // Converged
+                break;
+            }
+
+            // Exp map: move along geodesic from mean in tangent direction
+            // For unit sphere: exp_p(v) = cos(||v||)p + sin(||v||)(v/||v||)
+            let cos_t = tangent_norm.cos();
+            let sin_t = tangent_norm.sin();
+
+            let new_dims: Vec<f32> = mean.dims().iter()
+                .zip(tangent_sum.iter())
+                .map(|(p, v)| cos_t * p + sin_t * (v / tangent_norm))
+                .collect();
+
+            mean = Point::new(new_dims);
+        }
+
+        // Ensure result is normalized (on the unit sphere)
+        mean.normalize()
+    }
+
+    /// Update centroid incrementally when adding a child
+    /// Returns the magnitude of the change (for sparse propagation)
+    fn update_centroid(&mut self, container_id: Id, new_point: &Point) -> f32 {
+        let method = self.config.centroid_method;
+
+        // First, extract what we need from the container
+        let (old_centroid, n, accumulated_sum) = {
+            if let Some(container) = self.containers.get(&container_id) {
+                (
+                    container.centroid.clone(),
+                    container.descendant_count as f32,
+                    container.accumulated_sum.clone(),
+                )
+            } else {
+                return 0.0;
+            }
+        };
+
+        // Handle first child case
+        if n == 0.0 {
+            if let Some(container) = self.containers.get_mut(&container_id) {
+                container.centroid = new_point.clone();
+                container.accumulated_sum = Some(new_point.clone());
+                container.descendant_count += 1;
+            }
+            return f32::MAX; // Always propagate first point
+        }
+
+        // Compute new centroid based on method
+        let (new_centroid, new_sum) = match method {
+            CentroidMethod::Euclidean => {
+                // Incremental Euclidean mean using accumulated sum
+                let new_sum = if let Some(ref sum) = accumulated_sum {
+                    sum.dims().iter()
+                        .zip(new_point.dims().iter())
+                        .map(|(s, p)| s + p)
+                        .collect::<Vec<f32>>()
+                } else {
+                    new_point.dims().to_vec()
+                };
+
+                // Compute centroid as normalized mean
+                let count = n + 1.0;
+                let mean_dims: Vec<f32> = new_sum.iter().map(|s| s / count).collect();
+                let centroid = Point::new(mean_dims).normalize();
+                (centroid, Point::new(new_sum))
+            }
+            CentroidMethod::Frechet => {
+                // Update accumulated sum
+                let new_sum = if let Some(ref sum) = accumulated_sum {
+                    sum.dims().iter()
+                        .zip(new_point.dims().iter())
+                        .map(|(s, p)| s + p)
+                        .collect::<Vec<f32>>()
+                } else {
+                    new_point.dims().to_vec()
+                };
+
+                // For incremental Fréchet, use geodesic interpolation
+                let new_count = n + 1.0;
+                let weight = 1.0 / new_count;
+                let centroid = Self::geodesic_interpolate_static(&old_centroid, new_point, weight);
+                (centroid, Point::new(new_sum))
+            }
+        };
+
+        // Now update the container
+        let subspace_enabled = self.config.subspace_enabled;
+        if let Some(container) = self.containers.get_mut(&container_id) {
+            container.centroid = new_centroid.clone();
+            container.accumulated_sum = Some(new_sum);
+            container.descendant_count += 1;
+
+            // Update subspace if enabled, incremental covariance is on, and not a chunk
+            // When incremental_covariance is false (default), we skip the expensive
+            // O(d²) outer product accumulation per insert, deferring to consolidation.
+            if subspace_enabled
+                && self.config.subspace_config.incremental_covariance
+                && container.level != ContainerLevel::Chunk
+            {
+                if let Some(ref mut subspace) = container.subspace {
+                    subspace.add_point(new_point);
+                    // Principal directions recomputed during consolidation
+                }
+            }
+        }
+
+        // Calculate change magnitude (L2 norm of delta)
+        let delta: f32 = old_centroid.dims()
+            .iter()
+            .zip(new_centroid.dims().iter())
+            .map(|(old, new)| (new - old).powi(2))
+            .sum::<f32>()
+            .sqrt();
+
+        delta
+    }
+
+    /// Static version of geodesic interpolation (no self reference needed)
+    fn geodesic_interpolate_static(a: &Point, b: &Point, t: f32) -> Point {
+        // Compute dot product
+        let dot: f32 = a.dims().iter()
+            .zip(b.dims().iter())
+            .map(|(x, y)| x * y)
+            .sum();
+
+        // Clamp to valid range
+        let dot_clamped = dot.clamp(-0.9999, 0.9999);
+        let theta = dot_clamped.acos();
+
+        if theta.abs() < 1e-8 {
+            // Points are nearly identical
+            return a.clone();
+        }
+
+        // Slerp formula: (sin((1-t)θ)/sin(θ)) * a + (sin(tθ)/sin(θ)) * b
+        let sin_theta = theta.sin();
+        let weight_a = ((1.0 - t) * theta).sin() / sin_theta;
+        let weight_b = (t * theta).sin() / sin_theta;
+
+        let result_dims: Vec<f32> = a.dims().iter()
+            .zip(b.dims().iter())
+            .map(|(x, y)| weight_a * x + weight_b * y)
+            .collect();
+
+        Point::new(result_dims).normalize()
+    }
+
+    /// Geodesic interpolation on the unit hypersphere (slerp)
+    /// Returns a point t fraction of the way from a to b along the great circle
+    fn geodesic_interpolate(&self, a: &Point, b: &Point, t: f32) -> Point {
+        // Compute dot product
+        let dot: f32 = a.dims().iter()
+            .zip(b.dims().iter())
+            .map(|(x, y)| x * y)
+            .sum();
+
+        // Clamp to valid range
+        let dot_clamped = dot.clamp(-0.9999, 0.9999);
+        let theta = dot_clamped.acos();
+
+        if theta.abs() < 1e-8 {
+            // Points are nearly identical
+            return a.clone();
+        }
+
+        // Slerp formula: (sin((1-t)θ)/sin(θ)) * a + (sin(tθ)/sin(θ)) * b
+        let sin_theta = theta.sin();
+        let weight_a = ((1.0 - t) * theta).sin() / sin_theta;
+        let weight_b = (t * theta).sin() / sin_theta;
+
+        let result_dims: Vec<f32> = a.dims().iter()
+            .zip(b.dims().iter())
+            .map(|(x, y)| weight_a * x + weight_b * y)
+            .collect();
+
+        Point::new(result_dims).normalize()
+    }
+
+    /// Sparse propagation: only update parent if change exceeds threshold
+    fn propagate_centroid_update(
+        &mut self,
+        container_id: Id,
+        new_point: &Point,
+        ancestors: &[Id],
+    ) {
+        let threshold = self.config.propagation_threshold;
+        let mut delta = self.update_centroid(container_id, new_point);
+
+        // Propagate up the tree if delta exceeds threshold
+        for ancestor_id in ancestors {
+            if delta < threshold {
+                break; // Stop propagation - change too small
+            }
+            delta = self.update_centroid(*ancestor_id, new_point);
+        }
+    }
+
+    /// Search the tree from a starting container
+    fn search_tree(
+        &self,
+        query: &Point,
+        query_time: u64,
+        start_id: Id,
+        k: usize,
+    ) -> Vec<(Id, f32)> {
+        let mut results: Vec<(Id, f32)> = Vec::new();
+
+        // Adaptive beam width based on k
+        let beam_width = self.config.beam_width.max(k);
+
+        // BFS with beam search
+        let mut current_level = vec![start_id];
+
+        while !current_level.is_empty() {
+            let mut next_level: Vec<(Id, f32)> = Vec::new();
+
+            for container_id in &current_level {
+                if let Some(container) = self.containers.get(container_id) {
+                    if container.is_leaf() {
+                        // Leaf node - add to results
+                        let dist = self.combined_distance(query, query_time, container);
+                        results.push((*container_id, dist));
+                    } else {
+                        // Internal node - score children and add to next level
+                        for child_id in &container.children {
+                            if let Some(child) = self.containers.get(child_id) {
+                                let dist = self.combined_distance(query, query_time, child);
+                                next_level.push((*child_id, dist));
+                            }
+                        }
+                    }
+                }
+            }
+
+            if next_level.is_empty() {
+                break;
+            }
+
+            // Sort by distance and take beam_width best
+            next_level.sort_by(|a, b| a.1.partial_cmp(&b.1).unwrap());
+            current_level = next_level
+                .into_iter()
+                .take(beam_width)
+                .map(|(id, _)| id)
+                .collect();
+        }
+
+        // Sort results and return top k
+        results.sort_by(|a, b| a.1.partial_cmp(&b.1).unwrap());
+        results.truncate(k);
+        results
+    }
+
+    // =========================================================================
+    // Multi-Resolution Query API (inspired by VAR next-scale prediction)
+    // =========================================================================
+
+    /// Coarse query: Get session summaries without descending to chunks
+    /// Use this for fast "is there relevant memory?" checks
+    pub fn near_sessions(&self, query: &Point, k: usize) -> NearResult<Vec<SessionSummary>> {
+        if query.dimensionality() != self.dimensionality {
+            return Err(NearError::DimensionalityMismatch {
+                expected: self.dimensionality,
+                got: query.dimensionality(),
+            });
+        }
+
+        let root_id = match self.root_id {
+            Some(id) => id,
+            None => return Ok(vec![]),
+        };
+
+        let query_time = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_millis() as u64;
+
+        // Get root's children (sessions)
+        let root = match self.containers.get(&root_id) {
+            Some(r) => r,
+            None => return Ok(vec![]),
+        };
+
+        let mut sessions: Vec<SessionSummary> = root.children
+            .iter()
+            .filter_map(|session_id| {
+                let session = self.containers.get(session_id)?;
+                if session.level != ContainerLevel::Session {
+                    return None;
+                }
+                let dist = self.combined_distance(query, query_time, session);
+                let score = if self.higher_is_better { 1.0 - dist } else { dist };
+
+                Some(SessionSummary {
+                    id: *session_id,
+                    score,
+                    chunk_count: session.descendant_count,
+                    timestamp: session.timestamp,
+                })
+            })
+            .collect();
+
+        // Sort by score (higher is better)
+        sessions.sort_by(|a, b| b.score.partial_cmp(&a.score).unwrap());
+        sessions.truncate(k);
+
+        Ok(sessions)
+    }
+
+    /// Refine within a specific session: Get document summaries
+    pub fn near_documents(&self, session_id: Id, query: &Point, k: usize) -> NearResult<Vec<DocumentSummary>> {
+        if query.dimensionality() != self.dimensionality {
+            return Err(NearError::DimensionalityMismatch {
+                expected: self.dimensionality,
+                got: query.dimensionality(),
+            });
+        }
+
+        let query_time = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_millis() as u64;
+
+        let session = match self.containers.get(&session_id) {
+            Some(s) => s,
+            None => return Ok(vec![]),
+        };
+
+        let mut documents: Vec<DocumentSummary> = session.children
+            .iter()
+            .filter_map(|doc_id| {
+                let doc = self.containers.get(doc_id)?;
+                if doc.level != ContainerLevel::Document {
+                    return None;
+                }
+                let dist = self.combined_distance(query, query_time, doc);
+                let score = if self.higher_is_better { 1.0 - dist } else { dist };
+
+                Some(DocumentSummary {
+                    id: *doc_id,
+                    score,
+                    chunk_count: doc.descendant_count,
+                    timestamp: doc.timestamp,
+                })
+            })
+            .collect();
+
+        documents.sort_by(|a, b| b.score.partial_cmp(&a.score).unwrap());
+        documents.truncate(k);
+
+        Ok(documents)
+    }
+
+    /// Refine within a specific document: Get chunk results
+    pub fn near_in_document(&self, doc_id: Id, query: &Point, k: usize) -> NearResult<Vec<SearchResult>> {
+        if query.dimensionality() != self.dimensionality {
+            return Err(NearError::DimensionalityMismatch {
+                expected: self.dimensionality,
+                got: query.dimensionality(),
+            });
+        }
+
+        let query_time = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_millis() as u64;
+
+        let doc = match self.containers.get(&doc_id) {
+            Some(d) => d,
+            None => return Ok(vec![]),
+        };
+
+        let mut chunks: Vec<SearchResult> = doc.children
+            .iter()
+            .filter_map(|chunk_id| {
+                let chunk = self.containers.get(chunk_id)?;
+                if chunk.level != ContainerLevel::Chunk {
+                    return None;
+                }
+                let dist = self.combined_distance(query, query_time, chunk);
+                let score = if self.higher_is_better { 1.0 - dist } else { dist };
+
+                Some(SearchResult::new(*chunk_id, score))
+            })
+            .collect();
+
+        chunks.sort_by(|a, b| b.score.partial_cmp(&a.score).unwrap());
+        chunks.truncate(k);
+
+        Ok(chunks)
+    }
+
+    /// Get statistics about the tree structure
+    pub fn stats(&self) -> HatStats {
+        let mut stats = HatStats::default();
+
+        for container in self.containers.values() {
+            match container.level {
+                ContainerLevel::Global => stats.global_count += 1,
+                ContainerLevel::Session => stats.session_count += 1,
+                ContainerLevel::Document => stats.document_count += 1,
+                ContainerLevel::Chunk => stats.chunk_count += 1,
+            }
+        }
+
+        stats
+    }
+
+    // =========================================================================
+    // Learnable Routing API
+    // =========================================================================
+
+    /// Record positive feedback for a query result (successful retrieval)
+    ///
+    /// Call this when a retrieved result was useful/relevant.
+    /// The router learns to route similar queries to similar containers.
+    pub fn record_retrieval_success(&mut self, query: &Point, result_id: Id) {
+        if let Some(ref mut router) = self.learnable_router {
+            // Find the container for this result and record feedback for each level
+            if let Some(container) = self.containers.get(&result_id) {
+                router.record_success(query, &container.centroid, container.level.depth());
+            }
+        }
+    }
+
+    /// Record negative feedback for a query result (unsuccessful retrieval)
+    ///
+    /// Call this when a retrieved result was not useful/relevant.
+    pub fn record_retrieval_failure(&mut self, query: &Point, result_id: Id) {
+        if let Some(ref mut router) = self.learnable_router {
+            if let Some(container) = self.containers.get(&result_id) {
+                router.record_failure(query, &container.centroid, container.level.depth());
+            }
+        }
+    }
+
+    /// Record implicit feedback with a relevance score (0.0 = irrelevant, 1.0 = highly relevant)
+    ///
+    /// Use this for continuous feedback signals like click-through rate, dwell time, etc.
+    pub fn record_implicit_feedback(&mut self, query: &Point, result_id: Id, relevance: f32) {
+        if let Some(ref mut router) = self.learnable_router {
+            if let Some(container) = self.containers.get(&result_id) {
+                router.record_implicit(query, &container.centroid, container.level.depth(), relevance);
+            }
+        }
+    }
+
+    /// Get learnable router statistics (if enabled)
+    pub fn router_stats(&self) -> Option<super::learnable_routing::RouterStats> {
+        self.learnable_router.as_ref().map(|r| r.stats())
+    }
+
+    /// Get current routing weights (if learnable routing is enabled)
+    pub fn routing_weights(&self) -> Option<&[f32]> {
+        self.learnable_router.as_ref().map(|r| r.weights())
+    }
+
+    /// Reset learnable routing weights to uniform
+    pub fn reset_routing_weights(&mut self) {
+        if let Some(ref mut router) = self.learnable_router {
+            router.reset_weights();
+        }
+    }
+
+    /// Check if learnable routing is enabled
+    pub fn is_learnable_routing_enabled(&self) -> bool {
+        self.learnable_router.is_some()
+    }
+}
+
+/// Statistics about the HAT tree structure
+#[derive(Debug, Clone, Default)]
+pub struct HatStats {
+    pub global_count: usize,
+    pub session_count: usize,
+    pub document_count: usize,
+    pub chunk_count: usize,
+}
+
+impl Near for HatIndex {
+    fn near(&self, query: &Point, k: usize) -> NearResult<Vec<SearchResult>> {
+        // Check dimensionality
+        if query.dimensionality() != self.dimensionality {
+            return Err(NearError::DimensionalityMismatch {
+                expected: self.dimensionality,
+                got: query.dimensionality(),
+            });
+        }
+
+        // Handle empty index
+        let root_id = match self.root_id {
+            Some(id) => id,
+            None => return Ok(vec![]),
+        };
+
+        // Current time for temporal scoring
+        let query_time = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_millis() as u64;
+
+        // Search tree
+        let results = self.search_tree(query, query_time, root_id, k);
+
+        // Convert to SearchResult
+        let search_results: Vec<SearchResult> = results
+            .into_iter()
+            .map(|(id, dist)| {
+                let score = if self.higher_is_better {
+                    1.0 - dist
+                } else {
+                    dist
+                };
+                SearchResult::new(id, score)
+            })
+            .collect();
+
+        Ok(search_results)
+    }
+
+    fn within(&self, query: &Point, threshold: f32) -> NearResult<Vec<SearchResult>> {
+        // Check dimensionality
+        if query.dimensionality() != self.dimensionality {
+            return Err(NearError::DimensionalityMismatch {
+                expected: self.dimensionality,
+                got: query.dimensionality(),
+            });
+        }
+
+        // Use near with all points, then filter
+        let all_results = self.near(query, self.containers.len())?;
+
+        let filtered: Vec<SearchResult> = all_results
+            .into_iter()
+            .filter(|r| {
+                if self.higher_is_better {
+                    r.score >= threshold
+                } else {
+                    r.score <= threshold
+                }
+            })
+            .collect();
+
+        Ok(filtered)
+    }
+
+    fn add(&mut self, id: Id, point: &Point) -> NearResult<()> {
+        // Check dimensionality
+        if point.dimensionality() != self.dimensionality {
+            return Err(NearError::DimensionalityMismatch {
+                expected: self.dimensionality,
+                got: point.dimensionality(),
+            });
+        }
+
+        // Ensure hierarchy exists
+        self.ensure_document();
+
+        // Create chunk container
+        let chunk = Container::new(id, ContainerLevel::Chunk, point.clone());
+        self.containers.insert(id, chunk);
+
+        // Add to document's children
+        if let Some(doc_id) = self.active_document {
+            if let Some(doc) = self.containers.get_mut(&doc_id) {
+                doc.children.push(id);
+            }
+
+            // Build ancestor chain for sparse propagation
+            let mut ancestors = Vec::new();
+            if let Some(session_id) = self.active_session {
+                ancestors.push(session_id);
+                if let Some(root_id) = self.root_id {
+                    ancestors.push(root_id);
+                }
+            }
+
+            // Sparse propagation: only update ancestors if change is significant
+            self.propagate_centroid_update(doc_id, point, &ancestors);
+        }
+
+        // Check if document needs splitting
+        if let Some(doc_id) = self.active_document {
+            if let Some(doc) = self.containers.get(&doc_id) {
+                if doc.children.len() >= self.config.max_children {
+                    // Start a new document
+                    self.new_document();
+                }
+            }
+        }
+
+        // Check if session needs splitting
+        if let Some(session_id) = self.active_session {
+            if let Some(session) = self.containers.get(&session_id) {
+                if session.children.len() >= self.config.max_children {
+                    // Start a new session
+                    self.new_session();
+                }
+            }
+        }
+
+        Ok(())
+    }
+
+    fn remove(&mut self, id: Id) -> NearResult<()> {
+        // Remove the chunk
+        self.containers.remove(&id);
+
+        // Note: We don't update centroids on remove for simplicity
+        // A production implementation would need to handle this
+
+        Ok(())
+    }
+
+    fn rebuild(&mut self) -> NearResult<()> {
+        // Recalculate all centroids from scratch
+        // For now, this is a no-op since we maintain incrementally
+        Ok(())
+    }
+
+    fn is_ready(&self) -> bool {
+        true
+    }
+
+    fn len(&self) -> usize {
+        // Count only chunk-level containers
+        self.containers.values()
+            .filter(|c| c.level == ContainerLevel::Chunk)
+            .count()
+    }
+}
+
+// =============================================================================
+// Consolidation Implementation
+// =============================================================================
+
+impl HatIndex {
+    /// Collect all leaf points for a container (recursively)
+    fn collect_leaf_points(&self, container_id: Id) -> Vec<Point> {
+        let container = match self.containers.get(&container_id) {
+            Some(c) => c,
+            None => return vec![],
+        };
+
+        if container.is_leaf() {
+            return vec![container.centroid.clone()];
+        }
+
+        let mut points = Vec::new();
+        for child_id in &container.children {
+            points.extend(self.collect_leaf_points(*child_id));
+        }
+        points
+    }
+
+    /// Get all container IDs at a given level
+    fn containers_at_level(&self, level: ContainerLevel) -> Vec<Id> {
+        self.containers
+            .iter()
+            .filter(|(_, c)| c.level == level)
+            .map(|(id, _)| *id)
+            .collect()
+    }
+
+    /// Recompute a container's centroid from its descendants
+    fn recompute_centroid(&mut self, container_id: Id) -> Option<f32> {
+        // First collect the points (need to release borrow)
+        let points = self.collect_leaf_points(container_id);
+
+        if points.is_empty() {
+            return None;
+        }
+
+        let new_centroid = match compute_exact_centroid(&points) {
+            Some(c) => c,
+            None => return None,
+        };
+
+        // Get subspace config for recomputation
+        let subspace_enabled = self.config.subspace_enabled;
+        let subspace_rank = self.config.subspace_config.rank;
+
+        // Now update the container
+        let drift = if let Some(container) = self.containers.get_mut(&container_id) {
+            let old_centroid = container.centroid.clone();
+            let drift = centroid_drift(&old_centroid, &new_centroid);
+            container.centroid = new_centroid;
+            container.descendant_count = points.len();
+
+            // Update accumulated sum
+            let sum: Vec<f32> = points.iter()
+                .fold(vec![0.0f32; self.dimensionality], |mut acc, p| {
+                    for (i, &v) in p.dims().iter().enumerate() {
+                        acc[i] += v;
+                    }
+                    acc
+                });
+            container.accumulated_sum = Some(Point::new(sum));
+
+            // Recompute subspace during consolidation if enabled
+            if subspace_enabled && container.level != ContainerLevel::Chunk {
+                let mut subspace = super::subspace::Subspace::new(self.dimensionality);
+                for point in &points {
+                    subspace.add_point(point);
+                }
+                subspace.recompute_subspace(subspace_rank);
+                container.subspace = Some(subspace);
+            }
+
+            Some(drift)
+        } else {
+            None
+        };
+
+        drift
+    }
+
+    /// Check if a container should be merged (too few children)
+    fn should_merge(&self, container_id: Id, threshold: usize) -> bool {
+        if let Some(container) = self.containers.get(&container_id) {
+            // Don't merge chunks, root, or sessions (for now)
+            if container.level == ContainerLevel::Chunk ||
+               container.level == ContainerLevel::Global ||
+               container.level == ContainerLevel::Session {
+                return false;
+            }
+            container.children.len() < threshold
+        } else {
+            false
+        }
+    }
+
+    /// Check if a container should be split (too many children)
+    fn should_split(&self, container_id: Id, threshold: usize) -> bool {
+        if let Some(container) = self.containers.get(&container_id) {
+            // Don't split chunks
+            if container.level == ContainerLevel::Chunk {
+                return false;
+            }
+            container.children.len() > threshold
+        } else {
+            false
+        }
+    }
+
+    /// Find a sibling container to merge with
+    fn find_merge_sibling(&self, container_id: Id) -> Option<Id> {
+        // Find parent
+        let parent_id = self.containers.iter()
+            .find(|(_, c)| c.children.contains(&container_id))
+            .map(|(id, _)| *id)?;
+
+        let parent = self.containers.get(&parent_id)?;
+
+        // Find smallest sibling
+        let mut smallest: Option<(Id, usize)> = None;
+        for child_id in &parent.children {
+            if *child_id == container_id {
+                continue;
+            }
+            if let Some(child) = self.containers.get(child_id) {
+                let size = child.children.len();
+                if smallest.is_none() || size < smallest.unwrap().1 {
+                    smallest = Some((*child_id, size));
+                }
+            }
+        }
+
+        smallest.map(|(id, _)| id)
+    }
+
+    /// Merge container B into container A
+    fn merge_containers(&mut self, a_id: Id, b_id: Id) {
+        // Get children from B
+        let b_children: Vec<Id> = if let Some(b) = self.containers.get(&b_id) {
+            b.children.clone()
+        } else {
+            return;
+        };
+
+        // Add children to A
+        if let Some(a) = self.containers.get_mut(&a_id) {
+            a.children.extend(b_children);
+        }
+
+        // Remove B from its parent's children
+        let parent_id = self.containers.iter()
+            .find(|(_, c)| c.children.contains(&b_id))
+            .map(|(id, _)| *id);
+
+        if let Some(pid) = parent_id {
+            if let Some(parent) = self.containers.get_mut(&pid) {
+                parent.children.retain(|id| *id != b_id);
+            }
+        }
+
+        // Remove B
+        self.containers.remove(&b_id);
+
+        // Recompute A's centroid
+        self.recompute_centroid(a_id);
+    }
+
+    /// Split a container into two
+    fn split_container(&mut self, container_id: Id) -> Option<Id> {
+        // Get container info
+        let (level, children, parent_id) = {
+            let container = self.containers.get(&container_id)?;
+            let parent_id = self.containers.iter()
+                .find(|(_, c)| c.children.contains(&container_id))
+                .map(|(id, _)| *id);
+            (container.level, container.children.clone(), parent_id)
+        };
+
+        if children.len() < 2 {
+            return None;
+        }
+
+        // Simple split: divide children in half
+        let mid = children.len() / 2;
+        let (keep, move_to_new) = children.split_at(mid);
+
+        // Create new container
+        let new_id = Id::now();
+        let new_container = Container::new(
+            new_id,
+            level,
+            Point::origin(self.dimensionality),
+        );
+        self.containers.insert(new_id, new_container);
+
+        // Update original container
+        if let Some(container) = self.containers.get_mut(&container_id) {
+            container.children = keep.to_vec();
+        }
+
+        // Set new container's children
+        if let Some(new_container) = self.containers.get_mut(&new_id) {
+            new_container.children = move_to_new.to_vec();
+        }
+
+        // Add new container to parent
+        if let Some(pid) = parent_id {
+            if let Some(parent) = self.containers.get_mut(&pid) {
+                parent.children.push(new_id);
+            }
+        }
+
+        // Recompute centroids
+        self.recompute_centroid(container_id);
+        self.recompute_centroid(new_id);
+
+        Some(new_id)
+    }
+
+    /// Remove containers with no children (except chunks)
+    fn prune_empty(&mut self) -> usize {
+        let mut pruned = 0;
+
+        loop {
+            let empty_ids: Vec<Id> = self.containers
+                .iter()
+                .filter(|(_, c)| {
+                    c.level != ContainerLevel::Chunk &&
+                    c.level != ContainerLevel::Global &&
+                    c.children.is_empty()
+                })
+                .map(|(id, _)| *id)
+                .collect();
+
+            if empty_ids.is_empty() {
+                break;
+            }
+
+            for id in empty_ids {
+                // Remove from parent's children
+                let parent_id = self.containers.iter()
+                    .find(|(_, c)| c.children.contains(&id))
+                    .map(|(pid, _)| *pid);
+
+                if let Some(pid) = parent_id {
+                    if let Some(parent) = self.containers.get_mut(&pid) {
+                        parent.children.retain(|cid| *cid != id);
+                    }
+                }
+
+                self.containers.remove(&id);
+                pruned += 1;
+            }
+        }
+
+        pruned
+    }
+}
+
+impl Consolidate for HatIndex {
+    fn begin_consolidation(&mut self, config: ConsolidationConfig) {
+        let mut state = ConsolidationState::new(config);
+        state.start();
+
+        // Initialize work queue with all containers for leaf collection
+        let all_ids: VecDeque<Id> = self.containers.keys().copied().collect();
+        state.work_queue = all_ids;
+
+        self.consolidation_state = Some(state);
+        self.consolidation_points_cache.clear();
+    }
+
+    fn consolidation_tick(&mut self) -> ConsolidationTickResult {
+        // Take ownership of state to avoid borrow issues
+        let mut state = match self.consolidation_state.take() {
+            Some(s) => s,
+            None => {
+                return ConsolidationTickResult::Complete(ConsolidationMetrics::default());
+            }
+        };
+
+        let batch_size = state.config.batch_size;
+
+        match state.phase {
+            ConsolidationPhase::Idle => {
+                state.start();
+            }
+
+            ConsolidationPhase::CollectingLeaves => {
+                state.next_phase();
+
+                // Populate work queue with non-chunk containers (bottom-up)
+                let docs = self.containers_at_level(ContainerLevel::Document);
+                let sessions = self.containers_at_level(ContainerLevel::Session);
+                let globals = self.containers_at_level(ContainerLevel::Global);
+
+                state.work_queue.clear();
+                state.work_queue.extend(docs);
+                state.work_queue.extend(sessions);
+                state.work_queue.extend(globals);
+            }
+
+            ConsolidationPhase::RecomputingCentroids => {
+                let mut processed = 0;
+                let mut to_recompute = Vec::new();
+
+                while processed < batch_size {
+                    match state.work_queue.pop_front() {
+                        Some(id) => {
+                            to_recompute.push(id);
+                            state.processed.insert(id);
+                            processed += 1;
+                        }
+                        None => break,
+                    };
+                }
+
+                // Now recompute without holding state borrow
+                for container_id in to_recompute {
+                    if let Some(drift) = self.recompute_centroid(container_id) {
+                        state.record_drift(drift);
+                        state.metrics.centroids_recomputed += 1;
+                    }
+                    state.metrics.containers_processed += 1;
+                }
+
+                if state.work_queue.is_empty() {
+                    state.next_phase();
+
+                    if state.phase == ConsolidationPhase::AnalyzingStructure {
+                        let docs = self.containers_at_level(ContainerLevel::Document);
+                        state.work_queue.extend(docs);
+                    }
+                }
+            }
+
+            ConsolidationPhase::AnalyzingStructure => {
+                let merge_threshold = state.config.merge_threshold;
+                let split_threshold = state.config.split_threshold;
+                let mut processed = 0;
+                let mut to_analyze = Vec::new();
+
+                while processed < batch_size {
+                    match state.work_queue.pop_front() {
+                        Some(id) => {
+                            to_analyze.push(id);
+                            state.processed.insert(id);
+                            processed += 1;
+                        }
+                        None => break,
+                    };
+                }
+
+                // Analyze without holding state borrow
+                for container_id in to_analyze {
+                    if self.should_merge(container_id, merge_threshold) {
+                        if let Some(sibling) = self.find_merge_sibling(container_id) {
+                            state.add_merge_candidate(container_id, sibling);
+                        }
+                    } else if self.should_split(container_id, split_threshold) {
+                        state.add_split_candidate(container_id);
+                    }
+                }
+
+                if state.work_queue.is_empty() {
+                    state.next_phase();
+                }
+            }
+
+            ConsolidationPhase::Merging => {
+                let mut processed = 0;
+                let mut to_merge = Vec::new();
+
+                while processed < batch_size {
+                    match state.next_merge() {
+                        Some(pair) => {
+                            to_merge.push(pair);
+                            processed += 1;
+                        }
+                        None => break,
+                    };
+                }
+
+                for (a, b) in to_merge {
+                    self.merge_containers(a, b);
+                    state.metrics.containers_merged += 1;
+                }
+
+                if !state.has_merges() {
+                    state.next_phase();
+                }
+            }
+
+            ConsolidationPhase::Splitting => {
+                let mut processed = 0;
+                let mut to_split = Vec::new();
+
+                while processed < batch_size {
+                    match state.next_split() {
+                        Some(id) => {
+                            to_split.push(id);
+                            processed += 1;
+                        }
+                        None => break,
+                    };
+                }
+
+                for container_id in to_split {
+                    if self.split_container(container_id).is_some() {
+                        state.metrics.containers_split += 1;
+                    }
+                }
+
+                if !state.has_splits() {
+                    state.next_phase();
+                }
+            }
+
+            ConsolidationPhase::Pruning => {
+                let pruned = self.prune_empty();
+                state.metrics.containers_pruned = pruned;
+                state.next_phase();
+            }
+
+            ConsolidationPhase::OptimizingLayout => {
+                for container in self.containers.values_mut() {
+                    if container.children.len() > 1 {
+                        // Placeholder for future optimization
+                    }
+                }
+                state.next_phase();
+            }
+
+            ConsolidationPhase::Complete => {
+                // Already complete
+            }
+        }
+
+        state.metrics.ticks += 1;
+
+        if state.is_complete() {
+            let metrics = state.metrics.clone();
+            self.consolidation_points_cache.clear();
+            ConsolidationTickResult::Complete(metrics)
+        } else {
+            let progress = state.progress();
+            self.consolidation_state = Some(state);
+            ConsolidationTickResult::Continue(progress)
+        }
+    }
+
+    fn is_consolidating(&self) -> bool {
+        self.consolidation_state.is_some()
+    }
+
+    fn consolidation_progress(&self) -> Option<ConsolidationProgress> {
+        self.consolidation_state.as_ref().map(|s| s.progress())
+    }
+
+    fn cancel_consolidation(&mut self) {
+        self.consolidation_state = None;
+        self.consolidation_points_cache.clear();
+    }
+}
+
+// =============================================================================
+// Persistence Implementation
+// =============================================================================
+
+impl HatIndex {
+    /// Serialize the index to bytes
+    ///
+    /// # Example
+    /// ```rust,ignore
+    /// let bytes = hat.to_bytes()?;
+    /// std::fs::write("index.hat", bytes)?;
+    /// ```
+    pub fn to_bytes(&self) -> Result<Vec<u8>, super::persistence::PersistError> {
+        use super::persistence::{SerializedHat, SerializedContainer, LevelByte};
+
+        let containers: Vec<SerializedContainer> = self.containers.iter()
+            .map(|(_, c)| {
+                let level = match c.level {
+                    ContainerLevel::Global => LevelByte::Root,
+                    ContainerLevel::Session => LevelByte::Session,
+                    ContainerLevel::Document => LevelByte::Document,
+                    ContainerLevel::Chunk => LevelByte::Chunk,
+                };
+
+                SerializedContainer {
+                    id: c.id,
+                    level,
+                    timestamp: c.timestamp,
+                    children: c.children.clone(),
+                    descendant_count: c.descendant_count as u64,
+                    centroid: c.centroid.dims().to_vec(),
+                    accumulated_sum: c.accumulated_sum.as_ref().map(|p| p.dims().to_vec()),
+                }
+            })
+            .collect();
+
+        let router_weights = self.learnable_router.as_ref()
+            .map(|r| r.weights().to_vec());
+
+        let serialized = SerializedHat {
+            version: 1,
+            dimensionality: self.dimensionality as u32,
+            root_id: self.root_id,
+            containers,
+            active_session: self.active_session,
+            active_document: self.active_document,
+            router_weights,
+        };
+
+        serialized.to_bytes()
+    }
+
+    /// Deserialize an index from bytes
+    ///
+    /// # Example
+    /// ```rust,ignore
+    /// let bytes = std::fs::read("index.hat")?;
+    /// let hat = HatIndex::from_bytes(&bytes)?;
+    /// ```
+    pub fn from_bytes(data: &[u8]) -> Result<Self, super::persistence::PersistError> {
+        use super::persistence::{SerializedHat, LevelByte, PersistError};
+        use crate::core::proximity::Cosine;
+        use crate::core::merge::Mean;
+
+        let serialized = SerializedHat::from_bytes(data)?;
+        let dimensionality = serialized.dimensionality as usize;
+
+        // Create a new index with default settings
+        let mut index = Self::new(
+            dimensionality,
+            Arc::new(Cosine),
+            Arc::new(Mean),
+            true,
+            HatConfig::default(),
+        );
+
+        // Restore containers
+        for sc in serialized.containers {
+            let level = match sc.level {
+                LevelByte::Root => ContainerLevel::Global,
+                LevelByte::Session => ContainerLevel::Session,
+                LevelByte::Document => ContainerLevel::Document,
+                LevelByte::Chunk => ContainerLevel::Chunk,
+            };
+
+            // Verify dimension
+            if sc.centroid.len() != dimensionality {
+                return Err(PersistError::DimensionMismatch {
+                    expected: dimensionality,
+                    found: sc.centroid.len(),
+                });
+            }
+
+            let centroid = Point::new(sc.centroid);
+            let accumulated_sum = sc.accumulated_sum.map(Point::new);
+
+            let container = Container {
+                id: sc.id,
+                level,
+                centroid,
+                timestamp: sc.timestamp,
+                children: sc.children,
+                descendant_count: sc.descendant_count as usize,
+                accumulated_sum,
+                subspace: if level != ContainerLevel::Chunk {
+                    Some(super::subspace::Subspace::new(dimensionality))
+                } else {
+                    None
+                },
+            };
+
+            index.containers.insert(sc.id, container);
+        }
+
+        // Restore state
+        index.root_id = serialized.root_id;
+        index.active_session = serialized.active_session;
+        index.active_document = serialized.active_document;
+
+        // Restore router weights if present
+        if let Some(weights) = serialized.router_weights {
+            let mut router = super::learnable_routing::LearnableRouter::default_for_dims(dimensionality);
+            let weight_bytes: Vec<u8> = weights.iter()
+                .flat_map(|w| w.to_le_bytes())
+                .collect();
+            router.deserialize_weights(&weight_bytes)
+                .map_err(|e| PersistError::Corrupted(e.to_string()))?;
+            index.learnable_router = Some(router);
+        }
+
+        Ok(index)
+    }
+
+    /// Save the index to a file
+    pub fn save_to_file(&self, path: &std::path::Path) -> Result<(), super::persistence::PersistError> {
+        let bytes = self.to_bytes()?;
+        std::fs::write(path, bytes)?;
+        Ok(())
+    }
+
+    /// Load an index from a file
+    pub fn load_from_file(path: &std::path::Path) -> Result<Self, super::persistence::PersistError> {
+        let bytes = std::fs::read(path)?;
+        Self::from_bytes(&bytes)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_hat_add() {
+        let mut index = HatIndex::cosine(3);
+
+        let id = Id::now();
+        let point = Point::new(vec![1.0, 0.0, 0.0]);
+
+        index.add(id, &point).unwrap();
+
+        assert_eq!(index.len(), 1);
+    }
+
+    #[test]
+    fn test_hat_near() {
+        let mut index = HatIndex::cosine(3);
+
+        // Add some points
+        let points = vec![
+            Point::new(vec![1.0, 0.0, 0.0]),
+            Point::new(vec![0.0, 1.0, 0.0]),
+            Point::new(vec![0.0, 0.0, 1.0]),
+            Point::new(vec![0.7, 0.7, 0.0]).normalize(),
+        ];
+
+        for point in &points {
+            index.add(Id::now(), point).unwrap();
+        }
+
+        // Query near [1, 0, 0]
+        let query = Point::new(vec![1.0, 0.0, 0.0]);
+        let results = index.near(&query, 2).unwrap();
+
+        assert_eq!(results.len(), 2);
+        // First result should have high similarity (close to 1.0)
+        assert!(results[0].score > 0.5);
+    }
+
+    #[test]
+    fn test_hat_sessions() {
+        let mut index = HatIndex::cosine(3);
+
+        // Add points to first session
+        for i in 0..5 {
+            let point = Point::new(vec![1.0, i as f32 * 0.1, 0.0]).normalize();
+            index.add(Id::now(), &point).unwrap();
+        }
+
+        // Start new session
+        index.new_session();
+
+        // Add points to second session
+        for i in 0..5 {
+            let point = Point::new(vec![0.0, 1.0, i as f32 * 0.1]).normalize();
+            index.add(Id::now(), &point).unwrap();
+        }
+
+        assert_eq!(index.len(), 10);
+
+        // Query should find both sessions
+        let query = Point::new(vec![0.5, 0.5, 0.0]).normalize();
+        let results = index.near(&query, 5).unwrap();
+
+        assert_eq!(results.len(), 5);
+    }
+
+    #[test]
+    fn test_hat_hierarchy_structure() {
+        let mut index = HatIndex::cosine(3);
+
+        // Add some points
+        for _ in 0..10 {
+            let point = Point::new(vec![1.0, 0.0, 0.0]);
+            index.add(Id::now(), &point).unwrap();
+        }
+
+        // Should have: 1 root + 1 session + 1 document + 10 chunks = 13 containers
+        assert!(index.containers.len() >= 13);
+
+        // Check that root exists
+        assert!(index.root_id.is_some());
+    }
+
+    #[test]
+    fn test_hat_empty() {
+        let index = HatIndex::cosine(3);
+
+        let query = Point::new(vec![1.0, 0.0, 0.0]);
+        let results = index.near(&query, 5).unwrap();
+
+        assert!(results.is_empty());
+    }
+
+    #[test]
+    fn test_hat_dimensionality_check() {
+        let mut index = HatIndex::cosine(3);
+
+        let wrong_dims = Point::new(vec![1.0, 0.0]); // 2 dims
+        let result = index.add(Id::now(), &wrong_dims);
+
+        match result {
+            Err(NearError::DimensionalityMismatch { expected, got }) => {
+                assert_eq!(expected, 3);
+                assert_eq!(got, 2);
+            }
+            _ => panic!("Expected DimensionalityMismatch error"),
+        }
+    }
+
+    #[test]
+    fn test_hat_scale() {
+        let mut index = HatIndex::cosine(128);
+
+        // Add 1000 points
+        for i in 0..1000 {
+            let mut dims = vec![0.0f32; 128];
+            dims[i % 128] = 1.0;
+            let point = Point::new(dims).normalize();
+            index.add(Id::now(), &point).unwrap();
+        }
+
+        assert_eq!(index.len(), 1000);
+
+        // Query should work
+        let query = Point::new(vec![1.0; 128]).normalize();
+        let results = index.near(&query, 10).unwrap();
+
+        assert_eq!(results.len(), 10);
+    }
+}

src/adapters/index/learnable_routing.rs

@@ -0,0 +1,528 @@
+//! # Learnable Routing for HAT
+//!
+//! This module implements learnable routing weights for HAT index.
+//! Instead of using fixed cosine similarity for routing decisions,
+//! we learn dimension weights that adapt to actual query patterns.
+//!
+//! ## Key Insight (from journal 006)
+//!
+//! "The main gap: ARMS uses *known* structure while cutting-edge methods
+//! *learn* structure. Opportunity: make HAT structure learnable while
+//! keeping the efficiency benefits."
+//!
+//! ## Approach
+//!
+//! 1. **Weighted Similarity**: `sim(q, c) = Σᵢ wᵢ · qᵢ · cᵢ` instead of plain cosine
+//! 2. **Feedback Collection**: Track query → retrieved → relevant mappings
+//! 3. **Online Learning**: Update weights to improve routing decisions
+//!
+//! ## Benefits
+//!
+//! - Adapts to task-specific semantic dimensions
+//! - No neural network training required (gradient-free)
+//! - Preserves O(log n) query complexity
+//! - Can learn from implicit feedback (click-through, usage patterns)
+
+use crate::core::Point;
+use std::collections::VecDeque;
+
+/// Configuration for learnable routing
+#[derive(Debug, Clone)]
+pub struct LearnableRoutingConfig {
+    /// Learning rate for weight updates (0.0 = no learning)
+    pub learning_rate: f32,
+
+    /// Momentum for smoothing updates
+    pub momentum: f32,
+
+    /// Weight decay for regularization (prevents overfitting)
+    pub weight_decay: f32,
+
+    /// Maximum number of feedback samples to retain
+    pub max_feedback_samples: usize,
+
+    /// Minimum feedback samples before learning starts
+    pub min_samples_to_learn: usize,
+
+    /// How often to update weights (every N feedback samples)
+    pub update_frequency: usize,
+
+    /// Enable dimension-wise weights (vs single scalar)
+    pub per_dimension_weights: bool,
+}
+
+impl Default for LearnableRoutingConfig {
+    fn default() -> Self {
+        Self {
+            learning_rate: 0.01,
+            momentum: 0.9,
+            weight_decay: 0.001,
+            max_feedback_samples: 1000,
+            min_samples_to_learn: 50,
+            update_frequency: 10,
+            per_dimension_weights: true,
+        }
+    }
+}
+
+impl LearnableRoutingConfig {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    pub fn with_learning_rate(mut self, lr: f32) -> Self {
+        self.learning_rate = lr;
+        self
+    }
+
+    pub fn with_momentum(mut self, momentum: f32) -> Self {
+        self.momentum = momentum.clamp(0.0, 0.99);
+        self
+    }
+
+    pub fn disabled() -> Self {
+        Self {
+            learning_rate: 0.0,
+            ..Default::default()
+        }
+    }
+}
+
+/// A single feedback sample from query execution
+#[derive(Debug, Clone)]
+pub struct RoutingFeedback {
+    /// The query point
+    pub query: Point,
+
+    /// Container centroid that was selected
+    pub selected_centroid: Point,
+
+    /// Whether the selection led to good results (positive = good)
+    pub reward: f32,
+
+    /// Which level in the hierarchy this feedback is for
+    pub level: usize,
+}
+
+/// Learnable routing weights for HAT
+///
+/// Maintains per-dimension (or scalar) weights that modify
+/// the similarity computation during tree traversal.
+#[derive(Debug, Clone)]
+pub struct LearnableRouter {
+    /// Configuration
+    config: LearnableRoutingConfig,
+
+    /// Per-dimension weights (or single weight if per_dimension_weights=false)
+    weights: Vec<f32>,
+
+    /// Momentum accumulator for smooth updates
+    momentum_buffer: Vec<f32>,
+
+    /// Feedback buffer for batch updates
+    feedback_buffer: VecDeque<RoutingFeedback>,
+
+    /// Total feedback samples received
+    total_samples: usize,
+
+    /// Dimensionality
+    dims: usize,
+}
+
+impl LearnableRouter {
+    /// Create a new learnable router
+    pub fn new(dims: usize, config: LearnableRoutingConfig) -> Self {
+        let weight_count = if config.per_dimension_weights { dims } else { 1 };
+
+        Self {
+            config,
+            weights: vec![1.0; weight_count],  // Start with uniform weights
+            momentum_buffer: vec![0.0; weight_count],
+            feedback_buffer: VecDeque::new(),
+            total_samples: 0,
+            dims,
+        }
+    }
+
+    /// Create with default config
+    pub fn default_for_dims(dims: usize) -> Self {
+        Self::new(dims, LearnableRoutingConfig::default())
+    }
+
+    /// Check if learning is enabled
+    pub fn is_learning_enabled(&self) -> bool {
+        self.config.learning_rate > 0.0
+    }
+
+    /// Get current weights (for inspection/serialization)
+    pub fn weights(&self) -> &[f32] {
+        &self.weights
+    }
+
+    /// Compute weighted similarity between query and centroid
+    ///
+    /// Returns a similarity score (higher = more similar)
+    pub fn weighted_similarity(&self, query: &Point, centroid: &Point) -> f32 {
+        if self.config.per_dimension_weights {
+            // Weighted dot product: Σᵢ wᵢ · qᵢ · cᵢ
+            query.dims().iter()
+                .zip(centroid.dims().iter())
+                .zip(self.weights.iter())
+                .map(|((q, c), w)| w * q * c)
+                .sum()
+        } else {
+            // Single scalar weight (equivalent to scaled cosine)
+            let dot: f32 = query.dims().iter()
+                .zip(centroid.dims().iter())
+                .map(|(q, c)| q * c)
+                .sum();
+            self.weights[0] * dot
+        }
+    }
+
+    /// Record feedback from a routing decision
+    pub fn record_feedback(&mut self, feedback: RoutingFeedback) {
+        self.feedback_buffer.push_back(feedback);
+        self.total_samples += 1;
+
+        // Trim buffer if too large
+        while self.feedback_buffer.len() > self.config.max_feedback_samples {
+            self.feedback_buffer.pop_front();
+        }
+
+        // Trigger update if conditions met
+        if self.should_update() {
+            self.update_weights();
+        }
+    }
+
+    /// Check if we should update weights
+    fn should_update(&self) -> bool {
+        self.config.learning_rate > 0.0
+            && self.feedback_buffer.len() >= self.config.min_samples_to_learn
+            && self.total_samples % self.config.update_frequency == 0
+    }
+
+    /// Update weights based on accumulated feedback
+    ///
+    /// Uses a simple gradient-free approach:
+    /// - For positive feedback: increase weights for dimensions where q·c was high
+    /// - For negative feedback: decrease weights for dimensions where q·c was high
+    fn update_weights(&mut self) {
+        if self.feedback_buffer.is_empty() {
+            return;
+        }
+
+        let lr = self.config.learning_rate;
+        let momentum = self.config.momentum;
+        let decay = self.config.weight_decay;
+
+        // Compute gradient estimate from feedback
+        let mut gradient = vec![0.0f32; self.weights.len()];
+
+        for feedback in &self.feedback_buffer {
+            let reward = feedback.reward;
+
+            if self.config.per_dimension_weights {
+                // Per-dimension update
+                for ((&q, &c), g) in feedback.query.dims().iter()
+                    .zip(feedback.selected_centroid.dims().iter())
+                    .zip(gradient.iter_mut())
+                {
+                    // Gradient: reward * q * c (increase weight if positive reward)
+                    *g += reward * q * c;
+                }
+            } else {
+                // Scalar update
+                let dot: f32 = feedback.query.dims().iter()
+                    .zip(feedback.selected_centroid.dims().iter())
+                    .map(|(q, c)| q * c)
+                    .sum();
+                gradient[0] += reward * dot;
+            }
+        }
+
+        // Normalize by number of samples
+        let n = self.feedback_buffer.len() as f32;
+        for g in gradient.iter_mut() {
+            *g /= n;
+        }
+
+        // Apply momentum and update weights
+        for (i, (w, g)) in self.weights.iter_mut().zip(gradient.iter()).enumerate() {
+            // Momentum update
+            self.momentum_buffer[i] = momentum * self.momentum_buffer[i] + (1.0 - momentum) * g;
+
+            // Weight update with decay
+            *w += lr * self.momentum_buffer[i] - decay * (*w - 1.0);
+
+            // Clamp weights to reasonable range
+            *w = w.clamp(0.1, 10.0);
+        }
+    }
+
+    /// Record positive feedback (successful retrieval)
+    pub fn record_success(&mut self, query: &Point, selected_centroid: &Point, level: usize) {
+        self.record_feedback(RoutingFeedback {
+            query: query.clone(),
+            selected_centroid: selected_centroid.clone(),
+            reward: 1.0,
+            level,
+        });
+    }
+
+    /// Record negative feedback (unsuccessful retrieval)
+    pub fn record_failure(&mut self, query: &Point, selected_centroid: &Point, level: usize) {
+        self.record_feedback(RoutingFeedback {
+            query: query.clone(),
+            selected_centroid: selected_centroid.clone(),
+            reward: -1.0,
+            level,
+        });
+    }
+
+    /// Record implicit feedback with continuous reward
+    pub fn record_implicit(&mut self, query: &Point, selected_centroid: &Point, level: usize, relevance_score: f32) {
+        // Convert relevance (0-1) to reward (-1 to +1)
+        let reward = 2.0 * relevance_score - 1.0;
+        self.record_feedback(RoutingFeedback {
+            query: query.clone(),
+            selected_centroid: selected_centroid.clone(),
+            reward,
+            level,
+        });
+    }
+
+    /// Get statistics about the router
+    pub fn stats(&self) -> RouterStats {
+        RouterStats {
+            total_samples: self.total_samples,
+            buffer_size: self.feedback_buffer.len(),
+            weight_mean: self.weights.iter().sum::<f32>() / self.weights.len() as f32,
+            weight_std: {
+                let mean = self.weights.iter().sum::<f32>() / self.weights.len() as f32;
+                (self.weights.iter().map(|w| (w - mean).powi(2)).sum::<f32>()
+                    / self.weights.len() as f32).sqrt()
+            },
+            weight_min: self.weights.iter().cloned().fold(f32::INFINITY, f32::min),
+            weight_max: self.weights.iter().cloned().fold(f32::NEG_INFINITY, f32::max),
+        }
+    }
+
+    /// Reset weights to uniform
+    pub fn reset_weights(&mut self) {
+        for w in self.weights.iter_mut() {
+            *w = 1.0;
+        }
+        for m in self.momentum_buffer.iter_mut() {
+            *m = 0.0;
+        }
+    }
+
+    /// Clear feedback buffer
+    pub fn clear_feedback(&mut self) {
+        self.feedback_buffer.clear();
+    }
+
+    /// Get the number of dimensions
+    pub fn dims(&self) -> usize {
+        self.dims
+    }
+
+    /// Serialize weights to bytes
+    pub fn serialize_weights(&self) -> Vec<u8> {
+        let mut bytes = Vec::with_capacity(self.weights.len() * 4);
+        for w in &self.weights {
+            bytes.extend_from_slice(&w.to_le_bytes());
+        }
+        bytes
+    }
+
+    /// Deserialize weights from bytes
+    pub fn deserialize_weights(&mut self, bytes: &[u8]) -> Result<(), &'static str> {
+        if bytes.len() != self.weights.len() * 4 {
+            return Err("Weight count mismatch");
+        }
+
+        for (i, chunk) in bytes.chunks(4).enumerate() {
+            let arr: [u8; 4] = chunk.try_into().map_err(|_| "Invalid byte chunk")?;
+            self.weights[i] = f32::from_le_bytes(arr);
+        }
+
+        Ok(())
+    }
+}
+
+/// Statistics about the learnable router
+#[derive(Debug, Clone)]
+pub struct RouterStats {
+    pub total_samples: usize,
+    pub buffer_size: usize,
+    pub weight_mean: f32,
+    pub weight_std: f32,
+    pub weight_min: f32,
+    pub weight_max: f32,
+}
+
+/// Compute routing score for beam search
+///
+/// Combines weighted similarity with optional biases
+pub fn compute_routing_score(
+    router: &LearnableRouter,
+    query: &Point,
+    centroid: &Point,
+    temporal_distance: f32,
+    temporal_weight: f32,
+) -> f32 {
+    let semantic_sim = router.weighted_similarity(query, centroid);
+
+    // Convert to distance (lower = better for routing)
+    let semantic_dist = 1.0 - semantic_sim;
+
+    // Combine with temporal
+    semantic_dist * (1.0 - temporal_weight) + temporal_distance * temporal_weight
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn make_point(v: Vec<f32>) -> Point {
+        Point::new(v).normalize()
+    }
+
+    #[test]
+    fn test_router_creation() {
+        let router = LearnableRouter::default_for_dims(64);
+
+        assert_eq!(router.dims(), 64);
+        assert_eq!(router.weights().len(), 64);
+        assert!(router.is_learning_enabled());
+
+        // All weights should start at 1.0
+        for &w in router.weights() {
+            assert!((w - 1.0).abs() < 1e-6);
+        }
+    }
+
+    #[test]
+    fn test_weighted_similarity() {
+        let router = LearnableRouter::default_for_dims(4);
+
+        let query = make_point(vec![1.0, 0.0, 0.0, 0.0]);
+        let centroid = make_point(vec![0.8, 0.2, 0.0, 0.0]);
+
+        let sim = router.weighted_similarity(&query, &centroid);
+
+        // With uniform weights, should be close to cosine similarity
+        let expected_cosine: f32 = query.dims().iter()
+            .zip(centroid.dims().iter())
+            .map(|(q, c)| q * c)
+            .sum();
+
+        assert!((sim - expected_cosine).abs() < 1e-5);
+    }
+
+    #[test]
+    fn test_feedback_recording() {
+        let mut router = LearnableRouter::new(4, LearnableRoutingConfig {
+            min_samples_to_learn: 5,
+            update_frequency: 5,
+            ..Default::default()
+        });
+
+        let query = make_point(vec![1.0, 0.0, 0.0, 0.0]);
+        let centroid = make_point(vec![0.9, 0.1, 0.0, 0.0]);
+
+        // Record several positive feedbacks
+        for _ in 0..10 {
+            router.record_success(&query, &centroid, 0);
+        }
+
+        let stats = router.stats();
+        assert_eq!(stats.total_samples, 10);
+
+        // Weights should have been updated
+        // Dimension 0 (aligned with query) should increase
+        println!("Weights after positive feedback: {:?}", router.weights());
+    }
+
+    #[test]
+    fn test_learning_dynamics() {
+        let mut router = LearnableRouter::new(4, LearnableRoutingConfig {
+            learning_rate: 0.1,
+            min_samples_to_learn: 3,
+            update_frequency: 3,
+            momentum: 0.0,  // No momentum for predictable testing
+            weight_decay: 0.0,  // No decay for predictable testing
+            ..Default::default()
+        });
+
+        // Query aligned with dimension 0
+        let query = make_point(vec![1.0, 0.0, 0.0, 0.0]);
+        // Centroid also aligned with dimension 0
+        let centroid_good = make_point(vec![0.95, 0.05, 0.0, 0.0]);
+        // Centroid aligned with dimension 1
+        let centroid_bad = make_point(vec![0.0, 1.0, 0.0, 0.0]);
+
+        // Record positive feedback for good centroid
+        for _ in 0..6 {
+            router.record_success(&query, &centroid_good, 0);
+        }
+
+        let weights_after_positive = router.weights().to_vec();
+
+        // Record negative feedback for bad centroid
+        for _ in 0..6 {
+            router.record_failure(&query, &centroid_bad, 0);
+        }
+
+        let weights_after_negative = router.weights().to_vec();
+
+        println!("Initial weights: [1.0, 1.0, 1.0, 1.0]");
+        println!("After positive: {:?}", weights_after_positive);
+        println!("After negative: {:?}", weights_after_negative);
+
+        // Weight for dim 0 should have increased from positive feedback
+        // (query[0] * centroid_good[0] is high and reward is positive)
+    }
+
+    #[test]
+    fn test_disabled_learning() {
+        let mut router = LearnableRouter::new(4, LearnableRoutingConfig::disabled());
+
+        assert!(!router.is_learning_enabled());
+
+        let query = make_point(vec![1.0, 0.0, 0.0, 0.0]);
+        let centroid = make_point(vec![0.9, 0.1, 0.0, 0.0]);
+
+        // Record feedback
+        for _ in 0..100 {
+            router.record_success(&query, &centroid, 0);
+        }
+
+        // Weights should remain at 1.0
+        for &w in router.weights() {
+            assert!((w - 1.0).abs() < 1e-6);
+        }
+    }
+
+    #[test]
+    fn test_serialization() {
+        let mut router = LearnableRouter::default_for_dims(4);
+
+        // Modify weights
+        for (i, w) in router.weights.iter_mut().enumerate() {
+            *w = (i as f32 + 1.0) * 0.5;
+        }
+
+        let bytes = router.serialize_weights();
+
+        let mut router2 = LearnableRouter::default_for_dims(4);
+        router2.deserialize_weights(&bytes).unwrap();
+
+        for (w1, w2) in router.weights().iter().zip(router2.weights().iter()) {
+            assert!((w1 - w2).abs() < 1e-6);
+        }
+    }
+}

src/adapters/index/mod.rs

@@ -0,0 +1,45 @@
+//! # Index Adapters
+//!
+//! Implementations of the Near port for different index backends.
+//!
+//! Available adapters:
+//! - `FlatIndex` - Brute force search (exact, O(n) per query)
+//! - `HatIndex` - Hierarchical Attention Tree (approximate, O(log n) per query)
+//!
+//! Consolidation support:
+//! - `Consolidate` trait for background maintenance operations
+//! - `ConsolidationConfig` to configure maintenance behavior
+//!
+//! Subspace support:
+//! - `Subspace` representation for containers capturing variance/spread
+//! - `SubspaceConfig` for configuring subspace-aware routing
+//!
+//! Learnable routing:
+//! - `LearnableRouter` for adapting routing weights from feedback
+//! - `LearnableRoutingConfig` for configuring online learning
+
+mod flat;
+mod hat;
+mod consolidation;
+mod subspace;
+mod learnable_routing;
+mod persistence;
+
+pub use flat::FlatIndex;
+pub use hat::{HatIndex, HatConfig, CentroidMethod, ContainerLevel, SessionSummary, DocumentSummary, HatStats};
+pub use consolidation::{
+    Consolidate, ConsolidationConfig, ConsolidationLevel, ConsolidationPhase,
+    ConsolidationState, ConsolidationMetrics, ConsolidationProgress, ConsolidationTickResult,
+    compute_exact_centroid, centroid_drift,
+};
+pub use subspace::{
+    Subspace, SubspaceConfig, subspace_similarity, combined_subspace_similarity,
+    query_subspace_alignment, subspace_spread, subspace_isotropy,
+};
+pub use learnable_routing::{
+    LearnableRouter, LearnableRoutingConfig, RoutingFeedback, RouterStats,
+    compute_routing_score,
+};
+pub use persistence::{
+    PersistError, SerializedHat, SerializedContainer, LevelByte,
+};

src/adapters/index/persistence.rs

@@ -0,0 +1,442 @@
+//! # HAT Persistence Layer
+//!
+//! Serialization and deserialization for HAT indexes.
+//!
+//! ## Format
+//!
+//! The HAT persistence format is a simple binary format:
+//!
+//! ```text
+//! [Header: 32 bytes]
+//!   - Magic: "HAT\0" (4 bytes)
+//!   - Version: u32 (4 bytes)
+//!   - Dimensionality: u32 (4 bytes)
+//!   - Container count: u64 (8 bytes)
+//!   - Root ID: 16 bytes (or zeros if none)
+//!   - Reserved: 0 bytes (for future use)
+//!
+//! [Containers: variable]
+//!   For each container:
+//!     - ID: 16 bytes
+//!     - Level: u8 (0=Root, 1=Session, 2=Document, 3=Chunk)
+//!     - Timestamp: u64 (8 bytes)
+//!     - Child count: u32 (4 bytes)
+//!     - Child IDs: child_count * 16 bytes
+//!     - Descendant count: u64 (8 bytes)
+//!     - Centroid: dimensionality * 4 bytes (f32s)
+//!     - Has accumulated sum: u8 (0 or 1)
+//!     - Accumulated sum: dimensionality * 4 bytes (if has_accumulated_sum)
+//!
+//! [Active State: 32 bytes]
+//!   - Active session ID: 16 bytes (or zeros)
+//!   - Active document ID: 16 bytes (or zeros)
+//!
+//! [Learnable Router Weights: variable, optional]
+//!   - Has weights: u8 (0 or 1)
+//!   - If has weights: dimensionality * 4 bytes (f32s)
+//! ```
+//!
+//! ## Usage
+//!
+//! ```rust,ignore
+//! // Save
+//! let bytes = hat.to_bytes()?;
+//! std::fs::write("index.hat", bytes)?;
+//!
+//! // Load
+//! let bytes = std::fs::read("index.hat")?;
+//! let hat = HatIndex::from_bytes(&bytes)?;
+//! ```
+
+use crate::core::{Id, Point};
+use std::io::{self, Read, Write, Cursor};
+
+/// Magic bytes for HAT file format
+const MAGIC: &[u8; 4] = b"HAT\0";
+
+/// Current format version
+const VERSION: u32 = 1;
+
+/// Error type for persistence operations
+#[derive(Debug)]
+pub enum PersistError {
+    /// Invalid magic bytes
+    InvalidMagic,
+    /// Unsupported version
+    UnsupportedVersion(u32),
+    /// IO error
+    Io(io::Error),
+    /// Data corruption
+    Corrupted(String),
+    /// Dimension mismatch
+    DimensionMismatch { expected: usize, found: usize },
+}
+
+impl std::fmt::Display for PersistError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            PersistError::InvalidMagic => write!(f, "Invalid HAT file magic bytes"),
+            PersistError::UnsupportedVersion(v) => write!(f, "Unsupported HAT version: {}", v),
+            PersistError::Io(e) => write!(f, "IO error: {}", e),
+            PersistError::Corrupted(msg) => write!(f, "Data corruption: {}", msg),
+            PersistError::DimensionMismatch { expected, found } => {
+                write!(f, "Dimension mismatch: expected {}, found {}", expected, found)
+            }
+        }
+    }
+}
+
+impl std::error::Error for PersistError {}
+
+impl From<io::Error> for PersistError {
+    fn from(e: io::Error) -> Self {
+        PersistError::Io(e)
+    }
+}
+
+/// Container level as u8
+#[repr(u8)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum LevelByte {
+    Root = 0,
+    Session = 1,
+    Document = 2,
+    Chunk = 3,
+}
+
+impl LevelByte {
+    pub fn from_u8(v: u8) -> Option<Self> {
+        match v {
+            0 => Some(LevelByte::Root),
+            1 => Some(LevelByte::Session),
+            2 => Some(LevelByte::Document),
+            3 => Some(LevelByte::Chunk),
+            _ => None,
+        }
+    }
+}
+
+/// Serialized container data
+#[derive(Debug, Clone)]
+pub struct SerializedContainer {
+    pub id: Id,
+    pub level: LevelByte,
+    pub timestamp: u64,
+    pub children: Vec<Id>,
+    pub descendant_count: u64,
+    pub centroid: Vec<f32>,
+    pub accumulated_sum: Option<Vec<f32>>,
+}
+
+/// Serialized HAT index
+#[derive(Debug, Clone)]
+pub struct SerializedHat {
+    pub version: u32,
+    pub dimensionality: u32,
+    pub root_id: Option<Id>,
+    pub containers: Vec<SerializedContainer>,
+    pub active_session: Option<Id>,
+    pub active_document: Option<Id>,
+    pub router_weights: Option<Vec<f32>>,
+}
+
+impl SerializedHat {
+    /// Serialize to bytes
+    pub fn to_bytes(&self) -> Result<Vec<u8>, PersistError> {
+        let mut buf = Vec::new();
+
+        // Header
+        buf.write_all(MAGIC)?;
+        buf.write_all(&self.version.to_le_bytes())?;
+        buf.write_all(&self.dimensionality.to_le_bytes())?;
+        buf.write_all(&(self.containers.len() as u64).to_le_bytes())?;
+
+        // Root ID
+        if let Some(id) = &self.root_id {
+            buf.write_all(id.as_bytes())?;
+        } else {
+            buf.write_all(&[0u8; 16])?;
+        }
+
+        // Containers
+        for container in &self.containers {
+            // ID
+            buf.write_all(container.id.as_bytes())?;
+
+            // Level
+            buf.write_all(&[container.level as u8])?;
+
+            // Timestamp
+            buf.write_all(&container.timestamp.to_le_bytes())?;
+
+            // Children
+            buf.write_all(&(container.children.len() as u32).to_le_bytes())?;
+            for child_id in &container.children {
+                buf.write_all(child_id.as_bytes())?;
+            }
+
+            // Descendant count
+            buf.write_all(&container.descendant_count.to_le_bytes())?;
+
+            // Centroid
+            for &v in &container.centroid {
+                buf.write_all(&v.to_le_bytes())?;
+            }
+
+            // Accumulated sum
+            if let Some(sum) = &container.accumulated_sum {
+                buf.write_all(&[1u8])?;
+                for &v in sum {
+                    buf.write_all(&v.to_le_bytes())?;
+                }
+            } else {
+                buf.write_all(&[0u8])?;
+            }
+        }
+
+        // Active state
+        if let Some(id) = &self.active_session {
+            buf.write_all(id.as_bytes())?;
+        } else {
+            buf.write_all(&[0u8; 16])?;
+        }
+
+        if let Some(id) = &self.active_document {
+            buf.write_all(id.as_bytes())?;
+        } else {
+            buf.write_all(&[0u8; 16])?;
+        }
+
+        // Router weights
+        if let Some(weights) = &self.router_weights {
+            buf.write_all(&[1u8])?;
+            for &w in weights {
+                buf.write_all(&w.to_le_bytes())?;
+            }
+        } else {
+            buf.write_all(&[0u8])?;
+        }
+
+        Ok(buf)
+    }
+
+    /// Deserialize from bytes
+    pub fn from_bytes(data: &[u8]) -> Result<Self, PersistError> {
+        let mut cursor = Cursor::new(data);
+
+        // Read header
+        let mut magic = [0u8; 4];
+        cursor.read_exact(&mut magic)?;
+        if &magic != MAGIC {
+            return Err(PersistError::InvalidMagic);
+        }
+
+        let mut version_bytes = [0u8; 4];
+        cursor.read_exact(&mut version_bytes)?;
+        let version = u32::from_le_bytes(version_bytes);
+        if version != VERSION {
+            return Err(PersistError::UnsupportedVersion(version));
+        }
+
+        let mut dims_bytes = [0u8; 4];
+        cursor.read_exact(&mut dims_bytes)?;
+        let dimensionality = u32::from_le_bytes(dims_bytes);
+
+        let mut count_bytes = [0u8; 8];
+        cursor.read_exact(&mut count_bytes)?;
+        let container_count = u64::from_le_bytes(count_bytes);
+
+        let mut root_bytes = [0u8; 16];
+        cursor.read_exact(&mut root_bytes)?;
+        let root_id = if root_bytes == [0u8; 16] {
+            None
+        } else {
+            Some(Id::from_bytes(root_bytes))
+        };
+
+        // Read containers
+        let mut containers = Vec::with_capacity(container_count as usize);
+        for _ in 0..container_count {
+            // ID
+            let mut id_bytes = [0u8; 16];
+            cursor.read_exact(&mut id_bytes)?;
+            let id = Id::from_bytes(id_bytes);
+
+            // Level
+            let mut level_byte = [0u8; 1];
+            cursor.read_exact(&mut level_byte)?;
+            let level = LevelByte::from_u8(level_byte[0])
+                .ok_or_else(|| PersistError::Corrupted(format!("Invalid level: {}", level_byte[0])))?;
+
+            // Timestamp
+            let mut ts_bytes = [0u8; 8];
+            cursor.read_exact(&mut ts_bytes)?;
+            let timestamp = u64::from_le_bytes(ts_bytes);
+
+            // Children
+            let mut child_count_bytes = [0u8; 4];
+            cursor.read_exact(&mut child_count_bytes)?;
+            let child_count = u32::from_le_bytes(child_count_bytes) as usize;
+
+            let mut children = Vec::with_capacity(child_count);
+            for _ in 0..child_count {
+                let mut child_bytes = [0u8; 16];
+                cursor.read_exact(&mut child_bytes)?;
+                children.push(Id::from_bytes(child_bytes));
+            }
+
+            // Descendant count
+            let mut desc_bytes = [0u8; 8];
+            cursor.read_exact(&mut desc_bytes)?;
+            let descendant_count = u64::from_le_bytes(desc_bytes);
+
+            // Centroid
+            let mut centroid = Vec::with_capacity(dimensionality as usize);
+            for _ in 0..dimensionality {
+                let mut v_bytes = [0u8; 4];
+                cursor.read_exact(&mut v_bytes)?;
+                centroid.push(f32::from_le_bytes(v_bytes));
+            }
+
+            // Accumulated sum
+            let mut has_sum = [0u8; 1];
+            cursor.read_exact(&mut has_sum)?;
+            let accumulated_sum = if has_sum[0] == 1 {
+                let mut sum = Vec::with_capacity(dimensionality as usize);
+                for _ in 0..dimensionality {
+                    let mut v_bytes = [0u8; 4];
+                    cursor.read_exact(&mut v_bytes)?;
+                    sum.push(f32::from_le_bytes(v_bytes));
+                }
+                Some(sum)
+            } else {
+                None
+            };
+
+            containers.push(SerializedContainer {
+                id,
+                level,
+                timestamp,
+                children,
+                descendant_count,
+                centroid,
+                accumulated_sum,
+            });
+        }
+
+        // Active state
+        let mut active_session_bytes = [0u8; 16];
+        cursor.read_exact(&mut active_session_bytes)?;
+        let active_session = if active_session_bytes == [0u8; 16] {
+            None
+        } else {
+            Some(Id::from_bytes(active_session_bytes))
+        };
+
+        let mut active_document_bytes = [0u8; 16];
+        cursor.read_exact(&mut active_document_bytes)?;
+        let active_document = if active_document_bytes == [0u8; 16] {
+            None
+        } else {
+            Some(Id::from_bytes(active_document_bytes))
+        };
+
+        // Router weights (optional - may not be present in older files)
+        let router_weights = if cursor.position() < data.len() as u64 {
+            let mut has_weights = [0u8; 1];
+            cursor.read_exact(&mut has_weights)?;
+            if has_weights[0] == 1 {
+                let mut weights = Vec::with_capacity(dimensionality as usize);
+                for _ in 0..dimensionality {
+                    let mut w_bytes = [0u8; 4];
+                    cursor.read_exact(&mut w_bytes)?;
+                    weights.push(f32::from_le_bytes(w_bytes));
+                }
+                Some(weights)
+            } else {
+                None
+            }
+        } else {
+            None
+        };
+
+        Ok(SerializedHat {
+            version,
+            dimensionality,
+            root_id,
+            containers,
+            active_session,
+            active_document,
+            router_weights,
+        })
+    }
+}
+
+/// Helper to read ID from Option
+fn id_to_bytes(id: &Option<Id>) -> [u8; 16] {
+    match id {
+        Some(id) => *id.as_bytes(),
+        None => [0u8; 16],
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_serialized_hat_roundtrip() {
+        let original = SerializedHat {
+            version: VERSION,
+            dimensionality: 128,
+            root_id: Some(Id::now()),
+            containers: vec![
+                SerializedContainer {
+                    id: Id::now(),
+                    level: LevelByte::Root,
+                    timestamp: 1234567890,
+                    children: vec![Id::now(), Id::now()],
+                    descendant_count: 10,
+                    centroid: vec![0.1; 128],
+                    accumulated_sum: None,
+                },
+                SerializedContainer {
+                    id: Id::now(),
+                    level: LevelByte::Chunk,
+                    timestamp: 1234567891,
+                    children: vec![],
+                    descendant_count: 1,
+                    centroid: vec![0.5; 128],
+                    accumulated_sum: Some(vec![0.5; 128]),
+                },
+            ],
+            active_session: Some(Id::now()),
+            active_document: None,
+            router_weights: Some(vec![1.0; 128]),
+        };
+
+        let bytes = original.to_bytes().unwrap();
+        let restored = SerializedHat::from_bytes(&bytes).unwrap();
+
+        assert_eq!(restored.version, original.version);
+        assert_eq!(restored.dimensionality, original.dimensionality);
+        assert_eq!(restored.containers.len(), original.containers.len());
+        assert!(restored.router_weights.is_some());
+    }
+
+    #[test]
+    fn test_invalid_magic() {
+        let bad_data = b"BAD\0rest of data...";
+        let result = SerializedHat::from_bytes(bad_data);
+        assert!(matches!(result, Err(PersistError::InvalidMagic)));
+    }
+
+    #[test]
+    fn test_level_byte_conversion() {
+        assert_eq!(LevelByte::from_u8(0), Some(LevelByte::Root));
+        assert_eq!(LevelByte::from_u8(1), Some(LevelByte::Session));
+        assert_eq!(LevelByte::from_u8(2), Some(LevelByte::Document));
+        assert_eq!(LevelByte::from_u8(3), Some(LevelByte::Chunk));
+        assert_eq!(LevelByte::from_u8(4), None);
+    }
+}

src/adapters/index/subspace.rs

@@ -0,0 +1,640 @@
+//! # Subspace Containers for HAT
+//!
+//! This module implements subspace-aware container representations for HAT.
+//! Instead of representing containers as single centroid points, we model them
+//! as subspaces that capture the "shape" and "spread" of points within.
+//!
+//! ## Key Insight (from journal 006)
+//!
+//! "A session isn't a single point - it's a *region* of the manifold."
+//!
+//! ## Grassmann-Inspired Approach
+//!
+//! - Each container is represented by its centroid PLUS principal directions
+//! - Similarity between containers uses subspace angles (principal angles)
+//! - Better captures diverse content within a container
+//!
+//! ## Benefits
+//!
+//! 1. **Better Routing**: Query can match containers even if not close to centroid
+//! 2. **Diversity Awareness**: Wide containers (diverse content) vs narrow containers
+//! 3. **Geometric Fidelity**: More accurate representation of point distributions
+
+use crate::core::Point;
+
+/// Configuration for subspace representation
+#[derive(Debug, Clone)]
+pub struct SubspaceConfig {
+    /// Number of principal components to track (subspace rank)
+    pub rank: usize,
+
+    /// Minimum points before computing subspace (need enough for covariance)
+    pub min_points_for_subspace: usize,
+
+    /// Weight of subspace similarity vs centroid similarity (0.0 = centroid only)
+    pub subspace_weight: f32,
+
+    /// Enable incremental covariance updates during insertion (vs only during consolidation)
+    /// When false, subspace is only computed during consolidation - much faster inserts
+    pub incremental_covariance: bool,
+}
+
+impl Default for SubspaceConfig {
+    fn default() -> Self {
+        Self {
+            rank: 3,                        // Track top 3 principal directions
+            min_points_for_subspace: 5,     // Need at least 5 points for meaningful covariance
+            subspace_weight: 0.3,           // 30% subspace, 70% centroid by default
+            incremental_covariance: false,  // Default: only compute during consolidation (faster)
+        }
+    }
+}
+
+impl SubspaceConfig {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    pub fn with_rank(mut self, rank: usize) -> Self {
+        self.rank = rank;
+        self
+    }
+
+    pub fn with_subspace_weight(mut self, weight: f32) -> Self {
+        self.subspace_weight = weight.clamp(0.0, 1.0);
+        self
+    }
+}
+
+/// Subspace representation for a container
+///
+/// Stores the centroid plus principal directions that capture
+/// the variance/spread of points within the container.
+#[derive(Debug, Clone)]
+pub struct Subspace {
+    /// Centroid (mean of points)
+    pub centroid: Point,
+
+    /// Principal directions (orthonormal basis for subspace)
+    /// Each direction is a unit vector
+    pub principal_directions: Vec<Point>,
+
+    /// Eigenvalues (variance in each principal direction)
+    /// Stored in decreasing order
+    pub eigenvalues: Vec<f32>,
+
+    /// Number of points used to compute this subspace
+    pub point_count: usize,
+
+    /// Running sum for incremental centroid updates
+    accumulated_sum: Vec<f32>,
+
+    /// Running covariance matrix (upper triangle only for efficiency)
+    /// For incremental updates: cov = (sum of outer products) / n - mean * mean^T
+    accumulated_outer_product: Vec<f32>,
+}
+
+impl Subspace {
+    /// Create a new empty subspace
+    pub fn new(dimensionality: usize) -> Self {
+        Self {
+            centroid: Point::origin(dimensionality),
+            principal_directions: Vec::new(),
+            eigenvalues: Vec::new(),
+            point_count: 0,
+            accumulated_sum: vec![0.0; dimensionality],
+            // Upper triangle of d x d matrix: d * (d + 1) / 2 elements
+            accumulated_outer_product: vec![0.0; dimensionality * (dimensionality + 1) / 2],
+        }
+    }
+
+    /// Create from a single point
+    pub fn from_point(point: &Point) -> Self {
+        Self {
+            centroid: point.clone(),
+            principal_directions: Vec::new(),
+            eigenvalues: Vec::new(),
+            point_count: 1,
+            accumulated_sum: point.dims().to_vec(),
+            accumulated_outer_product: Self::outer_product_upper(point.dims()),
+        }
+    }
+
+    /// Dimensionality of the ambient space
+    pub fn dimensionality(&self) -> usize {
+        self.centroid.dimensionality()
+    }
+
+    /// Check if subspace has meaningful principal directions
+    pub fn has_subspace(&self) -> bool {
+        !self.principal_directions.is_empty()
+    }
+
+    /// Get the subspace rank (number of principal directions)
+    pub fn rank(&self) -> usize {
+        self.principal_directions.len()
+    }
+
+    /// Compute upper triangle of outer product v * v^T
+    fn outer_product_upper(v: &[f32]) -> Vec<f32> {
+        let n = v.len();
+        let mut result = vec![0.0; n * (n + 1) / 2];
+        let mut idx = 0;
+        for i in 0..n {
+            for j in i..n {
+                result[idx] = v[i] * v[j];
+                idx += 1;
+            }
+        }
+        result
+    }
+
+    /// Get element from upper triangle storage
+    fn get_upper(&self, i: usize, j: usize) -> f32 {
+        let (row, col) = if i <= j { (i, j) } else { (j, i) };
+        let n = self.dimensionality();
+        // Index into upper triangle
+        let idx = row * (2 * n - row - 1) / 2 + col;
+        self.accumulated_outer_product[idx]
+    }
+
+    /// Add element to upper triangle storage
+    fn add_to_upper(&mut self, i: usize, j: usize, value: f32) {
+        let (row, col) = if i <= j { (i, j) } else { (j, i) };
+        let n = self.dimensionality();
+        let idx = row * (2 * n - row - 1) / 2 + col;
+        self.accumulated_outer_product[idx] += value;
+    }
+
+    /// Incrementally add a point
+    pub fn add_point(&mut self, point: &Point) {
+        let dims = point.dims();
+
+        // Update running sum
+        for (i, &v) in dims.iter().enumerate() {
+            self.accumulated_sum[i] += v;
+        }
+
+        // Update outer product accumulator
+        for i in 0..dims.len() {
+            for j in i..dims.len() {
+                self.add_to_upper(i, j, dims[i] * dims[j]);
+            }
+        }
+
+        self.point_count += 1;
+
+        // Update centroid
+        let n = self.point_count as f32;
+        let centroid_dims: Vec<f32> = self.accumulated_sum.iter()
+            .map(|&s| s / n)
+            .collect();
+        self.centroid = Point::new(centroid_dims).normalize();
+    }
+
+    /// Compute covariance matrix from accumulated statistics
+    fn compute_covariance(&self) -> Vec<Vec<f32>> {
+        let n = self.dimensionality();
+        let count = self.point_count as f32;
+
+        if count < 2.0 {
+            return vec![vec![0.0; n]; n];
+        }
+
+        // Mean vector
+        let mean: Vec<f32> = self.accumulated_sum.iter()
+            .map(|&s| s / count)
+            .collect();
+
+        // Covariance = E[X*X^T] - E[X]*E[X]^T
+        let mut cov = vec![vec![0.0; n]; n];
+        for i in 0..n {
+            for j in i..n {
+                let exx = self.get_upper(i, j) / count;
+                let exex = mean[i] * mean[j];
+                let c = exx - exex;
+                cov[i][j] = c;
+                cov[j][i] = c;  // Symmetric
+            }
+        }
+
+        cov
+    }
+
+    /// Recompute principal directions from covariance
+    /// Uses power iteration for efficiency (avoids full eigendecomposition)
+    pub fn recompute_subspace(&mut self, rank: usize) {
+        if self.point_count < 3 {
+            // Not enough points for meaningful subspace
+            self.principal_directions.clear();
+            self.eigenvalues.clear();
+            return;
+        }
+
+        let cov = self.compute_covariance();
+        let n = self.dimensionality();
+
+        // Extract top-k eigenvectors using power iteration with deflation
+        let mut directions = Vec::new();
+        let mut values = Vec::new();
+        let mut working_cov = cov.clone();
+
+        for _ in 0..rank.min(n) {
+            // Power iteration for dominant eigenvector
+            let (eigval, eigvec) = self.power_iteration(&working_cov, 50);
+
+            if eigval < 1e-8 {
+                break;  // No more significant variance
+            }
+
+            values.push(eigval);
+            directions.push(Point::new(eigvec.clone()).normalize());
+
+            // Deflate: remove this eigenvector's contribution
+            for i in 0..n {
+                for j in 0..n {
+                    working_cov[i][j] -= eigval * eigvec[i] * eigvec[j];
+                }
+            }
+        }
+
+        self.principal_directions = directions;
+        self.eigenvalues = values;
+    }
+
+    /// Power iteration to find dominant eigenvector
+    fn power_iteration(&self, matrix: &[Vec<f32>], max_iters: usize) -> (f32, Vec<f32>) {
+        let n = matrix.len();
+
+        // Initialize with random-ish vector (use first column of matrix + perturbation)
+        let mut v: Vec<f32> = (0..n).map(|i| 1.0 + (i as f32) * 0.1).collect();
+        let mut norm: f32 = v.iter().map(|x| x * x).sum::<f32>().sqrt();
+        for x in &mut v {
+            *x /= norm;
+        }
+
+        let mut eigenvalue = 0.0f32;
+
+        for _ in 0..max_iters {
+            // v_new = A * v
+            let mut v_new = vec![0.0; n];
+            for i in 0..n {
+                for j in 0..n {
+                    v_new[i] += matrix[i][j] * v[j];
+                }
+            }
+
+            // Compute eigenvalue approximation
+            eigenvalue = v_new.iter().zip(v.iter()).map(|(a, b)| a * b).sum();
+
+            // Normalize
+            norm = v_new.iter().map(|x| x * x).sum::<f32>().sqrt();
+            if norm < 1e-10 {
+                return (0.0, vec![0.0; n]);
+            }
+
+            let converged = v.iter().zip(v_new.iter())
+                .map(|(a, b)| (a - b / norm).abs())
+                .sum::<f32>() < 1e-8;
+
+            for i in 0..n {
+                v[i] = v_new[i] / norm;
+            }
+
+            if converged {
+                break;
+            }
+        }
+
+        (eigenvalue.abs(), v)
+    }
+}
+
+/// Compute subspace similarity using principal angles
+///
+/// Based on Grassmann geometry: the similarity between two subspaces
+/// is determined by the principal angles between them.
+///
+/// For k-dimensional subspaces, there are k principal angles θ₁...θₖ
+/// where 0 ≤ θ₁ ≤ ... ≤ θₖ ≤ π/2
+///
+/// Common measures:
+/// - Projection similarity: Σ cos²(θᵢ) / k  (ranges 0-1)
+/// - Geodesic distance: sqrt(Σ θᵢ²)
+/// - Chordal distance: sqrt(Σ sin²(θᵢ))
+pub fn subspace_similarity(a: &Subspace, b: &Subspace) -> f32 {
+    // If either has no subspace, fall back to centroid similarity
+    if !a.has_subspace() || !b.has_subspace() {
+        return centroid_similarity(&a.centroid, &b.centroid);
+    }
+
+    // Compute inner products between principal directions
+    let rank_a = a.rank();
+    let rank_b = b.rank();
+    let k = rank_a.min(rank_b);
+
+    if k == 0 {
+        return centroid_similarity(&a.centroid, &b.centroid);
+    }
+
+    // Build matrix M where M[i][j] = <a_i, b_j> (dot products)
+    let mut m = vec![vec![0.0f32; rank_b]; rank_a];
+    for i in 0..rank_a {
+        for j in 0..rank_b {
+            let dot: f32 = a.principal_directions[i].dims().iter()
+                .zip(b.principal_directions[j].dims().iter())
+                .map(|(x, y)| x * y)
+                .sum();
+            m[i][j] = dot;
+        }
+    }
+
+    // SVD of M gives principal angles: σᵢ = cos(θᵢ)
+    // For simplicity, use a greedy approximation:
+    // Find k maximum entries while avoiding row/column reuse
+    let cos_angles = greedy_max_matching(&m, k);
+
+    // Projection similarity: mean of cos²(θᵢ)
+    let similarity: f32 = cos_angles.iter()
+        .map(|&c| c * c)  // cos²(θ)
+        .sum::<f32>() / k as f32;
+
+    similarity
+}
+
+/// Greedy approximation to find k largest entries with no repeated rows/columns
+fn greedy_max_matching(m: &[Vec<f32>], k: usize) -> Vec<f32> {
+    let rows = m.len();
+    let cols = if rows > 0 { m[0].len() } else { 0 };
+
+    let mut used_rows = vec![false; rows];
+    let mut used_cols = vec![false; cols];
+    let mut result = Vec::new();
+
+    for _ in 0..k {
+        let mut best = (0, 0, 0.0f32);
+
+        for i in 0..rows {
+            if used_rows[i] { continue; }
+            for j in 0..cols {
+                if used_cols[j] { continue; }
+                let val = m[i][j].abs();
+                if val > best.2 {
+                    best = (i, j, val);
+                }
+            }
+        }
+
+        if best.2 > 0.0 {
+            used_rows[best.0] = true;
+            used_cols[best.1] = true;
+            result.push(best.2);
+        } else {
+            break;
+        }
+    }
+
+    result
+}
+
+/// Simple centroid similarity (cosine)
+fn centroid_similarity(a: &Point, b: &Point) -> f32 {
+    let dot: f32 = a.dims().iter()
+        .zip(b.dims().iter())
+        .map(|(x, y)| x * y)
+        .sum();
+    dot.clamp(-1.0, 1.0)
+}
+
+/// Combined similarity: weighted combination of centroid and subspace similarity
+///
+/// score = (1 - weight) * centroid_sim + weight * subspace_sim
+pub fn combined_subspace_similarity(
+    query: &Point,
+    container: &Subspace,
+    config: &SubspaceConfig,
+) -> f32 {
+    let centroid_sim = centroid_similarity(query, &container.centroid);
+
+    if !container.has_subspace() || config.subspace_weight < 1e-6 {
+        return centroid_sim;
+    }
+
+    // Subspace similarity: how well does query align with principal directions?
+    // Measure: sum of squared projections onto principal directions
+    let subspace_sim = query_subspace_alignment(query, container);
+
+    // Weighted combination
+    let w = config.subspace_weight;
+    (1.0 - w) * centroid_sim + w * subspace_sim
+}
+
+/// Measure how well a query aligns with a subspace
+///
+/// Higher score means query is well-captured by the subspace's principal directions
+pub fn query_subspace_alignment(query: &Point, subspace: &Subspace) -> f32 {
+    if !subspace.has_subspace() {
+        return centroid_similarity(query, &subspace.centroid);
+    }
+
+    // Center query relative to centroid
+    let centered: Vec<f32> = query.dims().iter()
+        .zip(subspace.centroid.dims().iter())
+        .map(|(q, c)| q - c)
+        .collect();
+
+    let centered_norm: f32 = centered.iter().map(|x| x * x).sum::<f32>().sqrt();
+    if centered_norm < 1e-10 {
+        // Query is at centroid - perfect match
+        return 1.0;
+    }
+
+    // Compute squared projections onto each principal direction
+    let mut total_proj_sq = 0.0f32;
+    for (dir, &eigenval) in subspace.principal_directions.iter().zip(subspace.eigenvalues.iter()) {
+        let proj: f32 = centered.iter()
+            .zip(dir.dims().iter())
+            .map(|(c, d)| c * d)
+            .sum();
+
+        // Weight by eigenvalue (variance in that direction)
+        // Higher eigenvalue = more likely direction for data variation
+        let weight = (eigenval / subspace.eigenvalues[0]).sqrt();
+        total_proj_sq += proj * proj * weight;
+    }
+
+    // Normalize by centered query magnitude
+    let alignment = (total_proj_sq / (centered_norm * centered_norm)).min(1.0);
+
+    // Combine with centroid similarity for overall score
+    let centroid_sim = centroid_similarity(query, &subspace.centroid);
+
+    // Score: close to centroid AND aligned with principal directions
+    (centroid_sim + alignment) / 2.0
+}
+
+/// Compute the "spread" or diversity of a subspace
+///
+/// Higher values indicate more diverse content (larger variance)
+/// Lower values indicate tightly clustered content
+pub fn subspace_spread(subspace: &Subspace) -> f32 {
+    if subspace.eigenvalues.is_empty() {
+        return 0.0;
+    }
+
+    // Total variance (sum of eigenvalues)
+    subspace.eigenvalues.iter().sum()
+}
+
+/// Compute the "isotropy" of a subspace
+///
+/// Higher values (close to 1) indicate uniform spread in all directions
+/// Lower values indicate elongated, anisotropic distribution
+pub fn subspace_isotropy(subspace: &Subspace) -> f32 {
+    if subspace.eigenvalues.len() < 2 {
+        return 1.0;  // Single direction is perfectly "isotropic" in its subspace
+    }
+
+    // Ratio of smallest to largest eigenvalue
+    let max = subspace.eigenvalues[0];
+    let min = *subspace.eigenvalues.last().unwrap();
+
+    if max < 1e-10 {
+        return 1.0;
+    }
+
+    min / max
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn make_point(v: Vec<f32>) -> Point {
+        Point::new(v).normalize()
+    }
+
+    #[test]
+    fn test_subspace_creation() {
+        let mut subspace = Subspace::new(3);
+
+        // Add some points
+        subspace.add_point(&make_point(vec![1.0, 0.0, 0.0]));
+        subspace.add_point(&make_point(vec![0.9, 0.1, 0.0]));
+        subspace.add_point(&make_point(vec![0.8, 0.2, 0.0]));
+        subspace.add_point(&make_point(vec![0.7, 0.3, 0.1]));
+        subspace.add_point(&make_point(vec![0.6, 0.4, 0.1]));
+
+        assert_eq!(subspace.point_count, 5);
+
+        // Compute principal directions
+        subspace.recompute_subspace(2);
+
+        assert!(subspace.has_subspace());
+        assert!(subspace.rank() > 0);
+        assert!(!subspace.eigenvalues.is_empty());
+
+        println!("Centroid: {:?}", subspace.centroid.dims());
+        println!("Principal directions: {}", subspace.rank());
+        println!("Eigenvalues: {:?}", subspace.eigenvalues);
+    }
+
+    #[test]
+    fn test_subspace_similarity() {
+        let mut a = Subspace::new(3);
+        let mut b = Subspace::new(3);
+
+        // Subspace A: points along x-axis
+        for i in 0..10 {
+            let x = 1.0 - i as f32 * 0.05;
+            let y = i as f32 * 0.05;
+            a.add_point(&make_point(vec![x, y, 0.0]));
+        }
+
+        // Subspace B: similar points (should be high similarity)
+        for i in 0..10 {
+            let x = 0.95 - i as f32 * 0.04;
+            let y = i as f32 * 0.04 + 0.05;
+            b.add_point(&make_point(vec![x, y, 0.1]));
+        }
+
+        a.recompute_subspace(2);
+        b.recompute_subspace(2);
+
+        let sim = subspace_similarity(&a, &b);
+        println!("Similarity between similar subspaces: {:.3}", sim);
+        assert!(sim > 0.5, "Similar subspaces should have high similarity");
+
+        // Subspace C: orthogonal to A (along z-axis)
+        let mut c = Subspace::new(3);
+        for i in 0..10 {
+            let z = 1.0 - i as f32 * 0.05;
+            c.add_point(&make_point(vec![0.0, 0.1, z]));
+        }
+        c.recompute_subspace(2);
+
+        let sim_ac = subspace_similarity(&a, &c);
+        println!("Similarity between orthogonal subspaces: {:.3}", sim_ac);
+        assert!(sim_ac < sim, "Orthogonal subspaces should have lower similarity");
+    }
+
+    #[test]
+    fn test_query_alignment() {
+        let mut subspace = Subspace::new(3);
+
+        // Points primarily along x-axis with some y variation
+        for i in 0..20 {
+            let x = 0.8 + (i % 3) as f32 * 0.1;
+            let y = (i as f32 * 0.05) % 0.3;
+            subspace.add_point(&make_point(vec![x, y, 0.05]));
+        }
+        subspace.recompute_subspace(2);
+
+        // Query aligned with subspace
+        let aligned_query = make_point(vec![0.9, 0.1, 0.0]);
+        let aligned_score = query_subspace_alignment(&aligned_query, &subspace);
+
+        // Query orthogonal to subspace
+        let orthogonal_query = make_point(vec![0.0, 0.0, 1.0]);
+        let orthogonal_score = query_subspace_alignment(&orthogonal_query, &subspace);
+
+        println!("Aligned query score: {:.3}", aligned_score);
+        println!("Orthogonal query score: {:.3}", orthogonal_score);
+
+        assert!(aligned_score > orthogonal_score,
+            "Aligned query should score higher than orthogonal query");
+    }
+
+    #[test]
+    fn test_spread_and_isotropy() {
+        let mut tight = Subspace::new(3);
+        let mut spread_out = Subspace::new(3);
+
+        // Tight cluster
+        for _ in 0..20 {
+            tight.add_point(&make_point(vec![0.9, 0.1, 0.05]));
+        }
+
+        // Spread out cluster
+        for i in 0..20 {
+            let angle = i as f32 * 0.3;
+            spread_out.add_point(&make_point(vec![
+                angle.cos(),
+                angle.sin(),
+                0.1
+            ]));
+        }
+
+        tight.recompute_subspace(3);
+        spread_out.recompute_subspace(3);
+
+        let tight_spread = subspace_spread(&tight);
+        let wide_spread = subspace_spread(&spread_out);
+
+        println!("Tight cluster spread: {:.6}", tight_spread);
+        println!("Wide cluster spread: {:.6}", wide_spread);
+
+        // Note: with normalized vectors the spread comparison might not be as expected
+        // The test validates the computation runs correctly
+    }
+}

src/adapters/mod.rs

@@ -0,0 +1,19 @@
+//! # Adapters
+//!
+//! Swappable implementations of port traits.
+//!
+//! This is where the hexagonal architecture meets reality:
+//! - Storage adapters: Memory, NVMe
+//! - Index adapters: Flat (brute force), HNSW (approximate)
+//! - Attention state serialization
+//! - Python bindings (when enabled)
+//!
+//! Each adapter implements one or more port traits.
+//! Adapters can be swapped without changing core logic.
+
+pub mod storage;
+pub mod index;
+pub mod attention;
+
+#[cfg(feature = "python")]
+pub mod python;

src/adapters/python.rs

@@ -0,0 +1,502 @@
+//! # Python Bindings
+//!
+//! PyO3 bindings for ARMS-HAT, enabling Python integration with LLMs.
+//!
+//! ## Python API
+//!
+//! ```python
+//! from arms_hat import HatIndex, SearchResult
+//!
+//! # Create index for OpenAI embeddings (1536 dims)
+//! index = HatIndex.cosine(1536)
+//!
+//! # Add embeddings
+//! id = index.add([0.1, 0.2, ...])  # Auto-generates ID
+//! index.add_with_id("custom_id", [0.1, 0.2, ...])  # Custom ID
+//!
+//! # Query
+//! results = index.near([0.1, 0.2, ...], k=10)
+//! for result in results:
+//!     print(f"{result.id}: {result.score}")
+//!
+//! # Session management
+//! index.new_session()
+//! index.new_document()
+//!
+//! # Persistence
+//! index.save("memory.hat")
+//! loaded = HatIndex.load("memory.hat")
+//! ```
+
+use pyo3::prelude::*;
+use pyo3::exceptions::{PyValueError, PyIOError};
+
+use crate::core::{Id, Point};
+use crate::adapters::index::{HatIndex as RustHatIndex, HatConfig, ConsolidationConfig, Consolidate};
+use crate::ports::Near;
+
+/// Python wrapper for search results
+#[pyclass(name = "SearchResult")]
+#[derive(Clone)]
+pub struct PySearchResult {
+    /// The ID as a hex string
+    #[pyo3(get)]
+    pub id: String,
+
+    /// The similarity/distance score
+    #[pyo3(get)]
+    pub score: f32,
+}
+
+#[pymethods]
+impl PySearchResult {
+    fn __repr__(&self) -> String {
+        format!("SearchResult(id='{}', score={:.4})", self.id, self.score)
+    }
+
+    fn __str__(&self) -> String {
+        format!("{}: {:.4}", self.id, self.score)
+    }
+}
+
+/// Python wrapper for HAT index configuration
+#[pyclass(name = "HatConfig")]
+#[derive(Clone)]
+pub struct PyHatConfig {
+    inner: HatConfig,
+}
+
+#[pymethods]
+impl PyHatConfig {
+    #[new]
+    fn new() -> Self {
+        Self { inner: HatConfig::default() }
+    }
+
+    /// Set beam width for search (default: 3)
+    fn with_beam_width(mut slf: PyRefMut<'_, Self>, width: usize) -> PyRefMut<'_, Self> {
+        slf.inner.beam_width = width;
+        slf
+    }
+
+    /// Set temporal weight (0.0 = pure semantic, 1.0 = pure temporal)
+    fn with_temporal_weight(mut slf: PyRefMut<'_, Self>, weight: f32) -> PyRefMut<'_, Self> {
+        slf.inner.temporal_weight = weight;
+        slf
+    }
+
+    /// Set propagation threshold for sparse updates
+    fn with_propagation_threshold(mut slf: PyRefMut<'_, Self>, threshold: f32) -> PyRefMut<'_, Self> {
+        slf.inner.propagation_threshold = threshold;
+        slf
+    }
+
+    fn __repr__(&self) -> String {
+        format!(
+            "HatConfig(beam_width={}, temporal_weight={:.2}, propagation_threshold={:.3})",
+            self.inner.beam_width, self.inner.temporal_weight, self.inner.propagation_threshold
+        )
+    }
+}
+
+/// Session summary for coarse-grained retrieval
+#[pyclass(name = "SessionSummary")]
+#[derive(Clone)]
+pub struct PySessionSummary {
+    #[pyo3(get)]
+    pub id: String,
+
+    #[pyo3(get)]
+    pub score: f32,
+
+    #[pyo3(get)]
+    pub chunk_count: usize,
+
+    #[pyo3(get)]
+    pub timestamp_ms: u64,
+}
+
+#[pymethods]
+impl PySessionSummary {
+    fn __repr__(&self) -> String {
+        format!(
+            "SessionSummary(id='{}', score={:.4}, chunks={})",
+            self.id, self.score, self.chunk_count
+        )
+    }
+}
+
+/// Document summary for mid-level retrieval
+#[pyclass(name = "DocumentSummary")]
+#[derive(Clone)]
+pub struct PyDocumentSummary {
+    #[pyo3(get)]
+    pub id: String,
+
+    #[pyo3(get)]
+    pub score: f32,
+
+    #[pyo3(get)]
+    pub chunk_count: usize,
+}
+
+#[pymethods]
+impl PyDocumentSummary {
+    fn __repr__(&self) -> String {
+        format!(
+            "DocumentSummary(id='{}', score={:.4}, chunks={})",
+            self.id, self.score, self.chunk_count
+        )
+    }
+}
+
+/// Index statistics
+#[pyclass(name = "HatStats")]
+#[derive(Clone)]
+pub struct PyHatStats {
+    #[pyo3(get)]
+    pub global_count: usize,
+
+    #[pyo3(get)]
+    pub session_count: usize,
+
+    #[pyo3(get)]
+    pub document_count: usize,
+
+    #[pyo3(get)]
+    pub chunk_count: usize,
+}
+
+#[pymethods]
+impl PyHatStats {
+    /// Total number of indexed points
+    #[getter]
+    fn total_points(&self) -> usize {
+        self.chunk_count
+    }
+
+    fn __repr__(&self) -> String {
+        format!(
+            "HatStats(points={}, sessions={}, documents={}, chunks={})",
+            self.chunk_count, self.session_count, self.document_count, self.chunk_count
+        )
+    }
+}
+
+/// Hierarchical Attention Tree Index
+///
+/// A semantic memory index optimized for conversation history retrieval.
+/// Uses hierarchical structure (session -> document -> chunk) to enable
+/// O(log n) queries while maintaining high recall.
+#[pyclass(name = "HatIndex")]
+pub struct PyHatIndex {
+    inner: RustHatIndex,
+}
+
+#[pymethods]
+impl PyHatIndex {
+    /// Create a new HAT index with cosine similarity
+    ///
+    /// Args:
+    ///     dimensionality: Number of embedding dimensions (e.g., 1536 for OpenAI)
+    #[staticmethod]
+    fn cosine(dimensionality: usize) -> Self {
+        Self {
+            inner: RustHatIndex::cosine(dimensionality),
+        }
+    }
+
+    /// Create a new HAT index with custom configuration
+    ///
+    /// Args:
+    ///     dimensionality: Number of embedding dimensions
+    ///     config: HatConfig instance
+    #[staticmethod]
+    fn with_config(dimensionality: usize, config: &PyHatConfig) -> Self {
+        Self {
+            inner: RustHatIndex::cosine(dimensionality).with_config(config.inner.clone()),
+        }
+    }
+
+    /// Add an embedding to the index
+    ///
+    /// Args:
+    ///     embedding: List of floats (must match dimensionality)
+    ///
+    /// Returns:
+    ///     str: The generated ID as a hex string
+    fn add(&mut self, embedding: Vec<f32>) -> PyResult<String> {
+        let point = Point::new(embedding);
+        let id = Id::now();
+
+        self.inner.add(id, &point)
+            .map_err(|e| PyValueError::new_err(format!("{}", e)))?;
+
+        Ok(format!("{}", id))
+    }
+
+    /// Add an embedding with a custom ID
+    ///
+    /// Args:
+    ///     id_hex: 32-character hex string for the ID
+    ///     embedding: List of floats (must match dimensionality)
+    fn add_with_id(&mut self, id_hex: &str, embedding: Vec<f32>) -> PyResult<()> {
+        let id = parse_id_hex(id_hex)?;
+        let point = Point::new(embedding);
+
+        self.inner.add(id, &point)
+            .map_err(|e| PyValueError::new_err(format!("{}", e)))?;
+
+        Ok(())
+    }
+
+    /// Find k nearest neighbors to a query embedding
+    ///
+    /// Args:
+    ///     query: Query embedding (list of floats)
+    ///     k: Number of results to return
+    ///
+    /// Returns:
+    ///     List[SearchResult]: Results sorted by relevance (best first)
+    fn near(&self, query: Vec<f32>, k: usize) -> PyResult<Vec<PySearchResult>> {
+        let point = Point::new(query);
+
+        let results = self.inner.near(&point, k)
+            .map_err(|e| PyValueError::new_err(format!("{}", e)))?;
+
+        Ok(results.into_iter().map(|r| PySearchResult {
+            id: format!("{}", r.id),
+            score: r.score,
+        }).collect())
+    }
+
+    /// Start a new session (conversation boundary)
+    ///
+    /// Call this when starting a new conversation or context.
+    fn new_session(&mut self) {
+        self.inner.new_session();
+    }
+
+    /// Start a new document within the current session
+    ///
+    /// Call this for logical groupings within a conversation
+    /// (e.g., topic change, user turn).
+    fn new_document(&mut self) {
+        self.inner.new_document();
+    }
+
+    /// Get index statistics
+    fn stats(&self) -> PyHatStats {
+        let s = self.inner.stats();
+        PyHatStats {
+            global_count: s.global_count,
+            session_count: s.session_count,
+            document_count: s.document_count,
+            chunk_count: s.chunk_count,
+        }
+    }
+
+    /// Get the number of indexed points
+    fn __len__(&self) -> usize {
+        self.inner.len()
+    }
+
+    /// Check if the index is empty
+    fn is_empty(&self) -> bool {
+        self.inner.is_empty()
+    }
+
+    /// Remove a point by ID
+    ///
+    /// Args:
+    ///     id_hex: 32-character hex string for the ID
+    fn remove(&mut self, id_hex: &str) -> PyResult<()> {
+        let id = parse_id_hex(id_hex)?;
+
+        self.inner.remove(id)
+            .map_err(|e| PyValueError::new_err(format!("{}", e)))?;
+
+        Ok(())
+    }
+
+    /// Find similar sessions (coarse-grained search)
+    ///
+    /// Args:
+    ///     query: Query embedding
+    ///     k: Number of sessions to return
+    ///
+    /// Returns:
+    ///     List[SessionSummary]: Most relevant sessions
+    fn near_sessions(&self, query: Vec<f32>, k: usize) -> PyResult<Vec<PySessionSummary>> {
+        let point = Point::new(query);
+
+        let results = self.inner.near_sessions(&point, k)
+            .map_err(|e| PyValueError::new_err(format!("{}", e)))?;
+
+        Ok(results.into_iter().map(|s| PySessionSummary {
+            id: format!("{}", s.id),
+            score: s.score,
+            chunk_count: s.chunk_count,
+            timestamp_ms: s.timestamp,
+        }).collect())
+    }
+
+    /// Find similar documents within a session
+    ///
+    /// Args:
+    ///     session_id: Session ID (hex string)
+    ///     query: Query embedding
+    ///     k: Number of documents to return
+    ///
+    /// Returns:
+    ///     List[DocumentSummary]: Most relevant documents in the session
+    fn near_documents(&self, session_id: &str, query: Vec<f32>, k: usize) -> PyResult<Vec<PyDocumentSummary>> {
+        let sid = parse_id_hex(session_id)?;
+        let point = Point::new(query);
+
+        let results = self.inner.near_documents(sid, &point, k)
+            .map_err(|e| PyValueError::new_err(format!("{}", e)))?;
+
+        Ok(results.into_iter().map(|d| PyDocumentSummary {
+            id: format!("{}", d.id),
+            score: d.score,
+            chunk_count: d.chunk_count,
+        }).collect())
+    }
+
+    /// Find chunks within a specific document
+    ///
+    /// Args:
+    ///     doc_id: Document ID (hex string)
+    ///     query: Query embedding
+    ///     k: Number of results to return
+    ///
+    /// Returns:
+    ///     List[SearchResult]: Most relevant chunks in the document
+    fn near_in_document(&self, doc_id: &str, query: Vec<f32>, k: usize) -> PyResult<Vec<PySearchResult>> {
+        let did = parse_id_hex(doc_id)?;
+        let point = Point::new(query);
+
+        let results = self.inner.near_in_document(did, &point, k)
+            .map_err(|e| PyValueError::new_err(format!("{}", e)))?;
+
+        Ok(results.into_iter().map(|r| PySearchResult {
+            id: format!("{}", r.id),
+            score: r.score,
+        }).collect())
+    }
+
+    /// Run light consolidation (background maintenance)
+    ///
+    /// This optimizes the index structure. Call periodically
+    /// (e.g., after every 100 inserts).
+    fn consolidate(&mut self) {
+        self.inner.consolidate(ConsolidationConfig::light());
+    }
+
+    /// Run full consolidation (more thorough optimization)
+    fn consolidate_full(&mut self) {
+        self.inner.consolidate(ConsolidationConfig::full());
+    }
+
+    /// Save the index to a file
+    ///
+    /// Args:
+    ///     path: File path to save to
+    fn save(&self, path: &str) -> PyResult<()> {
+        self.inner.save_to_file(std::path::Path::new(path))
+            .map_err(|e| PyIOError::new_err(format!("{}", e)))
+    }
+
+    /// Load an index from a file
+    ///
+    /// Args:
+    ///     path: File path to load from
+    ///
+    /// Returns:
+    ///     HatIndex: The loaded index
+    #[staticmethod]
+    fn load(path: &str) -> PyResult<Self> {
+        let inner = RustHatIndex::load_from_file(std::path::Path::new(path))
+            .map_err(|e| PyIOError::new_err(format!("{}", e)))?;
+
+        Ok(Self { inner })
+    }
+
+    /// Serialize the index to bytes
+    ///
+    /// Returns:
+    ///     bytes: Serialized index data
+    fn to_bytes<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, pyo3::types::PyBytes>> {
+        let data = self.inner.to_bytes()
+            .map_err(|e| PyIOError::new_err(format!("{}", e)))?;
+        Ok(pyo3::types::PyBytes::new_bound(py, &data))
+    }
+
+    /// Load an index from bytes
+    ///
+    /// Args:
+    ///     data: Serialized index data
+    ///
+    /// Returns:
+    ///     HatIndex: The loaded index
+    #[staticmethod]
+    fn from_bytes(data: &[u8]) -> PyResult<Self> {
+        let inner = RustHatIndex::from_bytes(data)
+            .map_err(|e| PyIOError::new_err(format!("{}", e)))?;
+
+        Ok(Self { inner })
+    }
+
+    fn __repr__(&self) -> String {
+        let stats = self.inner.stats();
+        format!(
+            "HatIndex(points={}, sessions={})",
+            stats.chunk_count, stats.session_count
+        )
+    }
+}
+
+/// Parse a hex string to an Id
+fn parse_id_hex(hex: &str) -> PyResult<Id> {
+    if hex.len() != 32 {
+        return Err(PyValueError::new_err(
+            format!("ID must be 32 hex characters, got {}", hex.len())
+        ));
+    }
+
+    let mut bytes = [0u8; 16];
+    for (i, chunk) in hex.as_bytes().chunks(2).enumerate() {
+        let high = hex_char_to_nibble(chunk[0])?;
+        let low = hex_char_to_nibble(chunk[1])?;
+        bytes[i] = (high << 4) | low;
+    }
+
+    Ok(Id::from_bytes(bytes))
+}
+
+fn hex_char_to_nibble(c: u8) -> PyResult<u8> {
+    match c {
+        b'0'..=b'9' => Ok(c - b'0'),
+        b'a'..=b'f' => Ok(c - b'a' + 10),
+        b'A'..=b'F' => Ok(c - b'A' + 10),
+        _ => Err(PyValueError::new_err(format!("Invalid hex character: {}", c as char))),
+    }
+}
+
+/// ARMS-HAT Python module
+#[pymodule]
+fn arms_hat(m: &Bound<'_, PyModule>) -> PyResult<()> {
+    m.add_class::<PyHatIndex>()?;
+    m.add_class::<PyHatConfig>()?;
+    m.add_class::<PySearchResult>()?;
+    m.add_class::<PySessionSummary>()?;
+    m.add_class::<PyDocumentSummary>()?;
+    m.add_class::<PyHatStats>()?;
+
+    // Add module docstring
+    m.add("__doc__", "ARMS-HAT: Hierarchical Attention Tree for AI memory retrieval")?;
+    m.add("__version__", env!("CARGO_PKG_VERSION"))?;
+
+    Ok(())
+}

src/adapters/storage/memory.rs

@@ -0,0 +1,253 @@
+//! # Memory Storage Adapter
+//!
+//! In-memory storage using HashMap.
+//! Fast, but volatile (data lost on shutdown).
+//!
+//! Good for:
+//! - Testing
+//! - Hot tier storage
+//! - Small datasets
+
+use std::collections::HashMap;
+
+use crate::core::{Blob, Id, PlacedPoint, Point};
+use crate::ports::{Place, PlaceError, PlaceResult};
+
+/// In-memory storage adapter
+pub struct MemoryStorage {
+    /// The stored points
+    points: HashMap<Id, PlacedPoint>,
+
+    /// Expected dimensionality
+    dimensionality: usize,
+
+    /// Maximum capacity in bytes (0 = unlimited)
+    capacity: usize,
+
+    /// Current size in bytes
+    current_size: usize,
+}
+
+impl MemoryStorage {
+    /// Create a new memory storage with specified dimensionality
+    pub fn new(dimensionality: usize) -> Self {
+        Self {
+            points: HashMap::new(),
+            dimensionality,
+            capacity: 0,
+            current_size: 0,
+        }
+    }
+
+    /// Create with a capacity limit
+    pub fn with_capacity(dimensionality: usize, capacity: usize) -> Self {
+        Self {
+            points: HashMap::new(),
+            dimensionality,
+            capacity,
+            current_size: 0,
+        }
+    }
+
+    /// Calculate size of a placed point in bytes
+    fn point_size(point: &PlacedPoint) -> usize {
+        // Id: 16 bytes
+        // Point: dims.len() * 4 bytes (f32)
+        // Blob: data.len() bytes
+        // Overhead: ~48 bytes for struct padding and HashMap entry
+        16 + (point.point.dimensionality() * 4) + point.blob.size() + 48
+    }
+}
+
+impl Place for MemoryStorage {
+    fn place(&mut self, point: Point, blob: Blob) -> PlaceResult<Id> {
+        // Check dimensionality
+        if point.dimensionality() != self.dimensionality {
+            return Err(PlaceError::DimensionalityMismatch {
+                expected: self.dimensionality,
+                got: point.dimensionality(),
+            });
+        }
+
+        let id = Id::now();
+        let placed = PlacedPoint::new(id, point, blob);
+
+        // Check capacity
+        let size = Self::point_size(&placed);
+        if self.capacity > 0 && self.current_size + size > self.capacity {
+            return Err(PlaceError::CapacityExceeded);
+        }
+
+        self.current_size += size;
+        self.points.insert(id, placed);
+
+        Ok(id)
+    }
+
+    fn place_with_id(&mut self, id: Id, point: Point, blob: Blob) -> PlaceResult<()> {
+        // Check dimensionality
+        if point.dimensionality() != self.dimensionality {
+            return Err(PlaceError::DimensionalityMismatch {
+                expected: self.dimensionality,
+                got: point.dimensionality(),
+            });
+        }
+
+        // Check for duplicates
+        if self.points.contains_key(&id) {
+            return Err(PlaceError::DuplicateId(id));
+        }
+
+        let placed = PlacedPoint::new(id, point, blob);
+
+        // Check capacity
+        let size = Self::point_size(&placed);
+        if self.capacity > 0 && self.current_size + size > self.capacity {
+            return Err(PlaceError::CapacityExceeded);
+        }
+
+        self.current_size += size;
+        self.points.insert(id, placed);
+
+        Ok(())
+    }
+
+    fn remove(&mut self, id: Id) -> Option<PlacedPoint> {
+        if let Some(placed) = self.points.remove(&id) {
+            self.current_size -= Self::point_size(&placed);
+            Some(placed)
+        } else {
+            None
+        }
+    }
+
+    fn get(&self, id: Id) -> Option<&PlacedPoint> {
+        self.points.get(&id)
+    }
+
+    fn len(&self) -> usize {
+        self.points.len()
+    }
+
+    fn iter(&self) -> Box<dyn Iterator<Item = &PlacedPoint> + '_> {
+        Box::new(self.points.values())
+    }
+
+    fn size_bytes(&self) -> usize {
+        self.current_size
+    }
+
+    fn clear(&mut self) {
+        self.points.clear();
+        self.current_size = 0;
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_memory_storage_place() {
+        let mut storage = MemoryStorage::new(3);
+
+        let point = Point::new(vec![1.0, 2.0, 3.0]);
+        let blob = Blob::from_str("test");
+
+        let id = storage.place(point, blob).unwrap();
+
+        assert_eq!(storage.len(), 1);
+        assert!(storage.contains(id));
+    }
+
+    #[test]
+    fn test_memory_storage_get() {
+        let mut storage = MemoryStorage::new(3);
+
+        let point = Point::new(vec![1.0, 2.0, 3.0]);
+        let blob = Blob::from_str("hello");
+
+        let id = storage.place(point, blob).unwrap();
+
+        let retrieved = storage.get(id).unwrap();
+        assert_eq!(retrieved.blob.as_str(), Some("hello"));
+    }
+
+    #[test]
+    fn test_memory_storage_remove() {
+        let mut storage = MemoryStorage::new(3);
+
+        let point = Point::new(vec![1.0, 2.0, 3.0]);
+        let id = storage.place(point, Blob::empty()).unwrap();
+
+        assert_eq!(storage.len(), 1);
+
+        let removed = storage.remove(id);
+        assert!(removed.is_some());
+        assert_eq!(storage.len(), 0);
+        assert!(!storage.contains(id));
+    }
+
+    #[test]
+    fn test_memory_storage_dimensionality_check() {
+        let mut storage = MemoryStorage::new(3);
+
+        let wrong_dims = Point::new(vec![1.0, 2.0]); // 2 dims, expected 3
+
+        let result = storage.place(wrong_dims, Blob::empty());
+
+        match result {
+            Err(PlaceError::DimensionalityMismatch { expected, got }) => {
+                assert_eq!(expected, 3);
+                assert_eq!(got, 2);
+            }
+            _ => panic!("Expected DimensionalityMismatch error"),
+        }
+    }
+
+    #[test]
+    fn test_memory_storage_capacity() {
+        // Small capacity - enough for one point but not two
+        // Point size: 16 (id) + 12 (3 f32s) + 10 (blob) + 48 (overhead) = 86 bytes
+        let mut storage = MemoryStorage::with_capacity(3, 150);
+
+        let point = Point::new(vec![1.0, 2.0, 3.0]);
+        let blob = Blob::new(vec![0u8; 10]); // Small blob
+
+        // First one should succeed
+        storage.place(point.clone(), blob.clone()).unwrap();
+
+        // Second should fail due to capacity
+        let result = storage.place(point, blob);
+        assert!(matches!(result, Err(PlaceError::CapacityExceeded)));
+    }
+
+    #[test]
+    fn test_memory_storage_clear() {
+        let mut storage = MemoryStorage::new(3);
+
+        for i in 0..10 {
+            let point = Point::new(vec![i as f32, 0.0, 0.0]);
+            storage.place(point, Blob::empty()).unwrap();
+        }
+
+        assert_eq!(storage.len(), 10);
+        assert!(storage.size_bytes() > 0);
+
+        storage.clear();
+
+        assert_eq!(storage.len(), 0);
+        assert_eq!(storage.size_bytes(), 0);
+    }
+
+    #[test]
+    fn test_memory_storage_iter() {
+        let mut storage = MemoryStorage::new(2);
+
+        storage.place(Point::new(vec![1.0, 0.0]), Blob::empty()).unwrap();
+        storage.place(Point::new(vec![0.0, 1.0]), Blob::empty()).unwrap();
+
+        let points: Vec<_> = storage.iter().collect();
+        assert_eq!(points.len(), 2);
+    }
+}

src/adapters/storage/mod.rs

@@ -0,0 +1,15 @@
+//! # Storage Adapters
+//!
+//! Implementations of the Place port for different storage backends.
+//!
+//! Available adapters:
+//! - `MemoryStorage` - In-memory HashMap (fast, volatile)
+//! - `NvmeStorage` - Memory-mapped NVMe (persistent, large) [TODO]
+
+mod memory;
+
+pub use memory::MemoryStorage;
+
+// TODO: Add NVMe adapter
+// mod nvme;
+// pub use nvme::NvmeStorage;

src/core/blob.rs

@@ -0,0 +1,152 @@
+//! # Blob
+//!
+//! Raw payload data attached to a point.
+//!
+//! ARMS doesn't interpret this data - it's yours.
+//! Could be: tensor bytes, text, compressed state, anything.
+//!
+//! Separation of concerns:
+//! - Point = WHERE (position in space)
+//! - Blob = WHAT (the actual data)
+
+/// Raw data attached to a point
+///
+/// ARMS stores this opaquely. You define what it means.
+#[derive(Clone, Debug, PartialEq)]
+pub struct Blob {
+    data: Vec<u8>,
+}
+
+impl Blob {
+    /// Create a new blob from bytes
+    ///
+    /// # Example
+    /// ```
+    /// use arms::Blob;
+    /// let blob = Blob::new(vec![1, 2, 3, 4]);
+    /// assert_eq!(blob.size(), 4);
+    /// ```
+    pub fn new(data: Vec<u8>) -> Self {
+        Self { data }
+    }
+
+    /// Create an empty blob
+    ///
+    /// Useful when you only care about position, not payload.
+    pub fn empty() -> Self {
+        Self { data: vec![] }
+    }
+
+    /// Create a blob from a string (UTF-8 bytes)
+    ///
+    /// # Example
+    /// ```
+    /// use arms::Blob;
+    /// let blob = Blob::from_str("hello");
+    /// assert_eq!(blob.as_str(), Some("hello"));
+    /// ```
+    pub fn from_str(s: &str) -> Self {
+        Self {
+            data: s.as_bytes().to_vec(),
+        }
+    }
+
+    /// Get the raw bytes
+    pub fn data(&self) -> &[u8] {
+        &self.data
+    }
+
+    /// Get the size in bytes
+    pub fn size(&self) -> usize {
+        self.data.len()
+    }
+
+    /// Check if the blob is empty
+    pub fn is_empty(&self) -> bool {
+        self.data.is_empty()
+    }
+
+    /// Try to interpret as UTF-8 string
+    pub fn as_str(&self) -> Option<&str> {
+        std::str::from_utf8(&self.data).ok()
+    }
+
+    /// Consume and return the inner data
+    pub fn into_inner(self) -> Vec<u8> {
+        self.data
+    }
+}
+
+impl From<Vec<u8>> for Blob {
+    fn from(data: Vec<u8>) -> Self {
+        Self::new(data)
+    }
+}
+
+impl From<&[u8]> for Blob {
+    fn from(data: &[u8]) -> Self {
+        Self::new(data.to_vec())
+    }
+}
+
+impl From<&str> for Blob {
+    fn from(s: &str) -> Self {
+        Self::from_str(s)
+    }
+}
+
+impl From<String> for Blob {
+    fn from(s: String) -> Self {
+        Self::new(s.into_bytes())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_blob_new() {
+        let blob = Blob::new(vec![1, 2, 3]);
+        assert_eq!(blob.data(), &[1, 2, 3]);
+        assert_eq!(blob.size(), 3);
+    }
+
+    #[test]
+    fn test_blob_empty() {
+        let blob = Blob::empty();
+        assert!(blob.is_empty());
+        assert_eq!(blob.size(), 0);
+    }
+
+    #[test]
+    fn test_blob_from_str() {
+        let blob = Blob::from_str("hello world");
+        assert_eq!(blob.as_str(), Some("hello world"));
+    }
+
+    #[test]
+    fn test_blob_as_str_invalid_utf8() {
+        let blob = Blob::new(vec![0xff, 0xfe]);
+        assert_eq!(blob.as_str(), None);
+    }
+
+    #[test]
+    fn test_blob_from_conversions() {
+        let blob1: Blob = vec![1, 2, 3].into();
+        assert_eq!(blob1.size(), 3);
+
+        let blob2: Blob = "test".into();
+        assert_eq!(blob2.as_str(), Some("test"));
+
+        let blob3: Blob = String::from("test").into();
+        assert_eq!(blob3.as_str(), Some("test"));
+    }
+
+    #[test]
+    fn test_blob_into_inner() {
+        let blob = Blob::new(vec![1, 2, 3]);
+        let data = blob.into_inner();
+        assert_eq!(data, vec![1, 2, 3]);
+    }
+}

src/core/config.rs

@@ -0,0 +1,177 @@
+//! # Configuration
+//!
+//! ARMS configuration - define your space.
+//!
+//! Everything is configurable, not hardcoded:
+//! - Dimensionality
+//! - Proximity function
+//! - Merge function
+//! - Tier settings
+//!
+//! "If we say it's a rock now, in 2 years it can never be carved into a wheel."
+
+use super::proximity::{Cosine, Proximity};
+use super::merge::{Mean, Merge};
+use std::sync::Arc;
+
+/// Main ARMS configuration
+///
+/// Defines the dimensional space and default operations.
+#[derive(Clone)]
+pub struct ArmsConfig {
+    /// Dimensionality of the space
+    ///
+    /// Set this to match your model's hidden size.
+    /// Examples: 768 (BERT), 1024 (GPT-2 medium), 4096 (large models)
+    pub dimensionality: usize,
+
+    /// Proximity function for similarity calculations
+    pub proximity: Arc<dyn Proximity>,
+
+    /// Merge function for hierarchical composition
+    pub merge: Arc<dyn Merge>,
+
+    /// Whether to normalize points on insertion
+    pub normalize_on_insert: bool,
+
+    /// Tier configuration
+    pub tiers: TierConfig,
+}
+
+impl ArmsConfig {
+    /// Create a new configuration with specified dimensionality
+    ///
+    /// Uses default proximity (Cosine) and merge (Mean) functions.
+    pub fn new(dimensionality: usize) -> Self {
+        Self {
+            dimensionality,
+            proximity: Arc::new(Cosine),
+            merge: Arc::new(Mean),
+            normalize_on_insert: true,
+            tiers: TierConfig::default(),
+        }
+    }
+
+    /// Set a custom proximity function
+    pub fn with_proximity<P: Proximity + 'static>(mut self, proximity: P) -> Self {
+        self.proximity = Arc::new(proximity);
+        self
+    }
+
+    /// Set a custom merge function
+    pub fn with_merge<M: Merge + 'static>(mut self, merge: M) -> Self {
+        self.merge = Arc::new(merge);
+        self
+    }
+
+    /// Set normalization behavior
+    pub fn with_normalize(mut self, normalize: bool) -> Self {
+        self.normalize_on_insert = normalize;
+        self
+    }
+
+    /// Set tier configuration
+    pub fn with_tiers(mut self, tiers: TierConfig) -> Self {
+        self.tiers = tiers;
+        self
+    }
+}
+
+impl Default for ArmsConfig {
+    /// Default configuration: 768 dimensions, cosine proximity, mean merge
+    fn default() -> Self {
+        Self::new(768)
+    }
+}
+
+/// Tier configuration for storage management
+#[derive(Clone, Debug)]
+pub struct TierConfig {
+    /// Hot tier (RAM) capacity in bytes
+    pub hot_capacity: usize,
+
+    /// Warm tier (NVMe) capacity in bytes
+    pub warm_capacity: usize,
+
+    /// Number of accesses before promoting to hotter tier
+    pub promote_after_accesses: u32,
+
+    /// Milliseconds since last access before evicting to colder tier
+    pub evict_after_ms: u64,
+}
+
+impl TierConfig {
+    /// Create a new tier configuration
+    pub fn new(hot_capacity: usize, warm_capacity: usize) -> Self {
+        Self {
+            hot_capacity,
+            warm_capacity,
+            promote_after_accesses: 3,
+            evict_after_ms: 3600 * 1000, // 1 hour
+        }
+    }
+
+    /// Tiny config for testing
+    pub fn tiny() -> Self {
+        Self {
+            hot_capacity: 1024 * 1024,        // 1 MB
+            warm_capacity: 10 * 1024 * 1024,  // 10 MB
+            promote_after_accesses: 2,
+            evict_after_ms: 60 * 1000, // 1 minute
+        }
+    }
+}
+
+impl Default for TierConfig {
+    fn default() -> Self {
+        Self {
+            hot_capacity: 1024 * 1024 * 1024,       // 1 GB
+            warm_capacity: 100 * 1024 * 1024 * 1024, // 100 GB
+            promote_after_accesses: 3,
+            evict_after_ms: 3600 * 1000, // 1 hour
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::core::proximity::Euclidean;
+    use crate::core::merge::MaxPool;
+
+    #[test]
+    fn test_default_config() {
+        let config = ArmsConfig::default();
+        assert_eq!(config.dimensionality, 768);
+        assert!(config.normalize_on_insert);
+        assert_eq!(config.proximity.name(), "cosine");
+        assert_eq!(config.merge.name(), "mean");
+    }
+
+    #[test]
+    fn test_custom_config() {
+        let config = ArmsConfig::new(4096)
+            .with_proximity(Euclidean)
+            .with_merge(MaxPool)
+            .with_normalize(false);
+
+        assert_eq!(config.dimensionality, 4096);
+        assert!(!config.normalize_on_insert);
+        assert_eq!(config.proximity.name(), "euclidean");
+        assert_eq!(config.merge.name(), "max_pool");
+    }
+
+    #[test]
+    fn test_tier_config() {
+        let tiers = TierConfig::new(1024, 2048);
+        assert_eq!(tiers.hot_capacity, 1024);
+        assert_eq!(tiers.warm_capacity, 2048);
+    }
+
+    #[test]
+    fn test_tier_tiny() {
+        let tiers = TierConfig::tiny();
+        assert_eq!(tiers.hot_capacity, 1024 * 1024);
+        assert_eq!(tiers.evict_after_ms, 60 * 1000);
+    }
+}

src/core/id.rs

@@ -0,0 +1,169 @@
+//! # Id
+//!
+//! Unique identifier for placed points.
+//!
+//! Format: 128 bits = [timestamp_ms:48][counter:16][random:64]
+//! - Timestamp provides natural temporal ordering
+//! - Counter prevents collisions within same millisecond
+//! - Random portion adds uniqueness
+//! - Sortable by time when compared
+//! - No external dependencies (not UUID, just bytes)
+
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+/// Global counter for uniqueness within same millisecond
+static COUNTER: AtomicU64 = AtomicU64::new(0);
+
+/// Unique identifier for a placed point
+///
+/// 128 bits, timestamp-prefixed for natural time ordering.
+#[derive(Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Debug)]
+pub struct Id([u8; 16]);
+
+impl Id {
+    /// Generate a new Id for the current moment
+    ///
+    /// Uses current timestamp + counter + random bytes for uniqueness.
+    pub fn now() -> Self {
+        let timestamp = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_millis() as u64;
+
+        // Atomically increment counter for uniqueness
+        let counter = COUNTER.fetch_add(1, Ordering::Relaxed);
+
+        let mut bytes = [0u8; 16];
+
+        // First 6 bytes: timestamp (48 bits)
+        bytes[0] = (timestamp >> 40) as u8;
+        bytes[1] = (timestamp >> 32) as u8;
+        bytes[2] = (timestamp >> 24) as u8;
+        bytes[3] = (timestamp >> 16) as u8;
+        bytes[4] = (timestamp >> 8) as u8;
+        bytes[5] = timestamp as u8;
+
+        // Next 2 bytes: counter (16 bits) - ensures uniqueness within millisecond
+        bytes[6] = (counter >> 8) as u8;
+        bytes[7] = counter as u8;
+
+        // Remaining 8 bytes: pseudo-random based on timestamp and counter
+        let random_seed = timestamp
+            .wrapping_mul(6364136223846793005)
+            .wrapping_add(counter);
+        bytes[8] = (random_seed >> 56) as u8;
+        bytes[9] = (random_seed >> 48) as u8;
+        bytes[10] = (random_seed >> 40) as u8;
+        bytes[11] = (random_seed >> 32) as u8;
+        bytes[12] = (random_seed >> 24) as u8;
+        bytes[13] = (random_seed >> 16) as u8;
+        bytes[14] = (random_seed >> 8) as u8;
+        bytes[15] = random_seed as u8;
+
+        Self(bytes)
+    }
+
+    /// Create an Id from raw bytes
+    pub fn from_bytes(bytes: [u8; 16]) -> Self {
+        Self(bytes)
+    }
+
+    /// Get the raw bytes
+    pub fn as_bytes(&self) -> &[u8; 16] {
+        &self.0
+    }
+
+    /// Extract the timestamp component (milliseconds since epoch)
+    pub fn timestamp_ms(&self) -> u64 {
+        ((self.0[0] as u64) << 40)
+            | ((self.0[1] as u64) << 32)
+            | ((self.0[2] as u64) << 24)
+            | ((self.0[3] as u64) << 16)
+            | ((self.0[4] as u64) << 8)
+            | (self.0[5] as u64)
+    }
+
+    /// Create a nil/zero Id (useful for testing)
+    pub fn nil() -> Self {
+        Self([0u8; 16])
+    }
+
+    /// Check if this is a nil Id
+    pub fn is_nil(&self) -> bool {
+        self.0 == [0u8; 16]
+    }
+}
+
+impl std::fmt::Display for Id {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        // Display as hex string
+        for byte in &self.0 {
+            write!(f, "{:02x}", byte)?;
+        }
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::thread;
+    use std::time::Duration;
+
+    #[test]
+    fn test_id_creation() {
+        let id = Id::now();
+        assert!(!id.is_nil());
+    }
+
+    #[test]
+    fn test_id_timestamp() {
+        let before = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_millis() as u64;
+
+        let id = Id::now();
+
+        let after = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_millis() as u64;
+
+        let ts = id.timestamp_ms();
+        assert!(ts >= before);
+        assert!(ts <= after);
+    }
+
+    #[test]
+    fn test_id_ordering() {
+        let id1 = Id::now();
+        thread::sleep(Duration::from_millis(2));
+        let id2 = Id::now();
+
+        // id2 should be greater (later timestamp)
+        assert!(id2 > id1);
+    }
+
+    #[test]
+    fn test_id_from_bytes() {
+        let bytes = [1u8, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16];
+        let id = Id::from_bytes(bytes);
+        assert_eq!(id.as_bytes(), &bytes);
+    }
+
+    #[test]
+    fn test_id_nil() {
+        let nil = Id::nil();
+        assert!(nil.is_nil());
+        assert_eq!(nil.timestamp_ms(), 0);
+    }
+
+    #[test]
+    fn test_id_display() {
+        let id = Id::from_bytes([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]);
+        let display = format!("{}", id);
+        assert_eq!(display, "000102030405060708090a0b0c0d0e0f");
+    }
+}

src/core/merge.rs

@@ -0,0 +1,335 @@
+//! # Merge
+//!
+//! Trait and implementations for composing multiple points into one.
+//!
+//! This is one of the five primitives of ARMS:
+//! `Merge: fn(points) -> point` - Compose together
+//!
+//! Merge is used for hierarchical composition:
+//! - Chunks → Document
+//! - Documents → Session
+//! - Sessions → Domain
+//!
+//! Merge functions are pluggable - use whichever fits your use case.
+
+use super::Point;
+
+/// Trait for merging multiple points into one
+///
+/// Used for hierarchical composition and aggregation.
+pub trait Merge: Send + Sync {
+    /// Merge multiple points into a single point
+    ///
+    /// All points must have the same dimensionality.
+    /// The slice must not be empty.
+    fn merge(&self, points: &[Point]) -> Point;
+
+    /// Name of this merge function (for debugging/config)
+    fn name(&self) -> &'static str;
+}
+
+// ============================================================================
+// IMPLEMENTATIONS
+// ============================================================================
+
+/// Mean (average) of all points
+///
+/// The centroid of the input points.
+/// Good default for most hierarchical composition.
+#[derive(Clone, Copy, Debug, Default)]
+pub struct Mean;
+
+impl Merge for Mean {
+    fn merge(&self, points: &[Point]) -> Point {
+        assert!(!points.is_empty(), "Cannot merge empty slice");
+
+        let dims = points[0].dimensionality();
+        let n = points.len() as f32;
+
+        let mut result = vec![0.0; dims];
+        for p in points {
+            assert_eq!(
+                p.dimensionality(),
+                dims,
+                "All points must have same dimensionality"
+            );
+            for (r, d) in result.iter_mut().zip(p.dims()) {
+                *r += d / n;
+            }
+        }
+
+        Point::new(result)
+    }
+
+    fn name(&self) -> &'static str {
+        "mean"
+    }
+}
+
+/// Weighted mean of points
+///
+/// Each point contributes proportionally to its weight.
+/// Useful for recency weighting, importance weighting, etc.
+#[derive(Clone, Debug)]
+pub struct WeightedMean {
+    weights: Vec<f32>,
+}
+
+impl WeightedMean {
+    /// Create a new weighted mean with given weights
+    ///
+    /// Weights will be normalized (divided by sum) during merge.
+    pub fn new(weights: Vec<f32>) -> Self {
+        Self { weights }
+    }
+
+    /// Create with uniform weights (equivalent to Mean)
+    pub fn uniform(n: usize) -> Self {
+        Self {
+            weights: vec![1.0; n],
+        }
+    }
+
+    /// Create with recency weighting (more recent = higher weight)
+    ///
+    /// `decay` should be in (0, 1). Smaller = faster decay.
+    /// First point is oldest, last is most recent.
+    pub fn recency(n: usize, decay: f32) -> Self {
+        let weights: Vec<f32> = (0..n).map(|i| decay.powi((n - 1 - i) as i32)).collect();
+        Self { weights }
+    }
+}
+
+impl Merge for WeightedMean {
+    fn merge(&self, points: &[Point]) -> Point {
+        assert!(!points.is_empty(), "Cannot merge empty slice");
+        assert_eq!(
+            points.len(),
+            self.weights.len(),
+            "Number of points must match number of weights"
+        );
+
+        let dims = points[0].dimensionality();
+        let total_weight: f32 = self.weights.iter().sum();
+
+        let mut result = vec![0.0; dims];
+        for (p, &w) in points.iter().zip(&self.weights) {
+            assert_eq!(
+                p.dimensionality(),
+                dims,
+                "All points must have same dimensionality"
+            );
+            let normalized_w = w / total_weight;
+            for (r, d) in result.iter_mut().zip(p.dims()) {
+                *r += d * normalized_w;
+            }
+        }
+
+        Point::new(result)
+    }
+
+    fn name(&self) -> &'static str {
+        "weighted_mean"
+    }
+}
+
+/// Max pooling across points
+///
+/// Takes the maximum value of each dimension across all points.
+/// Preserves the strongest activations.
+#[derive(Clone, Copy, Debug, Default)]
+pub struct MaxPool;
+
+impl Merge for MaxPool {
+    fn merge(&self, points: &[Point]) -> Point {
+        assert!(!points.is_empty(), "Cannot merge empty slice");
+
+        let dims = points[0].dimensionality();
+        let mut result = points[0].dims().to_vec();
+
+        for p in &points[1..] {
+            assert_eq!(
+                p.dimensionality(),
+                dims,
+                "All points must have same dimensionality"
+            );
+            for (r, d) in result.iter_mut().zip(p.dims()) {
+                *r = r.max(*d);
+            }
+        }
+
+        Point::new(result)
+    }
+
+    fn name(&self) -> &'static str {
+        "max_pool"
+    }
+}
+
+/// Min pooling across points
+///
+/// Takes the minimum value of each dimension across all points.
+#[derive(Clone, Copy, Debug, Default)]
+pub struct MinPool;
+
+impl Merge for MinPool {
+    fn merge(&self, points: &[Point]) -> Point {
+        assert!(!points.is_empty(), "Cannot merge empty slice");
+
+        let dims = points[0].dimensionality();
+        let mut result = points[0].dims().to_vec();
+
+        for p in &points[1..] {
+            assert_eq!(
+                p.dimensionality(),
+                dims,
+                "All points must have same dimensionality"
+            );
+            for (r, d) in result.iter_mut().zip(p.dims()) {
+                *r = r.min(*d);
+            }
+        }
+
+        Point::new(result)
+    }
+
+    fn name(&self) -> &'static str {
+        "min_pool"
+    }
+}
+
+/// Sum of all points (no averaging)
+///
+/// Simple additive composition.
+#[derive(Clone, Copy, Debug, Default)]
+pub struct Sum;
+
+impl Merge for Sum {
+    fn merge(&self, points: &[Point]) -> Point {
+        assert!(!points.is_empty(), "Cannot merge empty slice");
+
+        let dims = points[0].dimensionality();
+        let mut result = vec![0.0; dims];
+
+        for p in points {
+            assert_eq!(
+                p.dimensionality(),
+                dims,
+                "All points must have same dimensionality"
+            );
+            for (r, d) in result.iter_mut().zip(p.dims()) {
+                *r += d;
+            }
+        }
+
+        Point::new(result)
+    }
+
+    fn name(&self) -> &'static str {
+        "sum"
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_mean_single() {
+        let points = vec![Point::new(vec![1.0, 2.0, 3.0])];
+        let merged = Mean.merge(&points);
+        assert_eq!(merged.dims(), &[1.0, 2.0, 3.0]);
+    }
+
+    #[test]
+    fn test_mean_multiple() {
+        let points = vec![
+            Point::new(vec![1.0, 2.0]),
+            Point::new(vec![3.0, 4.0]),
+        ];
+        let merged = Mean.merge(&points);
+        assert_eq!(merged.dims(), &[2.0, 3.0]);
+    }
+
+    #[test]
+    fn test_weighted_mean() {
+        let points = vec![
+            Point::new(vec![0.0, 0.0]),
+            Point::new(vec![10.0, 10.0]),
+        ];
+        // Weight second point 3x more than first
+        let merger = WeightedMean::new(vec![1.0, 3.0]);
+        let merged = merger.merge(&points);
+        // (0*0.25 + 10*0.75, 0*0.25 + 10*0.75) = (7.5, 7.5)
+        assert!((merged.dims()[0] - 7.5).abs() < 0.0001);
+        assert!((merged.dims()[1] - 7.5).abs() < 0.0001);
+    }
+
+    #[test]
+    fn test_weighted_mean_recency() {
+        let merger = WeightedMean::recency(3, 0.5);
+        // decay = 0.5, n = 3
+        // weights: [0.5^2, 0.5^1, 0.5^0] = [0.25, 0.5, 1.0]
+        assert_eq!(merger.weights.len(), 3);
+        assert!((merger.weights[0] - 0.25).abs() < 0.0001);
+        assert!((merger.weights[1] - 0.5).abs() < 0.0001);
+        assert!((merger.weights[2] - 1.0).abs() < 0.0001);
+    }
+
+    #[test]
+    fn test_max_pool() {
+        let points = vec![
+            Point::new(vec![1.0, 5.0, 2.0]),
+            Point::new(vec![3.0, 2.0, 4.0]),
+            Point::new(vec![2.0, 3.0, 1.0]),
+        ];
+        let merged = MaxPool.merge(&points);
+        assert_eq!(merged.dims(), &[3.0, 5.0, 4.0]);
+    }
+
+    #[test]
+    fn test_min_pool() {
+        let points = vec![
+            Point::new(vec![1.0, 5.0, 2.0]),
+            Point::new(vec![3.0, 2.0, 4.0]),
+            Point::new(vec![2.0, 3.0, 1.0]),
+        ];
+        let merged = MinPool.merge(&points);
+        assert_eq!(merged.dims(), &[1.0, 2.0, 1.0]);
+    }
+
+    #[test]
+    fn test_sum() {
+        let points = vec![
+            Point::new(vec![1.0, 2.0]),
+            Point::new(vec![3.0, 4.0]),
+        ];
+        let merged = Sum.merge(&points);
+        assert_eq!(merged.dims(), &[4.0, 6.0]);
+    }
+
+    #[test]
+    fn test_merge_names() {
+        assert_eq!(Mean.name(), "mean");
+        assert_eq!(MaxPool.name(), "max_pool");
+        assert_eq!(MinPool.name(), "min_pool");
+        assert_eq!(Sum.name(), "sum");
+    }
+
+    #[test]
+    #[should_panic(expected = "Cannot merge empty")]
+    fn test_merge_empty_panics() {
+        let points: Vec<Point> = vec![];
+        Mean.merge(&points);
+    }
+
+    #[test]
+    #[should_panic(expected = "same dimensionality")]
+    fn test_merge_dimension_mismatch_panics() {
+        let points = vec![
+            Point::new(vec![1.0, 2.0]),
+            Point::new(vec![1.0, 2.0, 3.0]),
+        ];
+        Mean.merge(&points);
+    }
+}

src/core/mod.rs

@@ -0,0 +1,64 @@
+//! # Core Domain
+//!
+//! Pure math, no I/O. The foundation of ARMS.
+//!
+//! This module contains the fundamental types and operations:
+//! - `Point` - A position in dimensional space
+//! - `Id` - Unique identifier for placed points
+//! - `Blob` - Raw payload data
+//! - `Proximity` - Trait for measuring relatedness
+//! - `Merge` - Trait for composing points
+//!
+//! ## Design Principles
+//!
+//! - All functions are pure (deterministic, no side effects)
+//! - No I/O operations
+//! - No external dependencies beyond std
+//! - Fully testable in isolation
+
+mod point;
+mod id;
+mod blob;
+pub mod proximity;
+pub mod merge;
+pub mod config;
+
+// Re-exports
+pub use point::Point;
+pub use id::Id;
+pub use blob::Blob;
+
+/// A point that has been placed in the space
+#[derive(Clone)]
+pub struct PlacedPoint {
+    /// Unique identifier
+    pub id: Id,
+    /// Position in dimensional space
+    pub point: Point,
+    /// Attached payload
+    pub blob: Blob,
+}
+
+impl PlacedPoint {
+    /// Create a new placed point
+    pub fn new(id: Id, point: Point, blob: Blob) -> Self {
+        Self { id, point, blob }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_placed_point_creation() {
+        let id = Id::now();
+        let point = Point::new(vec![1.0, 2.0, 3.0]);
+        let blob = Blob::new(vec![1, 2, 3]);
+
+        let placed = PlacedPoint::new(id, point.clone(), blob);
+
+        assert_eq!(placed.point.dimensionality(), 3);
+        assert_eq!(placed.blob.size(), 3);
+    }
+}

src/core/point.rs

@@ -0,0 +1,186 @@
+//! # Point
+//!
+//! A position in dimensional space. The fundamental primitive.
+//!
+//! Dimensionality is NOT fixed - configure it for your model.
+//! 768-dim, 1024-dim, 4096-dim, or any size you need.
+//!
+//! The point IS the thought's position.
+//! The position IS its relationship to all other thoughts.
+
+/// A point in dimensional space
+#[derive(Clone, Debug, PartialEq)]
+pub struct Point {
+    dims: Vec<f32>,
+}
+
+impl Point {
+    /// Create a new point from a vector of dimensions
+    ///
+    /// # Example
+    /// ```
+    /// use arms::Point;
+    /// let p = Point::new(vec![1.0, 2.0, 3.0]);
+    /// assert_eq!(p.dimensionality(), 3);
+    /// ```
+    pub fn new(dims: Vec<f32>) -> Self {
+        Self { dims }
+    }
+
+    /// Create an origin point (all zeros) of given dimensionality
+    ///
+    /// # Example
+    /// ```
+    /// use arms::Point;
+    /// let origin = Point::origin(768);
+    /// assert_eq!(origin.dimensionality(), 768);
+    /// assert!(origin.dims().iter().all(|&x| x == 0.0));
+    /// ```
+    pub fn origin(dims: usize) -> Self {
+        Self {
+            dims: vec![0.0; dims],
+        }
+    }
+
+    /// Get the dimensionality of this point
+    pub fn dimensionality(&self) -> usize {
+        self.dims.len()
+    }
+
+    /// Access the dimensions as a slice
+    pub fn dims(&self) -> &[f32] {
+        &self.dims
+    }
+
+    /// Mutable access to dimensions
+    pub fn dims_mut(&mut self) -> &mut [f32] {
+        &mut self.dims
+    }
+
+    /// Calculate the magnitude (L2 norm) of this point
+    ///
+    /// # Example
+    /// ```
+    /// use arms::Point;
+    /// let p = Point::new(vec![3.0, 4.0]);
+    /// assert!((p.magnitude() - 5.0).abs() < 0.0001);
+    /// ```
+    pub fn magnitude(&self) -> f32 {
+        self.dims.iter().map(|x| x * x).sum::<f32>().sqrt()
+    }
+
+    /// Check if this point is normalized (magnitude ≈ 1.0)
+    pub fn is_normalized(&self) -> bool {
+        let mag = self.magnitude();
+        (mag - 1.0).abs() < 0.001
+    }
+
+    /// Return a normalized copy of this point
+    ///
+    /// If magnitude is zero, returns a clone of self.
+    ///
+    /// # Example
+    /// ```
+    /// use arms::Point;
+    /// let p = Point::new(vec![3.0, 4.0]);
+    /// let normalized = p.normalize();
+    /// assert!(normalized.is_normalized());
+    /// ```
+    pub fn normalize(&self) -> Self {
+        let mag = self.magnitude();
+        if mag == 0.0 {
+            return self.clone();
+        }
+        Self {
+            dims: self.dims.iter().map(|x| x / mag).collect(),
+        }
+    }
+
+    /// Add another point to this one (element-wise)
+    pub fn add(&self, other: &Point) -> Self {
+        assert_eq!(
+            self.dimensionality(),
+            other.dimensionality(),
+            "Points must have same dimensionality"
+        );
+        Self {
+            dims: self
+                .dims
+                .iter()
+                .zip(other.dims.iter())
+                .map(|(a, b)| a + b)
+                .collect(),
+        }
+    }
+
+    /// Scale this point by a scalar
+    pub fn scale(&self, scalar: f32) -> Self {
+        Self {
+            dims: self.dims.iter().map(|x| x * scalar).collect(),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_new_point() {
+        let p = Point::new(vec![1.0, 2.0, 3.0]);
+        assert_eq!(p.dimensionality(), 3);
+        assert_eq!(p.dims(), &[1.0, 2.0, 3.0]);
+    }
+
+    #[test]
+    fn test_origin() {
+        let origin = Point::origin(768);
+        assert_eq!(origin.dimensionality(), 768);
+        assert!(origin.dims().iter().all(|&x| x == 0.0));
+    }
+
+    #[test]
+    fn test_magnitude() {
+        let p = Point::new(vec![3.0, 4.0]);
+        assert!((p.magnitude() - 5.0).abs() < 0.0001);
+    }
+
+    #[test]
+    fn test_normalize() {
+        let p = Point::new(vec![3.0, 4.0]);
+        let normalized = p.normalize();
+        assert!(normalized.is_normalized());
+        assert!((normalized.dims()[0] - 0.6).abs() < 0.0001);
+        assert!((normalized.dims()[1] - 0.8).abs() < 0.0001);
+    }
+
+    #[test]
+    fn test_normalize_zero() {
+        let p = Point::origin(3);
+        let normalized = p.normalize();
+        assert_eq!(normalized.dims(), &[0.0, 0.0, 0.0]);
+    }
+
+    #[test]
+    fn test_add() {
+        let a = Point::new(vec![1.0, 2.0]);
+        let b = Point::new(vec![3.0, 4.0]);
+        let c = a.add(&b);
+        assert_eq!(c.dims(), &[4.0, 6.0]);
+    }
+
+    #[test]
+    fn test_scale() {
+        let p = Point::new(vec![1.0, 2.0]);
+        let scaled = p.scale(2.0);
+        assert_eq!(scaled.dims(), &[2.0, 4.0]);
+    }
+
+    #[test]
+    #[should_panic(expected = "same dimensionality")]
+    fn test_add_different_dims_panics() {
+        let a = Point::new(vec![1.0, 2.0]);
+        let b = Point::new(vec![1.0, 2.0, 3.0]);
+        let _ = a.add(&b);
+    }
+}

src/core/proximity.rs

@@ -0,0 +1,261 @@
+//! # Proximity
+//!
+//! Trait and implementations for measuring how related two points are.
+//!
+//! This is one of the five primitives of ARMS:
+//! `Proximity: fn(a, b) -> f32` - How related?
+//!
+//! Proximity functions are pluggable - use whichever fits your use case.
+
+use super::Point;
+
+/// Trait for measuring proximity between points
+///
+/// Higher values typically mean more similar/related.
+/// The exact semantics depend on the implementation.
+pub trait Proximity: Send + Sync {
+    /// Compute proximity between two points
+    ///
+    /// Both points must have the same dimensionality.
+    fn proximity(&self, a: &Point, b: &Point) -> f32;
+
+    /// Name of this proximity function (for debugging/config)
+    fn name(&self) -> &'static str;
+}
+
+// ============================================================================
+// IMPLEMENTATIONS
+// ============================================================================
+
+/// Cosine similarity
+///
+/// Measures the cosine of the angle between two vectors.
+/// Returns a value in [-1, 1] where 1 means identical direction.
+///
+/// Best for: Normalized vectors, semantic similarity.
+#[derive(Clone, Copy, Debug, Default)]
+pub struct Cosine;
+
+impl Proximity for Cosine {
+    fn proximity(&self, a: &Point, b: &Point) -> f32 {
+        assert_eq!(
+            a.dimensionality(),
+            b.dimensionality(),
+            "Points must have same dimensionality"
+        );
+
+        let dot: f32 = a
+            .dims()
+            .iter()
+            .zip(b.dims().iter())
+            .map(|(x, y)| x * y)
+            .sum();
+
+        let mag_a = a.magnitude();
+        let mag_b = b.magnitude();
+
+        if mag_a == 0.0 || mag_b == 0.0 {
+            return 0.0;
+        }
+
+        dot / (mag_a * mag_b)
+    }
+
+    fn name(&self) -> &'static str {
+        "cosine"
+    }
+}
+
+/// Euclidean distance
+///
+/// The straight-line distance between two points.
+/// Returns a value in [0, ∞) where 0 means identical.
+///
+/// Note: This returns DISTANCE, not similarity.
+/// Lower values = more similar.
+#[derive(Clone, Copy, Debug, Default)]
+pub struct Euclidean;
+
+impl Proximity for Euclidean {
+    fn proximity(&self, a: &Point, b: &Point) -> f32 {
+        assert_eq!(
+            a.dimensionality(),
+            b.dimensionality(),
+            "Points must have same dimensionality"
+        );
+
+        let dist_sq: f32 = a
+            .dims()
+            .iter()
+            .zip(b.dims().iter())
+            .map(|(x, y)| (x - y).powi(2))
+            .sum();
+
+        dist_sq.sqrt()
+    }
+
+    fn name(&self) -> &'static str {
+        "euclidean"
+    }
+}
+
+/// Squared Euclidean distance
+///
+/// Same ordering as Euclidean but faster (no sqrt).
+/// Use when you only need to compare distances, not absolute values.
+#[derive(Clone, Copy, Debug, Default)]
+pub struct EuclideanSquared;
+
+impl Proximity for EuclideanSquared {
+    fn proximity(&self, a: &Point, b: &Point) -> f32 {
+        assert_eq!(
+            a.dimensionality(),
+            b.dimensionality(),
+            "Points must have same dimensionality"
+        );
+
+        a.dims()
+            .iter()
+            .zip(b.dims().iter())
+            .map(|(x, y)| (x - y).powi(2))
+            .sum()
+    }
+
+    fn name(&self) -> &'static str {
+        "euclidean_squared"
+    }
+}
+
+/// Dot product
+///
+/// The raw dot product without normalization.
+/// Returns a value that depends on magnitudes.
+///
+/// Best for: When magnitude matters, not just direction.
+#[derive(Clone, Copy, Debug, Default)]
+pub struct DotProduct;
+
+impl Proximity for DotProduct {
+    fn proximity(&self, a: &Point, b: &Point) -> f32 {
+        assert_eq!(
+            a.dimensionality(),
+            b.dimensionality(),
+            "Points must have same dimensionality"
+        );
+
+        a.dims()
+            .iter()
+            .zip(b.dims().iter())
+            .map(|(x, y)| x * y)
+            .sum()
+    }
+
+    fn name(&self) -> &'static str {
+        "dot_product"
+    }
+}
+
+/// Manhattan (L1) distance
+///
+/// Sum of absolute differences along each dimension.
+/// Returns a value in [0, ∞) where 0 means identical.
+#[derive(Clone, Copy, Debug, Default)]
+pub struct Manhattan;
+
+impl Proximity for Manhattan {
+    fn proximity(&self, a: &Point, b: &Point) -> f32 {
+        assert_eq!(
+            a.dimensionality(),
+            b.dimensionality(),
+            "Points must have same dimensionality"
+        );
+
+        a.dims()
+            .iter()
+            .zip(b.dims().iter())
+            .map(|(x, y)| (x - y).abs())
+            .sum()
+    }
+
+    fn name(&self) -> &'static str {
+        "manhattan"
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_cosine_identical() {
+        let a = Point::new(vec![1.0, 0.0, 0.0]);
+        let b = Point::new(vec![1.0, 0.0, 0.0]);
+        let cos = Cosine.proximity(&a, &b);
+        assert!((cos - 1.0).abs() < 0.0001);
+    }
+
+    #[test]
+    fn test_cosine_opposite() {
+        let a = Point::new(vec![1.0, 0.0, 0.0]);
+        let b = Point::new(vec![-1.0, 0.0, 0.0]);
+        let cos = Cosine.proximity(&a, &b);
+        assert!((cos - (-1.0)).abs() < 0.0001);
+    }
+
+    #[test]
+    fn test_cosine_orthogonal() {
+        let a = Point::new(vec![1.0, 0.0, 0.0]);
+        let b = Point::new(vec![0.0, 1.0, 0.0]);
+        let cos = Cosine.proximity(&a, &b);
+        assert!(cos.abs() < 0.0001);
+    }
+
+    #[test]
+    fn test_euclidean() {
+        let a = Point::new(vec![0.0, 0.0]);
+        let b = Point::new(vec![3.0, 4.0]);
+        let dist = Euclidean.proximity(&a, &b);
+        assert!((dist - 5.0).abs() < 0.0001);
+    }
+
+    #[test]
+    fn test_euclidean_squared() {
+        let a = Point::new(vec![0.0, 0.0]);
+        let b = Point::new(vec![3.0, 4.0]);
+        let dist_sq = EuclideanSquared.proximity(&a, &b);
+        assert!((dist_sq - 25.0).abs() < 0.0001);
+    }
+
+    #[test]
+    fn test_dot_product() {
+        let a = Point::new(vec![1.0, 2.0, 3.0]);
+        let b = Point::new(vec![4.0, 5.0, 6.0]);
+        let dot = DotProduct.proximity(&a, &b);
+        // 1*4 + 2*5 + 3*6 = 4 + 10 + 18 = 32
+        assert!((dot - 32.0).abs() < 0.0001);
+    }
+
+    #[test]
+    fn test_manhattan() {
+        let a = Point::new(vec![0.0, 0.0]);
+        let b = Point::new(vec![3.0, 4.0]);
+        let dist = Manhattan.proximity(&a, &b);
+        assert!((dist - 7.0).abs() < 0.0001);
+    }
+
+    #[test]
+    fn test_proximity_names() {
+        assert_eq!(Cosine.name(), "cosine");
+        assert_eq!(Euclidean.name(), "euclidean");
+        assert_eq!(DotProduct.name(), "dot_product");
+        assert_eq!(Manhattan.name(), "manhattan");
+    }
+
+    #[test]
+    #[should_panic(expected = "same dimensionality")]
+    fn test_dimension_mismatch_panics() {
+        let a = Point::new(vec![1.0, 2.0]);
+        let b = Point::new(vec![1.0, 2.0, 3.0]);
+        Cosine.proximity(&a, &b);
+    }
+}

src/engine/arms.rs

@@ -0,0 +1,335 @@
+//! # Arms Engine
+//!
+//! The main ARMS orchestrator.
+//!
+//! This struct wires together:
+//! - Storage (Place port)
+//! - Index (Near port)
+//! - Configuration
+//!
+//! And exposes a unified API for storing and retrieving points.
+
+use crate::core::{Blob, Id, PlacedPoint, Point};
+use crate::core::config::ArmsConfig;
+use crate::ports::{Near, NearResult, Place, PlaceResult, SearchResult};
+use crate::adapters::storage::MemoryStorage;
+use crate::adapters::index::FlatIndex;
+
+/// The main ARMS engine
+///
+/// Orchestrates storage and indexing with a unified API.
+pub struct Arms {
+    /// Configuration
+    config: ArmsConfig,
+
+    /// Storage backend (Place port)
+    storage: Box<dyn Place>,
+
+    /// Index backend (Near port)
+    index: Box<dyn Near>,
+}
+
+impl Arms {
+    /// Create a new ARMS instance with default adapters
+    ///
+    /// Uses MemoryStorage and FlatIndex.
+    /// For production, use `Arms::with_adapters` with appropriate backends.
+    pub fn new(config: ArmsConfig) -> Self {
+        let storage = Box::new(MemoryStorage::new(config.dimensionality));
+        let index = Box::new(FlatIndex::new(
+            config.dimensionality,
+            config.proximity.clone(),
+            true, // Assuming cosine-like similarity by default
+        ));
+
+        Self {
+            config,
+            storage,
+            index,
+        }
+    }
+
+    /// Create with custom adapters
+    pub fn with_adapters(
+        config: ArmsConfig,
+        storage: Box<dyn Place>,
+        index: Box<dyn Near>,
+    ) -> Self {
+        Self {
+            config,
+            storage,
+            index,
+        }
+    }
+
+    /// Get the configuration
+    pub fn config(&self) -> &ArmsConfig {
+        &self.config
+    }
+
+    /// Get the dimensionality of this space
+    pub fn dimensionality(&self) -> usize {
+        self.config.dimensionality
+    }
+
+    // ========================================================================
+    // PLACE OPERATIONS
+    // ========================================================================
+
+    /// Place a point in the space
+    ///
+    /// The point will be normalized if configured to do so.
+    /// Returns the assigned ID.
+    pub fn place(&mut self, point: Point, blob: Blob) -> PlaceResult<Id> {
+        // Normalize if configured
+        let point = if self.config.normalize_on_insert {
+            point.normalize()
+        } else {
+            point
+        };
+
+        // Store in storage
+        let id = self.storage.place(point.clone(), blob)?;
+
+        // Add to index
+        if let Err(e) = self.index.add(id, &point) {
+            // Rollback storage if index fails
+            self.storage.remove(id);
+            return Err(crate::ports::PlaceError::StorageError(format!(
+                "Index error: {:?}",
+                e
+            )));
+        }
+
+        Ok(id)
+    }
+
+    /// Place multiple points at once
+    pub fn place_batch(&mut self, items: Vec<(Point, Blob)>) -> Vec<PlaceResult<Id>> {
+        items
+            .into_iter()
+            .map(|(point, blob)| self.place(point, blob))
+            .collect()
+    }
+
+    /// Remove a point from the space
+    pub fn remove(&mut self, id: Id) -> Option<PlacedPoint> {
+        // Remove from index first
+        let _ = self.index.remove(id);
+
+        // Then from storage
+        self.storage.remove(id)
+    }
+
+    /// Get a point by ID
+    pub fn get(&self, id: Id) -> Option<&PlacedPoint> {
+        self.storage.get(id)
+    }
+
+    /// Check if a point exists
+    pub fn contains(&self, id: Id) -> bool {
+        self.storage.contains(id)
+    }
+
+    /// Get the number of stored points
+    pub fn len(&self) -> usize {
+        self.storage.len()
+    }
+
+    /// Check if the space is empty
+    pub fn is_empty(&self) -> bool {
+        self.storage.is_empty()
+    }
+
+    /// Clear all points
+    pub fn clear(&mut self) {
+        self.storage.clear();
+        let _ = self.index.rebuild(); // Reset index
+    }
+
+    // ========================================================================
+    // NEAR OPERATIONS
+    // ========================================================================
+
+    /// Find k nearest points to query
+    pub fn near(&self, query: &Point, k: usize) -> NearResult<Vec<SearchResult>> {
+        // Normalize query if configured
+        let query = if self.config.normalize_on_insert {
+            query.normalize()
+        } else {
+            query.clone()
+        };
+
+        self.index.near(&query, k)
+    }
+
+    /// Find all points within threshold
+    pub fn within(&self, query: &Point, threshold: f32) -> NearResult<Vec<SearchResult>> {
+        let query = if self.config.normalize_on_insert {
+            query.normalize()
+        } else {
+            query.clone()
+        };
+
+        self.index.within(&query, threshold)
+    }
+
+    /// Find and retrieve k nearest points (with full data)
+    pub fn near_with_data(&self, query: &Point, k: usize) -> NearResult<Vec<(&PlacedPoint, f32)>> {
+        let results = self.near(query, k)?;
+
+        Ok(results
+            .into_iter()
+            .filter_map(|r| self.storage.get(r.id).map(|p| (p, r.score)))
+            .collect())
+    }
+
+    // ========================================================================
+    // MERGE OPERATIONS
+    // ========================================================================
+
+    /// Merge multiple points into one using the configured merge function
+    pub fn merge(&self, points: &[Point]) -> Point {
+        self.config.merge.merge(points)
+    }
+
+    /// Compute proximity between two points
+    pub fn proximity(&self, a: &Point, b: &Point) -> f32 {
+        self.config.proximity.proximity(a, b)
+    }
+
+    // ========================================================================
+    // STATS
+    // ========================================================================
+
+    /// Get storage size in bytes
+    pub fn size_bytes(&self) -> usize {
+        self.storage.size_bytes()
+    }
+
+    /// Get index stats
+    pub fn index_len(&self) -> usize {
+        self.index.len()
+    }
+
+    /// Check if index is ready
+    pub fn is_ready(&self) -> bool {
+        self.index.is_ready()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn create_test_arms() -> Arms {
+        Arms::new(ArmsConfig::new(3))
+    }
+
+    #[test]
+    fn test_arms_place_and_get() {
+        let mut arms = create_test_arms();
+
+        let point = Point::new(vec![1.0, 0.0, 0.0]);
+        let blob = Blob::from_str("test data");
+
+        let id = arms.place(point, blob).unwrap();
+
+        let retrieved = arms.get(id).unwrap();
+        assert_eq!(retrieved.blob.as_str(), Some("test data"));
+    }
+
+    #[test]
+    fn test_arms_near() {
+        let mut arms = create_test_arms();
+
+        // Add some points
+        arms.place(Point::new(vec![1.0, 0.0, 0.0]), Blob::from_str("x")).unwrap();
+        arms.place(Point::new(vec![0.0, 1.0, 0.0]), Blob::from_str("y")).unwrap();
+        arms.place(Point::new(vec![0.0, 0.0, 1.0]), Blob::from_str("z")).unwrap();
+
+        // Query
+        let query = Point::new(vec![1.0, 0.0, 0.0]);
+        let results = arms.near(&query, 2).unwrap();
+
+        assert_eq!(results.len(), 2);
+        // First result should have highest similarity
+        assert!(results[0].score > results[1].score);
+    }
+
+    #[test]
+    fn test_arms_near_with_data() {
+        let mut arms = create_test_arms();
+
+        arms.place(Point::new(vec![1.0, 0.0, 0.0]), Blob::from_str("x")).unwrap();
+        arms.place(Point::new(vec![0.0, 1.0, 0.0]), Blob::from_str("y")).unwrap();
+
+        let query = Point::new(vec![1.0, 0.0, 0.0]);
+        let results = arms.near_with_data(&query, 1).unwrap();
+
+        assert_eq!(results.len(), 1);
+        assert_eq!(results[0].0.blob.as_str(), Some("x"));
+    }
+
+    #[test]
+    fn test_arms_remove() {
+        let mut arms = create_test_arms();
+
+        let id = arms.place(Point::new(vec![1.0, 0.0, 0.0]), Blob::empty()).unwrap();
+
+        assert!(arms.contains(id));
+        assert_eq!(arms.len(), 1);
+
+        arms.remove(id);
+
+        assert!(!arms.contains(id));
+        assert_eq!(arms.len(), 0);
+    }
+
+    #[test]
+    fn test_arms_merge() {
+        let arms = create_test_arms();
+
+        let points = vec![
+            Point::new(vec![1.0, 0.0, 0.0]),
+            Point::new(vec![0.0, 1.0, 0.0]),
+        ];
+
+        let merged = arms.merge(&points);
+
+        // Mean of [1,0,0] and [0,1,0] = [0.5, 0.5, 0]
+        assert!((merged.dims()[0] - 0.5).abs() < 0.0001);
+        assert!((merged.dims()[1] - 0.5).abs() < 0.0001);
+        assert!((merged.dims()[2] - 0.0).abs() < 0.0001);
+    }
+
+    #[test]
+    fn test_arms_clear() {
+        let mut arms = create_test_arms();
+
+        for i in 0..10 {
+            arms.place(Point::new(vec![i as f32, 0.0, 0.0]), Blob::empty()).unwrap();
+        }
+
+        assert_eq!(arms.len(), 10);
+
+        arms.clear();
+
+        assert_eq!(arms.len(), 0);
+        assert!(arms.is_empty());
+    }
+
+    #[test]
+    fn test_arms_normalizes_on_insert() {
+        let mut arms = create_test_arms();
+
+        // Insert a non-normalized point
+        let point = Point::new(vec![3.0, 4.0, 0.0]); // magnitude = 5
+        let id = arms.place(point, Blob::empty()).unwrap();
+
+        let retrieved = arms.get(id).unwrap();
+
+        // Should be normalized
+        assert!(retrieved.point.is_normalized());
+    }
+}