feat(recall): add a per-bank enable_text_search toggle for pure vector recall

[nicoloboschi]

Why

Recall runs four arms behind three per-bank switches — enable_temporal_retrieval, enable_graph_retrieval, enable_reranking. The keyword (BM25) arm had none, so a bank whose queries are conceptual rather than literal could not opt out of it, and there was no way to run pure vector recall.

The gate

Semantic and BM25 share a single UNION query, so "disabled" has to mean the BM25 half is never built, not that its rows are filtered away afterwards. The flag lands on the existing _include_bm25 path, which already omitted the arm for a query with no word characters:

tokens = tokenize_query(query_text) if enable_text_search else []

What a disabled arm no longer pays for:

Cost	Disabled
BM25 arms in the UNION (@@ / ts_rank_cd scan, one per fact type)	not built
select_selective_bm25_tokens — a real pg_stats round trip	not called
tokenize_query over the query text	not called
$3/$4 bind params (BM25 limit + prepared text)	not appended

The dense arm, its thresholds, and the graph seeding off it are unchanged. The emitted SQL is the semantic UNION alone.

Wired like enable_graph_retrieval

Hierarchical (global env → tenant → bank), threaded as a parameter rather than read off the global config:

• config.py — ENV_/DEFAULT_, dataclass field, from_env(), _CONFIGURABLE_FIELDS
• http.py — CreateBankRequest + BankTemplateConfig + the get_config_updates field list
• memory_engine → retrieve_all_fact_types_parallel → recall_unified → search → the SQL builder
• Regenerated: OpenAPI spec, bank-template schema, Python/TS/Go clients, docs skill
• Hand-written wrappers: HindsightClient (TS) and Hindsight (Python), both createBank and updateBankConfig
• Control plane: the Recall section of the bank config view, plus recallTextSearch* strings in all ten locales

HINDSIGHT_API_ENABLE_TEXT_SEARCH sets the deployment-wide default a bank inherits.

Two follow-through details

Knowledge-page search resolves the same per-bank flag and collapses to its vector half, so a bank that switched the arm off in recall does not keep hitting a text index there. Its BM25-only fallback (for a missing embedding) returns nothing rather than degrading into the arm the bank disabled.

The recall trace omits its bm25 entry when the arm is off, mirroring the existing graph guard — an empty entry reads as "ran, matched nothing" rather than "absent", which is backwards for anyone comparing traces to tune latency.

Scope

Read path only. memory_units.search_vector is a GENERATED column on the native backend and the text index is created by migrations, so skipping write-side maintenance would be a schema change and would make the flag one-way. As built it is reversible without a reindex.

Tests

• test_enable_text_search_flag.py — asserts the absence of work (no tokenization, no pg_stats lookup, no BM25 arm, 2 bind params instead of 4), each paired with an enabled-case guard so nothing passes vacuously; plus env parsing and membership in the configurable set.
• test_knowledge_search_text_search_disabled.py — the vector-only knowledge SQL, the empty-result case, the untouched fallback, and that bank isolation (kp.bank_id = $2) survives the rewritten query.
• test_recall_pipeline_toggles.py — extended so the new toggle is covered by both the plumbing test and the bank-override → retrieval-call wiring test.
• recall_pipeline_toggles_mapping.test.ts — new; the TS wrapper had no mapping test for any of the four toggles, mirroring the Python one.
• test_hierarchical_config.py (count 46 → 47) and test_bank_template_full_roundtrip.py updated.

Notes for the reviewer

• plain-retrieval.json and the "plain-retrieval (RAG) banks" doc section deliberately keep hybrid search — BM25 is cheap next to the LLM/graph/rerank work that section is about, and flipping them is a product opinion, not part of adding the flag.
• Unrelated: consolidation/consolidator.py calls recall_unified and reads only .semantic, so it pays for the keyword arm it discards (its comment claims it needs "dense/keyword"). Left alone — changing dedup's candidate set is not this PR's business.
• test_hnsw_indexes.py and test_bank_template_full_roundtrip.py fail on my machine against a shared pg0 stamped ahead by another branch; both were verified to fail identically on a clean tree.

https://claude.ai/code/session_017ufCz6qrNxn36Stug7ek8A

[strix-security]

Strix Security Review

Warning

This pull request has 2 commits after the last Strix review (7c21d70). Strix has not reviewed these changes.
Automatic review on push is off for this repository. To review the latest changes, tag @strix-security in a comment, or turn on re-review on push.

No security issues found.

_{Updated for 7c21d70.}

---

Reviewed by Strix
_{Re-run review · Configure security review settings}