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
/**
* Shadow-only retrieval_plan advisor (R3, t_3ffb021c).
*
* A strictly read-only advisor that composes four EXISTING deterministic
* signals into one per-question retrieval plan, without changing any of
* them:
* - the query plan ({@link ../search/query-plan.ts}): structural intent,
* the bounded weight profile, and the summary-surface route (R1);
* - the context-pack density allocation ({@link ./context-pack.ts} +
* {@link ./context-density.ts}): the impact-per-token ranking and the
* token budget the packer would actually spend;
* - the calibrated token-impact ledger ({@link ./token-impact.ts}): the
* first-pass rate that tells us how reliable recalled memory has been;
* - observed route latency ({@link ./mcp-route-metrics.ts}): the search
* route's success rate and p95 latency.
*
* From those it emits: source/query strategy, the token-budget allocation
* matching what the packer would spend, graph-expansion advice, observed
* reliability with p95 latency, and a marginal-value stop derived from the
* density curve plus p95 latency (each extra low-density page costs more when
* the route is slow, so the stop tightens as p95 rises).
*
* SHADOW-ONLY INVARIANT: this module reads signals and returns advice. It
* writes no config and no store rows (the context pack runs without a
* receipt, telemetry, or metric), and it exposes no handle that could mutate
* ranking or weight policy. The advisor is pure with respect to the vault.
*/
import { buildQueryPlan } from "../search/query-plan.ts";
import type { QueryIntent, QuerySurface, WeightProfile } from "../search/types.ts";
import { packContext, type ContextPackReport } from "./context-pack.ts";
import { summarizeTokenImpact, type TokenImpactSummary } from "./token-impact.ts";
import { summarizeMcpRouteLatency, type McpRouteLatencySummary } from "./mcp-route-metrics.ts";
import { loadSchemaPack } from "./schema-pack.ts";
import { marginalValueStop, type RetrievalPlanMarginalStop } from "./marginal-value-stop.ts";
// ----- Tunables -------------------------------------------------------------
/** Default context-pack token budget the advisor models when none is given. */
export const DEFAULT_PLAN_TOKEN_BUDGET = 2000;
/** The MCP route whose observed latency drives the reliability read. */
export const RETRIEVAL_PLAN_ROUTE = "brain_search";
// The stop predicate is a pure leaf (see ./marginal-value-stop.ts); its
// tunables, verdict type and function are re-exported here unchanged, so
// the advisor's public surface and every existing consumer are untouched.
export {
STOP_BASE_FRACTION,
STOP_MAX_EXTRA_FRACTION,
STOP_P95_SCALE_MS,
marginalValueStop,
type RetrievalPlanMarginalStop,
} from "./marginal-value-stop.ts";
/** Graph-expansion hop suggestions per structural intent. */
const HOPS_BY_INTENT: Readonly<Record<QueryIntent, number>> = Object.freeze({
broad: 2,
entity: 1,
exact: 0,
neutral: 0,
});
// ----- Types ----------------------------------------------------------------
export interface RetrievalPlanStrategy {
readonly intent: QueryIntent;
readonly surface: QuerySurface;
readonly weights: WeightProfile;
}
export interface RetrievalPlanAllocation {
readonly tokenBudget: number;
readonly tokensUsed: number;
readonly itemCount: number;
/** Per-item density, best-first: the density curve the stop reads off. */
readonly densityCurve: ReadonlyArray<number>;
}
export interface RetrievalPlanGraphExpansion {
readonly advised: boolean;
readonly suggestedHops: number;
readonly reason: string;
}
export interface RetrievalPlanReliability {
readonly routeSamples: number;
/** Route success rate in [0,1], or null when no route samples exist. */
readonly successRate: number | null;
/** Observed p95 latency (ms) for the route, or null when unobserved. */
readonly p95LatencyMs: number | null;
/** Calibrated token-impact first-pass rate, or null when uncalibrated. */
readonly firstPassRate: number | null;
}
export interface RetrievalPlanAdvice {
readonly question: string;
readonly strategy: RetrievalPlanStrategy;
readonly allocation: RetrievalPlanAllocation;
readonly graphExpansion: RetrievalPlanGraphExpansion;
readonly reliability: RetrievalPlanReliability;
readonly marginalStop: RetrievalPlanMarginalStop;
}
export interface RetrievalPlanDeps {
/** Context pack producer; defaults to a read-only {@link packContext}. */
readonly pack?: (
vault: string,
budget: number,
agentScope: string | undefined,
) => ContextPackReport;
/** Token-impact summary; defaults to {@link summarizeTokenImpact}. */
readonly tokenImpact?: (vault: string) => TokenImpactSummary;
/** Route latency summary; defaults to {@link summarizeMcpRouteLatency}. */
readonly routeLatency?: (vault: string) => McpRouteLatencySummary;
/** Summary-surface vocabulary; defaults to the schema pack's page types. */
readonly surfaceVocabulary?: ReadonlySet<string>;
/** Context-pack token budget; defaults to {@link DEFAULT_PLAN_TOKEN_BUDGET}. */
readonly tokenBudget?: number;
/**
* Owner scope for the pack the advice is computed over
* (context-integrity-gates, Unit A). The plan returns no memory
* bodies, but its item count and density curve are derived from them,
* so advice built over memories the caller may not see would describe
* a pack it can never receive. Gated like every other
* preference-backed surface; omitted filters nothing.
*/
readonly agentScope?: string;
}
// ----- Composition ----------------------------------------------------------
function summarySurfaceVocabulary(vault: string): ReadonlySet<string> {
try {
return new Set(loadSchemaPack(vault).vocabulary.page_types.map((t) => t.toLowerCase()));
} catch {
return new Set<string>();
}
}
/** Read-only default pack: no receipt, telemetry, or metric, so nothing is written. */
function defaultPack(
vault: string,
budget: number,
agentScope: string | undefined,
): ContextPackReport {
return packContext(vault, {
maxTokens: budget,
densityRanking: true,
...(agentScope !== undefined ? { agentScope } : {}),
});
}
function graphExpansionFor(intent: QueryIntent): RetrievalPlanGraphExpansion {
const suggestedHops = HOPS_BY_INTENT[intent];
if (suggestedHops === 0) {
return Object.freeze({
advised: false,
suggestedHops: 0,
reason: `intent '${intent}' is a direct lookup; graph expansion adds noise`,
});
}
return Object.freeze({
advised: true,
suggestedHops,
reason: `intent '${intent}' benefits from ${suggestedHops}-hop link expansion`,
});
}
function reliabilityFrom(
routes: McpRouteLatencySummary,
impact: TokenImpactSummary,
): RetrievalPlanReliability {
const route = routes.routes.find((r) => r.tool === RETRIEVAL_PLAN_ROUTE);
const successRate =
route && route.count > 0 ? (route.count - route.error_count) / route.count : null;
return Object.freeze({
routeSamples: route?.count ?? 0,
successRate,
p95LatencyMs: route ? route.p95_ms : null,
firstPassRate: impact.modeled_inference_avoidance.calibration.first_pass_rate,
});
}
/**
* Build the read-only retrieval plan for one question. Pure with respect to
* the vault: it composes existing signals and writes nothing.
*/
export function buildRetrievalPlan(
vault: string,
question: string,
deps: RetrievalPlanDeps = {},
): RetrievalPlanAdvice {
const budget = Math.max(1, Math.floor(deps.tokenBudget ?? DEFAULT_PLAN_TOKEN_BUDGET));
const vocab = deps.surfaceVocabulary ?? summarySurfaceVocabulary(vault);
const queryPlan = buildQueryPlan(question, [], null, vocab);
const pack = (deps.pack ?? defaultPack)(vault, budget, deps.agentScope);
const items = pack.items;
const densityCurve = items.map((i) => i.density ?? 0);
const tokens = items.map((i) => i.tokens);
const routes = (deps.routeLatency ?? summarizeMcpRouteLatency)(vault);
const impact = (deps.tokenImpact ?? summarizeTokenImpact)(vault);
const reliability = reliabilityFrom(routes, impact);
return Object.freeze({
question,
strategy: Object.freeze({
intent: queryPlan.intent,
surface: queryPlan.surface,
weights: queryPlan.weightProfile,
}),
allocation: Object.freeze({
tokenBudget: pack.maxTokens,
tokensUsed: pack.tokensUsed,
itemCount: items.length,
densityCurve: Object.freeze(densityCurve),
}),
graphExpansion: graphExpansionFor(queryPlan.intent),
reliability,
marginalStop: marginalValueStop(densityCurve, tokens, reliability.p95LatencyMs),
});
}
/** Snake_case JSON projection for the MCP tool and any --json surface. */
export function serializeRetrievalPlan(plan: RetrievalPlanAdvice): Record<string, unknown> {
return {
question: plan.question,
strategy: {
intent: plan.strategy.intent,
surface: plan.strategy.surface,
weights: plan.strategy.weights,
},
allocation: {
token_budget: plan.allocation.tokenBudget,
tokens_used: plan.allocation.tokensUsed,
item_count: plan.allocation.itemCount,
density_curve: plan.allocation.densityCurve,
},
graph_expansion: {
advised: plan.graphExpansion.advised,
suggested_hops: plan.graphExpansion.suggestedHops,
reason: plan.graphExpansion.reason,
},
reliability: {
route_samples: plan.reliability.routeSamples,
success_rate: plan.reliability.successRate,
p95_latency_ms: plan.reliability.p95LatencyMs,
first_pass_rate: plan.reliability.firstPassRate,
},
marginal_stop: {
stop_rank: plan.marginalStop.stopRank,
stop_tokens: plan.marginalStop.stopTokens,
reason: plan.marginalStop.reason,
},
};
}