feat(mcp): configurable search tuning — reranker choice, stale-fact filtering, result counts, relevance scores

[brentkearney]

Summary

Implements #1645: makes the MCP server's search behavior configurable instead of hardcoded. Adds a search config block (with SEARCH__* env vars) that controls which reranker orders results, whether superseded facts are returned, and the default result counts — and surfaces each result's relevance score so clients can judge match quality.

Everything lives in mcp_server/; graphiti_core is untouched.

What changes for users

search:
  reranker: rrf            # rrf | mmr | cross_encoder
  mmr_lambda: 0.5          # only used by mmr
  reranker_min_score: 0.0  # only meaningful for cross_encoder
  max_facts: 6             # default result count for search_memory_facts
  max_nodes: 6             # default result count for search_nodes
  exclude_invalidated: true

• search_memory_facts and search_nodes order results with the configured reranker. The default stays rrf, so out-of-the-box ordering is unchanged. When a center_node_uuid is given, the node-distance recipe still wins, as today.
• Facts that Graphiti's temporal model has marked invalid (superseded or expired) are excluded by default. Callers who want history back pass include_invalidated=true on the call.
• max_facts / max_nodes become deployment-level defaults with per-call overrides. The shipped default is 6, sized for feeding results into an LLM context window — happy to keep it at 10 if you'd rather not change the out-of-the-box count.
• Each returned fact/node now carries a score field from the reranker, so clients can apply their own cutoffs or weight results by confidence.

Design notes (learned on a live graph)

• MMR results are never score-filtered. MMR's scores aren't calibrated like cross-encoder scores; applying a cutoff to them collapses recall to near zero (same failure mode reported in [BUG] RuntimeWarning errors in MMR reranker, search does not return results #777). The config help text documents this, and reranker_min_score only applies to cross_encoder.
• cross_encoder is offered but not the default. It needs a configured cross-encoder client, adds a model call per search, and the core edge-search path currently truncates its candidate pool ([BUG] Cross-encoder reranking drops most candidates in edge_search #1642). The option is there for deployments that want it; the default doesn't depend on it.
• This PR is complementary to the cross-encoder client configuration work ([BUG] MCP Server: cross_encoder/reranker not configurable, hardcoded to OpenAI — requires OPENAI_API_KEY even with non-OpenAI providers #1393/MCP server crashes with non-OpenAI providers: OpenAIRerankerClient requires OPENAI_API_KEY even when using Azure/Anthropic/Gemini #1441 and PRs fix(mcp): configure cross-encoder from providers instead of hardcoded OpenAI #1637/fix(mcp): reuse configured LLM client for cross_encoder to avoid OPENAI_API_KEY requirement #1442/feat(mcp): add configurable reranker/cross-encoder support #1152/feat(mcp): add configurable cross-encoder for search result reranking #1174/feat(mcp): add local model support with openai_generic provider and reranker config #1227): those choose which client reranks; this chooses which strategy the search uses and how results are filtered and presented. With the default rrf, nothing here requires a cross-encoder client at all.

Files

• mcp_server/src/config/schema.py — new SearchTuningConfig block
• mcp_server/src/utils/search_tuning.py — builds the core SearchConfig for the chosen reranker; liveness filter for invalidated facts
• mcp_server/src/graphiti_mcp_server.py — search tools wired to the config, per-call overrides
• mcp_server/src/models/response_types.py, mcp_server/src/utils/formatting.py — score field on results
• mcp_server/README.md — env-var reference and cross-encoder caveat

Tests

• test_search_tuning.py, test_search_config_schema.py, test_formatting_score.py, test_search_tools_wiring.py — unit tests for the config block, search-config construction, liveness filtering, score formatting, and tool wiring (22 tests)
• test_search_relevance_int.py — integration test validating result relevance end-to-end (requires a live backend, skipped otherwise)

This configuration has been running in production on our deployment (Neo4j backend, OpenAI provider).

Closes #1645

[zep-cla-assistant]

Thank you for your submission, we really appreciate it. Like many open-source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution. For privacy information, see our Privacy Notice. You can sign the CLA by just posting a Pull Request Comment same as the below format.

---

I have read the CLA Document and I hereby sign the CLA behalf on myself, e-mail: example@example.com

or

I have read the CLA Document and I hereby sign the CLA behalf of my company, e-mail: example@example.com

Signature is valid for 6 months.

---

_{This bot will be retriggered when the Contributor License Agreement comment has been provided. Posted by the CLA Assistant Lite bot.}

[brentkearney]

I have read the CLA Document and I hereby sign the CLA behalf on myself, e-mail: 02cirque_ladles@icloud.com