Adds native FalkorDB vector index support to graphiti-core's FalkorDB
driver. Three patched files (graph_queries.py, falkordb_driver.py,
falkordb/operations/search_ops.py) plus apply.sh that backs up venv
files and copies patches over.
Why this exists: graphiti-core 0.29.0 builds similarity queries using
interpreted Cypher cosine math (vec.cosineDistance) which produces a
full-table scan over Entity/RELATES_TO/Community nodes for every search.
At ~4,000+ entities, single-episode add_episode took 8+ minutes for the
resolve-against-existing-graph step and bulk ingest hung indefinitely.
FalkorDB itself supports db.idx.vector.queryNodes and queryRelationships
procedures backed by HNSW indexes; the driver just doesn't use them.
Patches:
1. graph_queries.py — adds get_vector_indices() returning CREATE VECTOR
INDEX statements for FalkorDB (Entity.name_embedding,
RELATES_TO.fact_embedding, Community.name_embedding). HNSW with
cosine similarity. Adds VECTOR_INDEX_CANDIDATE_MULTIPLIER for
over-fetch when WHERE filters reject some top-k results. Original
get_vector_cosine_func_query preserved for fallback.
2. falkordb_driver.py — extends build_indices_and_constraints() to call
get_vector_indices() alongside range and fulltext. Adds cache
invalidation hook so the search_ops dispatcher re-probes for indexes
after they're built.
3. falkordb/operations/search_ops.py — adds vector-index dispatcher
helpers (_falkordb_vector_index_exists with module-level cache,
_falkordb_vector_node_search_cypher, _falkordb_vector_edge_search_cypher).
Rewrites the three vector-similarity call sites (Entity.name_embedding,
RELATES_TO.fact_embedding, Community.name_embedding) to use
db.idx.vector.queryNodes / queryRelationships when available, fall
back to interpreted-Cypher cosine math when not. Index existence
probed once per (label, attribute, entity_type) and cached.
Empirical result: single-episode add_episode against a 4,277-entity
graph went from indefinite hang to 8.2 seconds. Bulk re-ingest of
already-known content (worst case for entity dedup) committed in 60ms.
Activation requires bridging driver._search_ops to driver.search_interface
in the sidecar (see graphiti_service.py). graphiti-core declares
search_interface as the dispatcher attribute but never assigns the
per-driver implementation to it — naming mismatch in their internal
refactor. The bridge is one line in our sidecar's lifespan.
Upstream candidate: this is a known gap (referenced indirectly in
upstream issue #1263 RFC for external vector store overlay). Maintainers'
attention is on Milvus/Qdrant/Pinecone overlay; this is the FalkorDB-
native alternative for users who don't want to run a separate vector DB.
PR after empirical validation in production. Apache-2.0 graphiti-core
source is NOT vendored — backups/ is gitignored to keep the upstream
source out of this repo.
aaron
d2ec20e373