Module embedding_viz 

Memory embedding visualization (RFC-T1-B).

Projects high-dimensional memory embeddings into 2D coordinates for the web UI Memory Map. We use truncated PCA via pure-Rust power iteration (no external linear-algebra dependency) and cosine-similarity for neighbor detection.

Why not UMAP / t-SNE?

The RFC recommends UMAP. We chose PCA for the MVP because:

1. No external dep — linfa/linfa-umap would add ~5MB of compile time and a non-trivial pure-Rust surface area. PCA via power iteration fits in ~80 lines.
2. Deterministic — given the same input we always get the same output (UMAP/TSNE have stochastic init).
3. Cheap-ish — O(nnz · iterations · k) for k components, where nnz is the number of non-zero entries across the input. The TF-IDF vectors the kernel produces are sparse (most entries are zero), so the practical cost is much lower than the dense O(n · d) bound. We work directly on the sparse representation and never densify.
4. Caches well — pure function of embeddings, perfect for the 5-min epoch cache the RFC requires.

PCA captures global structure (the principal axes of variance), not local neighborhoods. That is sufficient for “is this cluster of Hot memories visually distinct from Cold?” — the use case for the MVP. UMAP can be added later behind the same interface.

Structs

MemoryMapEntry

One node on the memory map.

MemoryNeighbor

Edge from one memory to a similar neighbor.

Functions

compute_pca_2d

Project a set of embeddings into 2D coordinates via PCA.

compute_top_neighbors

Top-k most similar neighbors per embedding, cosine-similarity only.