fix(core): default reranker document cap to 2000 chars

[phernandez]

Closes #1234. Data-driven default change from the full LoCoMo sweep (results and decision
recorded on the issue):

Config	R@5	MRR	single_hop R@5
cap=0 (old default)	0.758	0.719	0.537
cap=2000 (new default)	0.758	0.719	0.537
cap=1000	0.744	0.708	0.524

Caps ≥ 2000 measured identical quality to unbounded, to three decimals, overall and
per-category — while a 2000-char cap bounds worst-case rerank latency on very long
documents (the pathological case behind the original 5x p95 finding in #1231). cap=1000
costs real quality and stays opt-in.

The sweep also showed LoCoMo-class latency is candidate-count-driven, not length-driven,
so the docs tuning guidance now says so: lower reranker_candidates to reduce latency;
the char cap only matters for long documents; 0 disables the cap.

Changes: config default 0 → 2000 with an evidence-citing description;
docs/semantic-search.md config table + tuning section updated.

Verification: rerank + config focused suites 224 passed; broad tests/repository/ +
tests/services/ 1018 passed; just typecheck + just lint clean.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CPdSXDbYyhyZ1TwgFnpEv8

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: aff07a0fac

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Migrate previously persisted zero defaults

For users whose config was saved after this field was introduced, save_basic_memory_config() serializes every model field, so config.json already contains reranker_max_document_chars: 0 even when the user never selected it. On upgrade, that stored value overrides this new Pydantic default, leaving those installations exposed to the same unbounded long-document latency this change is intended to fix. Add an upgrade path that moves automatically persisted old defaults to 2000 while retaining a way for users to explicitly opt into 0.

Useful? React with 👍 / 👎.