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
/**
* The explain envelope (what-the-index-already-knew, task F).
*
* Every gated search builds two compact-reference receipts - the
* retrieval decision trace and the memory trust assessment - and until
* this unit no surface serialized either: they were reachable only from a
* test. This module is the single definition of how those receipts reach
* a caller, so the CLI `--json` payload and the MCP response name the
* same keys with the same bodies.
*
* Two rules the surfaces inherit by using it:
*
* - Off means absent. With the explain flag unset the envelope is
* empty, so the response bytes are identical to the pre-change ones -
* never a null placeholder.
* - A check that could not run says so, and says which check. The
* receipts exist only when the retrieval trust gate is engaged and a
* cross-vault union never merges them, so asking for them without
* them returns `retrieval_trace_unavailable` carrying whichever of
* those two situations actually applies - never an unexplained
* silence, and never the wrong explanation.
*
* The receipt bodies are already snake_cased by their builders
* (src/core/brain/trust/retrieval-receipts.ts), so this is a key
* projection and not a re-serialization.
*/
import type { SearchLaneTiming, SearchOutcome } from "./types.ts";
/** Config key that engages the retrieval trust gate. */
export const TRUST_GATE_CONFIG_KEY = "search_trust_gate_enabled";
/** Environment variable equivalent of {@link TRUST_GATE_CONFIG_KEY}. */
export const TRUST_GATE_ENV_KEY = "OPEN_SECOND_BRAIN_SEARCH_TRUST_GATE";
/** Config key that names the gate's mode (off | shadow | enforce). */
export const TRUST_GATE_MODE_CONFIG_KEY = "search_trust_gate_mode";
/**
* Why an explain request carries no trace, and the exit that produces
* one. The receipts are a by-product of the retrieval trust gate: with
* the gate off there is no evaluated / excluded set to report. The mode
* key is named beside the legacy boolean: naming a mode (shadow first -
* it measures without excluding) is the other enablement path.
*/
export const RETRIEVAL_TRACE_UNAVAILABLE =
`no retrieval decision trace: the retrieval trust gate is off. ` +
`Enable it with ${TRUST_GATE_CONFIG_KEY}: true in the config, ${TRUST_GATE_ENV_KEY}=1, ` +
`or name a mode with ${TRUST_GATE_MODE_CONFIG_KEY}: shadow.`;
/**
* The cross-vault union's own reason. A union outcome is merged from one
* search per origin and the receipts are per-origin: they reference
* document and chunk ids that are only meaningful inside the store that
* issued them, so merging them would produce ambiguous references. The
* gate state is therefore NOT what is being reported here, and saying it
* was would be a false diagnosis.
*/
export const RETRIEVAL_TRACE_NOT_MERGED =
`no retrieval decision trace: a cross-vault union merges one search per origin and the ` +
`per-origin receipts reference ids that are local to their own store. ` +
`Run the query against a single vault to see its trace.`;
/**
* Both situations at once. The gate is named first because it is the one
* that has to change either way, and the union is named because changing
* it alone still yields nothing - reporting only one of the two would
* send the operator to an exit that does not produce a trace.
*/
export const RETRIEVAL_TRACE_UNAVAILABLE_AND_NOT_MERGED =
`no retrieval decision trace: the retrieval trust gate is off, and a cross-vault union ` +
`would not merge the per-origin receipts even with it on. ` +
`Enable ${TRUST_GATE_CONFIG_KEY}: true (or ${TRUST_GATE_ENV_KEY}=1, or ` +
`${TRUST_GATE_MODE_CONFIG_KEY}: shadow) and query a single vault.`;
/** Response key carrying the retrieval decision trace. */
export const RETRIEVAL_DECISION_TRACE_KEY = "retrieval_decision_trace";
/** Response key carrying the memory trust assessment. */
export const MEMORY_TRUST_ASSESSMENT_KEY = "memory_trust_assessment";
/**
* Response key carrying the gate's resolved mode, present whenever the
* gate ran. The shadow mode stamps its receipts; enforce keeps the
* pre-mode receipt shape, so a stampless receipt names enforce - receipts
* exist only when the gate ran in one of the two active modes. Off has no
* receipts and so no mode key.
*/
export const RETRIEVAL_TRUST_GATE_MODE_KEY = "retrieval_trust_gate_mode";
/** Response key carrying the reason there is no trace to show. */
export const RETRIEVAL_TRACE_UNAVAILABLE_KEY = "retrieval_trace_unavailable";
/** Response key carrying the overlapped-lane milliseconds. */
export const OVERLAPPED_MS_KEY = "overlapped_ms";
/** Response key carrying whether the semantic lane attempted the embed. */
export const SEMANTIC_ATTEMPTED_KEY = "semantic_attempted";
/**
* What a surface asks the envelope for. `crossVault` is not derivable
* from the outcome - a union and a single-vault search with the gate off
* are both receipt-less - and the two cases have different exits, so the
* caller that knows states it.
*/
export interface ExplainRequest {
readonly explain: boolean;
/** True when this outcome came from a cross-vault union. */
readonly crossVault: boolean;
/**
* True when the retrieval trust gate is engaged in the caller's own
* resolved config: its 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 - so the caller derives this
* from the resolved mode's presence. Neither this nor `crossVault` is
* derivable from a receipt-less outcome, and naming the wrong one of
* the two sends the operator to an exit that produces nothing - so the
* caller, which knows both, states both.
*/
readonly trustGateEnabled: boolean;
}
/** The default for every surface: opt-in, single vault. */
export const EXPLAIN_OFF: ExplainRequest = Object.freeze({
explain: false,
crossVault: false,
trustGateEnabled: false,
});
/**
* Why this outcome carries no receipts, as the caller's own situation
* explains it.
*/
export function retrievalTraceUnavailableReason(
crossVault: boolean,
trustGateEnabled: boolean,
): string {
if (crossVault && !trustGateEnabled) return RETRIEVAL_TRACE_UNAVAILABLE_AND_NOT_MERGED;
if (crossVault) return RETRIEVAL_TRACE_NOT_MERGED;
return RETRIEVAL_TRACE_UNAVAILABLE;
}
/**
* The explain keys for one outcome, ready to spread into a response
* object. `explain: false` yields an empty object - the caller's payload
* is then byte-identical to the pre-change one.
*
* `timing` (recall-lane-latency) is the per-call record the search's
* timing sink handed the caller. It rides beside the receipts only under
* an on flag - off means absent, never a null placeholder - and the
* cross-vault union never captures one, so a merged payload carries no
* timing rather than one origin's figure mislabeled as the union's.
*/
export function explainEnvelope(
outcome: SearchOutcome,
request: ExplainRequest,
timing?: SearchLaneTiming,
): Record<string, unknown> {
if (!request.explain) return {};
const trace = outcome.retrievalDecisionTrace;
const assessment = outcome.memoryTrustAssessment;
const receipts =
trace === undefined || assessment === undefined
? {
[RETRIEVAL_TRACE_UNAVAILABLE_KEY]: retrievalTraceUnavailableReason(
request.crossVault,
request.trustGateEnabled,
),
}
: {
[RETRIEVAL_DECISION_TRACE_KEY]: trace,
[MEMORY_TRUST_ASSESSMENT_KEY]: assessment,
// The resolved mode of the gate that built these receipts:
// shadow stamps them, enforce leaves them stampless.
[RETRIEVAL_TRUST_GATE_MODE_KEY]: trace.mode ?? "enforce",
};
if (timing === undefined) return receipts;
return {
...receipts,
[OVERLAPPED_MS_KEY]: timing.overlappedMs,
[SEMANTIC_ATTEMPTED_KEY]: timing.attempted,
};
}