v0.41.33.0 feat(search): intent-aware adaptive return-sizing + agent-facing query param#1640
Merged
Merged
Conversation
New opt-in retrieval feature: trim the ranked result set to an intent-driven cap (entity -> tight, else -> recall-preserving) instead of always returning top-K. Pure module src/core/search/return-policy.ts (resolve + apply + config-read + at-least-minKeep failsafe); wired into hybridSearch after rerank, before slice, offset===0 only; decision stamped into HybridSearchMeta.adaptive_return; cache skipped when on (KNOBS_HASH fold is a follow-up). SearchOpts.adaptiveReturn per-call override. Default OFF — existing search behavior byte-identical. Mechanism is an intent cap, not a score-cliff detector (PrecisionMemBench data showed the cliff carries no signal). 19 unit tests. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add a Key Files entry for src/core/search/return-policy.ts (intent-aware adaptive return-sizing, default OFF) covering its exports, the four search.adaptive_return* config knobs, the hybrid.ts wiring (post-rerank, pre-slice, offset===0 only), and the cache-skip behavior. Regenerate llms-full.txt to match. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Expose adaptive_return (boolean) on the query MCP/CLI op so the AGENT — not the human config knob — decides per query whether to return a tight, intent-sized set. The param description teaches WHEN (single-answer questions on; breadth off; limit:1 for a hard single-answer cap), matching the salience/recency 'YOU (the agent) decide' pattern. Threaded into hybridSearchCached. End users never touch config; their agent serves them per query. Pinned by test/search/query-op-adaptive-return.test.ts. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Re-version 0.41.30.0 -> 0.41.33.0 (VERSION/package.json/CHANGELOG/TODOS/CLAUDE.md). CHANGELOG + CLAUDE.md now document the agent-facing query-op adaptive_return param + when-to-use guidance. llms regenerated (build-llms test green). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
stripTakesFence/stripFactsFence crashed with "undefined is not an object" when a read op returned a page with no compiled_truth (e.g. metadata-only rows). The get_page untrusted-reader path calls both on page.compiled_truth, which can be undefined. Guard both to no-op when body is not a string. loadSearchModeConfig.safeGet trusted engine.getConfig to honor its string|null contract; a non-string value (array/boolean) reached loadOverridesFromConfig and crashed on ce.toLowerCase(). Treat any non-string config value as "not set" so it falls through to the mode-bundle default, matching missing-key behavior. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…embench-v0.1 # Conflicts: # CHANGELOG.md # TODOS.md # VERSION # package.json
…embench-v0.1 # Conflicts: # CHANGELOG.md # VERSION # package.json
…embench-v0.1 # Conflicts: # CHANGELOG.md # TODOS.md # VERSION # package.json
mgunnin
added a commit
to mgunnin/gbrain
that referenced
this pull request
Jun 3, 2026
* upstream/master: v0.41.36.0 feat(mcp): publish agent skills (list_skills / get_skill) for thin clients (garrytan#1661) v0.41.35.0 feat(guardrails): vendor-neutral content guardrail seams (supersedes garrytan#1652) (garrytan#1660) v0.41.34.0 feat(search): retrieval cathedral — max-pool + title + alias + evidence (garrytan#1657) v0.41.33.0 feat(search): intent-aware adaptive return-sizing + agent-facing query param (garrytan#1640) v0.41.32.0 fix(staleness): commit-relative sync staleness (supersedes garrytan#1623) (garrytan#1656) v0.41.31.0 feat(embed): delta-aware sync --all cost gate + real stale-embedding semantics (garrytan#1632) v0.41.30.0 fix(brainstorm/lsd): --save writes the advertised .md file via canonical ingestion path (garrytan#1655) # Conflicts: # src/core/operations.ts
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds intent-aware adaptive return-sizing — opt-in (default-OFF) retrieval that trims the ranked set to an intent-driven cap instead of always returning the full top-K. The point isn't the human config knob; it's that the agent driving gbrain now decides per query, the same way it already decides
salienceandrecency.Commits:
feat(search)—src/core/search/return-policy.ts(pure: resolve + apply + config-read + at-least-minKeepfailsafe), wired intohybridSearchafter rerank / before slice /offset===0only, decision stamped intoHybridSearchMeta.adaptive_return,hybridSearchCachedskips cache when on. NewSearchOpts.adaptiveReturn+ 4search.adaptive_return*config knobs. Default OFF — existing search behavior byte-identical.feat(query)— the agent-facing surface: thequeryop gains anadaptive_returnboolean param whose description tells the agent when to use it (single-answer questions → on; breadth/exploration → off;limit:1for a hard single-answer cap). End users never touch config; their agent serves them per query.chore/docs— VERSION/package.json → 0.41.33.0, CHANGELOG, TODOS follow-ups, CLAUDE.md Key Files entry + agent-surface note, regeneratedllms-full.txt.Born from the PrecisionMemBench integration (gbrain-evals PR #14). Default top-K scores low on a precision-only benchmark, as any top-K system does; with this on, gbrain lands #2 behind a purpose-built belief store. Instrumenting first also killed a "score cliff" detector — the gap after the top hit carries no signal — so the mechanism is a simple intent cap.
How the agent uses it (the point)
querytool,adaptive_return: truewhen the user's question has a small specific answer; omit it for breadth. Never returns empty when there are matches; only applies to the first page. This is documented in the op param description (the agent's instruction channel) and in CLAUDE.md, matching thesalience/recencyprecedent.Test Coverage
test/search/return-policy.test.ts— 19 cases (config precedence, intent→cap, never-empty failsafe,minKeep > capfloor, default-off passthrough).test/search/query-op-adaptive-return.test.ts— 3 cases (agent surface: param exists + description teaches both directions + never-empty contract).test/search/+test/parity.test.ts+test/operations-descriptions.test.ts+test/operations-trust-boundary.test.ts: 229 pass / 0 fail (op-contract + default-off path unchanged).test/e2e/search-quality.test.ts: 12 pass.Pre-Landing Review
Small, additive, default-off (gated by
enableddefaulting false +offset===0). No P1.bun run verify29/29 (typecheck + guards).build-llms7/0. Prior plan-eng + plan-ceo + codex-plan reviews CLEAR on this branch.Eval Results
No prompt-related files changed — evals skipped. Feature measured against PrecisionMemBench in gbrain-evals (#14).
Plan Completion
Core feature + agent surface DONE. Deferred (TODOS.md): cross-surface ablation before any mode-default flip, KNOBS_HASH fold for adaptive-on caching, gather-stage gate (A3),
--explainhuman header, structured-alias facts-mode.Documentation
CLAUDE.md gained the
return-policy.tsKey Files entry + the agent-facingqueryop param note;llms-full.txtregenerated (build-llms 7/0). CHANGELOG + TODOS updated.Test plan
bun run verify— 29/29build-llms— 7/0🤖 Generated with Claude Code