README.md

---
language: en
license: apache-2.0
tags:
  - sentence-transformers
  - feature-extraction
  - sentence-similarity
  - e8-lattice
  - rf-snap
  - latticememory
base_model: BAAI/bge-large-en-v1.5
model-index:
  - name: bge-large-e8-snap
    results:
      - task:
          type: semantic-textual-similarity
        dataset:
          name: STSBenchmark
          type: mteb/stsbenchmark-sts
        metrics:
          - type: spearman_cosine
            value: 0.8714
---

# bge-large-e8-snap

**bge-large-en-v1.5 fine-tuned with RF-Snap to align embeddings to the E8 lattice.**

Part of the [LatticeMemory](https://huggingface.co/spaces/dfrokido/LatticeMemory) project.
[**GitHub →**](https://github.com/sangmorg1-debug/latticememory)

## What this model is for

Standard embedding models output float32 vectors. This model is trained so its outputs
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** |
| 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 describes the *added* E8 key
> structure's size, not a reduction in what's stored — LatticeMemory retains a full-precision
> embedding for every document permanently (used for exact-hit scoring), in every mode,
> whether or not a dense fallback is configured; there's no path to discard it once a document
> is keyed. The E8 key is an O(1) hash-bucket lookup layer added on top of the retained
> embedding, not a replacement for it — it buys lookup **speed** for exact/near-exact hits, not
> smaller total memory. See [LatticeMemory's README](https://github.com/sangmorg1-debug/latticememory#readme)
> for the full breakdown, including hybrid mode's separate dense (Int8/float32) fallback index
> for asymmetric retrieval — that fallback, not the E8 key, is what actually serves
> paraphrase/RAG queries today.

## Usage

```python
from sentence_transformers import SentenceTransformer
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.
# 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

Fine-tuned from `BAAI/bge-large-en-v1.5` using RF-Snap training:
- Loss: cosine similarity + MNRL + E8 address cross-entropy + teacher anchor
- Data: NLI 50K pairs
- Config: freeze_until=10/24, lr=3e-6, batch=8, grad_accum=4, 1 epoch
- Hardware: GTX 1660 Ti (6GB VRAM)

## LatticeMemory

This model powers [LatticeMemory](https://huggingface.co/spaces/dfrokido/LatticeMemory)
([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