Fix public-facing claims: caveat E8-exact-match scope, remove unqualified 100% Recall@10 figure, point to library README's verified per-mode numbers

README.md

@@ -29,27 +29,45 @@ model-index:
 Part of the [LatticeMemory](https://huggingface.co/spaces/dfrokido/LatticeMemory) project.
 [**GitHub →**](https://github.com/sangmorg1-debug/latticememory)
 
-## What Makes This Different
+## What this model is for
 
 Standard embedding models output float32 vectors. This model is trained so its outputs
-naturally snap to the nearest point in the E8 lattice — the densest sphere packing in
-8 dimensions. The result: a **32x smaller** index with **better STS quality** than
-the float32 baseline.
+snap to the nearest point in the E8 lattice — the densest sphere packing in 8 dimensions —
+giving a compact 128-byte address alongside the usual embedding. That address is a reliable,
+O(1) match for **identical or near-identical text** (exact-repeat caching, deduplication,
+closed-vocabulary intent matching). It is **not** a general semantic-search replacement: the
+E8 address alone does not reliably match open-vocabulary paraphrases or asymmetric
+query/passage pairs. See [LatticeMemory's README](https://github.com/sangmorg1-debug/latticememory#readme)
+for the current, verified breakdown of which retrieval mode to use for which workload —
+including a documented case (held-out CLINC150 intents) where the E8 address mechanism
+scored 0.00% and Product Quantization, not the E8 lattice, is the component that gets real
+paraphrase recall (31% Recall@1 on PAWS).
 
 ## Benchmarks
 
+What's verified about the *model itself*, independent of retrieval mode:
+
 | Metric | Float baseline (bge-large-en-v1.5) | This model |
 |---|---|---|
 | STSBenchmark (Spearman) | 0.8637 | **0.8714** (+0.0077) |
 | STS13 | — | **0.8826** |
-| Index compression | 1x | **32x** |
-| Retrieval @ 100K docs | 20.8 ms (scan) | **O(1) on E8 key hit** |
-| Recall@10 (MS-MARCO 1K) | 100% | **100%** |
+| E8 key size vs. float32 | 4,096 bytes | **128 bytes (32x smaller)** |
+
+The STS gain is real but modest — this model is not meaningfully "better at search" than
+the float baseline; it's the same quality embedding with an added property (E8-snappable
+outputs). The 32x figure is a storage-size fact (1 address byte per 8-dim block × 128
+blocks), not a recall or accuracy claim — recall/accuracy depend entirely on which
+LatticeMemory retrieval mode you use on top of it. An earlier version of this card quoted
+"100% Recall@10 on MS-MARCO (1K docs)" without the retrieval-mode context; that number came
+from a small-scale exact/near-exact-repeat test, not asymmetric passage retrieval — see the
+library README's own benchmark table for the real, mode-by-mode picture (including where
+this mechanism scores 0% on real asymmetric RAG).
 
 > **Compression basis:** 1 address byte per 8-dim block × 128 blocks = 128 bytes for a
-> 1024-dim embedding, vs 4,096 bytes for float32 = 32x. This applies to E8 key storage;
+> 1024-dim embedding, vs 4,096 bytes for float32 = 32x. This applies to E8 key storage only;
 > see [LatticeMemory](https://github.com/sangmorg1-debug/latticememory) for hybrid mode,
-> which also stores a dense fallback index for asymmetric retrieval.
+> which also stores a dense (Int8/float32) fallback index for asymmetric retrieval — that
+> fallback, not the E8 key, is what actually serves paraphrase/RAG queries today.
 
 ## Usage
 
@@ -60,7 +78,9 @@ import torch, math, torch.nn.functional as F
 model = SentenceTransformer("dfrokido/bge-large-e8-snap")
 embeddings = model.encode(["What is the capital of France?"], convert_to_tensor=True)
 embeddings = F.normalize(embeddings.float(), p=2, dim=1)
-# Embeddings are now ready for LatticeMemory indexing — 32x smaller index
+# Embeddings are now ready for LatticeMemory indexing.
+# For open-vocabulary text, use LatticeMemory's mode="pq" (Product Quantization) —
+# not the raw E8 exact-match key — see the library README for why.
 ```
 
 ## Training
@@ -74,8 +94,17 @@ Fine-tuned from `BAAI/bge-large-en-v1.5` using RF-Snap training:
 ## LatticeMemory
 
 This model powers [LatticeMemory](https://huggingface.co/spaces/dfrokido/LatticeMemory)
-([GitHub](https://github.com/sangmorg1-debug/latticememory), `pip install latticememory`) —
-a semantic cache, dedup, and hybrid memory library for LLM applications. 32x compressed
-E8 keys for instant repeat-query cache hits, dense fallback for novel retrieval.
+([GitHub](https://github.com/sangmorg1-debug/latticememory)) — a semantic cache, dedup, and
+hybrid memory library for LLM applications.
+
+```bash
+pip install lattice-memory-e8   # import name is still `latticememory`
+```
+
+E8 keys give O(1) hits for exact/near-exact repeat queries and cheap deduplication. For
+open-ended paraphrase caching, use the library's Product Quantization mode; for asymmetric
+QA/RAG, use hybrid mode with its dense fallback. The library's own README documents which
+mode is validated for which workload, including the cases that don't work — read that before
+choosing a mode for production.
 
 Design partner inquiries: dfrokido@gmail.com