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
/**
* `runDecision` - the one entry point every use goes through.
*
* Uses never call `provider.decide` directly. This function owns the
* rules that must hold for all of them:
*
* - `off` (the default, and every configuration that is not `active`):
* no state is built, nothing is sent, nothing is recorded.
* - the daily cost gate, checked before the state is built;
* - the state builder's own budget refusal;
* - the request itself, over the configured provider chain in order:
* an entry that is not configured is skipped, a connection error or
* timeout falls through to the next entry, and the whole chain
* shares the caller's one timeout budget (each attempt gets an even
* slice of what remains, so a dead first server can never stretch
* the call);
* - exactly one `decision_model_call` record per attempted request,
* each naming the provider and model that attempted or answered it;
* - the per-route latency component for MCP route metrics.
*
* It never throws. A degrade is returned as a typed reason and the use
* applies its own failure policy (context uses fall back to the
* deterministic result; advisory uses omit their field).
*/
import {
DecisionProviderError,
type DecisionDegradeReason,
type DecisionModelMode,
type DecisionModelUse,
type DecisionProvider,
type DecisionQuestion,
type DecisionResponse,
type DecisionState,
} from "./contract.ts";
import {
decisionModelModeFor,
resolvedProviderEntries,
type ResolvedDecisionModelConfig,
} from "./config.ts";
import type { ResolvedDecisionProvider } from "./config-types.ts";
import { noteDecisionLatency } from "./latency.ts";
import { makeEntryDecisionProvider } from "./provider.ts";
import { emitDecisionModelCall, todaySpendUsd } from "./record.ts";
import { attemptTimeoutMs } from "./request-floor.ts";
import { estimateTokens } from "./state.ts";
/** Estimated cost of requests in flight in this process, per vault. */
const IN_FLIGHT_USD = new Map<string, number>();
function inFlightUsd(vault: string): number {
return IN_FLIGHT_USD.get(vault) ?? 0;
}
/** Reserve an estimate until the request settles; returns the release. */
function reserveInFlight(vault: string | null, usd: number): () => void {
if (vault === null || usd <= 0) return () => undefined;
IN_FLIGHT_USD.set(vault, inFlightUsd(vault) + usd);
return () => {
const left = inFlightUsd(vault) - usd;
if (left > 1e-12) IN_FLIGHT_USD.set(vault, left);
else IN_FLIGHT_USD.delete(vault);
};
}
/** What a use's state builder hands back. */
export type BuiltDecisionState<C> =
| {
readonly kind: "ok";
readonly state: DecisionState;
readonly candidateCount: number;
/** Use-private context (e.g. the mask mapping); never sent or recorded. */
readonly context: C;
}
/** The minimum useful state does not fit `max_state_tokens`. */
| { readonly kind: "budget" }
/** Nothing to decide (e.g. every candidate is private); no request, no record. */
| { readonly kind: "empty" };
export type DecisionRunResult<C> =
| { readonly status: "off" }
| { readonly status: "empty"; readonly mode: Exclude<DecisionModelMode, "off"> }
| {
readonly status: "ok";
readonly mode: Exclude<DecisionModelMode, "off">;
readonly response: DecisionResponse;
readonly context: C;
readonly latencyMs: number;
/**
* The chain entry that answered: its configured provider name and
* model. Stored thresholds are keyed by this model, and a stored
* verdict names this provider.
*/
readonly answeredBy: { readonly provider: string; readonly model: string | null };
}
| {
readonly status: "degraded";
readonly mode: Exclude<DecisionModelMode, "off">;
readonly reason: DecisionDegradeReason;
};
export interface RunDecisionOptions<C> {
readonly config: ResolvedDecisionModelConfig | null | undefined;
/**
* Injected provider (tests): replaces the whole chain with this one
* adapter. Defaults to the configured chain, first entry first.
*/
readonly provider?: DecisionProvider;
readonly env?: Readonly<Record<string, string | undefined>>;
/**
* Vault whose custody store backs a `$secret:NAME` key value at the use
* site. Absent, the key value is read from `env` exactly as before the
* resolver routing existed.
*/
readonly secretsVault?: string | null;
/** Overrides `decision_model_timeout_ms` (e.g. a hook sub-budget). */
readonly timeoutMs?: number;
/**
* Holds the minimum request time (`request-floor.ts`, design D20) for
* the topic and hook uses: the budget runs from this call's start, so
* the time spent preparing the request counts; no attempt of the chain
* starts with less than the floor, and an entry whose share would fall
* below it is not attempted (its time goes to the entries that are).
* When not even the first attempt fits, nothing is built, sent or
* recorded and the call degrades as `budget`.
*/
readonly requestFloor?: boolean;
/**
* The caller's cancellation (the search's composite hybrid deadline).
* Handed to the provider, whose transport stops the request when it
* aborts; the run then degrades and records it like any cut request.
*/
readonly signal?: AbortSignal;
/** Forces a mode (the eval gate measures `enforce` regardless of config). */
readonly modeOverride?: Exclude<DecisionModelMode, "off">;
readonly now?: () => Date;
/**
* Per-use evaluation identifiers for the record, given the reply (null
* on a degrade). Identifiers and numbers only, never text.
*/
readonly recordDetails?: (
response: DecisionResponse | null,
context: C | null,
/** The chain entry this record is for (the one that answered, on `ok`). */
answeredBy: { readonly provider: string; readonly model: string | null },
) => Readonly<Record<string, unknown>> | undefined;
}
/** One attempt of the chain: an adapter plus the mode it answers under. */
interface ChainAttempt {
readonly adapter: DecisionProvider;
readonly entry: ResolvedDecisionProvider;
readonly mode: Exclude<DecisionModelMode, "off">;
}
/** The chain options `buildChain` reads; a subset of {@link RunDecisionOptions}. */
interface ChainOptions {
readonly provider?: DecisionProvider;
readonly modeOverride?: Exclude<DecisionModelMode, "off">;
}
/**
* The chain of attempts for one call, in configured order. An entry the
* factory cannot build (no endpoint, a missing key) is skipped: it is
* not configured, exactly as the resolver's status rules say. An
* injected provider (tests) is the whole chain.
*/
function buildChain(
cfg: ResolvedDecisionModelConfig,
use: DecisionModelUse,
mode: Exclude<DecisionModelMode, "off">,
opts: ChainOptions,
env: Readonly<Record<string, string | undefined>>,
secretsVault: string | null | undefined,
): ReadonlyArray<ChainAttempt> {
if (opts.provider !== undefined) {
const entry = resolvedProviderEntries(cfg)[0];
if (entry === undefined) return [];
return [{ adapter: opts.provider, entry, mode }];
}
const attempts: ChainAttempt[] = [];
for (const [index, entry] of resolvedProviderEntries(cfg).entries()) {
const adapter = makeEntryDecisionProvider(
entry,
{ allowInsecureHttp: cfg.allowInsecureHttp, timeoutMs: cfg.timeoutMs },
env,
secretsVault,
);
if (adapter === null) continue;
// The first entry answers for the config as written: the top-level
// modes are its held modes, and a caller that overrode them (the
// eval gate forces enforce) means it for the primary. A later entry
// is judged by its own thresholds - a fallback model without tuned
// thresholds answers as shadow even when the primary enforces. A
// held mode is never off (off-ness is the global config's decision);
// anything but enforce is shadow.
const held = opts.modeOverride ?? (index === 0 ? cfg.uses[use] : (entry.uses[use] ?? "shadow"));
attempts.push({ adapter, entry, mode: held === "enforce" ? "enforce" : "shadow" });
}
return attempts;
}
/** The degrade reasons that mean "this route could not answer": fall through. */
function isFailoverReason(reason: DecisionDegradeReason): boolean {
return reason === "network" || reason === "timeout";
}
export async function runDecision<C>(
use: DecisionModelUse,
buildState: () => BuiltDecisionState<C>,
questions: (
built: Extract<BuiltDecisionState<C>, { kind: "ok" }>,
) => Readonly<Record<string, DecisionQuestion>>,
opts: RunDecisionOptions<C>,
): Promise<DecisionRunResult<C>> {
const cfg = opts.config;
const configured = decisionModelModeFor(cfg, use);
if (configured === "off" || cfg === null || cfg === undefined) return { status: "off" };
const mode = opts.modeOverride ?? configured;
const env = opts.env ?? process.env;
const budgetMs = opts.timeoutMs ?? cfg.timeoutMs;
// With the floor the budget runs from here, so preparation counts,
// the construction of the provider chain included.
const floorDeadline = opts.requestFloor === true ? Date.now() + budgetMs : null;
const chain = buildChain(cfg, use, mode, opts, env, opts.secretsVault);
if (chain.length === 0 || chain[0] === undefined) return { status: "off" };
const primary = chain[0];
const now = opts.now ?? (() => new Date());
const floorLeft = (): boolean =>
floorDeadline === null || attemptTimeoutMs(floorDeadline - Date.now(), 1) !== null;
if (!floorLeft()) return { status: "degraded", mode, reason: "budget" };
const record = (
attempt: ChainAttempt,
outcome: string,
extra: {
readonly questionCount?: number;
readonly candidateCount?: number;
readonly response?: DecisionResponse;
readonly context?: C;
readonly latencyMs?: number;
} = {},
): void => {
let details: Readonly<Record<string, unknown>> | undefined;
try {
details = opts.recordDetails?.(extra.response ?? null, extra.context ?? null, {
provider: attempt.entry.name,
model: attempt.entry.model,
});
} catch {
details = undefined;
}
emitDecisionModelCall(cfg.vault, {
use,
mode: attempt.mode,
provider: attempt.adapter.name,
model: extra.response?.model ?? attempt.adapter.model,
calibrated: extra.response?.calibrated ?? attempt.adapter.calibrated,
questionCount: extra.questionCount ?? 0,
candidateCount: extra.candidateCount ?? 0,
...(extra.response !== undefined ? { usage: extra.response.usage } : {}),
inputPriceUsdPerMtok: attempt.entry.inputPriceUsdPerMtok,
...(attempt.entry.outputPriceUsdPerMtok !== undefined &&
attempt.entry.outputPriceUsdPerMtok !== null
? { outputPriceUsdPerMtok: attempt.entry.outputPriceUsdPerMtok }
: {}),
latencyMs: extra.latencyMs ?? 0,
outcome,
...(extra.response?.stateHash !== undefined ? { stateHash: extra.response.stateHash } : {}),
...(details !== undefined ? { details } : {}),
...(cfg.recordOrigin !== undefined ? { origin: cfg.recordOrigin } : {}),
createdAt: now().toISOString(),
});
};
// Daily cost gate, before any state is built. A gate of 0 is off. The
// check counts requests still in flight in this process, and the new
// request's estimate is reserved in the same synchronous step (no await
// between the check, the build and the reservation), so concurrent
// requests cannot all pass against the same recorded spend. Separate
// processes still share only the recorded spend, so the gate is a
// soft limit that can be passed by the requests in flight elsewhere.
// The estimate uses the FIRST entry's price; a fallback attempt is
// judged by its own price only in its own record.
const gated = cfg.dailyCostGateUsd > 0 && cfg.vault !== null;
if (gated) {
let spend: number;
try {
spend = todaySpendUsd(cfg.vault!, now()) + inFlightUsd(cfg.vault!);
} catch {
spend = Number.POSITIVE_INFINITY;
}
if (spend >= cfg.dailyCostGateUsd) {
record(primary, "cost_gate");
return { status: "degraded", mode, reason: "cost_gate" };
}
}
let built: BuiltDecisionState<C>;
try {
built = buildState();
} catch {
built = { kind: "budget" };
}
if (built.kind === "empty") return { status: "empty", mode };
if (built.kind === "budget") {
record(primary, "budget");
return { status: "degraded", mode, reason: "budget" };
}
// Preparation may have spent the margin above the floor.
if (!floorLeft()) return { status: "degraded", mode, reason: "budget" };
const ready: Extract<BuiltDecisionState<C>, { kind: "ok" }> = built;
const qs = questions(ready);
const questionCount = Object.keys(qs).length;
const reservation =
gated && cfg.inputPriceUsdPerMtok !== null
? (estimateTokens({ state: ready.state, questions: qs }) * cfg.inputPriceUsdPerMtok) /
1_000_000
: 0;
// The whole chain shares the caller's one budget (`timeout_ms`, or the
// hook sub-budget): each attempt gets an even slice of what remains, so
// a dead first server can never stretch the call past the budget, and
// the last entry always keeps a real slice to answer in. With the
// floor, no slice is below it and the budget began at the call's start.
const send = async (): Promise<DecisionRunResult<C>> => {
const deadline = floorDeadline ?? Date.now() + budgetMs;
let last: {
readonly reason: DecisionDegradeReason;
readonly mode: Exclude<DecisionModelMode, "off">;
} | null = null;
for (const [index, attempt] of chain.entries()) {
const remaining = chain.length - index;
const left = deadline - Date.now();
const slice =
floorDeadline === null
? Math.max(1, Math.floor(left / remaining))
: attemptTimeoutMs(left, remaining);
// No later entry fits either: the call ends with what it has.
if (slice === null) break;
const started = Date.now();
let response: DecisionResponse;
try {
// eslint-disable-next-line no-await-in-loop -- the fallback is sequential by design: an attempt must settle before the next starts
response = await attempt.adapter.decide(
{ use, state: ready.state, questions: qs },
{
timeoutMs: slice,
...(opts.signal !== undefined ? { signal: opts.signal } : {}),
},
);
} catch (e) {
const latencyMs = Date.now() - started;
noteDecisionLatency(latencyMs);
const reason: DecisionDegradeReason =
e instanceof DecisionProviderError ? e.reason : "network";
record(attempt, reason, {
questionCount,
candidateCount: ready.candidateCount,
context: ready.context,
latencyMs,
});
// Only a route that could not answer falls through; an HTTP or
// reply-shape failure is the endpoint's answer about THIS
// request, and retrying it elsewhere would multiply the same
// refusal.
if (!isFailoverReason(reason)) {
return { status: "degraded", mode: attempt.mode, reason };
}
last = { reason, mode: attempt.mode };
continue;
}
const latencyMs = Date.now() - started;
noteDecisionLatency(latencyMs);
record(attempt, "ok", {
questionCount,
candidateCount: ready.candidateCount,
response,
context: ready.context,
latencyMs,
});
return {
status: "ok",
mode: attempt.mode,
response,
context: ready.context,
latencyMs,
answeredBy: { provider: attempt.entry.name, model: attempt.entry.model },
};
}
return {
status: "degraded",
mode: last?.mode ?? mode,
// No attempt fitted the floor: a budget skip.
reason: last?.reason ?? (floorDeadline === null ? "network" : "budget"),
};
};
const release = reserveInFlight(gated ? cfg.vault : null, reservation);
try {
return await send();
} finally {
release();
}
}