feat(neo4j): route similarity search through HNSW vector indexes

[xiaoyaner0201]

Refs #1793.

Problem

Neo4j similarity search computes vector.similarity.cosine() against every matching node/edge. On larger graphs this makes dedup/search take minutes and can leave long-running transactions behind.

What this does

• Creates opt-in Neo4j vector indexes for Entity.name_embedding, Community.name_embedding, and RELATES_TO.fact_embedding, using the configured embedding dimension rather than a hard-coded dimension.
• Routes both node_similarity_search and edge_similarity_search through db.index.vector.queryNodes / queryRelationships when use_vector_index is enabled.
• Keeps the exact cosine path as the default and as a fallback when the index is unavailable, offline, populating, mismatched, or otherwise cannot be used.
• Applies group_id, search, and endpoint filters after a bounded ANN over-fetch. If the filtered candidate window is sparse, it reruns the exact query so the old result-count contract is preserved.
• Plumbs the opt-in through Neo4jDriver and the public Graphiti constructor; indirect MCP construction can use GRAPHITI_NEO4J_USE_VECTOR_INDEX.
• Fixes the pre-existing edge bug where source/target UUID filters were silently ignored when group_ids was None.
• Leaves community_similarity_search and non-Neo4j providers unchanged.

Why this is not a blind #859 revert

#859 previously added an HNSW path but used a hard-coded dimension and a simpler opt-in. This implementation keeps indexing disabled by default, couples the index dimension to the configured embedder, preserves exact fallback, validates query dimensions, bounds lifecycle fallback to known index errors, and covers both node and edge search paths.

Evidence

A live local Neo4j 5.26 graph with approximately 52k Entity nodes and 2560-dimensional embeddings was used for an independent node canary. For the same real embedding vector:

• HNSW queryNodes top-10: approximately 4.9 seconds under host load
• Existing brute-force cosine top-10: approximately 155 seconds
• Top-10 set and order: identical in the single-seed comparison

A second live filtered probe used 12 random xiaoyaner-core seeds. The HNSW candidate path returned 10 rows for every seed and reduced the measured query time from 490.5 seconds total to 6.6 seconds total. Six of twelve had identical set and order; the remaining results had the same row count but ANN ranking/set differences, which is expected from approximate search and is why exact fallback remains available for sparse windows and the feature is opt-in.

A sparse-group probe showed the bounded candidate window can produce fewer than the requested limit. The implementation detects that case and reruns the exact filtered query; a focused regression test covers this fallback.

Testing

• 85 passed focused tests covering node/edge routing, filters, over-fetch, sparse-window exact fallback, lifecycle fallback, dimension validation, result shape, public wiring, and provider isolation.
• ruff check clean.
• ruff format --check clean.
• git diff --check clean.

The repository-wide non-integration suite was attempted but cannot be used as a green gate in this environment: unrelated integration-marked tests try to connect to localhost:7687, while the live Neo4j instance is isolated inside Docker and is not exposed on that host port. The run reached existing database-dependent errors; no code failure from this patch was established.

Scope / trade-off

HNSW is approximate. Results may differ from exact cosine even when the candidate window is full. Operators who require exact recall can leave the opt-in disabled. Operators enabling it should create/verify the indexes and compare their workload before making it the default in their deployment.

Index creation remains opt-in to avoid silently starting a potentially expensive index population during upgrade. The current local deployment has the indexes online and has separately verified the live node path, but this PR does not change upstream defaults.