neuron/docs/architecture/design/perf/engram-geometry-priming-profile.md

Perf Profile — M9 Geometry Priming (ENGRAM_GEOMETRY_PRIMING)

Date: 2026-08-12 Branch: engram-tiered-storage Change: ENGRAM_GEOMETRY_PRIMING (default OFF) in el_runtime.c engram_activate + engram_geometry.c Method: A/B over 15 representative queries against a copy of the recovered store (~/.neuron/engram/.neuron.egm.disabled, ~4190 embedded nodes, 768-d nomic-embed-text), throwaway HOME, ports 48799/48800. Live :8742 never touched. engram.c (folded from server.el) reused byte-identical across M8 and M9, so the only variable is el_runtime.c.

Three configs: A = M9 flag OFF · B = M9 flag ON (=1) · C = pre-M9 M8 baseline binary.

---

Build

Artifact	Result
M9 -O2 link (… engram_geometry.c … -lssl -lcrypto -lcurl -lpthread -lm)	rc=0, 499,720 B arm64
ASan/UBSan link (-fsanitize=address,undefined -O1)	rc=0, 1,945,616 B
Warnings from el_runtime.c / engram_geometry.c	0 (3 pre-existing -Wparentheses-equality in generated engram.c only)
nm: engram_geo_mean_build, engram_geometry_descriptor	present (T); eg_geometry_priming_on inlined (static-local .cached present in both binaries)

Note: the bare cc … -lm link fails with undefined _curl_* — el_runtime.c uses libcurl for the ollama embedder. The canonical link must include -lssl -lcrypto -lcurl (per link.sh).

---

Latency (wall-clock, curl -w %{time_total}, 15 queries)

config	median	p90	min	max
A — M9 OFF	77.8 ms	80.5 ms	71.1	84.2
C — M8 baseline	76.0 ms	81.2 ms	71.4	91.4
B — M9 ON	249.6 ms	1039.2 ms	169.2	1256.3

• OFF adds zero cost: 77.8 ms vs M8 76.0 ms — within noise. The flag is free when unset.
• ON regresses hard: 3.21x median (+171.8 ms), ~13x p90 (80 → 1039 ms), max 1.26 s.
• The warm-cache path (global mean already built) is ~0.5 s; the cold path pays the full engram_geo_mean_build scan (O(N·dim) over ~4190 × 768). The persistent per-query cost is the descriptor itself — covariance eigensolve over up to max_members (400) × 768-d plus one store_get_node paged read per member — run on every activation while the flag is ON.

---

Retrieval quality (the win it was supposed to buy)

Coherence — mean pairwise cosine in centered space, top-20 by activation strength (node embeddings re-derived via nomic-embed-text; centered against the mean of the gathered result set — the true store-wide mean is not exposed by the API, flagged as an approximation):

	OFF	ON	Δ
mean over 15 queries	0.1067	0.1114	+0.0047 (noise)
queries where ON > OFF	—	—	4 / 15

Two real sparse-cue wins (self identity values +0.118, hebbian learning edges +0.064), but the polysemous cues — the disambiguation target — are mostly flat or down.

Disambiguation — no clean "scope to one sense" pattern on polysemous cues. Additions/drops are small (±2..8 of 300-item sets) and not sense-coherent (e.g. memory gains some on-domain nodes but also infra items; core similar).

Count shift: ON adds sub-threshold neighbors to sparse cues (+3..+4) and trims a few from dense polysemous cues (−1..−3) — consistent with priming warming sparse neighborhoods and damping off-domain seeds on dense ones, but the net does not move measured coherence.

---

Correctness / safety (all pass)

Check	Result
Byte-identical: A (OFF) == C (M8) result id sequence + order, all 15 queries (incl. 301/294/263-item sets)	PASS (only wall-clock ACT-R fields differ; activation_strength max |Δ| = 2e-5)
WM promoted ≤ 24 under ON	holds (exactly 24 on dense cues)
Queries with results under OFF → empty under ON	0
Crash / hang under ON	none (max hops = 1)
ASan + UBSan under ON (cold build + warm descriptor paths)	CLEAN — no report

---

Conclusion

• Deploy default-OFF binary: GO. Byte-identical to M8, zero cost off, clean build, sanitizer clean.
• Enable flag: NO-GO (for now). 3.21x median / ~13x p90 latency for no reliable quality gain (coherence +0.0047 mean = noise; no clean disambiguation). Correctness/safety are fine — it simply does not earn its cost. This is a cost/benefit NO-GO, not a defect.

Prerequisites before re-evaluating the flag

1. Amortize the descriptor cost. The per-query geo-mean build + eigensolve + paged reads dominate. Cache the neighborhood descriptor (it is the M10 cell-assembly cache's job) and/or compute geometry periodically/off-hot-path rather than on every engram_activate.
2. Center against the true store-wide mean (the GeoMeanCache already computes it) rather than a per-query gathered-set approximation, and re-measure coherence — the current signal may be understated by the approximation.
3. Re-tune ENGRAM_GEO_SEED_LO / PRIME_SCALE / PRIME_MAX and re-measure only after (1), so tuning is not chasing latency noise.