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 `head_select` decision use (task 4.2, design D10): one `noul`
* question per candidate head, the state `{ project, branch, topics }`.
* The deterministic fallback is the recency and scope ranking the hook
* glue computed; `enforce` reorders the heads by p(yes) descending (the
* fallback order on ties) and leaves the heads below `drop_below` out
* (counted in the digest's cut line). Never adds a head outside the
* candidate set. No store record: recorded in `decision_model_call`
* only.
*
* Budget: `min(cfg.hookBudgetMs, remaining hook budget)`, enforced
* again around the call, as `recall-inject-decision.ts` does.
*/
import { decisionModelModeFor } from "../decision-model/config.ts";
import type { ResolvedDecisionModelConfig } from "../decision-model/config-types.ts";
import type { DecisionProvider, DecisionNoulQuestion } from "../decision-model/contract.ts";
import {
HEAD_SELECT_QUESTIONS,
TOPIC_DECISION_LIMITS,
} from "../decision-model/questions-topics.ts";
import { mayStartRequest } from "../decision-model/request-floor.ts";
import { runDecision } from "../decision-model/run.ts";
import { appliedThreshold } from "../decision-model/use-thresholds.ts";
import { buildCandidateState, type StateCandidate } from "../decision-model/state.ts";
import { REMOTE_DENY_VISIBILITY_TOKEN } from "../graph/visibility.ts";
import { privateRegionTexts } from "../redactor.ts";
import type { TopicState } from "../topics/fold.ts";
import { mayShareRecord, shareableHeadFields } from "../decision-model/egress-guard.ts";
export interface HeadSelectRequest {
/** The session's project key (the scoped-rule key), or null without a project. */
readonly project: string | null;
/** The workspace's branch from `.git/HEAD`, or null. */
readonly branch: string | null;
}
export interface HeadSelectOutcome {
/** The candidate heads, reordered or filtered (enforce) or as given (fallback). */
readonly heads: ReadonlyArray<TopicState>;
/** How many heads the use left out below `drop_below` (enforce only). */
readonly droppedBelow: number;
/** Whether the model answered (enforce applied). */
readonly applied: boolean;
}
/** The state candidate of one head, guarded like every other use's. */
function headCandidate(
cfg: ResolvedDecisionModelConfig,
use: "head_select",
topic: TopicState,
): StateCandidate {
// A private field of a shared topic stays home unless private records may leave.
const head = shareableHeadFields(cfg, use, topic);
const text = [head.title, head.description, head.goal].filter((v) => v !== "").join(" - ");
return {
text,
visibility: mayShareRecord(cfg, use, topic.private) ? [] : [REMOTE_DENY_VISIBILITY_TOKEN],
privateRegions: privateRegionTexts(text),
};
}
/**
* The heads one request carries, in order: up to `headsPerRequest` heads
* the egress rule lets leave, with the withheld heads among them riding
* along (recorded as withheld, never sent), so a run of private heads
* never keeps a shared one from being asked.
*/
function cappedHeads(
cfg: ResolvedDecisionModelConfig,
use: "head_select",
heads: ReadonlyArray<TopicState>,
): TopicState[] {
const out: TopicState[] = [];
let shareable = 0;
for (const topic of heads) {
if (shareable >= TOPIC_DECISION_LIMITS.headsPerRequest) break;
out.push(topic);
if (mayShareRecord(cfg, use, topic.private)) shareable += 1;
}
return out;
}
/**
* Ask the model which heads matter for this session. Returns the
* fallback order unless `head_select` answered in `enforce`.
*/
export async function runHeadSelect(input: {
readonly config: ResolvedDecisionModelConfig | null | undefined;
readonly heads: ReadonlyArray<TopicState>;
readonly request: HeadSelectRequest;
/** The remaining hook budget in ms; the request gets the smaller of it and `hookBudgetMs`. */
readonly remainingMs: number;
readonly provider?: DecisionProvider;
readonly env?: Readonly<Record<string, string | undefined>>;
/** Clip of one head field in the state (default `headFieldClipChars`). */
readonly clipChars?: number;
}): Promise<HeadSelectOutcome> {
const use = "head_select" as const;
const cfg = input.config;
const mode = decisionModelModeFor(cfg, use);
const fallback: HeadSelectOutcome = { heads: input.heads, droppedBelow: 0, applied: false };
if (mode === "off" || cfg === null || cfg === undefined) return fallback;
if (input.heads.length === 0) return fallback;
const budgetMs = Math.max(0, Math.min(cfg.hookBudgetMs, input.remainingMs));
// No request starts with less than the minimum request time left.
if (budgetMs <= 0 || !mayStartRequest(0, input.remainingMs, cfg.hookBudgetMs)) return fallback;
const heads = cappedHeads(cfg, use, input.heads);
const clipChars = input.clipChars ?? TOPIC_DECISION_LIMITS.headFieldClipChars;
const request = runDecision<{ map: Map<number, TopicState> }>(
use,
() => {
const built = buildCandidateState({
candidates: heads.map((topic) => headCandidate(cfg, use, topic)),
prefix: HEAD_SELECT_QUESTIONS.headPrefix,
clipChars,
maxStateTokens: cfg.maxStateTokens,
frame: (texts) => ({
project: input.request.project ?? "",
branch: input.request.branch ?? "",
topics: texts,
}),
});
if (built.kind !== "ok") return { kind: "empty" as const };
const context = { map: new Map<number, TopicState>() };
built.included.forEach((candidateIndex, k) => context.map.set(k, heads[candidateIndex]!));
return {
kind: "ok" as const,
state: built.state,
candidateCount: built.included.length,
context,
};
},
(built): Record<string, DecisionNoulQuestion> => {
// One question per mask in the state: a withheld head has none.
const questions: Record<string, DecisionNoulQuestion> = {};
for (let k = 0; k < built.candidateCount; k++) {
questions[HEAD_SELECT_QUESTIONS.relevantId(k)] = HEAD_SELECT_QUESTIONS.relevant(k);
}
return questions;
},
{
config: cfg,
timeoutMs: budgetMs,
// The floor holds for each attempt of the chain, not only here.
requestFloor: true,
...(input.provider !== undefined ? { provider: input.provider } : {}),
...(input.env !== undefined ? { env: input.env } : {}),
recordDetails: (response, context) => {
const details: Record<string, unknown> = {
topic_ids: heads.map((t) => (mayShareRecord(cfg, use, t.private) ? t.id : "(withheld)")),
};
if (response !== null && context !== null) {
// Aligned with `topic_ids`: null for a head that was not asked.
const probabilities: Array<number | null> = heads.map(() => null);
for (const [k, topic] of context.map) {
const a = response.answers[HEAD_SELECT_QUESTIONS.relevantId(k)];
probabilities[heads.indexOf(topic)] =
a !== undefined && a.valid === true && typeof a.value === "number" ? a.value : null;
}
details["probabilities"] = probabilities;
}
return details;
},
},
);
// A provider that outlives its own timeout must not hold the hook.
let timer: ReturnType<typeof setTimeout> | undefined;
const cutoff = new Promise<"cutoff">((resolve) => {
timer = setTimeout(() => resolve("cutoff"), budgetMs);
});
let result: Awaited<typeof request> | "cutoff";
try {
result = await Promise.race([request, cutoff]);
} finally {
if (timer !== undefined) clearTimeout(timer);
}
if (result === "cutoff") return fallback;
if (result.status !== "ok" || result.mode !== "enforce") return fallback;
// A shadow answer is recorded by runDecision and has no effect.
const dropBelow = appliedThreshold(cfg, use, result.answeredBy.model, "drop_below");
const scored: Array<{ topic: TopicState; p: number }> = [];
const excluded = new Set<string>();
let droppedBelow = 0;
for (const [k, topic] of result.context.map) {
const a = result.response.answers[HEAD_SELECT_QUESTIONS.relevantId(k)];
const p = a !== undefined && a.valid === true && typeof a.value === "number" ? a.value : null;
// No valid answer: the model did not judge the head, which keeps
// its fallback place in the tail below.
if (p === null) continue;
if (p < dropBelow) {
droppedBelow += 1;
excluded.add(topic.id);
continue;
}
scored.push({ topic, p });
}
scored.sort(
(a, b) =>
b.p - a.p ||
b.topic.updatedAt - a.topic.updatedAt ||
(a.topic.id < b.topic.id ? -1 : a.topic.id > b.topic.id ? 1 : 0),
);
const applied = new Set(scored.map((s) => s.topic.id));
// The heads the model never judged (invalid answers) keep their
// fallback order after the scored ones; the excluded ones stay out.
const tail = input.heads.filter((t) => !applied.has(t.id) && !excluded.has(t.id));
return { heads: [...scored.map((s) => s.topic), ...tail], droppedBelow, applied: true };
}