MCPcopy Index your code
hub / github.com/carsonpo/haystackdb

github.com/carsonpo/haystackdb @main

Chat with this repo
repository ↗ · DeepWiki ↗ · + Follow
198 symbols 531 edges 36 files 6 documented · 3%
What it actually does AI analysis from the code graph — generated when you open this
loading…
README

HaystackDB

Minimal but performant Vector DB

Features

  • Binary embeddings by default (soon int8 reranking)
  • JSON filtering for queries
  • Scalable, distributed architecture for use with multi replica deployments
  • Durable (WAL), persistent data, mem mapped for fast access in the client

Benchmarks

On a MacBook with an M2, 1024 dimension, binary quantized.

FAISS is using a flat index, so brute force, but it's in memory. Haystack is storing the data on disk, and also brute forces.

TLDR is Haystack is ~10x faster despite being stored on disk.

100,000 Vectors
Haystack — 3.44ms
FAISS    — 29.67ms

500,000 Vectors
Haystack — 11.98ms
FAISS    - 146.50ms

1,000,000 Vectors
Haystack — 22.65ms
FAISS    — 293.91ms

Roadmap

  • Quickstart Guide
  • Quality benchmarks (this is in progress)
  • Int8 reranking
  • ~~Better queries with more than simple equality~~ (this is done now)
  • Full text search
  • ~~Better insertion performance with batch B+Tree insertion~~ (could probably be further improved, but good for now)
  • ~~Point in time backups/rollback~~
  • currently this is destructive (ie you cannot return forward after you go backwards), so a nondestructive version is next on the todo list.
  • Cursor based pagination
  • Schema migrations
  • Vector Kmeans clustering with centroid similarity for improved search perf

Extension points exported contracts — how you extend this code

TreeSerialization (Interface)
(no doc) [10 implementers]
src/structures/tree/serialization.rs
TreeDeserialization (Interface)
(no doc) [10 implementers]
src/structures/tree/serialization.rs
TreeSerialization (Interface)
(no doc) [2 implementers]
src/structures/mmap_tree/serialization.rs
TreeDeserialization (Interface)
(no doc) [2 implementers]
src/structures/mmap_tree/serialization.rs

Core symbols most depended-on inside this repo

clone
called by 88
src/structures/tree/node.rs
len
called by 72
src/structures/dense_vector_list.rs
push
called by 48
src/structures/dense_vector_list.rs
insert
called by 32
src/structures/tree.rs
store_node
called by 20
src/structures/mmap_tree/storage.rs
load_node
called by 14
src/structures/mmap_tree/storage.rs
insert
called by 8
src/structures/mmap_tree.rs
read_from_offset
called by 8
src/structures/mmap_tree/storage.rs

Shape

Method 111
Function 60
Class 20
Interface 4
Enum 3

Languages

Rust100%

Modules by API surface

tests/trees.rs16 symbols
src/structures/wal.rs16 symbols
src/structures/mmap_tree/node.rs15 symbols
src/structures/mmap_tree/storage.rs14 symbols
src/structures/metadata_index.rs13 symbols
src/structures/filters.rs13 symbols
src/structures/mmap_tree.rs12 symbols
tests/math.rs11 symbols
tests/filters.rs11 symbols
src/structures/inverted_index.rs11 symbols
src/structures/dense_vector_list.rs9 symbols
src/structures/tree/node.rs7 symbols

For agents

$ claude mcp add haystackdb \
  -- python -m otcore.mcp_server <graph>

⬇ download graph artifact