Upload folder using huggingface_hub

.gitattributes

@@ -33,3 +33,10 @@ 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
+paper/figures/fig01_architecture.jpg filter=lfs diff=lfs merge=lfs -text
+paper/figures/fig02_hexagonal.jpg filter=lfs diff=lfs merge=lfs -text
+paper/figures/fig03_primitives.jpg filter=lfs diff=lfs merge=lfs -text
+paper/figures/fig04_position_relationship.jpg filter=lfs diff=lfs merge=lfs -text
+paper/figures/fig05_hippocampus.jpg filter=lfs diff=lfs merge=lfs -text
+paper/figures/fig06_traditional_vs_arms.jpg filter=lfs diff=lfs merge=lfs -text
+paper/figures/fig07_ecosystem.jpg filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,7 @@
+/target/
+Cargo.lock
+.env
+.venv/
+.claude/
+*.pyc
+__pycache__/

Cargo.toml

@@ -0,0 +1,39 @@
+[package]
+name = "arms-core"
+version = "0.1.0"
+edition = "2021"
+authors = ["Automate Capture LLC <research@automate-capture.com>"]
+description = "ARMS: Attention Reasoning Memory Store - A spatial memory fabric for AI. Position IS relationship."
+license = "MIT"
+repository = "https://github.com/automate-capture/arms"
+homepage = "https://research.automate-capture.com/arms"
+documentation = "https://docs.rs/arms"
+readme = "README.md"
+keywords = ["memory", "spatial-database", "ai", "embeddings", "vector-search"]
+categories = ["database", "science", "algorithms"]
+exclude = [
+    "target/",
+    ".venv/",
+    ".git/",
+    ".claude/",
+    "paper/",
+    "images/",
+    ".env",
+]
+
+[lib]
+name = "arms"
+path = "src/lib.rs"
+
+[dependencies]
+thiserror = "1.0"
+
+[dev-dependencies]
+criterion = "0.5"
+
+[features]
+default = []
+
+[profile.release]
+lto = true
+codegen-units = 1

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Young / 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,171 @@
+---
+license: mit
+tags:
+  - spatial-database
+  - memory
+  - embeddings
+  - ai
+  - vector-search
+  - rust
+library_name: arms-core
+pipeline_tag: feature-extraction
+---
+
+# ARMS - Attention Reasoning Memory Store
+
+> **Position IS Relationship** - A Spatial Memory Fabric for AI Systems
+
+ARMS is a spatial memory fabric that enables AI systems to store and retrieve computed states by their native dimensional coordinates. Unlike traditional databases that require explicit relationships through foreign keys or learned topology through approximate nearest neighbor algorithms, ARMS operates on a fundamental principle: **proximity defines connection**.
+
+![ARMS Architecture](paper/figures/fig01_architecture.jpg)
+
+## The Problem
+
+Current AI memory approaches all lose information:
+
+- **Extended context**: Expensive, doesn't scale beyond training length
+- **RAG retrieval**: Retrieves text, requires recomputation of attention
+- **Vector databases**: Treat all data as unstructured point clouds
+- **External memory**: Key-value stores with explicit indexing
+
+![Traditional vs ARMS](paper/figures/fig06_traditional_vs_arms.jpg)
+
+## The ARMS Insight
+
+```
+Traditional:  State → Project → Index → Retrieve → Reconstruct
+              (lossy at each step)
+
+ARMS:         State → Store AT coordinates → Retrieve → Inject directly
+              (native representation preserved)
+```
+
+## The Five Primitives
+
+Everything in ARMS reduces to five operations:
+
+![Five Primitives](paper/figures/fig03_primitives.jpg)
+
+| Primitive | Type | Purpose |
+|-----------|------|---------|
+| **Point** | `Vec<f32>` | Any dimensionality |
+| **Proximity** | `fn(a, b) -> f32` | How related? |
+| **Merge** | `fn(points) -> point` | Compose together |
+| **Place** | `fn(point, data) -> id` | Exist in space |
+| **Near** | `fn(point, k) -> ids` | What's related? |
+
+## Quick Start
+
+```rust
+use arms_core::{Arms, ArmsConfig, Point};
+
+// Create ARMS with default config
+let mut arms = Arms::new(ArmsConfig::new(768));
+
+// Place a point in the space
+let point = Point::new(vec![0.1; 768]);
+let id = arms.place(point, b"my data".to_vec()).unwrap();
+
+// Find nearby points
+let query = Point::new(vec![0.1; 768]);
+let neighbors = arms.near(&query, 5).unwrap();
+```
+
+## Hexagonal Architecture
+
+ARMS follows a hexagonal (ports-and-adapters) architecture. The core domain contains pure math with no I/O. Ports define trait contracts. Adapters provide swappable implementations.
+
+![Hexagonal Architecture](paper/figures/fig02_hexagonal.jpg)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                         ARMS                                │
+├─────────────────────────────────────────────────────────────┤
+│  CORE (pure math, no I/O)                                   │
+│    Point, Id, Blob, Proximity, Merge                        │
+│                                                             │
+│  PORTS (trait contracts)                                    │
+│    Place, Near, Latency                                     │
+│                                                             │
+│  ADAPTERS (swappable implementations)                       │
+│    Storage: Memory, NVMe (planned)                          │
+│    Index: Flat, HAT (see arms-hat crate)                    │
+│                                                             │
+│  ENGINE (orchestration)                                     │
+│    Arms - the main entry point                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## The Hippocampus Analogy
+
+ARMS functions as an artificial hippocampus for AI systems:
+
+![Hippocampus Analogy](paper/figures/fig05_hippocampus.jpg)
+
+| Hippocampus | ARMS |
+|-------------|------|
+| Encodes episodic memories | Stores attention states |
+| Spatial navigation | High-dimensional proximity |
+| Pattern completion | Near queries |
+| Memory consolidation | Merge operations |
+| Place cells | Points at coordinates |
+
+## Ecosystem
+
+![ARMS Ecosystem](paper/figures/fig07_ecosystem.jpg)
+
+### Related Crates
+
+- [`arms-hat`](https://crates.io/crates/arms-hat) - Hierarchical Attention Tree index adapter (100% recall, 70x faster than HNSW)
+
+### Planned Adapters
+
+- `arms-nvme` - Persistent storage via memory-mapped files
+- `arms-distributed` - Sharded storage across machines
+- `arms-gpu` - CUDA-accelerated similarity search
+- `arms-py` - Python bindings
+
+## Proximity Functions
+
+Built-in proximity measures:
+
+- **Cosine** - Angle between vectors (semantic similarity)
+- **Euclidean** - Straight-line distance
+- **DotProduct** - Raw dot product
+- **Manhattan** - L1 distance
+
+## Installation
+
+```toml
+[dependencies]
+arms-core = "0.1"
+```
+
+## Paper
+
+The research paper is available in the [`paper/`](paper/) directory.
+
+**ARMS: A Spatial Memory Fabric for AI Systems**
+Andrew Young, 2026
+
+## License
+
+MIT License - see [LICENSE](LICENSE)
+
+## Citation
+
+If you use ARMS in research, please cite:
+
+```bibtex
+@article{young2026arms,
+  author = {Young, Andrew},
+  title = {ARMS: A Spatial Memory Fabric for AI Systems},
+  journal = {arXiv preprint},
+  year = {2026},
+  url = {https://github.com/automate-capture/arms}
+}
+```
+
+## Author
+
+Andrew Young - [andrew@automate-capture.com](mailto:andrew@automate-capture.com)

paper/ARMS_Spatial_Memory_Young_2026.tex

@@ -0,0 +1,520 @@
+% ARMS: A Spatial Memory Fabric for AI Systems
+% arXiv submission - January 2026
+
+\documentclass[11pt,a4paper]{article}
+
+% ============================================================================
+% PACKAGES
+% ============================================================================
+
+\usepackage[utf8]{inputenc}
+\usepackage[T1]{fontenc}
+\usepackage{lmodern}
+
+% Math
+\usepackage{amsmath,amssymb,amsthm}
+\usepackage{mathtools}
+
+% Graphics
+\usepackage{graphicx}
+\usepackage{float}
+\usepackage{subcaption}
+\usepackage[dvipsnames]{xcolor}
+\graphicspath{{figures/}{Diagrams/}}
+
+% Tables
+\usepackage{booktabs}
+\usepackage{multirow}
+\usepackage{array}
+
+% Algorithms
+\usepackage{algorithm}
+\usepackage{algorithmic}
+
+% Code
+\usepackage{listings}
+\lstset{
+    basicstyle=\ttfamily\small,
+    breaklines=true,
+    frame=single,
+    numbers=left,
+    numberstyle=\tiny,
+    language=Python,
+}
+
+% Links
+\usepackage[colorlinks=true,linkcolor=blue,citecolor=blue,urlcolor=blue]{hyperref}
+\usepackage{cleveref}
+
+% Layout
+\usepackage[margin=1in]{geometry}
+
+% Bibliography
+\usepackage[numbers,sort&compress]{natbib}
+
+% ============================================================================
+% CUSTOM COMMANDS
+% ============================================================================
+
+\DeclareMathOperator*{\argmax}{arg\,max}
+\DeclareMathOperator*{\argmin}{arg\,min}
+\newcommand{\R}{\mathbb{R}}
+
+% ============================================================================
+% TITLE
+% ============================================================================
+
+\title{%
+    \textbf{ARMS: A Spatial Memory Fabric for AI Systems}\\[0.5em]
+    \large Position IS Relationship
+}
+
+\author{%
+    Andrew Young\\
+    \texttt{andrew@automate-capture.com}
+}
+
+\date{January 2026}
+
+% ============================================================================
+% DOCUMENT
+% ============================================================================
+
+\begin{document}
+
+\maketitle
+
+% ----------------------------------------------------------------------------
+\begin{abstract}
+\noindent
+This paper introduces ARMS (Attention Reasoning Memory Store), a spatial memory fabric that enables AI systems to store and retrieve computed states by their native dimensional coordinates. Unlike traditional databases that require explicit relationships through foreign keys or learned topology through approximate nearest neighbor algorithms, ARMS operates on a fundamental principle: \textbf{position IS relationship}. Proximity in high-dimensional space defines semantic connection without explicit declaration.
+
+ARMS reduces memory operations to five primitives: \textbf{Point} (any-dimensional vectors), \textbf{Proximity} (relationship measurement), \textbf{Merge} (composition), \textbf{Place} (existence in space), and \textbf{Near} (retrieval by similarity). This minimal abstraction enables a hexagonal architecture where storage backends, index algorithms, and APIs can be swapped without changing core logic.
+
+The framework provides the foundation for specialized index adapters like HAT (Hierarchical Attention Tree), demonstrating that domain-specific structure can be exploited for superior performance. ARMS functions as an artificial hippocampus---enabling AI systems to form, consolidate, and retrieve episodic memories through spatial organization rather than explicit indexing.
+
+\vspace{1em}
+\noindent\textbf{Keywords:} spatial memory, AI memory systems, vector databases, hexagonal architecture, episodic memory
+\end{abstract}
+
+% ----------------------------------------------------------------------------
+\section{Introduction}
+\label{sec:intro}
+
+\subsection{The Memory Problem in AI}
+
+Large language models and AI agents face a fundamental limitation: they lack persistent, retrievable memory beyond their context window. Current approaches include:
+
+\begin{itemize}
+    \item \textbf{Extended context}: Expensive, doesn't scale beyond training length
+    \item \textbf{RAG retrieval}: Retrieves text, requires recomputation of attention
+    \item \textbf{Vector databases}: Treat all data as unstructured point clouds
+    \item \textbf{External memory}: Key-value stores with explicit indexing
+\end{itemize}
+
+None of these approaches preserve the \emph{native representation} of computed states. When an LLM processes text, it produces attention states in high-dimensional space. Current systems project, compress, or discard these states rather than storing them directly.
+
+\begin{figure}[H]
+\centering
+\includegraphics[width=0.9\textwidth]{fig06_traditional_vs_arms.jpg}
+\caption{Traditional approaches vs ARMS: Traditional systems project, compress, and approximate states at each step, introducing cumulative error. ARMS stores states at their native coordinates and retrieves by proximity, preserving the original representation.}
+\label{fig:traditional}
+\end{figure}
+
+\subsection{The ARMS Insight}
+
+ARMS takes a different approach:
+
+\begin{quote}
+\textbf{Store states at their native coordinates. Retrieve by proximity. Position IS relationship.}
+\end{quote}
+
+This insight has three implications:
+
+\begin{enumerate}
+    \item \textbf{No projection loss}: States are stored in their original dimensionality
+    \item \textbf{No explicit relationships}: Semantic similarity is spatial proximity
+    \item \textbf{No learned topology}: Structure can be known or exploited, not discovered
+\end{enumerate}
+
+\begin{figure}[H]
+\centering
+\includegraphics[width=0.9\textwidth]{fig01_architecture.jpg}
+\caption{ARMS architecture overview. The five primitives (Point, Proximity, Merge, Place, Near) form the core, with swappable storage and index adapters.}
+\label{fig:architecture}
+\end{figure}
+
+\subsection{Contributions}
+
+This paper makes the following contributions:
+
+\begin{enumerate}
+    \item A \textbf{five-primitive abstraction} for spatial memory (Point, Proximity, Merge, Place, Near)
+    \item A \textbf{hexagonal architecture} enabling swappable storage, index, and API adapters
+    \item The \textbf{``position is relationship''} principle for AI memory systems
+    \item A \textbf{foundation framework} demonstrated through the HAT index adapter
+\end{enumerate}
+
+% ----------------------------------------------------------------------------
+\section{The Five Primitives}
+\label{sec:primitives}
+
+ARMS reduces all memory operations to five primitives. This minimal surface area enables maximum flexibility while maintaining semantic clarity.
+
+\begin{figure}[H]
+\centering
+\includegraphics[width=0.85\textwidth]{fig03_primitives.jpg}
+\caption{The five primitives of ARMS: Point (representation), Proximity (relationship), Merge (composition), Place (storage), and Near (retrieval). These operations form the complete interface for spatial memory.}
+\label{fig:primitives}
+\end{figure}
+
+\begin{table}[H]
+\centering
+\caption{The five primitives of ARMS.}
+\label{tab:primitives}
+\begin{tabular}{llp{7cm}}
+\toprule
+\textbf{Primitive} & \textbf{Signature} & \textbf{Purpose} \\
+\midrule
+Point & \texttt{Vec<f32>} & Any-dimensional vector representation \\
+Proximity & \texttt{fn(a, b) -> f32} & Measure how related two points are \\
+Merge & \texttt{fn(points) -> point} & Compose multiple points into one \\
+Place & \texttt{fn(point, data) -> id} & Store a point in the space \\
+Near & \texttt{fn(point, k) -> ids} & Find k most related points \\
+\bottomrule
+\end{tabular}
+\end{table}
+
+\subsection{Point: The Universal Representation}
+
+A Point is simply a vector of floating-point numbers:
+
+\begin{lstlisting}[language=Rust,caption={Point definition.}]
+pub struct Point {
+    dims: Vec<f32>,
+}
+
+impl Point {
+    pub fn new(dims: Vec<f32>) -> Self;
+    pub fn dimensionality(&self) -> usize;
+    pub fn magnitude(&self) -> f32;
+    pub fn normalize(&self) -> Point;
+}
+\end{lstlisting}
+
+Points are dimensionality-agnostic. The same ARMS instance can store 768-dimensional BERT embeddings or 1536-dimensional OpenAI embeddings---the primitives don't change.
+
+\subsection{Proximity: Relationship Without Declaration}
+
+Proximity functions measure how related two points are:
+
+\begin{table}[H]
+\centering
+\caption{Built-in proximity functions.}
+\label{tab:proximity}
+\begin{tabular}{llp{6cm}}
+\toprule
+\textbf{Function} & \textbf{Range} & \textbf{Use Case} \\
+\midrule
+Cosine & $[-1, 1]$ & Semantic similarity (direction matters) \\
+Euclidean & $[0, \infty)$ & Spatial distance (magnitude matters) \\
+DotProduct & $(-\infty, \infty)$ & Raw correlation \\
+Manhattan & $[0, \infty)$ & L1 distance \\
+\bottomrule
+\end{tabular}
+\end{table}
+
+The key insight: \textbf{proximity replaces foreign keys}. In a relational database, you declare relationships explicitly. In ARMS, relationships emerge from spatial position.
+
+\subsection{Merge: Composition Without Loss}
+
+Merge combines multiple points into a single representative:
+
+\begin{itemize}
+    \item \textbf{Mean}: Arithmetic average (default)
+    \item \textbf{WeightedMean}: Importance-weighted average
+    \item \textbf{MaxPool}: Element-wise maximum
+\end{itemize}
+
+Merge enables hierarchical summarization. A conversation can be represented by the merge of its messages; a session by the merge of its conversations.
+
+\subsection{Place and Near: The Memory Interface}
+
+Place stores a point with associated data:
+
+\begin{lstlisting}[language=Rust,caption={Place and Near operations.}]
+// Store
+let id = arms.place(embedding, blob)?;
+
+// Retrieve
+let neighbors = arms.near(&query, k)?;
+\end{lstlisting}
+
+This is the complete memory interface. Everything else---storage backends, index algorithms, APIs---is implementation detail.
+
+% ----------------------------------------------------------------------------
+\section{Hexagonal Architecture}
+\label{sec:architecture}
+
+ARMS follows hexagonal (ports-and-adapters) architecture. The core domain contains pure math with no I/O. Ports define trait contracts. Adapters provide swappable implementations.
+
+\begin{figure}[H]
+\centering
+\includegraphics[width=0.9\textwidth]{fig02_hexagonal.jpg}
+\caption{Hexagonal architecture of ARMS. The core domain contains pure math with no I/O. Ports define trait contracts. Adapters provide swappable implementations for storage, indexing, and APIs.}
+\label{fig:hexagonal}
+\end{figure}
+
+\subsection{Core Domain}
+
+The core contains:
+
+\begin{itemize}
+    \item \textbf{Point}: Vector representation
+    \item \textbf{Id}: Unique identifiers
+    \item \textbf{Blob}: Associated data
+    \item \textbf{Proximity}: Relationship measurement
+    \item \textbf{Merge}: Point composition
+\end{itemize}
+
+No I/O, no side effects, pure functions. This enables testing without mocks and reasoning without context.
+
+\subsection{Ports}
+
+Ports define what the system needs without specifying how:
+
+\begin{lstlisting}[language=Rust,caption={Port definitions.}]
+pub trait Place {
+    fn place(&mut self, point: Point, blob: Blob) -> Result<Id>;
+    fn get(&self, id: Id) -> Option<&PlacedPoint>;
+    fn remove(&mut self, id: Id) -> Option<PlacedPoint>;
+}
+
+pub trait Near {
+    fn near(&self, query: &Point, k: usize) -> Result<Vec<SearchResult>>;
+    fn add(&mut self, id: Id, point: &Point) -> Result<()>;
+}
+\end{lstlisting}
+
+\subsection{Adapters}
+
+Adapters implement ports for specific technologies:
+
+\begin{table}[H]
+\centering
+\caption{Available adapters.}
+\label{tab:adapters}
+\begin{tabular}{lll}
+\toprule
+\textbf{Port} & \textbf{Adapter} & \textbf{Description} \\
+\midrule
+Place & MemoryStorage & In-memory hash map \\
+Place & NVMeStorage & Memory-mapped files (planned) \\
+Near & FlatIndex & Brute-force exact search \\
+Near & HatIndex & Hierarchical Attention Tree \\
+\bottomrule
+\end{tabular}
+\end{table}
+
+The HAT index adapter (published separately as \texttt{arms-hat}) demonstrates how domain-specific knowledge can be exploited for superior performance on hierarchical data.
+
+\begin{figure}[H]
+\centering
+\includegraphics[width=0.85\textwidth]{fig07_ecosystem.jpg}
+\caption{The ARMS ecosystem: \texttt{arms-core} provides the foundational primitives, while specialized adapters like \texttt{arms-hat} exploit domain-specific structure. Future adapters will add persistence, distribution, and GPU acceleration.}
+\label{fig:ecosystem}
+\end{figure}
+
+% ----------------------------------------------------------------------------
+\section{Position IS Relationship}
+\label{sec:philosophy}
+
+The core philosophical innovation of ARMS is treating position as the fundamental relationship primitive.
+
+\begin{figure}[H]
+\centering
+\includegraphics[width=0.9\textwidth]{fig04_position_relationship.jpg}
+\caption{Position IS relationship: Comparison of relationship representation across database paradigms. ARMS uses spatial position as the fundamental relationship primitive, eliminating the need for explicit declarations.}
+\label{fig:position}
+\end{figure}
+
+\subsection{Traditional Approaches}
+
+\begin{table}[H]
+\centering
+\caption{Relationship representation in different paradigms.}
+\label{tab:paradigms}
+\begin{tabular}{lll}
+\toprule
+\textbf{Paradigm} & \textbf{Relationship} & \textbf{Limitation} \\
+\midrule
+Relational DB & Foreign keys & Must be declared explicitly \\
+Document DB & Nesting & Limited to containment \\
+Graph DB & Edges & Must be declared explicitly \\
+Vector DB & Learned topology & Requires training/building \\
+\textbf{ARMS} & \textbf{Spatial position} & \textbf{Inherent in representation} \\
+\bottomrule
+\end{tabular}
+\end{table}
+
+\subsection{Implications}
+
+When position is relationship:
+
+\begin{enumerate}
+    \item \textbf{Schema-free}: No need to declare relationship types
+    \item \textbf{Continuous}: Relationships have degrees, not just existence
+    \item \textbf{Emergent}: New relationships discovered through proximity
+    \item \textbf{Composable}: Merged points represent group relationships
+\end{enumerate}
+
+\subsection{The Hippocampus Analogy}
+
+ARMS mirrors the function of the biological hippocampus:
+
+\begin{figure}[H]
+\centering
+\includegraphics[width=0.85\textwidth]{fig05_hippocampus.jpg}
+\caption{The hippocampus analogy: ARMS functions as an artificial hippocampus, enabling AI systems to form, consolidate, and retrieve episodic memories through spatial organization.}
+\label{fig:hippocampus}
+\end{figure}
+
+\begin{table}[H]
+\centering
+\caption{Hippocampus vs ARMS.}
+\label{tab:hippocampus}
+\begin{tabular}{ll}
+\toprule
+\textbf{Hippocampus} & \textbf{ARMS} \\
+\midrule
+Encodes episodic memories & Stores attention states \\
+Spatial navigation & High-dimensional proximity \\
+Pattern completion & Near queries \\
+Memory consolidation & Merge operations \\
+Place cells & Points at coordinates \\
+\bottomrule
+\end{tabular}
+\end{table}
+
+% ----------------------------------------------------------------------------
+\section{Implementation}
+\label{sec:implementation}
+
+ARMS is implemented in Rust for performance and safety, with Python bindings planned.
+
+\subsection{Usage Example}
+
+\begin{lstlisting}[language=Rust,caption={Complete ARMS usage example.}]
+use arms_core::{Arms, ArmsConfig, Point, Blob};
+
+// Create ARMS with 768 dimensions
+let mut arms = Arms::new(ArmsConfig::new(768));
+
+// Store embeddings
+let embedding = Point::new(vec![0.1; 768]);
+let id = arms.place(embedding, Blob::from_str("hello")).unwrap();
+
+// Query by proximity
+let query = Point::new(vec![0.1; 768]);
+let neighbors = arms.near(&query, 10).unwrap();
+
+// Get with data
+let results = arms.near_with_data(&query, 5).unwrap();
+for (point, score) in results {
+    println!("{}: {}", point.blob.as_str().unwrap(), score);
+}
+\end{lstlisting}
+
+\subsection{Performance}
+
+With the flat index (exact search):
+
+\begin{table}[H]
+\centering
+\caption{Flat index performance.}
+\label{tab:performance}
+\begin{tabular}{rrr}
+\toprule
+\textbf{Points} & \textbf{Dimensions} & \textbf{Query Time} \\
+\midrule
+1,000 & 768 & 0.3ms \\
+10,000 & 768 & 3ms \\
+100,000 & 768 & 30ms \\
+\bottomrule
+\end{tabular}
+\end{table}
+
+For large-scale deployments, the HAT index adapter provides $O(\log n)$ queries with 100\% recall on hierarchical data.
+
+% ----------------------------------------------------------------------------
+\section{Related Work}
+\label{sec:related}
+
+\textbf{Vector Databases}: Pinecone, Weaviate, Milvus, and Qdrant provide vector storage and retrieval. ARMS differs by providing a minimal primitive set and hexagonal architecture rather than a monolithic solution.
+
+\textbf{Memory-Augmented Networks}: Neural Turing Machines and Differentiable Neural Computers use learned memory access. ARMS provides explicit, interpretable memory operations.
+
+\textbf{RAG Systems}: Retrieval-Augmented Generation retrieves text for reprocessing. ARMS can store pre-computed attention states, avoiding recomputation.
+
+\textbf{Embedding Stores}: LangChain, LlamaIndex provide embedding storage. ARMS provides lower-level primitives for building such systems.
+
+% ----------------------------------------------------------------------------
+\section{Future Work}
+\label{sec:future}
+
+\subsection{Planned Adapters}
+
+\begin{itemize}
+    \item \textbf{NVMe Storage}: Memory-mapped files for persistence
+    \item \textbf{Distributed Storage}: Sharded across machines
+    \item \textbf{GPU Index}: CUDA-accelerated similarity search
+\end{itemize}
+
+\subsection{Applications}
+
+\begin{itemize}
+    \item \textbf{LLM Memory}: Long-term episodic memory for chatbots
+    \item \textbf{Agent State}: Persistent state for AI agents
+    \item \textbf{Attention Caching}: Store and retrieve KV cache states
+    \item \textbf{Multimodal Memory}: Unified space for text, image, audio embeddings
+\end{itemize}
+
+% ----------------------------------------------------------------------------
+\section{Conclusion}
+\label{sec:conclusion}
+
+ARMS provides a minimal, principled foundation for AI memory systems. By reducing memory operations to five primitives and adopting a hexagonal architecture, ARMS enables:
+
+\begin{enumerate}
+    \item \textbf{Simplicity}: Five operations cover all memory needs
+    \item \textbf{Flexibility}: Swap storage, index, and API independently
+    \item \textbf{Performance}: Domain-specific adapters like HAT
+    \item \textbf{Philosophy}: Position IS relationship
+\end{enumerate}
+
+ARMS functions as an artificial hippocampus for AI systems, enabling them to form, consolidate, and retrieve memories through spatial organization rather than explicit indexing.
+
+% ----------------------------------------------------------------------------
+\section*{Acknowledgments}
+
+I thank the open-source Rust community for excellent tooling and the researchers whose work on memory-augmented networks inspired this architecture.
+
+% ----------------------------------------------------------------------------
+\bibliographystyle{plainnat}
+\bibliography{refs}
+
+% ----------------------------------------------------------------------------
+\appendix
+
+\section{Code Availability}
+\label{app:code}
+
+ARMS is available as open-source software:
+
+\begin{itemize}
+    \item \textbf{Rust crate}: \texttt{arms-core} on crates.io
+    \item \textbf{HAT adapter}: \texttt{arms-hat} on crates.io
+    \item \textbf{Repository}: \url{https://github.com/automate-capture/arms}
+\end{itemize}
+
+\end{document}

paper/refs.bib

@@ -0,0 +1,78 @@
+% ARMS Paper Bibliography
+
+@article{graves2014neural,
+    author = {Graves, Alex and Wayne, Greg and Danihelka, Ivo},
+    title = {Neural Turing Machines},
+    journal = {arXiv preprint arXiv:1410.5401},
+    year = {2014},
+}
+
+@article{graves2016dnc,
+    author = {Graves, Alex and Wayne, Greg and Reynolds, Malcolm and Harley, Tim and Danihelka, Ivo and others},
+    title = {Hybrid Computing Using a Neural Network with Dynamic External Memory},
+    journal = {Nature},
+    volume = {538},
+    number = {7626},
+    pages = {471--476},
+    year = {2016},
+}
+
+@inproceedings{weston2015memory,
+    author = {Weston, Jason and Chopra, Sumit and Bordes, Antoine},
+    title = {Memory Networks},
+    booktitle = {International Conference on Learning Representations},
+    year = {2015},
+}
+
+@inproceedings{lewis2020rag,
+    author = {Lewis, Patrick and others},
+    title = {Retrieval-Augmented Generation for Knowledge-Intensive {NLP} Tasks},
+    booktitle = {Advances in Neural Information Processing Systems},
+    volume = {33},
+    pages = {9459--9474},
+    year = {2020},
+}
+
+@article{malkov2018hnsw,
+    author = {Malkov, Yu A. and Yashunin, D. A.},
+    title = {Efficient and Robust Approximate Nearest Neighbor Search Using Hierarchical Navigable Small World Graphs},
+    journal = {IEEE Transactions on Pattern Analysis and Machine Intelligence},
+    volume = {42},
+    number = {4},
+    pages = {824--836},
+    year = {2018},
+}
+
+@article{johnson2019faiss,
+    author = {Johnson, Jeff and Douze, Matthijs and J{\'e}gou, Herv{\'e}},
+    title = {Billion-scale Similarity Search with {GPU}s},
+    journal = {IEEE Transactions on Big Data},
+    volume = {7},
+    number = {3},
+    pages = {535--547},
+    year = {2019},
+}
+
+@article{vaswani2017attention,
+    author = {Vaswani, Ashish and others},
+    title = {Attention is All You Need},
+    journal = {Advances in Neural Information Processing Systems},
+    volume = {30},
+    year = {2017},
+}
+
+@book{cockburn2005hexagonal,
+    author = {Cockburn, Alistair},
+    title = {Hexagonal Architecture},
+    year = {2005},
+    note = {Also known as Ports and Adapters pattern},
+}
+
+@article{moser2008place,
+    author = {Moser, Edvard I. and Kropff, Emilio and Moser, May-Britt},
+    title = {Place Cells, Grid Cells, and the Brain's Spatial Representation System},
+    journal = {Annual Review of Neuroscience},
+    volume = {31},
+    pages = {69--89},
+    year = {2008},
+}

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/mod.rs

@@ -0,0 +1,15 @@
+//! # Index Adapters
+//!
+//! Implementations of the Near port for different index backends.
+//!
+//! Available adapters:
+//! - `FlatIndex` - Brute force search (exact, slow for large N)
+//! - `HnswIndex` - Hierarchical Navigable Small World (approximate, fast) [TODO]
+
+mod flat;
+
+pub use flat::FlatIndex;
+
+// TODO: Add HNSW adapter
+// mod hnsw;
+// pub use hnsw::HnswIndex;

src/adapters/mod.rs

@@ -0,0 +1,16 @@
+//! # Adapters
+//!
+//! Swappable implementations of port traits.
+//!
+//! This is where the hexagonal architecture meets reality:
+//! - Storage adapters: Memory, NVMe
+//! - Index adapters: Flat (brute force)
+//!
+//! Each adapter implements one or more port traits.
+//! Adapters can be swapped without changing core logic.
+//!
+//! For advanced index adapters like HAT (Hierarchical Attention Tree),
+//! see the `arms-hat` crate.
+
+pub mod storage;
+pub mod index;

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());
+    }
+}

src/engine/mod.rs

@@ -0,0 +1,12 @@
+//! # Engine
+//!
+//! The orchestration layer that wires everything together.
+//!
+//! This is where:
+//! - Configuration is applied
+//! - Adapters are connected to ports
+//! - The unified ARMS interface is exposed
+
+mod arms;
+
+pub use arms::Arms;

src/lib.rs

@@ -0,0 +1,107 @@
+//! # ARMS - Attention Reasoning Memory Store
+//!
+//! > "The hippocampus of artificial minds"
+//!
+//! ARMS is a spatial memory fabric for AI models. It stores computed attention
+//! states at their native dimensional coordinates, enabling instant retrieval
+//! by proximity rather than traditional indexing.
+//!
+//! ## Philosophy
+//!
+//! - **Position IS relationship** - No foreign keys, proximity defines connection
+//! - **Configurable, not hardcoded** - Dimensionality, proximity functions, all flexible
+//! - **Generators over assets** - Algorithms, not rigid structures
+//! - **Pure core, swappable adapters** - Hexagonal architecture
+//!
+//! ## Architecture
+//!
+//! ```text
+//! ┌─────────────────────────────────────────────────────────────┐
+//! │                         ARMS                                 │
+//! ├─────────────────────────────────────────────────────────────┤
+//! │                                                              │
+//! │  CORE (pure math, no I/O)                                   │
+//! │    Point, Id, Blob, Proximity, Merge                        │
+//! │                                                              │
+//! │  PORTS (trait contracts)                                     │
+//! │    Place, Near, Latency                                     │
+//! │                                                              │
+//! │  ADAPTERS (swappable implementations)                       │
+//! │    Storage: Memory, NVMe                                    │
+//! │    Index: Flat, HNSW                                        │
+//! │    API: Python bindings                                      │
+//! │                                                              │
+//! │  ENGINE (orchestration)                                      │
+//! │    Arms - the main entry point                              │
+//! │                                                              │
+//! └─────────────────────────────────────────────────────────────┘
+//! ```
+//!
+//! ## Quick Start
+//!
+//! ```rust,ignore
+//! use arms::{Arms, ArmsConfig, Point};
+//!
+//! // Create ARMS with default config (768 dimensions)
+//! let mut arms = Arms::new(ArmsConfig::default());
+//!
+//! // Place a point in the space
+//! let point = Point::new(vec![0.1; 768]);
+//! let id = arms.place(point, b"my data".to_vec());
+//!
+//! // Find nearby points
+//! let query = Point::new(vec![0.1; 768]);
+//! let neighbors = arms.near(&query, 5);
+//! ```
+
+// ============================================================================
+// MODULES
+// ============================================================================
+
+/// Core domain - pure math, no I/O
+/// Contains: Point, Id, Blob, Proximity trait, Merge trait
+pub mod core;
+
+/// Port definitions - trait contracts for adapters
+/// Contains: Place trait, Near trait, Latency trait
+pub mod ports;
+
+/// Adapter implementations - swappable components
+/// Contains: storage, index, python submodules
+pub mod adapters;
+
+/// Engine - orchestration layer
+/// Contains: Arms main struct
+pub mod engine;
+
+// ============================================================================
+// RE-EXPORTS (public API)
+// ============================================================================
+
+// Core types
+pub use crate::core::{Point, Id, Blob, PlacedPoint};
+pub use crate::core::proximity::{Proximity, Cosine, Euclidean, DotProduct};
+pub use crate::core::merge::{Merge, Mean, WeightedMean, MaxPool};
+pub use crate::core::config::ArmsConfig;
+
+// Port traits
+pub use crate::ports::{Place, Near, Latency};
+
+// Engine
+pub use crate::engine::Arms;
+
+// ============================================================================
+// CRATE-LEVEL DOCUMENTATION
+// ============================================================================
+
+/// The five primitives of ARMS:
+///
+/// 1. **Point**: `Vec<f32>` - Any dimensionality
+/// 2. **Proximity**: `fn(a, b) -> f32` - How related?
+/// 3. **Merge**: `fn(points) -> point` - Compose together
+/// 4. **Place**: `fn(point, data) -> id` - Exist in space
+/// 5. **Near**: `fn(point, k) -> ids` - What's related?
+///
+/// Everything else is configuration or adapters.
+#[doc(hidden)]
+pub const _PRIMITIVES: () = ();

src/ports/latency.rs

@@ -0,0 +1,126 @@
+//! # Latency Port
+//!
+//! Trait for runtime latency measurement and adaptation.
+//!
+//! This enables the model to know its actual retrieval constraints:
+//! - How fast is the hot tier right now?
+//! - How much budget do I have for retrieval?
+//! - Should I use fewer, faster retrievals or more, slower ones?
+
+use std::time::Duration;
+
+/// Storage tier levels
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum Tier {
+    /// RAM storage - fastest
+    Hot,
+    /// NVMe storage - fast
+    Warm,
+    /// Archive storage - slow
+    Cold,
+}
+
+impl Tier {
+    /// Get expected latency range for this tier
+    pub fn expected_latency(&self) -> (Duration, Duration) {
+        match self {
+            Tier::Hot => (Duration::from_micros(1), Duration::from_millis(1)),
+            Tier::Warm => (Duration::from_millis(1), Duration::from_millis(10)),
+            Tier::Cold => (Duration::from_millis(10), Duration::from_millis(100)),
+        }
+    }
+}
+
+/// Latency measurement result
+#[derive(Debug, Clone)]
+pub struct LatencyMeasurement {
+    /// The tier that was measured
+    pub tier: Tier,
+
+    /// Measured latency for a single operation
+    pub latency: Duration,
+
+    /// Throughput (operations per second) if measured
+    pub throughput_ops: Option<f64>,
+
+    /// Timestamp of measurement
+    pub measured_at: std::time::Instant,
+}
+
+/// Budget allocation for retrieval operations
+#[derive(Debug, Clone)]
+pub struct LatencyBudget {
+    /// Total time budget for this retrieval batch
+    pub total: Duration,
+
+    /// Maximum time per individual retrieval
+    pub per_operation: Duration,
+
+    /// Maximum number of operations in this budget
+    pub max_operations: usize,
+}
+
+impl Default for LatencyBudget {
+    fn default() -> Self {
+        Self {
+            total: Duration::from_millis(50),
+            per_operation: Duration::from_millis(5),
+            max_operations: 10,
+        }
+    }
+}
+
+/// Tier statistics
+#[derive(Debug, Clone)]
+pub struct TierStats {
+    /// The tier
+    pub tier: Tier,
+
+    /// Number of points in this tier
+    pub count: usize,
+
+    /// Total size in bytes
+    pub size_bytes: usize,
+
+    /// Capacity in bytes
+    pub capacity_bytes: usize,
+
+    /// Usage ratio (0.0 to 1.0)
+    pub usage_ratio: f32,
+}
+
+/// Trait for latency measurement and adaptation
+///
+/// System adapters implement this trait.
+pub trait Latency: Send + Sync {
+    /// Probe a tier to measure current latency
+    ///
+    /// Performs a small test operation to measure actual latency.
+    fn probe(&mut self, tier: Tier) -> LatencyMeasurement;
+
+    /// Get the current latency budget
+    fn budget(&self) -> LatencyBudget;
+
+    /// Set a new latency budget
+    fn set_budget(&mut self, budget: LatencyBudget);
+
+    /// Get available capacity in a tier
+    fn available_capacity(&self, tier: Tier) -> usize;
+
+    /// Recommend which tier to use for an access pattern
+    ///
+    /// `expected_accesses` is the expected number of accesses for this data.
+    fn recommend_tier(&self, expected_accesses: u32) -> Tier;
+
+    /// Get statistics for a tier
+    fn tier_stats(&self, tier: Tier) -> TierStats;
+
+    /// Get statistics for all tiers
+    fn all_stats(&self) -> Vec<TierStats> {
+        vec![
+            self.tier_stats(Tier::Hot),
+            self.tier_stats(Tier::Warm),
+            self.tier_stats(Tier::Cold),
+        ]
+    }
+}

src/ports/mod.rs

@@ -0,0 +1,28 @@
+//! # Ports
+//!
+//! Trait definitions for adapters. Contracts only, no implementations.
+//!
+//! This is the hexagonal architecture boundary:
+//! - Ports define WHAT operations are needed
+//! - Adapters define HOW they're implemented
+//!
+//! The CORE doesn't know about adapters.
+//! Adapters implement these port traits.
+
+mod place;
+mod near;
+mod latency;
+
+// Re-export traits
+pub use place::Place;
+pub use near::Near;
+pub use latency::Latency;
+
+// Re-export types from place
+pub use place::{PlaceError, PlaceResult};
+
+// Re-export types from near
+pub use near::{NearError, NearResult, SearchResult};
+
+// Re-export types from latency
+pub use latency::{Tier, LatencyBudget, LatencyMeasurement, TierStats};

src/ports/near.rs

@@ -0,0 +1,95 @@
+//! # Near Port
+//!
+//! Trait for finding related points.
+//!
+//! This is one of the five primitives of ARMS:
+//! `Near: fn(point, k) -> ids` - What's related?
+//!
+//! Implemented by index adapters (Flat, HNSW, etc.)
+
+use crate::core::{Id, Point};
+
+/// Result type for near operations
+pub type NearResult<T> = Result<T, NearError>;
+
+/// A search result with ID and distance/similarity score
+#[derive(Debug, Clone, PartialEq)]
+pub struct SearchResult {
+    /// The ID of the found point
+    pub id: Id,
+
+    /// Distance or similarity score
+    /// Interpretation depends on the proximity function used.
+    pub score: f32,
+}
+
+impl SearchResult {
+    pub fn new(id: Id, score: f32) -> Self {
+        Self { id, score }
+    }
+}
+
+/// Errors that can occur during near operations
+#[derive(Debug, Clone, PartialEq)]
+pub enum NearError {
+    /// The query point has wrong dimensionality
+    DimensionalityMismatch { expected: usize, got: usize },
+
+    /// Index is not built/ready
+    IndexNotReady,
+
+    /// Index backend error
+    IndexError(String),
+}
+
+impl std::fmt::Display for NearError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            NearError::DimensionalityMismatch { expected, got } => {
+                write!(f, "Dimensionality mismatch: expected {}, got {}", expected, got)
+            }
+            NearError::IndexNotReady => write!(f, "Index not ready"),
+            NearError::IndexError(msg) => write!(f, "Index error: {}", msg),
+        }
+    }
+}
+
+impl std::error::Error for NearError {}
+
+/// Trait for finding related points
+///
+/// Index adapters implement this trait.
+pub trait Near: Send + Sync {
+    /// Find k nearest points to query
+    ///
+    /// Returns results sorted by relevance (most relevant first).
+    fn near(&self, query: &Point, k: usize) -> NearResult<Vec<SearchResult>>;
+
+    /// Find all points within a distance/similarity threshold
+    ///
+    /// For distance metrics (Euclidean), finds points with distance < threshold.
+    /// For similarity metrics (Cosine), finds points with similarity > threshold.
+    fn within(&self, query: &Point, threshold: f32) -> NearResult<Vec<SearchResult>>;
+
+    /// Add a point to the index
+    ///
+    /// Call this after placing a point in storage.
+    fn add(&mut self, id: Id, point: &Point) -> NearResult<()>;
+
+    /// Remove a point from the index
+    fn remove(&mut self, id: Id) -> NearResult<()>;
+
+    /// Rebuild the index (if needed for performance)
+    fn rebuild(&mut self) -> NearResult<()>;
+
+    /// Check if the index is ready for queries
+    fn is_ready(&self) -> bool;
+
+    /// Get the number of indexed points
+    fn len(&self) -> usize;
+
+    /// Check if the index is empty
+    fn is_empty(&self) -> bool {
+        self.len() == 0
+    }
+}

src/ports/place.rs

@@ -0,0 +1,91 @@
+//! # Place Port
+//!
+//! Trait for placing points in the space.
+//!
+//! This is one of the five primitives of ARMS:
+//! `Place: fn(point, data) -> id` - Exist in space
+//!
+//! Implemented by storage adapters (Memory, NVMe, etc.)
+
+use crate::core::{Blob, Id, PlacedPoint, Point};
+
+/// Result type for place operations
+pub type PlaceResult<T> = Result<T, PlaceError>;
+
+/// Errors that can occur during place operations
+#[derive(Debug, Clone, PartialEq)]
+pub enum PlaceError {
+    /// The point has wrong dimensionality for this space
+    DimensionalityMismatch { expected: usize, got: usize },
+
+    /// Storage capacity exceeded
+    CapacityExceeded,
+
+    /// Point with this ID already exists
+    DuplicateId(Id),
+
+    /// Storage backend error
+    StorageError(String),
+}
+
+impl std::fmt::Display for PlaceError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            PlaceError::DimensionalityMismatch { expected, got } => {
+                write!(f, "Dimensionality mismatch: expected {}, got {}", expected, got)
+            }
+            PlaceError::CapacityExceeded => write!(f, "Storage capacity exceeded"),
+            PlaceError::DuplicateId(id) => write!(f, "Duplicate ID: {}", id),
+            PlaceError::StorageError(msg) => write!(f, "Storage error: {}", msg),
+        }
+    }
+}
+
+impl std::error::Error for PlaceError {}
+
+/// Trait for placing points in the space
+///
+/// Storage adapters implement this trait.
+pub trait Place: Send + Sync {
+    /// Place a point with its payload in the space
+    ///
+    /// Returns the ID assigned to the placed point.
+    fn place(&mut self, point: Point, blob: Blob) -> PlaceResult<Id>;
+
+    /// Place a point with a specific ID
+    ///
+    /// Use when you need deterministic IDs (e.g., replication, testing).
+    fn place_with_id(&mut self, id: Id, point: Point, blob: Blob) -> PlaceResult<()>;
+
+    /// Remove a point from the space
+    ///
+    /// Returns the removed point if it existed.
+    fn remove(&mut self, id: Id) -> Option<PlacedPoint>;
+
+    /// Get a placed point by ID
+    ///
+    /// Returns None if not found.
+    fn get(&self, id: Id) -> Option<&PlacedPoint>;
+
+    /// Check if a point exists
+    fn contains(&self, id: Id) -> bool {
+        self.get(id).is_some()
+    }
+
+    /// Get the number of placed points
+    fn len(&self) -> usize;
+
+    /// Check if the space is empty
+    fn is_empty(&self) -> bool {
+        self.len() == 0
+    }
+
+    /// Iterate over all placed points
+    fn iter(&self) -> Box<dyn Iterator<Item = &PlacedPoint> + '_>;
+
+    /// Get current storage size in bytes
+    fn size_bytes(&self) -> usize;
+
+    /// Clear all points
+    fn clear(&mut self);
+}