EchoSpine

Approximate nearest neighbor (ANN) for apps on every device — phone, tablet, laptop, desktop. Native C++ core (ctypes / optional pybind) with Python API. Two install flavors: general core and app-optimized AppKit.

License: PolyForm Noncommercial 1.0.0 (free for non-profit use). See LICENSE and LICENSE_NOTES.md.

---

Choose your flavor

General ANN core

git clone https://github.com/DPGS-oss/echospine-lab.git
cd echospine-lab
pip install -e .
cmake -S native -B native/build
cmake --build native/build --config Release --target echospine_core

from echospine import Index
import numpy as np
data = np.random.randn(2000, 64).astype(np.float32)
idx = Index(64)
idx.build(data)
ids, stats = idx.search(data[0], top_k=5)  # stats.backend == "native" when DLL found

Docs: docs/CORE.md

App-optimized layer (includes core)

pip install -e ".[app]"

from echospine.app import AppIndex
app = AppIndex(64, preset="balanced")
app.set_memory_budget_bytes(32 * 1024 * 1024)  # hard trim of re-rank tiers
app.build(data)
ids, stats = app.search(data[0], top_k=5)

Native: cmake --build native/build --config Release --target echospine_app

Docs: docs/APP.md

---

Where we stand vs other ANNs (measured)

Same machine, fresh AppScore run with native echospine_core.dll wired.

A. General vectors — Index vs FAISS HNSW (N=2000, dim=64)

Method	Recall@5	Query ms	Bytes/vec	RAM B/vec	Append	Cold-start
EchoSpine Index (native)	0.992	0.068	268	281	~54 ms	~22 ms
FAISS HNSW	1.000	0.075	384	384	(rebuild/insert)	full load

Verdict: near-HNSW recall with lower disk and RAM. With the native library loaded, query P50 matches or beats FAISS HNSW on this harness (≤2× gate; here slightly faster). Disk bytes are honest (PQ + full SQ + CSR + sq8 re-rank), still ~30% under HNSW. Pure-NumPy fallback remains slower — build the shared library for the latency win.

B. Legacy ledger cascade vs industry (N=3000, dim=16)

Method	Recall@5	Query ms	Bytes/vec
FAISS HNSW / IVF-Flat	1.00	~0.04–0.07	68–192
FAISS IVF-PQ	0.77	~0.05	8
EchoSpine Cascade (ledger)	0.80	~2.4	9.1 (codes+metadata)

Prefer Index / AppIndex for new general-app work; keep Cascade for structured ledgers.

Honest summary

Question	Answer
Best ANN overall (exact + GPU / billion-scale)?	No — FAISS Flat / GPU / large-scale stacks still win that.
Match HNSW recall with less memory?	Yes — ≈0.99 R@5 at fewer bytes.
Competitive query µs with native core?	Yes on this app-scale harness.
Beat FAISS in pure Python alone?	No. Build echospine_core.

Reproduce:

pip install -e ".[app,dev]"
cmake -S native -B native/build && cmake --build native/build --config Release --target echospine_core
python -m echospine.appscore --n 2000 --dim 64 --profile laptop
python -m echospine.industry_compare --n 3000 --queries 20

More detail: COMPARISON.md · HOW_IT_WORKS.md

---

Layout

echospine/           # Python general core (Index)
echospine/app/       # AppKit (AppIndex)
native/core/         # C++ echospine_core (SHARED)
native/app/          # C++ echospine_app
docs/CORE.md
docs/APP.md