Skip to content

v3.1.0 — Vector Store Overhaul

Choose a tag to compare

View all tags
@tuancookiez-hub tuancookiez-hub released this 06 Jul 20:06
v3.1.0
fb8bbe0

Vector Store Overhaul: Qdrant → Zvec

From external vector service to embedded retrieval core. Less overhead. Faster search. Cleaner memory architecture.

What Changed

  • Zvec is the sole runtime vector store — no Qdrant sidecar, no external binary, no network hop
  • Qdrant runtime adapter removed — vector_store_qdrant.py and bm25_fastembed.py (Qdrant sparse BM25 encoder) deleted from runtime
  • Factory is zvec-only — create_vector_store() rejects any provider other than zvec
  • Config validation enforces zvec — hyatlas config validate rejects provider: qdrant
  • hyatlas start never starts Qdrant — even if stale config says qdrant
  • Native BM25 via Zvec FTS — no fastembed dependency, built-in full-text search on content and search_text fields
  • Dashboard uses VDB API — layer counts, L1 scroll, payload enrichment via /api/v1/vdb/* endpoints (not direct Qdrant HTTP)
  • hyatlas archive qdrant — cold zip backup of legacy Qdrant data
  • hyatlas zvec doctor — path lock/reopen diagnostics
  • Migration tooling — scripts/migrate_qdrant_to_zvec.py --apply --verify

Metrics

Metric Value
Vector search speed 18x faster (0.9ms vs 16.4ms)
Filtered retrieval 169x faster (native filter path)
Recall quality 100% (zero precision loss)
BM25 Native (no fastembed dependency)
Operations Qdrant removed (simpler, local backend)

Search Completeness Fixes

  • _doc_to_node normalizes migrated epoch-string timestamps → ISO
  • vdb_dashboard.payload_by_ids reads MemoryNode.importance/access_count (was crashing on .meta_info)

Consistency (Deep Review)

  • config_cli validate enforces zvec as only runtime provider
  • default_config uses zvec
  • hyatlas doctor vector-store check is provider-aware
  • Console TUI shows Zvec health row
  • L1_RAW sweep is provider-aware (zvec path reuses live handle)
  • Legacy Qdrant warning is now non-blocking with archive guidance

Upgrade Notes

  1. Set vector_store.provider to zvec in your config
  2. Install: pip install hyatlas-memory[zvec] (or zvec>=0.5.1)
  3. Stop server, run migration: python scripts/migrate_qdrant_to_zvec.py --apply --verify
  4. Run: hyatlas zvec doctor
  5. Start: hyatlas start
  6. Archive Qdrant: hyatlas archive qdrant

Verification

  • Tests: 54 passed, 12 deselected (CI mode)
  • Ruff: All checks passed (src/ + tests/)
  • Security scan: No secrets, no injection risks
  • Sentinel adversarial review: Passed
  • Live E2E: Search ✓, layer counts ✓, graph (1444 nodes / 6374 relations) ✓, dashboard ✓, VDB scroll ✓

Qdrant is archived, not deleted. Safe rollback if ever needed.

Assets 3
Loading