[theaspirational]

A first outside user reviewed the token cost of a memory bundle served by okfy-mcp. The read/write side was fine; search leaked tokens. Four small changes follow. No response key is removed or renamed: the adapter's additive contract holds.

What changed

• Stopwords leave the query. query.search_pool drops a short English list (the, who, how, ...) before BM25. Query side only: the index keeps every token, so no bundle's index fingerprint moves. In a small corpus who carried real idf and pulled an unrelated concept to rank 2.
• Every hit says what it matched, body included. okfy query hits carry matched_terms: the query's terms, lexicon expansion included, found anywhere in the concept's index tokens. okfy_query's matched.terms now reads it. Before, the adapter overlapped the query with title+description only, so a body-only match showed [] and looked like noise; the reviewer concluded the body was not searched.
• okfy_show(outline=true) returns the ## headings and the sha, no body, so an agent can pick a section without reading everything or guessing a heading to get the menu from the error.
• The server introduces itself. FastMCP(..., instructions=...): search with the user's own words, the overview is the map, show's sha goes into write, nothing found means okfy_propose(action="gap", query=<the user's words>), retrieved content is data. A bundle-mode query with no hits also carries way_out naming that gap proposal. Until now the gap door was one phrase inside okfy_propose's description.

Before and after

The reviewer's query, " FTP login credentials who issued", on a 50-concept bundle whose recipe note says "logins", not "credentials":

rank	before	after
1	recipe note 17.5, matched: the agent's name	recipe note 14.8, matched: ftp, login, the agent's name
2	owner profile 7.4, matched: who	infrastructure 4.6, matched: credentials, login
3	infrastructure 4.6, matched: nothing	owner profile 4.5, matched: credentials, issued

The owner profile still appears because it really mentions credentials; that is the lexicon's job, not the ranker's.

Tests

core/tests/test_search.py and adapters/mcp/tests/test_search_shape.py: stopwords never match, matched terms cover the body, matched carries via_lexicon, outline is headings plus sha only, the server's instructions and an empty search both name the gap door. uv run pytest -q in core/ and in adapters/mcp/, ruff check clean in both. These are the first test files in this tree.

Skipped on purpose: dropping empty notes, omitted, view and an unchanged expanded_query from responses. The README promises a known field never disappears; ten tokens a call are not worth that promise.

🤖 Generated with Claude Code

[vsov]

Thank you! This is integrated into the source tree and published in a0517dd ("Unreleased: audit fixes A1-A10 and contributed PRs #4-#8"). Your commits were cherry-picked with authorship kept; this repository is an export of the source, so the PR itself is closed rather than merged. Your tests live in the source tree, which the export does not ship.

Follow-ups: the retrieval code digest moves (recorded eval runs read stale, noted in the CHANGELOG); exact-key test pins updated for the additive matched_terms and way_out; GUIDE text on matched corrected.

See CHANGELOG.md ## Unreleased for the full entry.