feat(core): add opt-in OR search fallback

[kongtou20070406]

Summary

• add an opt-in fallback: 'or' retry when the existing FTS query returns zero rows
• preserve exact search as the unchanged default and keep every existing visibility/source/time filter on the retry
• document the option as a second-pass recall tool in the shipped skill

Closes #143.

Evidence

• npm test -- tests/query.test.mjs: 32/32 passed
• core typecheck and changed-file lint passed
• skill validation passed
• frozen Mem2ActBench-small development split (50 positive questions, Luna Max reader): end-to-end exact match 0.00 -> 0.18; argument F1 0.0313 -> 0.3047; slot accuracy 0.0283 -> 0.2453
• paired end-to-end wins/harms: 9/0, exact one-sided sign-test p=0.001953
• retrieval p95: 19.82 ms; the original exact arm's prompts and predictions were byte-identical to no-context, confirming the retry only activates after zero hits

The external test split remains sealed and is not used to tune this change.

[Copilot]

🟢 Approval recommended

The change is opt-in, preserves existing default behavior, and is covered by targeted tests and updated documentation.

Pull request overview

This PR adds an opt-in fallback: 'or' mode to the Core search() helper so that multi-token semantic-history searches can broaden recall only when the initial FTS query returns zero hits, while preserving current exact/FTS5 semantics as the default behavior.

Changes:

• Add opts.fallback: 'or' to search() to retry a safe-token OR query only after a zero-hit primary search.
• Add unit coverage to ensure broadening is opt-in, activates only on empty results, and retains visibility filters.
• Document the new option in the shipped skill and API reference, including guidance on when not to use it.

File summaries

File	Description
tests/query.test.mjs	Adds regression coverage for opt-in OR fallback behavior and filter preservation.
skill-doc/SKILL.md	Updates the recommended semantic-history retrieval pattern to opt into fallback: 'or' and documents intended usage.
skill-doc/references/api-reference.md	Extends the search() API reference to include and explain opts.fallback.
packages/core/src/query.ts	Implements fallback: 'or' by retrying safe-token OR only when the primary search yields zero rows.

Review details

• Files reviewed: 4/4 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.