Local-first 🧠memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
TypeScript
/**
* MCP tool registry slice for Brain Search.
*
* Exposes `brain_search` (agent-facing; write-classified - it persists
* ranking-state ledgers under `Brain/search/`, see the kind comment at
* the definition) and the `search.*` enrichment used by
* `second_brain_status`. Index management verbs (`index`, `reindex`,
* `check`) are intentionally NOT exposed over MCP — they are operator
* business, never agent business (design doc §3, principle 5).
*
* Anchored in docs/plans/2026-05-16-brain-search-design.md §9.
*/
import {
captureRecallFeedback,
EMBEDDING_QUOTA_MESSAGE,
evaluateSurfacingGate,
expandHit,
indexStatus,
resolveSearchConfig,
search,
SearchError,
serializeEvidencePack,
serializeSearchCard,
serializeIndexStatus,
} from "../core/search/index.ts";
import { evaluateGradedSurfacing } from "../core/search/surfacing-gate.ts";
import { SURFACING_TIERS } from "../core/search/surfacing-key.ts";
import { normalizeSessionFocus, parseStructuredRecallQueryDocument } from "../core/search/index.ts";
import type { BrainSearchResult, SearchOutcome } from "../core/search/index.ts";
import { parseDegreePredicate, type DegreePredicate } from "../core/search/property-filter.ts";
import { SEARCH_KINDS, isSearchKind } from "../core/search/property-pushdown.ts";
import { REMOTE_DENY_VISIBILITY_TOKEN, normToken } from "../core/graph/visibility.ts";
import { searchAcrossVaults } from "../core/search/cross-vault.ts";
import { fileContextRecall } from "../core/brain/file-recall.ts";
import { withTimeout } from "../core/search/with-timeout.ts";
import {
defaultConfigPath,
resolveRecallAdequacyThresholds,
resolveRecallGateTelemetry,
} from "../core/config.ts";
import { assessRecallAdequacy } from "../core/brain/recall-adequacy.ts";
import {
NEGATIVE_RECALL_STATE,
NEGATIVE_RECALL_UNKNOWN_REASONS,
type NegativeRecallState,
type NegativeRecallVerdict,
} from "../core/brain/negative-recall.ts";
import {
RETRIEVAL_DEGRADATION_CODES,
RETRIEVAL_TRAIL_KEY,
retrievalTrailEnvelope,
} from "../core/search/retrieval-trail.ts";
import { corpusVerdictAtReach, probeRetrievalCorpus } from "../core/search/pipeline/outcome.ts";
import { deliveryView, UNPROBED_DELIVERY_REL } from "./brain/reach-events.ts";
import { LOCAL_ORIGIN } from "../core/brain/portability/origins.ts";
import { INTERNAL_ERROR, INVALID_PARAMS, MCPError } from "./protocol.ts";
import type { ToolErrorCode } from "./tool-error-codes.ts";
import { contextReach, contextVault } from "./tool-contract.ts";
import type { ServerContext, ToolDefinition } from "./tool-contract.ts";
import {
AGENT_SCOPE_SCHEMA,
MATCH_QUALITY_ARG_NAME,
matchQualitySchema,
RECALL_SCORES_SCHEMA,
coerceAgentScope,
coerceBoolOptional,
coerceDecisionAnswerable,
coerceRecallAdequacyInput,
coerceStr,
coerceStringOptional,
DECISION_ANSWERABLE_ARG_NAME,
decisionAnswerablePairing,
decisionAnswerableSchema,
recallAdequacyPairing,
} from "./coerce.ts";
import { decisionAnswerableFor, type DecisionAnswerableOutcome } from "./decision-answerable.ts";
import { decisionModelSearchEnvelope } from "../core/decision-model/answerable.ts";
import { MCP_PREVIEW_BUDGET } from "./preview-budget.ts";
import { explainEnvelope } from "../core/search/explain-envelope.ts";
import { deriveRecallHint } from "../core/search/recall-hint.ts";
import { FTS_MATCH_MODES, isFtsMatchMode } from "../core/search/fts-match-mode.ts";
import {
DISCLOSURE_MODE,
DISCLOSURE_MODES,
isDisclosureMode,
} from "../core/search/disclosure-mode.ts";
import {
ELLIPSIS,
HEAD_WINDOW_START,
alignToCodePointStart,
markWindow,
matchOffset,
windowStartWithin,
} from "../core/search/snippet-window.ts";
import { projectScoreBreakdown } from "../core/search/enrich.ts";
import { recordReinforce } from "../core/search/reinforce.ts";
import { parseRecallBenchmarkDataset, runRecallBenchmark } from "../core/search/benchmark.ts";
import {
deriveSearchInputSchema,
MCP_LIMIT_MAX,
MCP_QUERY_MAX_CHARS,
} from "../core/search/search-options-descriptor.ts";
import {
deriveRecallSignals,
emitRecallTelemetry,
RECALL_CHANNEL,
RECALL_SIGNALS_UNMEASURED_CARDS,
recallTelemetryEnvelope,
type RecallQualitySignals,
type RecallSignalsUnmeasured,
} from "../core/brain/recall-telemetry.ts";
import { emitGateTelemetry, emitNegativeRecallTelemetry } from "../core/brain/gate-telemetry.ts";
import { emitGatedTelemetry } from "../core/brain/continuity/emit.ts";
import { recordQueryDemand, recordRecallAdequacyDemand } from "../core/brain/query-demand.ts";
/**
* The longest `query` a recall tool accepts, advertised and enforced from
* here. DECLARED in the search-options descriptor beside the schema that
* advertises it (t_50c81d5c substrate); re-exported for the sibling tools
* that cap the same way.
*/
export { MCP_QUERY_MAX_CHARS };
/** The refusal text of a query over {@link MCP_QUERY_MAX_CHARS}, shared by every capped tool. */
export const MCP_QUERY_CAP_MESSAGE = `argument 'query' exceeds ${MCP_QUERY_MAX_CHARS} characters`;
/**
* Whether `query` is longer than {@link MCP_QUERY_MAX_CHARS}, counted in
* code points as the advertised JSON Schema `maxLength` counts them: a
* character outside the Basic Multilingual Plane is one character, not the
* two UTF-16 units `String.length` would see.
*/
export function exceedsMcpQueryCap(query: string): boolean {
if (query.length <= MCP_QUERY_MAX_CHARS) return false;
let count = 0;
for (const _ of query) {
if (++count > MCP_QUERY_MAX_CHARS) return true;
}
return false;
}
const MCP_CONTENT_MAX = 600;
const SEARCH_TIMEOUT_MS = 10_000;
/** Surfaced rows named as source refs on one recall-telemetry record. */
const TELEMETRY_TOP_ARTIFACTS_MAX = 10;
/**
* The served `brain_search` input schema: the search-options descriptor's
* mcp-visible projection, one derivation instead of a second
* hand-maintained copy (t_50c81d5c substrate). Pinned byte-identical to
* the pre-derivation literal by
* tests/core/search/search-query-schema-artifact.test.ts - the day-one
* contract is that tools/list and the vendored Hermes projection see the
* same bytes.
*/
export const SEARCH_INPUT_SCHEMA: Record<string, unknown> = deriveSearchInputSchema();
/**
* The negative-recall states a zero-result `brain_search` can report.
*
* The same two-of-three narrowing {@link RECALL_GATE_NEGATIVE_STATES}
* makes, for the same reason: the probe behind the trail supplies neither
* retraction evidence nor an assertion of non-occurrence, so
* `did_not_happen` is not a claim this surface has grounds for. Declaring
* it would leave a client unable to tell "this surface cannot say that"
* from "it did not happen".
*/
export const SEARCH_NEGATIVE_STATES: ReadonlyArray<NegativeRecallState> = Object.freeze([
NEGATIVE_RECALL_STATE.notFound,
NEGATIVE_RECALL_STATE.unknown,
]);
const SEARCH_OUTPUT_SCHEMA: NonNullable<ToolDefinition["outputSchema"]> = {
type: "object",
required: ["results", "warnings", "total"],
properties: {
results: {
type: "array",
items: {
type: "object",
required: [
"path",
"title",
"content",
"score",
"startLine",
"endLine",
"searchType",
"reasons",
],
properties: {
path: { type: "string" },
// Titles are nullable for markdown files without frontmatter/title.
// The lightweight contract validator has no union types, so leave
// this field unconstrained while keeping it required in the shape.
title: {},
content: { type: "string" },
score: { type: "number" },
startLine: { type: "integer" },
endLine: { type: "integer" },
searchType: { type: "string" },
reasons: { type: "array", items: { type: "string" } },
authoredAt: { type: "integer" },
score_breakdown: {
type: "object",
properties: {
keyword: { type: "number" },
semantic: { type: "number" },
rrf: { type: "number" },
entity: { type: "number" },
activation: { type: "number" },
coAccess: { type: "number" },
link: { type: "number" },
recency: { type: "number" },
tier: { type: "number" },
trend: { type: "number" },
sessionFocus: { type: "number" },
},
},
origin: { type: "string" },
why_retrieved: { type: "array", items: { type: "string" } },
relations: {
type: "array",
items: {
type: "object",
required: ["relation", "target"],
properties: {
relation: { type: "string" },
target: { type: "string" },
},
},
},
trust: {
type: "object",
properties: {
age_days: { type: "integer" },
superseded: { type: "boolean" },
conflict: { type: "boolean" },
},
},
// Exact-duplicate merge: locations folded into this row.
// Declared deliberately — this output schema does not set
// `additionalProperties: false`, so an undeclared field would
// pass validation silently and be invisible to a caller
// reading the contract.
duplicates: {
type: "array",
items: {
type: "object",
required: ["documentId", "chunkId", "path", "title", "startLine", "endLine"],
properties: {
documentId: { type: "integer" },
chunkId: { type: "integer" },
path: { type: "string" },
// Nullable, same as the result title above.
title: {},
startLine: { type: "integer" },
endLine: { type: "integer" },
},
},
},
},
},
},
cards: {
type: "array",
items: {
type: "object",
required: [
"path",
"title",
"score",
"snippet",
"pointer",
"reasons",
"document_id",
"chunk_id",
],
properties: {
path: { type: "string" },
// Nullable, same as full search result titles above.
title: {},
score: { type: "number" },
snippet: { type: "string" },
pointer: { type: "string" },
reasons: { type: "array", items: { type: "string" } },
document_id: { type: "integer" },
chunk_id: { type: "integer" },
origin: { type: "string" },
// Exact-duplicate merge: the `path:Lstart-Lend` pointers this
// card was folded from. Declared deliberately for the same
// reason `duplicates` is on the full row above - this output
// schema does not set `additionalProperties: false`, so an
// undeclared field would validate silently and stay invisible
// to a caller reading the contract.
duplicate_pointers: { type: "array", items: { type: "string" } },
},
},
},
warnings: { type: "array", items: { type: "string" } },
// Iterative recall round-trip marker (recall-quality wave). Present
// only on an opt-in iterative call: the plan phase (needs-llm-step)
// or the commit call's final marker. Declared deliberately for the
// same reason every envelope here is declared.
iterative: {
type: "object",
required: ["phase"],
properties: {
phase: { type: "string" },
round: { type: "integer" },
token: { type: "string" },
llm_step: { type: "object" },
pool_ids: { type: "array", items: { type: "integer" } },
gaps: { type: "array", items: { type: "string" } },
rounds: { type: "array", items: { type: "object" } },
stop_reason: { type: "string" },
},
},
// The ranked pool the `limit` sliced these rows from (task F) - how
// many candidates were ranked, not how many came back. The descriptor
// grammar carries no prose, so the meaning is documented here, in
// SearchOutcome.total, and in docs/mcp.md.
total: { type: "integer" },
recall_hint: { type: "string" },
evidence_pack: { type: "object" },
decision_model: {
type: "object",
required: ["answerable"],
properties: {
answerable: {
type: "object",
required: ["probability", "model", "calibrated"],
properties: {
probability: { type: "number" },
model: { type: "string" },
calibrated: { type: "boolean" },
},
},
},
},
// Retrieval receipts under `explain` (what-the-index-already-knew,
// task F). Declared deliberately: this output schema does not set
// `additionalProperties: false`, so an undeclared key would pass
// validation silently and stay invisible to a caller reading the
// contract.
retrieval_decision_trace: {
type: "object",
required: ["evaluated", "surfaced", "excluded", "exclusions"],
properties: {
evaluated: { type: "integer" },
surfaced: { type: "integer" },
excluded: { type: "integer" },
exclusions: {
type: "array",
items: {
type: "object",
required: ["document_id", "chunk_id", "path", "reasons"],
properties: {
document_id: { type: "integer" },
chunk_id: { type: "integer" },
path: { type: "string" },
reasons: { type: "array", items: { type: "string" } },
},
},
},
},
},
memory_trust_assessment: {
type: "object",
required: ["evaluated", "surfaced", "quarantined", "reason_counts"],
properties: {
evaluated: { type: "integer" },
surfaced: { type: "integer" },
quarantined: { type: "integer" },
// Open-keyed histogram: one integer per namespaced exclusion reason.
reason_counts: { type: "object" },
},
},
retrieval_trace_unavailable: { type: "string" },
// Retrieval trail (evidence-at-the-boundary, C2). Declared for the
// same reason the receipts above are: this schema does not set
// `additionalProperties: false`, so an undeclared key would validate
// silently. The `code` enum is the enforcement - the server validates
// every response against this schema, so emitting a code that is not
// in `RETRIEVAL_DEGRADATION` fails the contract loudly instead of
// handing a client a value it cannot interpret. Same rule as
// {@link RECALL_GATE_NEGATIVE_STATES}.
[RETRIEVAL_TRAIL_KEY]: {
type: "object",
required: ["retrieved", "pool", "degraded"],
properties: {
// Rows handed back, which `total` does not state: that is the
// ranked pool the window was cut from.
retrieved: { type: "integer" },
pool: { type: "integer" },
degraded: {
type: "array",
items: {
type: "object",
required: ["code"],
properties: {
code: { type: "string", enum: [...RETRIEVAL_DEGRADATION_CODES] },
// Identifiers and integers only, by the vocabulary's own
// rule; open-keyed because each code names its own fields.
detail: { type: "object" },
},
},
},
empty: {
type: "object",
required: ["state", "reason"],
properties: {
state: { type: "string", enum: [...SEARCH_NEGATIVE_STATES] },
reason: { type: "string" },
unknown_reason: { type: "string", enum: [...NEGATIVE_RECALL_UNKNOWN_REASONS] },
},
},
},
},
telemetry_id: { type: "string" },
},
};
/**
* The argument name the scores are paired with, as the schema spells it.
*
* One constant for the property key, the `dependentRequired` entry, and the
* handler's read, so this tool's declaration and its enforcement cannot
* drift onto different names.
*/
const RECALL_SCORES_ARG_NAME = "scores";
/** The bound on the gate's `session_id` and `turn_id` correlation arguments. */
const GATE_CORRELATION_ID_MAX_CHARS = 512;
/** The bound on the gate's `telemetry_host` label. */
const GATE_TELEMETRY_HOST_MAX_CHARS = 200;
const RECALL_GATE_INPUT_SCHEMA: Record<string, unknown> = {
type: "object",
properties: {
prompt: {
type: "string",
minLength: 1,
maxLength: 4000,
description: "The turn's prompt, scored to decide whether recall is worth running at all.",
},
previous_prompt: {
type: "string",
maxLength: 4000,
description:
"The preceding turn's prompt, so a follow-up is judged in context rather than on its own.",
},
explicit: {
type: "boolean",
description:
"The user asked for memory in so many words; the gate then retrieves regardless of score. Default false.",
},
telemetry_host: {
type: "string",
maxLength: GATE_TELEMETRY_HOST_MAX_CHARS,
description: "Optional host/client label recorded on the telemetry record.",
},
session_id: {
type: "string",
maxLength: GATE_CORRELATION_ID_MAX_CHARS,
description: "Optional session correlation id recorded on the telemetry record.",
},
turn_id: {
type: "string",
maxLength: GATE_CORRELATION_ID_MAX_CHARS,
description: "Optional turn correlation id recorded on the telemetry record.",
},
[RECALL_SCORES_ARG_NAME]: RECALL_SCORES_SCHEMA,
[MATCH_QUALITY_ARG_NAME]: matchQualitySchema(RECALL_SCORES_ARG_NAME),
[DECISION_ANSWERABLE_ARG_NAME]: decisionAnswerableSchema(RECALL_SCORES_ARG_NAME),
},
required: ["prompt"],
// Both or neither, stated declaratively so a schema-driven client can
// discover the pairing instead of learning it from an INVALID_PARAMS at
// call time. Built beside the enforcement; see `recallAdequacyPairing`.
dependentRequired: {
...recallAdequacyPairing(RECALL_SCORES_ARG_NAME),
...decisionAnswerablePairing(RECALL_SCORES_ARG_NAME),
},
additionalProperties: false,
};
/**
* The negative-recall states `brain_recall_gate` can actually produce.
*
* The vocabulary is three states wide (`NEGATIVE_RECALL_STATES` in
* `core/brain/negative-recall.ts`); this surface reaches two of them. `did_not_happen` is missing because
* {@link assessNegativeRecall} supplies neither of the two things that
* state requires - stored retraction evidence and the caller's assertion
* of non-occurrence - and it reads no claim graph to find any. Declaring
* the full vocabulary here would leave a client unable to tell "this
* surface cannot say that" from "it did not happen this time", which is
* the same conflation between an unanswerable check and a passing one
* that the negative-recall unit exists to remove.
*
* Enforced, not documentary: the server validates every response against
* this schema, so wiring an evidence read into the gate without widening
* this list fails the contract loudly instead of emitting an undeclared
* value. Order follows the vocabulary's weakest-to-strongest ordering.
*/
export const RECALL_GATE_NEGATIVE_STATES: ReadonlyArray<NegativeRecallState> = Object.freeze([
NEGATIVE_RECALL_STATE.notFound,
NEGATIVE_RECALL_STATE.unknown,
]);
const RECALL_GATE_OUTPUT_SCHEMA: NonNullable<ToolDefinition["outputSchema"]> = {
type: "object",
required: ["retrieve", "admit", "reason"],
properties: {
retrieve: { type: "boolean" },
// The admission the verdict stands on, always present: with a
// measurement it IS the graded admission (so `retrieve` can never
// contradict `tier`); without one it names the structural fail-open.
admit: { type: "boolean" },
reason: { type: "string" },
// Graded surfacing key (t_107a3249): present only when the caller
// supplied the scores/match_quality pair. `key` is the measured
// match quality, null exactly where nothing was measurable (a
// structurally suppressed prompt); `tier` is the closed admission
// vocabulary. Absent - never implied - without a measurement. The
// entry is permissive because the descriptor language declares ONE
// `type` per node: `number|null` is not expressible here, so `{}` is
// a statement about the language, not an omission.
key: {},
tier: { type: "string", enum: [...SURFACING_TIERS] },
adequacy: {
type: "object",
required: [
"level",
"action",
"escalate",
"result_count",
"top_score",
"mean_score",
// Required, not optional: the block used to return the two scores
// that decide NOTHING and withhold the one that decides the level,
// so a caller could not check the verdict against its own input or
// tell which threshold band it landed beside.
MATCH_QUALITY_ARG_NAME,
"reason",
],
properties: {
level: { type: "string", enum: ["sufficient", "weak", "insufficient"] },
action: { type: "string", enum: ["proceed", "re_recall", "abstain"] },
escalate: { type: "boolean" },
result_count: { type: "integer" },
top_score: { type: "number" },
mean_score: { type: "number" },
[MATCH_QUALITY_ARG_NAME]: { type: "number" },
reason: { type: "string" },
// Advisory decision-model annotation (issue #213, Part 8): present
// only when the caller passed `decision_answerable` and the use is
// not off. Never changes `level` or `action`.
[DECISION_ANSWERABLE_ARG_NAME]: {
type: "object",
required: ["probability", "disagrees"],
properties: {
probability: { type: "number" },
disagrees: { type: "boolean" },
},
},
},
},
// Present only when an argument was ignored (a `decision_answerable`
// while the use is off); absent otherwise.
warnings: { type: "array", items: { type: "string" } },
// Typed negative recall (silence-is-not-an-answer, U2). Present only
// when the caller reported no usable result, mirroring `adequacy`
// above: absent - never null - when it does not apply.
negative: {
type: "object",
required: ["state", "complete", "reason"],
properties: {
state: { type: "string", enum: [...RECALL_GATE_NEGATIVE_STATES] },
complete: { type: "boolean" },
reason: { type: "string" },
unknown_reason: { type: "string", enum: [...NEGATIVE_RECALL_UNKNOWN_REASONS] },
coverage: {
type: "object",
required: ["digest", "documents", "chunks", "embeddings", "scope", "unindexed_roots"],
properties: {
digest: { type: "string" },
documents: { type: "integer" },
chunks: { type: "integer" },
// Declared beside `chunks` because the pair is the claim: a
// count below the chunk count is an index a semantic query
// could not read out in full.
embeddings: { type: "integer" },
index_path: { type: "string" },
// Three fields whose value is an integer/string OR null.
// The output-schema vocabulary declares one type per node
// and has no union, so they are declared untyped rather
// than declared wrongly: a `string` here would make the
// never-indexed case fail its own contract.
schema_version: {},
embedding_signature: {},
last_indexed_at: {},
scope: { type: "array", items: { type: "string" } },
unindexed_roots: { type: "array", items: { type: "string" } },
},
},
},
},
},
};
function searchTimeoutError(ms: number): MCPError {
return new MCPError(INTERNAL_ERROR, `search timeout after ${ms}ms`);
}
/**
* Validate + normalise the `properties` argument shape. Returns
* `undefined` when the argument is absent. Throws INVALID_PARAMS
* on a malformed shape so callers get a clear error rather than a
* silently-ignored filter.
*/
function parsePropertiesArgument(
raw: unknown,
): ReadonlyMap<string, ReadonlyArray<string>> | undefined {
if (raw === undefined || raw === null) return undefined;
if (typeof raw !== "object" || Array.isArray(raw)) {
throw new MCPError(
INVALID_PARAMS,
"argument 'properties' must be an object mapping key → array of strings",
);
}
const map = new Map<string, ReadonlyArray<string>>();
for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {
if (!Array.isArray(v)) {
throw new MCPError(INVALID_PARAMS, `argument 'properties.${k}' must be an array of strings`);
}
const accepted: string[] = [];
for (const item of v) {
if (typeof item !== "string") {
throw new MCPError(INVALID_PARAMS, `argument 'properties.${k}' must contain only strings`);
}
accepted.push(item);
}
if (accepted.length === 0) {
throw new MCPError(INVALID_PARAMS, `argument 'properties.${k}' must not be empty`);
}
map.set(k, Object.freeze(accepted));
}
return map;
}
function parseVisibilityArgument(raw: unknown): string[] | undefined {
if (raw === undefined || raw === null) return undefined;
if (!Array.isArray(raw)) {
throw new MCPError(INVALID_PARAMS, "argument 'visibility' must be an array of strings");
}
const out: string[] = [];
for (const item of raw) {
if (typeof item !== "string") {
throw new MCPError(INVALID_PARAMS, "argument 'visibility' must contain only strings");
}
// The reserved token is a reach boundary, not a caller-liftable scope.
// Every other visibility token keeps its caller-liftable semantics
// (`isVisible`), but letting a caller add `private` to its own scope
// would hand one argument the whole private class - the exact lift
// the reserved token exists to deny a remote reach, and the reason a
// prompt-injected agent would ask for it. Withheld here by name so
// the refusal explains itself; the transport reach that mints `local`
// for operator surfaces is where private visibility is granted.
if (normToken(item) === REMOTE_DENY_VISIBILITY_TOKEN) {
throw new MCPError(
INVALID_PARAMS,
`argument 'visibility' cannot include the reserved token "${REMOTE_DENY_VISIBILITY_TOKEN}": ` +
"it is a reach boundary the transport grants, not a scope a caller can request",
);
}
if (item.length > 0) out.push(item);
}
return out;
}
/**
* Validate the `degree` argument (array of `<field><op><count>` strings)
* into a predicate list. A malformed shape or predicate throws
* INVALID_PARAMS rather than silently dropping the filter.
*/
function parseDegreeArgument(raw: unknown): DegreePredicate[] | undefined {
if (raw === undefined || raw === null) return undefined;
if (!Array.isArray(raw)) {
throw new MCPError(INVALID_PARAMS, "argument 'degree' must be an array of strings");
}
const out: DegreePredicate[] = [];
for (const item of raw) {
if (typeof item !== "string") {
throw new MCPError(INVALID_PARAMS, "argument 'degree' must contain only strings");
}
try {
out.push(parseDegreePredicate(item));
} catch (e) {
if (e instanceof SearchError) throw searchErrorToMcp(e);
throw e;
}
}
return out;
}
function parseReinforceArgument(raw: unknown): string[] | undefined {
if (raw === undefined || raw === null) return undefined;
if (!Array.isArray(raw)) {
throw new MCPError(INVALID_PARAMS, "argument 'reinforce' must be an array of strings");
}
const out: string[] = [];
for (const item of raw) {
if (typeof item !== "string") {
throw new MCPError(INVALID_PARAMS, "argument 'reinforce' must contain only strings");
}
if (item.length > 0) out.push(item);
}
return out;
}
/**
* The delivery shaper for one search-family request (delivery-trust,
* lane A): how this caller's stored record text - row `content`, card
* `snippet`, `brain_search_expand` note and chunk bodies - is shaped on
* its way out.
*
* This delegates to the ONE shared binding (`deliveryView`, beside
* `requestRefView` in reach-events.ts) instead of re-implementing the
* probe-plus-shape body, so the two constructors cannot drift: at local
* reach the shape is the identity and holds no state at all - the
* operator's own tools get the pre-wave bytes, which is what the dozens
* of local-reach shape pins assert. At remote reach every shaped string
* is probed through ONE `FrontmatterCache` per request - one frontmatter
* read per distinct page however many rows or chunks name it - and
* delivered through the K1 shaper: fenced unless the page proves
* operator-authorship, fail-closed to fenced on every absence. The fence
* lives inside the existing `content` / `snippet` fields, so no output
* schema changes and a row the reach view already withheld never reaches
* the shaper (a fence on a withheld row would be an existence leak).
*
* The binding's cache is the shaper's own per-request Map, not the
* search pipeline's internal one: that cache lives inside `search()` and
* is not part of the returned outcome, so sharing it would extend the
* core search contract. Both are per-request Maps, so each stage still
* reads a given page's frontmatter at most once.
*
* A cross-vault union row names a page of a FOREIGN vault by
* relative path; probing it here would read the local vault and find
* nothing, which is the fail-closed answer: foreign text with no
* probeable provenance is fenced, never trusted.
*/
function storedTextDelivery(ctx: ServerContext): { shape(text: string, rel: string): string } {
return deliveryView(ctx);
}
/**
* The rel a search row's body is probed at. A cross-vault union row
* names a FOREIGN vault's page by relative path; probing it against the
* local vault would let whatever happens to sit at that relative path
* here - an operator-authored note with the same name - decide the
* treatment of text it never carried. A foreign row therefore probes
* the guaranteed-absent page and ships fenced, while the row's own
* `origin` field keeps naming the vault it came from.
*/
function rowDeliveryRel(row: { path: string; origin?: string }, globalSearch: boolean): string {
return globalSearch && row.origin !== undefined && row.origin !== LOCAL_ORIGIN
? UNPROBED_DELIVERY_REL
: row.path;
}
/**
* The `content` window for one MCP result: at most `max` characters
* INCLUDING its continuation markers, centred on the first significant
* query term the chunk contains (task E).
*
* With no occurrence the window is the head of the chunk and the bytes
* are exactly what the pre-anchoring head truncation produced: content
* at or under the cap passes through untouched, and content over it is
* cut one character short to make room for the trailing marker.
*
* Content at or under the cap is a case of the general rule rather than an
* early return of its own: {@link windowStartWithin} opens it at the head,
* the budget is the whole cap, `hasMore` is false, and the slice is the
* string itself. Stating it once means the "never truncate text the cap
* had room for" invariant cannot drift between this surface and the two
* that measure their caps in other units.
*
* The start is aligned to a code-point boundary because this surface
* slices UTF-16 units: an anchored start can land on the low half of a
* surrogate pair, and a body opening with a lone surrogate becomes U+FFFD
* as soon as the JSON-RPC frame is encoded as UTF-8. The TRAILING cut is
* deliberately left as it is - it has always cut on a raw offset, its
* bytes are the pre-anchoring contract this wave must not move, and
* unlike the head it is not a hazard anchoring introduced.
*/
function windowContent(c: string, query: string, max: number): string {
const start = alignToCodePointStart(c, windowStartWithin(matchOffset(c, query), max, c.length));
const budget = max - (start > HEAD_WINDOW_START ? ELLIPSIS.length : 0);
const hasMore = start + budget < c.length;
const body = c.slice(start, start + budget - (hasMore ? ELLIPSIS.length : 0));
return markWindow(body, start, hasMore, ELLIPSIS);
}
/**
* The structured `data` every mapped {@link SearchError} carries: its own
* code, verbatim. `SEARCH_ERROR_CODES` is imported into the boundary
* registry unchanged, so the UPPER token is already a registered wire code
* and no second spelling is minted for it.
*/
export function searchErrorData(e: SearchError): { readonly code: ToolErrorCode } {
return { code: e.code };
}
export function searchErrorToMcp(e: SearchError): MCPError {
const data = searchErrorData(e);
if (e.code === "INVALID_INPUT") return new MCPError(INVALID_PARAMS, e.message, data);
if (e.code === "EMBEDDING_QUOTA_EXHAUSTED") {
return new MCPError(INTERNAL_ERROR, EMBEDDING_QUOTA_MESSAGE, data);
}
if (e.code === "INDEX_MISSING") {
return new MCPError(
INTERNAL_ERROR,
"search index not initialised. Run: o2b search index",
data,
);
}
if (e.code === "INDEX_UNREADABLE") {
return new MCPError(INTERNAL_ERROR, `search index unreadable: ${e.message}`, data);
}
if (e.code === "VEC_EXTENSION_UNAVAILABLE") {
return new MCPError(
INTERNAL_ERROR,
"semantic search unavailable: sqlite-vec extension not loaded",
data,
);
}
if (e.code === "EMBEDDING_KEY_MISSING") {
return new MCPError(INTERNAL_ERROR, "embedding key not configured", data);
}
if (e.code === "EMBEDDING_PROVIDER_HTTP" || e.code === "EMBEDDING_PROVIDER_TIMEOUT") {
return new MCPError(INTERNAL_ERROR, `embedding provider unavailable: ${e.message}`, data);
}
// The `[CODE]` suffix predates `data.code` and stays as legacy text:
// callers that parsed it before this release keep working.
return new MCPError(INTERNAL_ERROR, `${e.message} [${e.code}]`, data);
}
async function toolBrainSearch(
ctx: ServerContext,
args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
// `null` on a server with no vault: the index holds the brain store only,
// keyed by the store id (D14 item 14). A cross-vault union reads
// `ctx.vault`, which refuses with `vault_required` there.
const vault = contextVault(ctx);
const query = args["query"];
if (typeof query !== "string" || query.trim() === "") {
throw new MCPError(INVALID_PARAMS, "missing required argument: query");
}
if (exceedsMcpQueryCap(query)) {
throw new MCPError(INVALID_PARAMS, MCP_QUERY_CAP_MESSAGE);
}
let limit = 10;
if ("limit" in args && args["limit"] !== undefined && args["limit"] !== null) {
const raw = args["limit"];
if (typeof raw !== "number" || !Number.isInteger(raw)) {
throw new MCPError(INVALID_PARAMS, "argument 'limit' must be an integer");
}
if (raw < 1 || raw > MCP_LIMIT_MAX) {
throw new MCPError(INVALID_PARAMS, `argument 'limit' must be between 1 and ${MCP_LIMIT_MAX}`);
}
limit = raw;
}
const semantic = coerceBoolOptional(args, "semantic");
const keywordOnly = coerceBoolOptional(args, "keyword_only") ?? false;
// The enum checks alone bound these values, so no separate length cap:
// any present value outside the modes, whatever its type or length, is
// refused with the accepted list.
const disclosure = args["disclosure"] ?? undefined;
if (disclosure !== undefined && !isDisclosureMode(disclosure)) {
throw new MCPError(
INVALID_PARAMS,
`argument 'disclosure' must be one of ${DISCLOSURE_MODES.join(", ")}`,
);
}
const matchModeRaw = args["match_mode"] ?? undefined;
if (matchModeRaw !== undefined && !isFtsMatchMode(matchModeRaw)) {
throw new MCPError(
INVALID_PARAMS,
`argument 'match_mode' must be one of ${FTS_MATCH_MODES.join(", ")}`,
);
}
const matchMode = matchModeRaw;
// Chunk-kind pushdown (recall-quality, C4). Same enum-gate shape as the
// match mode above: any present value outside the two kinds, whatever
// its type or length, is refused with the accepted list.
const kindRaw = args["kind"] ?? undefined;
if (kindRaw !== undefined && !isSearchKind(kindRaw)) {
throw new MCPError(INVALID_PARAMS, `argument 'kind' must be one of ${SEARCH_KINDS.join(", ")}`);
}
const kind = kindRaw as "page" | "section" | undefined;
const explain = coerceBoolOptional(args, "explain") ?? false;
const trust = coerceBoolOptional(args, "trust") ?? false;
const rerank = coerceBoolOptional(args, "rerank") ?? false;
let threshold: number | undefined;
if ("threshold" in args && args["threshold"] !== undefined && args["threshold"] !== null) {
const raw = args["threshold"];
if (typeof raw !== "number" || !Number.isFinite(raw) || raw < 0 || raw > 1) {
throw new MCPError(INVALID_PARAMS, "argument 'threshold' must be a number between 0 and 1");
}
threshold = raw;
}
const globalSearch = coerceBoolOptional(args, "global") ?? false;
const profile = coerceStringOptional(args, "profile", 32);
const pathPrefix = coerceStringOptional(args, "path_prefix", 256);
const evidencePack = coerceBoolOptional(args, "evidence_pack") ?? false;
const includeSuperseded = coerceBoolOptional(args, "include_superseded") ?? false;
const since = coerceStringOptional(args, "since", 64);
const until = coerceStringOptional(args, "until", 64);
const recordAccess = coerceBoolOptional(args, "record_access") ?? true;
const telemetry = coerceBoolOptional(args, "telemetry") ?? false;
const telemetrySessionId = coerceStringOptional(args, "session_id", 512);
const telemetryTurnId = coerceStringOptional(args, "turn_id", 512);
// One envelope for both emit sites below: the correlation fields are
// copied once, and `channel` is a fact about this handler rather than
// about the caller-supplied `telemetry_host` string.
const telemetryEnvelope = recallTelemetryEnvelope({
host: coerceStringOptional(args, "telemetry_host", 200) ?? RECALL_CHANNEL.mcp,
channel: RECALL_CHANNEL.mcp,
...(telemetrySessionId !== undefined ? { sessionId: telemetrySessionId } : {}),
...(telemetryTurnId !== undefined ? { turnId: telemetryTurnId } : {}),
});
const rawQueryDocument = coerceStringOptional(args, "query_document", 4000);
const structuredQuery =
rawQueryDocument !== undefined
? parseStructuredRecallQueryDocument(rawQueryDocument)
: undefined;
const focusQuery = coerceStringOptional(args, "focus_query", 1000);
const focusPathPrefix = coerceStringOptional(args, "focus_path_prefix", 256);
const sessionFocus =
focusQuery !== undefined || focusPathPrefix !== undefined
? normalizeSessionFocus({
query: focusQuery ?? null,
pathPrefix: focusPathPrefix ?? null,
})
: undefined;
// Iterative round-trip args (recall-quality wave). The flag is the
// per-query opt-in; token and payload are the commit leg's fields. Any
// present value of the wrong shape is refused with a named argument
// error rather than silently ignored - the kernel cannot tell an
// intended commit from a typo'd one.
const iterative = coerceBoolOptional(args, "iterative") ?? false;
const iterativeToken = coerceStringOptional(args, "iterative_token", 128);
const iterativePayload = args["iterative_payload"];
if (
iterativePayload !== undefined &&
(typeof iterativePayload !== "object" ||
iterativePayload === null ||
Array.isArray(iterativePayload))
) {
throw new MCPError(INVALID_PARAMS, "argument 'iterative_payload' must be an object");
}
// The iterative round-trip is a single-vault loop: a cross-vault
// union cannot carry the pause across origins (each leg mints its own
// token, and a commit would mark one spent while the others rebuild
// the pause and fail token_mismatch). The combination is refused by
// name at the argument layer, so no iterative field ever reaches the
// federated legs.
if (
globalSearch &&
(iterative || iterativeToken !== undefined || iterativePayload !== undefined)
) {
throw new MCPError(
INVALID_PARAMS,
"iterative recall arguments are not supported with global: true; the loop runs on the single-vault path",
);
}
const focusSession = coerceStringOptional(args, "focus_session", 128);
const properties = parsePropertiesArgument(args["properties"]);
const degreeFilters = parseDegreeArgument(args["degree"]);
const visibility = parseVisibilityArgument(args["visibility"]);
const agentScope = coerceAgentScope(ctx, args, false);
const sessionScope = coerceStringOptional(args, "session_scope", 128);
const projectScope = coerceStringOptional(args, "project_scope", 128);
const scope =
sessionScope !== undefined || projectScope !== undefined
? {
...(sessionScope !== undefined ? { session: sessionScope } : {}),
...(projectScope !== undefined ? { project: projectScope } : {}),
}
: undefined;
const reinforce = parseReinforceArgument(args["reinforce"]);
const config = resolveSearchConfig({
vault: vault,
configPath: ctx.configPath ?? undefined,
});
// Self-tuning reinforce (Search & Recall Quality Suite): the ledger
// write is the surface's side effect, recorded BEFORE the query so the
// just-named paths participate in this query's bounded boost. The pure
// re-rank lives in core. Best-effort: a failed write never breaks the
// search.
if (reinforce !== undefined && reinforce.length > 0) {
try {
recordReinforce(vault, reinforce);
} catch {
// Ledger persistence is best-effort.
}
}
let outcome: SearchOutcome;
const startedAtMs = Date.now();
const searchOpts = {
query,
limit,
semantic: semantic ?? null,
keywordOnly,
pathPrefix,
...(matchMode !== undefined ? { matchMode } : {}),
...(profile !== undefined ? { profile } : {}),
...(disclosure === DISCLOSURE_MODE.cards ? { disclosure } : {}),
...(properties !== undefined ? { properties } : {}),
...(kind !== undefined ? { kind } : {}),
...(degreeFilters !== undefined ? { degreeFilters } : {}),
...(visibility !== undefined ? { visibility } : {}),
// The reach the transport minted for this caller. Carried into the
// cross-vault union too, which spreads these options onto every
// federated leg, so a federated caller is bound by the same rule.
transportReach: contextReach(ctx),
...(agentScope !== undefined ? { agentScope } : {}),
...(scope !== undefined ? { scope } : {}),
...(structuredQuery !== undefined ? { structuredQuery } : {}),
...(sessionFocus !== undefined ? { sessionFocus } : {}),
...(focusSession !== undefined ? { focusSession } : {}),
...(evidencePack ? { evidencePack: true } : {}),
...(includeSuperseded ? { includeSuperseded: true } : {}),
...(trust ? { trust: true } : {}),
...(threshold !== undefined ? { threshold } : {}),
...(rerank ? { rerank: true } : {}),
...(reinforce !== undefined ? { reinforce } : {}),
...(since !== undefined ? { since } : {}),
...(until !== undefined ? { until } : {}),
// Access recording (Time-Aware Recall & Activation Suite): the MCP
// surface opts in by default; record_access=false suppresses it,
// and cross-vault union never records (results span foreign vaults).
...(recordAccess && !globalSearch ? { recordAccess: true } : {}),
...(iterative ? { iterative: true } : {}),
...(iterativeToken !== undefined ? { iterativeToken } : {}),
...(iterativePayload !== undefined ? { iterativePayload } : {}),
};
try {
// Cross-vault union (t_72a22658): explicit per-call opt-in.
outcome = await withTimeout(
globalSearch
? searchAcrossVaults(ctx.configPath ?? defaultConfigPath(), ctx.vault, searchOpts, config)
: search(config, searchOpts),
SEARCH_TIMEOUT_MS,
searchTimeoutError,
);
} catch (e) {
// Lazy emit kernel (t_5d7aa7c5): a throwing telemetry write inside
// this catch can no longer mask the original search error.
emitGatedTelemetry(telemetry || undefined, () =>
emitRecallTelemetry(vault, {
...telemetryEnvelope,
mode: "search",
status: e instanceof MCPError && e.message.includes("timeout") ? "timeout" : "error",
durationMs: Date.now() - startedAtMs,
resultCount: 0,
gaps: [
e instanceof MCPError && e.message.includes("timeout")
? "search_timeout"
: "search_error",
],
metadata: {
limit,
keyword_only: keywordOnly,
semantic: semantic ?? null,
},
}),
);
if (e instanceof SearchError) throw searchErrorToMcp(e);
if (e instanceof MCPError) throw e;
throw new MCPError(INTERNAL_ERROR, e instanceof Error ? e.message : String(e));
}
const recallHint = deriveRecallHint(outcome.results, outcome.total);
// Delivery shaping (delivery-trust, lane A): one shaper per request,
// applied AFTER the window so the fence wraps the exact snippet the
// pre-wave shape carried, inside the same field.
const delivery = storedTextDelivery(ctx);
// Under disclosure:'cards' the surfaced rows live on `cards`, not
// `results`; both shapes carry documentId/chunkId/path/score, so the
// telemetry count/status/top-artifacts stay honest either way.
const surfaced = outcome.cards ?? outcome.results;
const telemetryRecord = emitGatedTelemetry(telemetry || undefined, () => {
// Recall signals (what-the-index-already-knew, task G): derived
// INSIDE the gated thunk, so with the gate off - the default - not a
// single comparison runs. `search()` has already returned and its
// outcome and rows are frozen, so this lane can only read them.
const signals = searchRecallSignals(outcome);
return emitRecallTelemetry(vault, {
...telemetryEnvelope,
mode: "search",
status: surfaced.length > 0 ? "ok" : "empty",
durationMs: Date.now() - startedAtMs,
resultCount: surfaced.length,
topArtifacts: surfaced.slice(0, TELEMETRY_TOP_ARTIFACTS_MAX).map((result) => ({
id: `${result.documentId}:${result.chunkId}`,
path: result.path,
score: result.score,
})),
gaps: searchTelemetryGaps(outcome),
metadata: {
limit,
total: outcome.total,
keyword_only: keywordOnly,
semantic: semantic ?? null,
evidence_pack: evidencePack,
warnings_count: outcome.warnings.length,
...(pathPrefix !== undefined ? { path_prefix: pathPrefix } : {}),
},
...(signals !== null ? { signals } : {}),
});
});
// Cross-query demand log (t_97091fff): persist the normalized query
// terms, result count, and (when the evidence pack computed it) the
// IDF-weighted coverage so recurring poorly-answered queries can be
// surfaced as unmet-demand knowledge gaps. Gated behind the same
// telemetry opt-in and fail-open — a log write never breaks search.
emitGatedTelemetry(telemetry || undefined, () =>
recordQueryDemand(vault, {
query,
resultCount: surfaced.length,
coverage: outcome.evidencePack?.idfWeightedCoverage ?? null,
}),
);
return {
results: outcome.results.map((r: BrainSearchResult) => ({
path: r.path,
title: r.title,
content: delivery.shape(
windowContent(r.content, query, MCP_CONTENT_MAX),
rowDeliveryRel(r, globalSearch),
),
score: r.score,
startLine: r.startLine,
endLine: r.endLine,
searchType: r.searchType,
reasons: r.reasons,
// Conversation chronology (S1): present only for a note carrying an
// authored_at instant, so the shape stays byte-identical otherwise.
...(r.authoredAt !== undefined ? { authoredAt: r.authoredAt } : {}),
...(explain ? { score_breakdown: projectScoreBreakdown(r) } : {}),
...(r.trust !== undefined ? { trust: r.trust } : {}),
...(r.origin !== undefined ? { origin: r.origin } : {}),
...(outcome.evidencePack ? { why_retrieved: r.reasons } : {}),
...(r.relations && r.relations.length > 0 ? { relations: r.relations } : {}),
// Exact-duplicate merge (task D): the locations this row was folded
// from. Absent, never null, when nothing was merged.
...(r.duplicates && r.duplicates.length > 0 ? { duplicates: r.duplicates } : {}),
})),
// Cards shape their snippet under the same rule the rows shape
// `content`: same request shaper, same field, no schema change.
...(outcome.cards
? {
cards: outcome.cards.map((c) => {
const card = serializeSearchCard(c);
return { ...card, snippet: delivery.shape(c.snippet, rowDeliveryRel(c, globalSearch)) };
}),
}
: {}),
warnings: outcome.warnings,
total: outcome.total,
...(outcome.evidencePack ? { evidence_pack: serializeEvidencePack(outcome.evidencePack) } : {}),
...(recallHint !== null ? { recall_hint: recallHint } : {}),
// Summary-search router (t_7b96f242): advisory routing hint, present
// only when the query was structurally routed to the summary surface.
// Absent on the generic path, so the default response stays
// byte-identical.
...(outcome.surface !== undefined ? { surface: outcome.surface } : {}),
// Retrieval trail (evidence-at-the-boundary, C2): why this answer
// narrowed and why it is empty when it is, through the same seam the
// CLI payload uses so both surfaces name one key with one body.
// Absent - never null - on a healthy non-empty answer.
...retrievalTrailEnvelope(outcome),
// Retrieval receipts (what-the-index-already-knew, task F): the
// decision trace and the trust assessment every gated search already
// built and no surface serialized. Under `explain` only, absent -
// never null - otherwise; when the gate is off, one line naming the
// switch that produces them rather than an unexplained silence.
...explainEnvelope(outcome, {
explain,
crossVault: globalSearch,
// Engaged means the resolved mode is not off - the legacy boolean
// alone cannot answer that (an explicit search_trust_gate_mode runs
// the gate with the boolean left false).
trustGateEnabled: config.recall.searchTrustGateMode !== undefined,
}),
...(telemetryRecord ? { telemetry_id: telemetryRecord.id } : {}),
// Iterative round-trip marker: the plan phase carries the decider
// envelope and its token; a committed call carries the final marker.
// Absent - never null - on every other response, so the default
// shape stays byte-identical.
...(outcome.iterative === undefined
? {}
: {
iterative:
outcome.iterative.phase === "needs-llm-step"
? {
phase: outcome.iterative.phase,
round: outcome.iterative.round,
token: outcome.iterative.token,
llm_step: outcome.iterative.llmStep,
pool_ids: [...outcome.iterative.poolIds],
gaps: [...outcome.iterative.gaps],
// The deterministic loop's accounting before the pause,
// projected the same way the final marker does it.
rounds: [...outcome.iterative.rounds],
stop_reason: outcome.iterative.stopReason,
}
: {
phase: outcome.iterative.phase,
rounds: [...outcome.iterative.rounds],
stop_reason: outcome.iterative.stopReason,
},
}),
// Advisory decision-model answer carried by the rerank request (issue
// #213, Part 8). Absent unless rerank kind `decision-model` ran with
// the `answerable` use on and a valid answer arrived.
...decisionModelSearchEnvelope(outcome),
};
}
/**
* The recall signals for one query, or `null` when the window is empty
* and there is nothing to measure - `result_count: 0` already says that.
*
* Under `disclosure: "cards"` the pipeline returns projected cards and an
* EMPTY `results` array, so none of the per-row values the signals are
* derived from exist; that path records the named unmeasured marker
* rather than an all-zero block that would read as a measurement.
*/
function searchRecallSignals(
outcome: SearchOutcome,
): RecallQualitySignals | RecallSignalsUnmeasured | null {
if (outcome.cards !== undefined) return RECALL_SIGNALS_UNMEASURED_CARDS;
return deriveRecallSignals(outcome.results);
}
/**
* The recall-telemetry gaps for one search.
*
* `no_matching_context` is the shared gap every producer in this tree
* emits for an empty answer (`context-pack`, `pre-compress-pack`,
* `brain_query`), so it stays. What used to be missing is WHY: this
* function answered the same question as the retrieval trail from the same
* outcome and invented its own free strings to do it. It now emits the
* trail's codes, so a gap histogram and a search response name one
* vocabulary rather than two.
*/
function searchTelemetryGaps(outcome: SearchOutcome): ReadonlyArray<string> {
const gaps = new Set<string>();
const trail = outcome.retrievalTrail;
if (outcome.total === 0) gaps.add("no_matching_context");
for (const degradation of trail?.degraded ?? []) gaps.add(degradation.code);
// The corpus statement's `unknown` half is a gap in its own right: it
// says the index could not answer, not that the vault holds nothing.
if (trail?.empty?.unknownReason !== undefined) gaps.add(trail.empty.unknownReason);
for (const term of outcome.evidencePack?.missingTerms ?? []) {
gaps.add(`missing_term:${term}`);
}
return [...gaps];
}
async function toolBrainRecallGate(
ctx: ServerContext,
args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
const prompt = args["prompt"];
if (typeof prompt !== "string" || prompt.trim() === "") {
throw new MCPError(INVALID_PARAMS, "missing required argument: prompt");
}
if (prompt.length > 4000) {
throw new MCPError(INVALID_PARAMS, "argument 'prompt' exceeds 4000 characters");
}
const previousPrompt = coerceStringOptional(args, "previous_prompt", 4000);
const explicit = coerceBoolOptional(args, "explicit") ?? false;
// The telemetry correlation arguments are checked here, before anything
// runs, rather than inside the telemetry thunks below: those are
// fail-open, so a bound broken there was dropped without a word, and
// with telemetry off it was never checked at all.
const telemetryHost =
coerceStringOptional(args, "telemetry_host", GATE_TELEMETRY_HOST_MAX_CHARS) ?? "mcp";
const sessionId = coerceStringOptional(args, "session_id", GATE_CORRELATION_ID_MAX_CHARS);
const turnId = coerceStringOptional(args, "turn_id", GATE_CORRELATION_ID_MAX_CHARS);
const decision = evaluateSurfacingGate({
prompt,
previousPrompt: previousPrompt ?? null,
explicit,
});
// Adequacy verdict (t_b8f66fec): thin verdict + action layer over one
// recall attempt. Only computed when the caller passes the pair,
// keeping the pure structural-gate contract otherwise. Computed before
// the gate record so that record can carry the advisory signal below;
// a refused argument is rethrown only after the record, as before.
let refused: unknown = null;
let attempt: ReturnType<typeof coerceRecallAdequacyInput> | undefined;
let verdict: ReturnType<typeof assessRecallAdequacy> | undefined;
let answerable: DecisionAnswerableOutcome | undefined;
try {
attempt = coerceRecallAdequacyInput("brain_recall_gate", args, RECALL_SCORES_ARG_NAME);
const answerableArg = coerceDecisionAnswerable(
"brain_recall_gate",
args,
RECALL_SCORES_ARG_NAME,
attempt !== undefined,
);
if (attempt !== undefined) {
verdict = assessRecallAdequacy(
attempt,
resolveRecallAdequacyThresholds(ctx.configPath ?? undefined),
);
// Advisory decision-model signal (issue #213, Part 8): annotates the
// verdict, never changes its level or action. Resolved only when passed.
if (answerableArg !== undefined) {
answerable = decisionAnswerableFor(ctx, verdict.level, answerableArg);
}
}
} catch (err) {
refused = err;
}
// Graded surfacing key (t_107a3249): the structural decision above
// composed with the shared admission calculator over the MEASURED
// quality, when the caller supplied the pair. The quality argument is
// already validated to a finite [0,1] number by the coercion above, so
// this cannot refuse. With a measurement the graded admission IS the
// binary verdict - a below-floor quality refuses, it does not ride the
// structural fail-open behind the tier's back - and the response carries
// both `retrieve` and `admit` so the two can never drift apart again.
// Without a measurement the structural fail-open stands unchanged and
// `admit` simply names it.
const measured = attempt?.matchQuality;
const graded = evaluateGradedSurfacing({
prompt,
previousPrompt: previousPrompt ?? null,
explicit,
channel: RECALL_CHANNEL.mcp,
...(measured !== undefined ? { matchQuality: measured } : {}),
});
const retrieve = measured !== undefined ? graded.admit : decision.retrieve;
const gradedFields = measured !== undefined ? { key: graded.key, tier: graded.tier } : {};
const answerableVerdict = answerable?.kind === "annotated" ? answerable.verdict : undefined;
// Gate telemetry (t_65036e02): default off. Routed through the lazy
// emit kernel (t_5d7aa7c5) - the payload thunk never runs with the
// config off, and a broken continuity store never breaks the gate's
// pure-diagnostic contract (fail-open).
emitGatedTelemetry(resolveRecallGateTelemetry(ctx.configPath ?? undefined), () =>
emitGateTelemetry(ctx.vault, {
host: telemetryHost,
prompt,
// The recorded decision agrees with the admission, so a measured
// below-floor call is summarized as a skip, never as retrieved.
retrieve,
reason: decision.reason,
...(sessionId !== undefined ? { sessionId } : {}),
...(turnId !== undefined ? { turnId } : {}),
// The transport rides measured decisions only: it calibrates the
// measured admission, and an unmeasured structural verdict is
// already described by decision and reason.
...(measured !== undefined ? { channel: RECALL_CHANNEL.mcp } : {}),
...(measured !== undefined ? { surfacing: { key: graded.key, tier: graded.tier } } : {}),
...(verdict !== undefined && answerableVerdict !== undefined
? {
decisionAnswerable: {
level: verdict.level,
probability: answerableVerdict.probability,
disagrees: answerableVerdict.disagrees,
},
}
: {}),
}),
);
if (refused !== null) throw refused;
if (verdict === undefined)
return { retrieve, admit: retrieve, reason: decision.reason, ...gradedFields };
// signals-that-survive, unit 6: an unmet verdict is stamped onto the
// cross-query demand log under the bucket key normalizeQueryTerms already
// computes, so the knowledge-gap loop can aggregate recurrence without a
// second identity concept. Gated behind the same telemetry opt-in as the
// gate record above and fail-open — a log write never breaks the gate.
//
// `recall_gate_telemetry` is the SINGLE opt-in for this log wherever it
// is written: `brain_context_pack` writes the same records under the
// same key (see `brain/pack-tools.ts`), so one config decision governs
// the whole feature rather than one per surface.
emitGatedTelemetry(resolveRecallGateTelemetry(ctx.configPath ?? undefined), () =>
recordRecallAdequacyDemand(ctx.vault, { query: prompt, verdict }),
);
// Typed negative recall (silence-is-not-an-answer, U2). The adequacy
// verdict above judges the HITS; this judges the CORPUS they were drawn
// from, and only a zero-usable-result attempt has a corpus statement to
// make. Persisted behind the same `recall_gate_telemetry` opt-in and the
// same fail-open kernel as everything else this handler writes.
const negative = verdict.resultCount === 0 ? await assessNegativeRecall(ctx) : null;
if (negative !== null) {
emitGatedTelemetry(resolveRecallGateTelemetry(ctx.configPath ?? undefined), () =>
emitNegativeRecallTelemetry(ctx.vault, {
prompt,
verdict: negative,
...(sessionId !== undefined ? { sessionId } : {}),
}),
);
}
return {
retrieve,
admit: retrieve,
reason: decision.reason,
...gradedFields,
adequacy: {
level: verdict.level,
action: verdict.action,
escalate: verdict.escalate,
result_count: verdict.resultCount,
top_score: verdict.topScore,
mean_score: verdict.meanScore,
// The quantity the level was decided by. Returning only the two
// descriptive scores left the caller unable to reconstruct the
// verdict from its own inputs.
[MATCH_QUALITY_ARG_NAME]: verdict.matchQuality,
reason: verdict.reason,
...(answerableVerdict !== undefined
? {
[DECISION_ANSWERABLE_ARG_NAME]: {
probability: answerableVerdict.probability,
disagrees: answerableVerdict.disagrees,
},
}
: {}),
},
...(answerable?.kind === "ignored" ? { warnings: [answerable.warning] } : {}),
// Absent, never null, when the attempt had usable results - the
// convention the `explain` trace and the `adequacy` block above set.
...(negative !== null ? { negative } : {}),
};
}
/**
* The corpus statement behind a zero-result recall attempt.
*
* The gathering itself lives in `core/search/pipeline/outcome.ts` since
* evidence-at-the-boundary C2, because the search pipeline owes the same
* answer on its own zero-result path and two copies of it would drift.
* This gate keeps its own wiring - a vault plus a config path, resolved
* inside the probe's guard so a resolution failure is reported as
* `coverage-unavailable` like every other unreadable input.
*
* It supplies no retraction evidence and asserts nothing, which is why
* this surface declares only {@link RECALL_GATE_NEGATIVE_STATES}: a gate
* that reads no claim graph has no grounds for `did_not_happen`.
*/
async function assessNegativeRecall(ctx: ServerContext): Promise<NegativeRecallVerdict> {
const reach = contextReach(ctx);
const verdict = await probeRetrievalCorpus(
() => resolveSearchConfig({ vault: ctx.vault, configPath: ctx.configPath ?? undefined }),
reach,
);
return corpusVerdictAtReach(verdict, reach);
}
const RECALL_FEEDBACK_INPUT_SCHEMA: Record<string, unknown> = {
type: "object",
properties: {
query: {
type: "string",
minLength: 1,
maxLength: MCP_QUERY_MAX_CHARS,
description: "The query that produced the judged result; re-run to recover its layer scores.",
},
result_path: {
type: "string",
minLength: 1,
maxLength: 512,
description: "Vault path of the single result being judged.",
},
verdict: {
type: "string",
enum: ["up", "down"],
description: "'up' when the result was useful, 'down' when it was not.",
},
},
required: ["query", "result_path", "verdict"],
additionalProperties: false,
};
const RECALL_FEEDBACK_OUTPUT_SCHEMA: NonNullable<ToolDefinition["outputSchema"]> = {
type: "object",
properties: {
recorded: { type: "boolean" },
result_found: { type: "boolean" },
learned: { type: "object" },
// Retrieval degradation codes of the re-run (for example
// semantic-cost-unpriced); empty when nothing narrowed it.
degraded: { type: "array", items: { type: "string" } },
},
required: ["recorded", "result_found", "learned"],
};
/**
* `brain_recall_feedback` (recall-trust-suite): record one explicit
* per-result recall feedback event. The judged result's per-layer
* contributions are captured by re-running the query; the learned
* weights refresh deterministically from the full event set.
*/
async function toolBrainRecallFeedback(
ctx: ServerContext,
args: Record<string, unknown>,
): Promise<unknown> {
const query = coerceStr(args, "query")!;
if (exceedsMcpQueryCap(query)) {
throw new MCPError(INVALID_PARAMS, MCP_QUERY_CAP_MESSAGE);
}
const resultPath = coerceStr(args, "result_path")!;
const verdict = coerceStr(args, "verdict")!;
if (verdict !== "up" && verdict !== "down") {
throw new MCPError(INVALID_PARAMS, "argument 'verdict' must be 'up' or 'down'");
}
const config = resolveSearchConfig({
vault: ctx.vault,
configPath: ctx.configPath ?? undefined,
});
const outcome = await captureRecallFeedback(config, {
query,
resultPath,
verdict,
transportReach: contextReach(ctx),
});
return {
recorded: true,
result_found: outcome.resultFound,
learned: outcome.learned,
degraded: outcome.degraded,
};
}
const EVAL_INPUT_SCHEMA: Record<string, unknown> = {
type: "object",
properties: {
dataset: {
type: "object",
description:
"Eval dataset: { queries: [{ id, query, expected[], k?, answer? }] }. Scored against the active vault.",
properties: {
queries: {
type: "array",
minItems: 1,
description: "The benchmark cases, one per scored query. Non-empty.",
items: {
type: "object",
required: ["id", "query", "expected"],
properties: {
id: {
type: "string",
minLength: 1,
description: "Stable case id, reported back in per_query.",
},
query: { type: "string", minLength: 1, description: "The query text to run." },
expected: {
type: "array",
minItems: 1,
items: { type: "string", minLength: 1 },
description: "Vault paths a correct answer must surface. Non-empty.",
},
k: {
type: "integer",
minimum: 1,
maximum: MCP_LIMIT_MAX,
description: "Per-case cutoff, overriding the run-wide k.",
},
answer: {
type: "string",
minLength: 1,
description:
"Reference answer text; enables answer-containment scoring for this case.",
},
},
},
},
},
required: ["queries"],
},
k: {
type: "integer",
minimum: 1,
maximum: MCP_LIMIT_MAX,
description: "Run-wide rank depth for hit@k and the containment metrics. Default 5.",
},
expand: {
type: "boolean",
description:
"Route every query through deterministic expansion before scoring. Default false.",
},
},
required: ["dataset"],
additionalProperties: false,
};
const EVAL_OUTPUT_SCHEMA: NonNullable<ToolDefinition["outputSchema"]> = {
type: "object",
required: [
"total",
"k",
"hit_at_k",
"mrr",
"answer_queries",
"answer_containment_at_k",
"source_utilization_at_k",
"citation_depth",
"source_warnings",
],
properties: {
total: { type: "integer" },
k: { type: "integer" },
expand: { type: "boolean" },
hit_at_k: { type: "number" },
mrr: { type: "number" },
answer_queries: { type: "integer" },
answer_containment_at_k: { type: "number" },
source_utilization_at_k: { type: "number" },
citation_depth: { type: "number" },
source_warnings: { type: "integer" },
degraded: { type: "array", items: { type: "string" } },
per_query: {
type: "array",
items: {
type: "object",
properties: {
id: { type: "string" },
hit: { type: "boolean" },
rank: { type: "integer" },
answer_contained: { type: "boolean" },
degraded: { type: "array", items: { type: "string" } },
},
},
},
},
};
const EVAL_TIMEOUT_MS = 60_000;
/**
* `brain_eval` (Search & Recall Quality Suite): run the recall benchmark
* over a caller-supplied dataset against the active vault and return the
* quality metrics - hit@k, MRR, answer-containment@k, source-utilization,
* citation-depth, and the source-warnings count a CI gate can cap.
* Read-only; the fast path needs no embedding key.
*/
async function toolBrainEval(
ctx: ServerContext,
args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
let dataset;
try {
dataset = parseRecallBenchmarkDataset(args["dataset"]);
} catch (e) {
if (e instanceof SearchError) throw searchErrorToMcp(e);
throw new MCPError(INVALID_PARAMS, e instanceof Error ? e.message : String(e));
}
// Bound per-query rank depth at the untrusted MCP boundary. The library
// accepts any positive `k`, but an over-MCP caller must not bypass the
// top-level `k <= MCP_LIMIT_MAX` guard with a deep per-query override and
// trigger expensive searches.
for (const q of dataset.queries) {
if (q.k !== undefined && q.k > MCP_LIMIT_MAX) {
throw new MCPError(INVALID_PARAMS, `query '${q.id}' k must not exceed ${MCP_LIMIT_MAX}`);
}
}
let k: number | undefined;
if ("k" in args && args["k"] !== undefined && args["k"] !== null) {
const raw = args["k"];
if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 1 || raw > MCP_LIMIT_MAX) {
throw new MCPError(
INVALID_PARAMS,
`argument 'k' must be an integer between 1 and ${MCP_LIMIT_MAX}`,
);
}
k = raw;
}
const expand = coerceBoolOptional(args, "expand") ?? false;
const config = resolveSearchConfig({
vault: ctx.vault,
configPath: ctx.configPath ?? undefined,
});
let report;
try {
report = await withTimeout(
runRecallBenchmark(config, dataset, {
...(k !== undefined ? { k } : {}),
expand,
// The dataset is the caller's, and so is the reach it is scored
// at: `hit` / `rank` / `answerContained` over a corpus the caller
// did not earn is an oracle, not a metric.
transportReach: contextReach(ctx),
}),
EVAL_TIMEOUT_MS,
searchTimeoutError,
);
} catch (e) {
if (e instanceof SearchError) throw searchErrorToMcp(e);
if (e instanceof MCPError) throw e;
throw new MCPError(INTERNAL_ERROR, e instanceof Error ? e.message : String(e));
}
return {
total: report.total,
k: report.k,
expand: report.expand,
hit_at_k: report.hitAtK,
mrr: report.mrr,
answer_queries: report.answerQueries,
answer_containment_at_k: report.answerContainmentAtK,
source_utilization_at_k: report.sourceUtilizationAtK,
citation_depth: report.citationDepth,
source_warnings: report.sourceWarnings,
// A degraded run measured a smaller system than the configured one.
...(report.degraded.length > 0 ? { degraded: report.degraded } : {}),
per_query: report.perQuery.map((q) => ({
id: q.id,
hit: q.hit,
...(q.rank !== null ? { rank: q.rank } : {}),
...(q.answerContained !== null ? { answer_contained: q.answerContained } : {}),
...(q.degraded !== undefined ? { degraded: q.degraded } : {}),
})),
};
}
const FILE_CONTEXT_INPUT_SCHEMA: Record<string, unknown> = {
type: "object",
properties: {
file_path: {
type: "string",
minLength: 1,
maxLength: 1024,
description:
"Path of the file about to be read; its basename, stem and parent directory become the query terms.",
},
limit: {
type: "integer",
minimum: 1,
maximum: MCP_LIMIT_MAX,
description: "How many prior-work hits to return. Default 5.",
},
min_bytes: {
type: "integer",
minimum: 0,
maximum: 10_000_000,
description:
"Skip files smaller than this, reporting the reason instead of an empty hit. Default 1500.",
},
agent_scope: AGENT_SCOPE_SCHEMA,
},
required: ["file_path"],
additionalProperties: false,
};
const FILE_CONTEXT_OUTPUT_SCHEMA: NonNullable<ToolDefinition["outputSchema"]> = {
type: "object",
properties: {
file_path: { type: "string" },
skipped: { type: "boolean" },
// reason and title are string-or-null; the contract type is a single
// value, so the type check is omitted (both nullable shapes pass).
reason: {},
query: { type: "string" },
results: {
type: "array",
items: {
type: "object",
properties: {
path: { type: "string" },
title: {},
score: { type: "number" },
},
},
},
},
required: ["file_path", "skipped", "reason", "query", "results"],
};
async function toolBrainFileContext(
ctx: ServerContext,
args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
const filePath = coerceStr(args, "file_path");
if (filePath === null || filePath.length > 1024) {
throw new MCPError(
INVALID_PARAMS,
"argument 'file_path' must be a non-empty string up to 1024 characters",
);
}
const limit = coerceIntInRange(args, "limit", 1, MCP_LIMIT_MAX);
const minBytes = coerceIntInRange(args, "min_bytes", 0, 10_000_000);
const config = resolveSearchConfig({
vault: ctx.vault,
configPath: ctx.configPath ?? undefined,
});
try {
const agentScope = coerceAgentScope(ctx, args, false);
const outcome = await fileContextRecall(config, {
...(agentScope !== undefined ? { agentScope } : {}),
transportReach: contextReach(ctx),
filePath,
...(limit !== undefined ? { limit } : {}),
...(minBytes !== undefined ? { minBytes } : {}),
});
return {
file_path: outcome.filePath,
skipped: outcome.skipped,
reason: outcome.reason,
query: outcome.query,
results: outcome.results.map((r) => ({
path: r.path,
title: r.title,
score: r.score,
})),
};
} catch (e) {
if (e instanceof SearchError) throw searchErrorToMcp(e);
if (e instanceof MCPError) throw e;
throw new MCPError(INTERNAL_ERROR, e instanceof Error ? e.message : String(e));
}
}
function coerceIntInRange(
args: Record<string, unknown>,
key: string,
min: number,
max: number,
): number | undefined {
if (!(key in args) || args[key] === undefined || args[key] === null) return undefined;
const raw = args[key];
if (typeof raw !== "number" || !Number.isInteger(raw) || raw < min || raw > max) {
throw new MCPError(
INVALID_PARAMS,
`argument '${key}' must be an integer between ${min} and ${max}`,
);
}
return raw;
}
const SEARCH_EXPAND_INPUT_SCHEMA: Record<string, unknown> = {
type: "object",
properties: {
chunk_id: {
type: "integer",
minimum: 1,
description: "The chunk_id of a layer-1 card (from brain_search disclosure:'cards').",
},
raw_limit: {
type: "integer",
minimum: 1,
maximum: MCP_LIMIT_MAX,
description: "Layer-3 raw-chunk page size (default 10).",
},
cursor: {
type: "string",
maxLength: 32,
description: "Pagination cursor returned as next_cursor by a prior expand call.",
},
agent_scope: AGENT_SCOPE_SCHEMA,
},
required: ["chunk_id"],
additionalProperties: false,
};
const SEARCH_EXPAND_OUTPUT_SCHEMA: NonNullable<ToolDefinition["outputSchema"]> = {
type: "object",
required: ["chunk_id", "note", "raw_content", "next_cursor"],
properties: {
chunk_id: { type: "integer" },
note: {
type: "object",
required: ["document_id", "path", "title", "line_start", "line_end", "pointer", "content"],
properties: {
document_id: { type: "integer" },
path: { type: "string" },
// Nullable for title-less notes; the local schema validator does not
// support union types, so keep the field present but unconstrained.
title: {},
line_start: { type: "integer" },
line_end: { type: "integer" },
pointer: { type: "string" },
content: { type: "string" },
},
},
raw_content: {
type: "array",
items: {
type: "object",
required: ["chunk_id", "chunk_index", "start_line", "end_line", "pointer", "content"],
properties: {
chunk_id: { type: "integer" },
chunk_index: { type: "integer" },
start_line: { type: "integer" },
end_line: { type: "integer" },
pointer: { type: "string" },
content: { type: "string" },
},
},
},
// String cursor or null when the raw transcript is exhausted.
next_cursor: {},
},
};
/**
* `brain_search_expand` (progressive disclosure layers 2 + 3): drill a
* layer-1 card into the fuller note and the paginated raw chunk
* transcript. Read-only; reuses the existing store read, never rebuilds
* the index.
*/
async function toolBrainSearchExpand(
ctx: ServerContext,
args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
const rawChunk = args["chunk_id"];
if (typeof rawChunk !== "number" || !Number.isInteger(rawChunk) || rawChunk < 1) {
throw new MCPError(INVALID_PARAMS, "argument 'chunk_id' must be a positive integer");
}
const rawLimit = coerceIntInRange(args, "raw_limit", 1, MCP_LIMIT_MAX);
const cursor = coerceStringOptional(args, "cursor", 32);
const expandScope = coerceAgentScope(ctx, args, false);
const config = resolveSearchConfig({
vault: ctx.vault,
configPath: ctx.configPath ?? undefined,
});
let result;
try {
result = await withTimeout(
expandHit(config, {
chunkId: rawChunk,
transportReach: contextReach(ctx),
...(expandScope !== undefined ? { agentScope: expandScope } : {}),
...(rawLimit !== undefined ? { rawLimit } : {}),
...(cursor !== undefined ? { cursor } : {}),
}),
SEARCH_TIMEOUT_MS,
searchTimeoutError,
);
} catch (e) {
if (e instanceof SearchError) throw searchErrorToMcp(e);
if (e instanceof MCPError) throw e;
throw new MCPError(INTERNAL_ERROR, e instanceof Error ? e.message : String(e));
}
// Delivery shaping (delivery-trust, lane A): the drill-down bodies are
// stored record text of ONE page - the note `expandHit` already proved
// readable at this caller's reach - so every body this envelope hands
// back is shaped under the same remote-quoted / local-identical rule
// the search rows follow, probed once per request.
const delivery = storedTextDelivery(ctx);
return {
chunk_id: result.chunkId,
note: {
document_id: result.note.documentId,
path: result.note.path,
title: result.note.title,
line_start: result.note.lineStart,
line_end: result.note.lineEnd,
pointer: result.note.pointer,
// Drill-down tool: return the full note (layer 2) and raw chunks
// (layer 3), not a snippet. The preview budget caps the envelope
// and hands back an artifact_id when the payload is large.
content: delivery.shape(result.note.content, result.note.path),
},
raw_content: result.raw_content.map((c) => ({
chunk_id: c.chunkId,
chunk_index: c.chunkIndex,
start_line: c.startLine,
end_line: c.endLine,
pointer: c.pointer,
content: delivery.shape(c.content, result.note.path),
})),
next_cursor: result.next_cursor,
};
}
export const SEARCH_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
{
name: "brain_recall_feedback",
kind: "write",
description:
"Record explicit recall feedback (up/down) for one search result. Feeds the deterministic learned-weight fold; each event is recorded as recall feedback.",
inputSchema: RECALL_FEEDBACK_INPUT_SCHEMA,
outputSchema: RECALL_FEEDBACK_OUTPUT_SCHEMA,
handler: toolBrainRecallFeedback,
},
{
name: "brain_recall_gate",
kind: "read",
description:
"Classify whether recall should run. Diagnostics only; does not search. Pass `scores` AND `match_quality` together for an adequacy verdict; either alone is INVALID_PARAMS (see `dependentRequired`). A measurement decides the verdict: below-floor quality answers retrieve false. `admit` echoes it.",
inputSchema: RECALL_GATE_INPUT_SCHEMA,
outputSchema: RECALL_GATE_OUTPUT_SCHEMA,
handler: toolBrainRecallGate,
},
{
name: "brain_search",
// Write-mode-dominant (tool-contract.ts), not "read". The handler's
// writes are ranking STATE, not accepted-loss telemetry appends:
// `reinforce` persists boost events the fold reads back
// (`recordReinforce` -> Brain/search/reinforce/), access recording is
// default-on and writes activation events plus the derived state
// (`recordAccessEvent` -> Brain/search/activation/), and under the
// telemetry opt-in the recall-telemetry and query-demand ledgers
// append. All of these feed later searches' behaviour, so they fail
// the fail-soft-appends carve-out and gate the write path.
kind: "write",
description:
"Full-text search across the vault. Optional semantic layer when configured. Persists access events and the opt-in reinforce and telemetry ledgers. When a query misses, consult brain_recall_gate before widening recall: it classifies whether widening is warranted.",
inputSchema: SEARCH_INPUT_SCHEMA,
outputSchema: SEARCH_OUTPUT_SCHEMA,
previewBudget: MCP_PREVIEW_BUDGET,
handler: toolBrainSearch,
},
{
name: "brain_search_expand",
kind: "read",
description:
"Progressive disclosure layers 2 + 3: drill a brain_search card (by chunk_id) into the fuller note and the paginated raw chunk transcript. Read-only; reuses the existing index.",
inputSchema: SEARCH_EXPAND_INPUT_SCHEMA,
outputSchema: SEARCH_EXPAND_OUTPUT_SCHEMA,
previewBudget: MCP_PREVIEW_BUDGET,
handler: toolBrainSearchExpand,
},
{
name: "brain_eval",
kind: "read",
description:
"Score retrieval quality over a dataset against the active vault: hit@k, MRR, answer-containment@k, source-utilization, citation-depth, source warnings. Read-only.",
inputSchema: EVAL_INPUT_SCHEMA,
outputSchema: EVAL_OUTPUT_SCHEMA,
previewBudget: MCP_PREVIEW_BUDGET,
handler: toolBrainEval,
},
{
name: "brain_file_context",
kind: "read",
description:
"Given a file path, surface prior vault work that mentions it (decisions, bug notes, refactor history) by querying the index with terms derived from the path. A size gate skips trivial files. Read-only; no LLM.",
inputSchema: FILE_CONTEXT_INPUT_SCHEMA,
outputSchema: FILE_CONTEXT_OUTPUT_SCHEMA,
previewBudget: MCP_PREVIEW_BUDGET,
handler: toolBrainFileContext,
},
]);
/**
* `search.*` block for `second_brain_status`. Mirrors design §9
* exactly. Never throws — returns `{ exists: false, hint }` if the
* index does not exist; surfaces errors as `error: "<message>"`.
*/
export async function buildSearchStatusBlock(ctx: ServerContext): Promise<Record<string, unknown>> {
try {
const config = resolveSearchConfig({
vault: ctx.vault,
configPath: ctx.configPath ?? undefined,
});
const snap = await indexStatus(config);
if (!snap.exists) {
return { exists: false, hint: "run: o2b search index" };
}
// Token-budget conscious: pick the MCP subset out of the shared
// serializer's full field set rather than re-declaring the mapping.
//
// `warnings` used to be dropped with the rest, which is how an
// agent driving the vault entirely over MCP could not observe
// embedding-ABI drift at any setting short of `fail`
// (context-integrity-gates, Unit E): the drift line, the
// instruction-prefix line and the "sqlite-vec unavailable" line all
// died here. It is now spread back in only when non-empty, so a
// healthy vault's block is byte-identical and the token cost lands
// exactly on the vaults that have something to say. The structured
// `embedding_abi` field rides through in `rest` on the same
// condition, so an agent can branch instead of matching text.
const {
embedding_signature: _embeddingSignature,
estimated_refresh_cost_usd: _estimatedRefreshCostUsd,
refresh_price_source: _refreshPriceSource,
warnings,
...rest
} = serializeIndexStatus(snap);
// Held chunks travel as a COUNT, never as the item list: the items'
// paths are an operator diagnostic (`o2b search status`, the doctor),
// while this block reaches callers a transport may serve at `remote`
// reach, and a held chunk's path is exactly the location a reservation
// may want kept off the wire. The total is what an agent needs to
// know - work is waiting that the active configuration will not spend.
const heldChunks = rest["held_chunks"] as { total: number } | undefined;
const trimmed =
heldChunks === undefined ? rest : { ...rest, held_chunks: { total: heldChunks.total } };
const reportable = Array.isArray(warnings) ? warnings : [];
return reportable.length > 0 ? { ...trimmed, warnings: reportable } : trimmed;
} catch (e) {
return { exists: false, error: e instanceof Error ? e.message : String(e) };
}
}