ADR-312: Long-term spatial memory — learn the normal physics of a location

Status: Accepted — initial implementation (ADR-300 phase 3)
Date: 2026-08-11
Deciders: ruv
Tags: spatial-memory, ruvector, anomaly-detection, temporal, world-state, phase-3

Context

This ADR is a child of ADR-300 and owns primitive #12, long-term spatial memory. In the ADR-300 phasing it is a phase-3 primitive that sits on the fused world state produced by ADR-311 (real sensor fusion) and ties to ADR-315 (digital RF twin): spatial memory is the learned normal that a twin can simulate against and that anomaly detection compares against. It is authored as Proposed.

The capability is to learn the normal physics of a location so anomalies surface without training a detector for every anomaly. Concretely, the system should learn statements like: "a chair is normally here"; "this bedroom is usually occupied between these hours"; "the RF propagation of this space changed"; "this machine's vibration signature changed"; "a new reflector appeared." None of these is a labeled anomaly class — they are deviations from a learned baseline of normality. This is the difference between supervised anomaly detection (which needs examples of every failure) and baseline-relative anomaly detection (which needs only a well-characterized normal).

Substantial substrate already exists and must be reused/extended, not rebuilt:

RuVector (v2/crates/wifi-densepose-ruvector) is the designated substrate in the ADR-282 layer stack ("persistent objects, Gaussian fields, scene graphs, temporal memory"). It already provides the vector/temporal machinery this ADR needs — HNSW indexing (hnsw.rs, hnsw_quantized.rs), an event log (event_log.rs), coverage and estimator surfaces, and the crv/mat temporal sub-modules — so long-term spatial memory is a consumer and organizer of RuVector primitives, not a new store.
ADR-306 supplies the entity vocabulary the memory is indexed by (Space, Object, Sensor, Track, Event); ADR-311 supplies the fused, uncertainty-carrying WorldState snapshots that memory accumulates over time.
ADR-135 (empty-room baseline calibration) and ADR-301 (automatic domain calibration) already establish a calibration-time baseline of a space; ADR-312 extends that from a one-shot baseline to a continuously learned, time-of-day-aware model of normal.

What is missing is the temporal normality model: a per-Space learned distribution of fused world states over time (including periodicity — hour of day, day of week), plus RF-propagation and modality-signature baselines, against which a live fused state is scored for deviation.

Options considered

Supervised anomaly classifiers per anomaly type. Rejected: it needs labeled examples of every anomaly (fall, intrusion, machine fault, moved furniture), which do not exist for most spaces and do not transfer between rooms; it also cannot catch a novel anomaly it was never trained on.
Single static baseline (the ADR-135 empty-room snapshot, used forever). Rejected as the endpoint: it cannot express when a space is normally occupied, cannot track slow legitimate drift (furniture rearranged on purpose), and flags every diurnal change as anomalous.
Continuously learned, time-aware normality model on the RuVector substrate, scoring live fused state against learned normal. Chosen.

Decision

Adopt a long-term spatial memory that learns each location's normal physics on the RuVector substrate and scores live fused state against it.

1. What "normal" is learned over

Per ADR-306 Space (and the entities within it), accumulate the ADR-311 fused WorldState over time into a learned normality model covering:

Occupancy / activity periodicity — the distribution of presence and activity by hour-of-day and day-of-week (the "bedroom usually occupied certain hours" case).
Static scene layout — persistent Object positions and the expected reflector set (the "chair normally here" / "new reflector appeared" cases), building on the ADR-135/298 baseline.
RF-propagation baseline — the space's normal multipath/propagation signature (the "RF propagation changed" case).
Per-modality signatures — e.g., a machine's normal vibration/acoustic/IMU signature (the "vibration signature changed" case).

Each learned baseline carries its own uncertainty and an EvidenceLevel (ADR-282); a baseline learned from replay is L1, from a field pilot L4, and is never presented above the evidence of the observations it was learned from.

2. Substrate: RuVector, temporally compressed

The memory is stored and indexed on RuVector (HNSW for nearest-normal recall, the event log for the temporal stream, the temporal sub-modules for compression). Long-horizon history is temporally compressed — recent detail retained, older history summarized — so memory cost is bounded rather than growing linearly forever.
The memory is keyed by the ADR-306 ontology, so "normal for this Space at this hour" is a first-class query, and slow legitimate drift updates the baseline (with provenance) instead of accumulating as permanent anomaly.

3. Anomaly = deviation from learned normal

A live fused WorldState is scored against the applicable learned baseline (matched by space and time context). A deviation beyond the baseline's uncertainty is surfaced as an ADR-306 Event — without a per-anomaly detector — carrying the baseline it deviated from, the deviation magnitude, and its evidence level. Whether that event is actionable is a policy/consumer decision (ADR-277), not this layer's.
The learned normal is exactly what ADR-315 (RF twin) can simulate against: the twin proposes an expected state, spatial memory supplies the learned actual-normal, and their divergence is a physically grounded anomaly signal.

Consequences

Anomaly detection generalizes: a space gets deviation detection from its own learned normal, so a novel anomaly (never labeled anywhere) still registers as a deviation, and the model transfers to a new room by learning that room's normal rather than importing a foreign detector.
Bounded memory: temporal compression keeps long-horizon memory finite; the trade-off is that fine detail of old history is summarized, which is acceptable for a normality baseline.
Legitimate change is not a permanent false positive: slow drift updates the baseline with provenance, distinguishing "furniture deliberately rearranged" (baseline shifts) from "reflector appeared unexpectedly" (deviation event).
No accuracy claim is made. Deviation-detection quality is not asserted here; any detection-rate or false-positive number requires a named reproducer tagged MEASURED / SYNTHETIC / CLAIMED, and a health/safety framing stays within the ADR-282 bounded-claims discipline (decision support, not diagnosis). No number is invented.
The memory is governed: learned baselines are observations of a space, subject to the same ADR-277 retention/privacy policy as the fused state they summarize; no raw P0 RF is retained to build a baseline.

Validation

cargo test -p wifi-densepose-ruvector — the normality model builds on the existing HNSW/event-log/temporal primitives; nearest-normal recall and temporal-compression bounds are exercised on synthetic streams.
Baseline/deviation tests: a synthetic scene with a known injected change (moved Object, altered propagation, altered modality signature) produces a deviation Event against the learned normal without a per-anomaly detector; an unchanged diurnal cycle produces none (no false positive on normal periodicity).
Drift test: a slow legitimate change updates the baseline (with provenance) rather than emitting a persistent anomaly; an abrupt change does emit one.
Evidence test: a learned baseline carries the evidence level of its source observations and is never presented above it; retention honors ADR-277.
Twin-linkage design check (with ADR-315): divergence between a twin-simulated expected state and the learned normal is expressible as a deviation signal.

8.2 KiB Raw Blame History