Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(search): an empty result with healthy retrieval says what to try next instead of "clean miss" (#7972)

garrytan6ee8d2fcf755
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a7e5634ffe..37632511a5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -31,6 +31,7 @@ An identifier is a `#` number, a run of 6 or more digits, a code such as INV-202
| `gbrain search '"dan-example" OR "erin-example"' --match keyword`, where the person pages hold the handles only in their slugs | the pages that mention the handles came back, never the pages they name: a hyphenated handle only matches text holding the literal handle | the pages whose slug ends in each handle (`people/dan-example`, `people/erin-example`) are listed and counted first |
| The same query with `--types '["person"]'` | no results | the two person pages |
| The same query in hybrid search | quoted terms skip the any-word retry, so the title arm found nothing either | the named pages lead the keyword arm, as rows that count like strict keyword rows |
+| A search that matches nothing while every retrieval stage ran | the CLI said "clean miss — no retrieval degradation" and MCP "this is a clean miss", which agents read as "the brain has no page for this" | "retrieval healthy", followed by the next things to try (the display name, a synonym, hybrid search) before concluding the brain has nothing; the query skill says the same |
A handle is a hyphenated token with a letter in it, bare or quoted on its own (`acme-example-2` counts, `2026-10-24` does not), and resolves only to a page whose slug ends in exactly that handle. A negated handle (`-dan-example`) or one inside a longer quoted phrase is not resolved. The named pages pass the same filters as any keyword match: `--types`, the caller's sources, and for remote callers no private or quarantined page.
@@ -50,6 +51,7 @@ A handle is a hyphenated token with a letter in it, bare or quoted on its own (`
- A query with a hyphenated token costs one more index lookup on page slugs: one more statement in hybrid search, and one more arm of the same statement with `--match keyword`. `keyword_total` and the `--match keyword` count include the named pages.
- Pages that hold the identifier but not the other words can now rank above pages that match the question's meaning better. The page holding every word still comes first among keyword rows.
- `_meta.retrieval.coverage.could_affect` can carry `pending_images`, and `could_affect.pending_projection` can drop for queries whose digits or short words used to match unrelated slugs.
+- A script that matched the text `clean miss` in an empty result should match `retrieval healthy` instead; `_meta.retrieval` is unchanged.
- Nothing is rewritten on upgrade, no setting changed, and there is no schema migration.
## [0.60.427.0] - 2026-10-24
diff --git a/docs/operations/mcp-surface-runbook.md b/docs/operations/mcp-surface-runbook.md
index b15bf54189..8d4680bc76 100644
--- a/docs/operations/mcp-surface-runbook.md
+++ b/docs/operations/mcp-surface-runbook.md
@@ -322,7 +322,7 @@ Post-deploy checks, in order:
`SELECT token_name, params->>'tool_count' FROM mcp_request_log WHERE operation='tools/list' ORDER BY created_at DESC LIMIT 10;`
2. **Empty-query probe shows the degraded block** — call `search` with a
nonsense query; the empty result must carry a second content block
- ("0 results. … clean miss." or degraded stages) + `_meta.retrieval`.
+ ("0 results. … retrieval healthy …" or degraded stages) + `_meta.retrieval`.
3. **Workerless submit warns** — `submit_agent` while no worker runs must
still succeed and carry `queue_state.warning` (worker_alive false).
4. **put_page lint fields present** — put an uncited page; the response
diff --git a/plugin-variants/gbrain-coding/skills/query/SKILL.md b/plugin-variants/gbrain-coding/skills/query/SKILL.md
index 0ac43a80ee..1a71e3d0c9 100644
--- a/plugin-variants/gbrain-coding/skills/query/SKILL.md
+++ b/plugin-variants/gbrain-coding/skills/query/SKILL.md
@@ -82,7 +82,7 @@ Follow the [agent operator protocol](../conventions/agent-operator-protocol.md)
- Check each retrieval result for notices before answering: on MCP, extra text blocks whose first line looks like [gbrain notice empty_retrieval kind=degraded], mirrored in `_meta.gbrain_notices`; on the CLI, the `[AGENT]` block, `search_degraded`, or a `note: search degraded` line.
- `empty_retrieval` with `kind=degraded` (or `search_degraded: keyword_only_no_embedding_provider`): an empty result is NOT proof the user has no notes. Tell the user "your brain is searching keywords only right now, so I may be missing notes on X", try exact names and synonyms with `gbrain search`, and point to the notice's fix (usually enabling embeddings).
-- `empty_retrieval` with "no retrieval degradation — this is a clean miss": then say "the brain doesn't have information on X".
+- `empty_retrieval` with "retrieval healthy": nothing was degraded, but this one query matched nothing. Before saying "the brain doesn't have information on X", try the display name, a synonym or a hybrid search (`--match hybrid`, the default).
- `listing_truncated` or `budget_truncated`: the list was cut off. Say "showing the first N", and page or narrow the query before claiming something is absent.
- `page_not_found` from `get_page`: the slug is wrong or in another source; search by title (and check `--source`) before reporting the page missing.
diff --git a/plugin-variants/gbrain-daily/skills/query/SKILL.md b/plugin-variants/gbrain-daily/skills/query/SKILL.md
index 0ac43a80ee..1a71e3d0c9 100644
--- a/plugin-variants/gbrain-daily/skills/query/SKILL.md
+++ b/plugin-variants/gbrain-daily/skills/query/SKILL.md
@@ -82,7 +82,7 @@ Follow the [agent operator protocol](../conventions/agent-operator-protocol.md)
- Check each retrieval result for notices before answering: on MCP, extra text blocks whose first line looks like [gbrain notice empty_retrieval kind=degraded], mirrored in `_meta.gbrain_notices`; on the CLI, the `[AGENT]` block, `search_degraded`, or a `note: search degraded` line.
- `empty_retrieval` with `kind=degraded` (or `search_degraded: keyword_only_no_embedding_provider`): an empty result is NOT proof the user has no notes. Tell the user "your brain is searching keywords only right now, so I may be missing notes on X", try exact names and synonyms with `gbrain search`, and point to the notice's fix (usually enabling embeddings).
-- `empty_retrieval` with "no retrieval degradation — this is a clean miss": then say "the brain doesn't have information on X".
+- `empty_retrieval` with "retrieval healthy": nothing was degraded, but this one query matched nothing. Before saying "the brain doesn't have information on X", try the display name, a synonym or a hybrid search (`--match hybrid`, the default).
- `listing_truncated` or `budget_truncated`: the list was cut off. Say "showing the first N", and page or narrow the query before claiming something is absent.
- `page_not_found` from `get_page`: the slug is wrong or in another source; search by title (and check `--source`) before reporting the page missing.
diff --git a/plugin/skills/query/SKILL.md b/plugin/skills/query/SKILL.md
index 0ac43a80ee..1a71e3d0c9 100644
--- a/plugin/skills/query/SKILL.md
+++ b/plugin/skills/query/SKILL.md
@@ -82,7 +82,7 @@ Follow the [agent operator protocol](../conventions/agent-operator-protocol.md)
- Check each retrieval result for notices before answering: on MCP, extra text blocks whose first line looks like [gbrain notice empty_retrieval kind=degraded], mirrored in `_meta.gbrain_notices`; on the CLI, the `[AGENT]` block, `search_degraded`, or a `note: search degraded` line.
- `empty_retrieval` with `kind=degraded` (or `search_degraded: keyword_only_no_embedding_provider`): an empty result is NOT proof the user has no notes. Tell the user "your brain is searching keywords only right now, so I may be missing notes on X", try exact names and synonyms with `gbrain search`, and point to the notice's fix (usually enabling embeddings).
-- `empty_retrieval` with "no retrieval degradation — this is a clean miss": then say "the brain doesn't have information on X".
+- `empty_retrieval` with "retrieval healthy": nothing was degraded, but this one query matched nothing. Before saying "the brain doesn't have information on X", try the display name, a synonym or a hybrid search (`--match hybrid`, the default).
- `listing_truncated` or `budget_truncated`: the list was cut off. Say "showing the first N", and page or narrow the query before claiming something is absent.
- `page_not_found` from `get_page`: the slug is wrong or in another source; search by title (and check `--source`) before reporting the page missing.
diff --git a/skills/query/SKILL.md b/skills/query/SKILL.md
index 2125a8a3c9..4958360c66 100644
--- a/skills/query/SKILL.md
+++ b/skills/query/SKILL.md
@@ -81,7 +81,7 @@ Follow the [agent operator protocol](../conventions/agent-operator-protocol.md)
- Check each retrieval result for notices before answering: on MCP, extra text blocks whose first line looks like [gbrain notice empty_retrieval kind=degraded], mirrored in `_meta.gbrain_notices`; on the CLI, the `[AGENT]` block, `search_degraded`, or a `note: search degraded` line.
- `empty_retrieval` with `kind=degraded` (or `search_degraded: keyword_only_no_embedding_provider`): an empty result is NOT proof the user has no notes. Tell the user "your brain is searching keywords only right now, so I may be missing notes on X", try exact names and synonyms with `gbrain search`, and point to the notice's fix (usually enabling embeddings).
-- `empty_retrieval` with "no retrieval degradation — this is a clean miss": then say "the brain doesn't have information on X".
+- `empty_retrieval` with "retrieval healthy": nothing was degraded, but this one query matched nothing. Before saying "the brain doesn't have information on X", try the display name, a synonym or a hybrid search (`--match hybrid`, the default).
- `listing_truncated` or `budget_truncated`: the list was cut off. Say "showing the first N", and page or narrow the query before claiming something is absent.
- `page_not_found` from `get_page`: the slug is wrong or in another source; search by title (and check `--source`) before reporting the page missing.
diff --git a/src/cli/main.ts b/src/cli/main.ts
index 4dbe7ee7f4..56fb24a632 100755
--- a/src/cli/main.ts
+++ b/src/cli/main.ts
@@ -1583,13 +1583,13 @@ function describeEmptyRetrieval(): string {
parts.push(`retrieved ${m.retrieved_count} before trimming`);
}
// Ranking-only stages (a skipped reranker) never cause a miss — keep the
- // "clean miss" verdict honest.
+ // "retrieval healthy" verdict honest.
const stages = Array.isArray(m.degraded)
? [...new Set((m.degraded as Array<{ stage?: string }>).filter(affectsRecall).map(d => d?.stage).filter(Boolean))]
: [];
parts.push(stages.length > 0
? `degraded: ${stages.join(', ')}`
- : 'clean miss — no retrieval degradation');
+ : 'retrieval healthy; try the display name or --match hybrid before concluding the brain has nothing');
return ` (${parts.join('; ')})`;
}
diff --git a/src/mcp/dispatch.ts b/src/mcp/dispatch.ts
index 1cb0d43f48..54db686014 100644
--- a/src/mcp/dispatch.ts
+++ b/src/mcp/dispatch.ts
@@ -479,7 +479,7 @@ export function buildEmptyRetrievalBlock(retrieval: unknown): string | null {
.filter((s): s is string => typeof s === 'string' && s.length > 0);
parts.push(stages.length > 0
? `degraded: ${[...new Set(stages)].join(', ')}.`
- : 'no retrieval degradation — this is a clean miss.');
+ : 'retrieval healthy (no recall-impairing stage). Try the display name, a synonym or hybrid match (the default) before concluding the brain has nothing.');
if (typeof r.hint === 'string' && r.hint.length > 0) parts.push(`hint: ${r.hint}`);
return parts.join(' ');
}
diff --git a/test/cli-empty-retrieval-render.test.ts b/test/cli-empty-retrieval-render.test.ts
index 9c5186a2e6..316f061def 100644
--- a/test/cli-empty-retrieval-render.test.ts
+++ b/test/cli-empty-retrieval-render.test.ts
@@ -34,12 +34,12 @@ describe('formatResult empty-result rendering (T15)', () => {
test('clean-miss meta → clean miss named', () => {
captureRetrievalMeta('retrieval', { returned_count: 0, retrieved_count: 0, degraded: [] });
- expect(formatResult('search', [], {})).toContain('clean miss — no retrieval degradation');
+ expect(formatResult('search', [], {})).toContain('retrieval healthy; try the display name or --match hybrid before concluding the brain has nothing');
});
test('a ranking-only stage (reranker_skipped) is not a retrieval degradation on the empty-result line', () => {
captureRetrievalMeta('retrieval', { returned_count: 0, retrieved_count: 0, degraded: [{ stage: 'reranker_skipped', reason: 'no_key' }] });
- expect(formatResult('search', [], {})).toContain('clean miss — no retrieval degradation');
+ expect(formatResult('search', [], {})).toContain('retrieval healthy; try the display name or --match hybrid before concluding the brain has nothing');
});
test('non-retrieval keys are ignored by the capture', () => {
diff --git a/test/cli-explain-degraded-render.test.ts b/test/cli-explain-degraded-render.test.ts
index a30c947e06..a524e87cb5 100644
--- a/test/cli-explain-degraded-render.test.ts
+++ b/test/cli-explain-degraded-render.test.ts
@@ -61,7 +61,7 @@ describe('formatResult --explain prints the stage timings', () => {
test('an empty result names its cause, then the timings', () => {
setCliOptions({ ...getCliOptions(), explain: true });
captureRetrievalMeta('retrieval', { returned_count: 0, retrieved_count: 0, degraded: [], timings });
- expect(formatResult('query', [], {})).toBe(`No results. (clean miss — no retrieval degradation)\n${line}\n`);
+ expect(formatResult('query', [], {})).toBe(`No results. (retrieval healthy; try the display name or --match hybrid before concluding the brain has nothing)\n${line}\n`);
});
test('without --explain no timings are printed', () => {
diff --git a/test/cli-incomplete-retrieval-render.test.ts b/test/cli-incomplete-retrieval-render.test.ts
index b2089d75aa..d99069e180 100644
--- a/test/cli-incomplete-retrieval-render.test.ts
+++ b/test/cli-incomplete-retrieval-render.test.ts
@@ -8,7 +8,7 @@ describe('CLI incomplete retrieval is visible without changing JSON result shape
'%s is visible for empty and partial results', stage => {
captureRetrievalMeta('retrieval', { degraded: [{ stage }] });
expect(formatResult('search', [], {})).toContain(`degraded: ${stage}`);
- expect(formatResult('search', [], {})).not.toContain('clean miss');
+ expect(formatResult('search', [], {})).not.toContain('retrieval healthy');
const partial = formatResult('query', [{ slug: 'notes/synthetic', score: 1, chunk_text: 'Synthetic note' }], {});
expect(partial).toContain(`Retrieval incomplete: ${stage}.`);
expect(partial).toContain('notes/synthetic');
diff --git a/test/dispatch-response-meta.serial.test.ts b/test/dispatch-response-meta.serial.test.ts
index d67e5943e3..a47bb1c00e 100644
--- a/test/dispatch-response-meta.serial.test.ts
+++ b/test/dispatch-response-meta.serial.test.ts
@@ -82,13 +82,13 @@ describe('dispatch response meta (WP2/D3/D8)', () => {
expect(retrieval.degraded).toEqual([{ stage: 'embed_unavailable' }]);
});
- test('clean miss → second block says clean miss, degraded absent', async () => {
+ test('clean miss → second block says retrieval healthy, degraded absent', async () => {
nextResults = [];
nextMeta = { vector_enabled: true, expansion_applied: false, detail_resolved: null };
const out = await callSearch();
expect(out.content.length).toBe(3);
expect(out.content[1].text).toContain('Keyword matches: 0 pages');
- expect(out.content[2].text).toContain('clean miss');
+ expect(out.content[2].text).toContain('retrieval healthy');
const retrieval = (out._meta as Record<string, any>).retrieval;
expect(retrieval.degraded).toBeUndefined();
expect(retrieval.vector_enabled).toBe(true);
@@ -127,7 +127,7 @@ describe('buildEmptyRetrievalBlock (unit)', () => {
test('a ranking-only stage (reranker_skipped) never impairs recall → still a clean miss', async () => {
const { buildEmptyRetrievalBlock } = await import('../src/mcp/dispatch.ts');
const out = buildEmptyRetrievalBlock({ retrieved_count: 0, degraded: [{ stage: 'reranker_skipped', reason: 'no_key' }] });
- expect(out).toContain('clean miss');
+ expect(out).toContain('retrieval healthy');
expect(out).not.toContain('reranker_skipped');
const mixed = buildEmptyRetrievalBlock({ retrieved_count: 0, degraded: [{ stage: 'reranker_skipped' }, { stage: 'embed_unavailable', reason: 'no_provider' }] });
expect(mixed).toContain('degraded: embed_unavailable.');
diff --git a/test/dispatch-vector-incomplete.serial.test.ts b/test/dispatch-vector-incomplete.serial.test.ts
index c5ce1b940c..5aea0df009 100644
--- a/test/dispatch-vector-incomplete.serial.test.ts
+++ b/test/dispatch-vector-incomplete.serial.test.ts
@@ -36,7 +36,7 @@ describe('HTTP MCP dispatch preserves bounded-vector incompleteness', () => {
if (!nonempty) {
// content[1] is F2's keyword count line; the empty-retrieval diagnosis follows it.
expect(response.content[2].text).toContain('vector_candidates_incomplete');
- expect(response.content[2].text).not.toContain('clean miss');
+ expect(response.content[2].text).not.toContain('retrieval healthy');
}
});
});
diff --git a/test/e2e/legacy-chunk-privacy.test.ts b/test/e2e/legacy-chunk-privacy.test.ts
index 11b48db575..8e3b9f398c 100644
--- a/test/e2e/legacy-chunk-privacy.test.ts
+++ b/test/e2e/legacy-chunk-privacy.test.ts
@@ -228,7 +228,7 @@ for (const kind of ['pglite', 'postgres'] as const) {
expect(degradedStages()).toContain('safe_index_pending');
const block = buildEmptyRetrievalBlock(meta.retrieval) ?? '';
expect(block).toContain('safe_index_pending');
- expect(block).not.toContain('clean miss');
+ expect(block).not.toContain('retrieval healthy');
// Trusted local reads also withhold unsealed projections; the rebuild
// diagnostic is emitted only for remote callers.
meta = {};
diff --git a/test/e2e/mcp-search-transport-matrix.test.ts b/test/e2e/mcp-search-transport-matrix.test.ts
index 0a7f1828f0..70539695ee 100644
--- a/test/e2e/mcp-search-transport-matrix.test.ts
+++ b/test/e2e/mcp-search-transport-matrix.test.ts
@@ -242,7 +242,7 @@ for (const backend of backends) describe(`search transport safety matrix (${back
const miss = await search(client, PRIVATE);
expect(miss.rows).toEqual([]);
expect(miss.meta.degraded).toEqual([]);
- expect(miss.content.find(c => c.text.startsWith('[gbrain notice empty_retrieval'))!.text).toContain('clean miss');
+ expect(miss.content.find(c => c.text.startsWith('[gbrain notice empty_retrieval'))!.text).toContain('retrieval healthy');
});
}, 60_000);
@@ -362,7 +362,7 @@ for (const backend of backends) describe(`search transport safety matrix (${back
const miss = await search(client, query);
expect(miss.rows).toEqual([]);
expect(miss.meta.degraded ?? []).toEqual([]);
- expect(miss.content.find(c => c.text.startsWith('[gbrain notice empty_retrieval'))!.text).toContain('clean miss');
+ expect(miss.content.find(c => c.text.startsWith('[gbrain notice empty_retrieval'))!.text).toContain('retrieval healthy');
}
};
await withStdio(BOUND, verify);