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
/**
* Decision-model filter for the recall-inject hook (issue #213, Part 9).
*
* Runs only when {@link decideRecallInject} would inject: abstentions and
* errors never reach it, so they stay free. One request per prompt: the
* state is the (clipped) prompt plus the notes the brief carries, masked
* as `N0..Nn`; the questions are one `helps_<k>` noul per note and one
* `inject_any` noul over all of them. Question texts and thresholds live
* in `decision-model/questions.ts`.
*
* Modes come from `decision_model_uses` `recall_inject`:
* - `off`, or any configuration that is not active: no filter is built
* at all ({@link createRecallInjectDecisionFilter} returns null), so
* the hook behaves exactly as without the feature;
* - `shadow`: the request is sent and recorded, today's brief goes out;
* - `enforce`: the core drops notes or withholds the brief, never adds.
*
* Budget: `min(decision_model_hook_budget_ms, remaining retrieval budget)`,
* passed to {@link runDecision} as `timeoutMs` and enforced here as well,
* so a provider that ignores its timeout still cannot hold the hook.
*
* Privacy: a note leaves the machine only when it is a page of the active
* vault whose visibility resolves without the reserved `private` token and
* whose text carries no part of a `<private>` region (the shared state
* builder). Notes from other origins are never sent. The prompt has its
* `<private>` regions stripped and is clipped; the adapter redacts the
* whole body. The record carries note paths (withheld ones masked) and
* probabilities, never the prompt or note text.
*/
import { readFileSync } from "node:fs";
import { join } from "node:path";
import { decisionModelModeFor } from "../decision-model/config.ts";
import type { ResolvedDecisionModelConfig } from "../decision-model/config.ts";
import type { DecisionProvider, DecisionResponse } from "../decision-model/contract.ts";
import { RECALL_INJECT_QUESTIONS } from "../decision-model/questions.ts";
import { runDecision } from "../decision-model/run.ts";
import { buildCandidateState, mayLeaveMachine } from "../decision-model/state.ts";
import { remoteDenyVisibilityTokens } from "../graph/privacy-markers.ts";
import { privateRegionTexts, stripPrivateRegions } from "../redactor.ts";
import { readCachedFrontmatterEntry, type FrontmatterCache } from "../search/result-filters.ts";
import { LOCAL_ORIGIN } from "./portability/origins.ts";
import {
recallInjectFilterOutcome,
type RecallCandidate,
type RecallInjectFilter,
type RecallInjectFilterMode,
type RecallInjectFilterVerdict,
} from "./recall-inject.ts";
/** Stands in for a note that may not be named in a synced record. */
const WITHHELD_PATH = "(withheld)";
export interface RecallInjectDecisionFilterOptions {
readonly config: ResolvedDecisionModelConfig | null | undefined;
/** The active vault; notes are resolved against it. */
readonly vault: string;
/** Injected provider (tests). */
readonly provider?: DecisionProvider;
readonly env?: Readonly<Record<string, string | undefined>>;
/**
* Resolves a note's visibility tokens and `<private>` regions. Defaults
* to reading the page from the active vault; null when it cannot be
* read (the note is then not sent).
*/
readonly resolvePage?: (note: RecallCandidate) => {
readonly visibility: ReadonlyArray<string> | null;
readonly privateRegions: ReadonlyArray<string> | null;
};
}
interface FilterContext {
/** `included[k]` is the brief index of mask `N<k>`. */
readonly included: ReadonlyArray<number>;
readonly withheld: number;
readonly dropped: number;
}
function clipChars(text: string, max: number): string {
const chars = [...text];
return chars.length <= max ? text : chars.slice(0, max).join("");
}
function isActiveVaultNote(note: RecallCandidate): boolean {
return note.origin === undefined || note.origin === LOCAL_ORIGIN;
}
function defaultResolvePage(
vault: string,
): NonNullable<RecallInjectDecisionFilterOptions["resolvePage"]> {
const cache: FrontmatterCache = new Map();
return (note) => {
if (!isActiveVaultNote(note)) return { visibility: null, privateRegions: null };
const entry = readCachedFrontmatterEntry(cache, vault, note.path);
// The tokens fold in an informal privacy marker's reservation
// (graph/privacy-markers.ts): a marker-only note resolves to no
// caller-scope token at all, and without the fold `mayLeaveMachine`
// would read it as public and send it.
const visibility = entry.unreadable ? null : remoteDenyVisibilityTokens(entry.meta);
if (!mayLeaveMachine(visibility)) return { visibility, privateRegions: null };
let privateRegions: ReadonlyArray<string> | null;
try {
privateRegions = privateRegionTexts(readFileSync(join(vault, note.path), "utf8"));
} catch {
privateRegions = null;
}
return { visibility, privateRegions };
};
}
/**
* The filter for this configuration, or null when the `recall_inject` use
* is `off` (the default) or the feature is not active: then nothing is
* built, sent or recorded.
*/
export function createRecallInjectDecisionFilter(
opts: RecallInjectDecisionFilterOptions,
): RecallInjectFilter | null {
const cfg = opts.config;
const configured = decisionModelModeFor(cfg, "recall_inject");
if (configured === "off" || cfg === null || cfg === undefined) return null;
const mode: RecallInjectFilterMode = configured;
const resolvePage = opts.resolvePage ?? defaultResolvePage(opts.vault);
return {
mode,
async run(input): Promise<RecallInjectFilterVerdict> {
const notes = input.notes;
const n = notes.length;
const budgetMs = Math.max(0, Math.min(cfg.hookBudgetMs, input.remainingMs));
if (budgetMs <= 0) return { status: "degraded", mode, reason: "timeout", latencyMs: 0 };
const pages = notes.map((note) =>
note.content === undefined ? { visibility: null, privateRegions: null } : resolvePage(note),
);
const prompt = clipChars(
stripPrivateRegions(input.query),
RECALL_INJECT_QUESTIONS.promptClipChars,
);
const answersFor = (
response: DecisionResponse,
context: FilterContext,
): { helps: (number | null)[]; sent: boolean[]; injectAny: number | null } => {
const helps: (number | null)[] = Array.from({ length: n }, () => null);
const sent: boolean[] = Array.from({ length: n }, () => false);
context.included.forEach((briefIndex, k) => {
sent[briefIndex] = true;
const a = response.answers[RECALL_INJECT_QUESTIONS.helpsId(k)];
if (a?.valid === true && typeof a.value === "number") helps[briefIndex] = a.value;
});
const any = response.answers[RECALL_INJECT_QUESTIONS.injectAnyId];
const injectAny = any?.valid === true && typeof any.value === "number" ? any.value : null;
return { helps, sent, injectAny };
};
const started = Date.now();
const request = runDecision<FilterContext>(
"recall_inject",
() => {
const built = buildCandidateState({
candidates: notes.map((note, i) => ({
text: note.content ?? "",
visibility: pages[i]!.visibility,
privateRegions: pages[i]!.privateRegions,
})),
prefix: RECALL_INJECT_QUESTIONS.prefix,
clipChars: RECALL_INJECT_QUESTIONS.clipChars,
maxStateTokens: cfg.maxStateTokens,
frame: (texts) => ({ prompt, notes: texts }),
});
if (built.kind !== "ok") return built;
return {
kind: "ok",
state: built.state,
candidateCount: built.included.length,
context: {
included: built.included,
withheld: built.withheld.length,
dropped: built.dropped.length,
},
};
},
(built) => {
const questions: Record<string, ReturnType<typeof RECALL_INJECT_QUESTIONS.helps>> = {};
for (let k = 0; k < built.context.included.length; k++) {
questions[RECALL_INJECT_QUESTIONS.helpsId(k)] = RECALL_INJECT_QUESTIONS.helps(k);
}
questions[RECALL_INJECT_QUESTIONS.injectAnyId] = RECALL_INJECT_QUESTIONS.injectAny();
return questions;
},
{
config: cfg,
timeoutMs: budgetMs,
secretsVault: opts.vault,
...(opts.provider !== undefined ? { provider: opts.provider } : {}),
...(opts.env !== undefined ? { env: opts.env } : {}),
recordDetails: (response, context) => {
// Paths of notes that may leave the machine, the rest masked:
// continuity records sync and can be read raw.
const details: Record<string, unknown> = {
note_paths: notes.map((note, i) =>
isActiveVaultNote(note) && mayLeaveMachine(pages[i]!.visibility)
? note.path
: WITHHELD_PATH,
),
budget_ms: budgetMs,
};
if (response === null || context === null) return details;
const { helps, sent, injectAny } = answersFor(response, context);
const { abstain, keep } = recallInjectFilterOutcome(helps, sent, injectAny);
details["helps"] = helps;
details["inject_any"] = injectAny;
details["abstained"] = abstain;
details["notes_dropped"] = abstain ? n : keep.filter((k) => !k).length;
details["withheld_count"] = context.withheld;
details["budget_dropped_count"] = context.dropped;
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);
}
const latencyMs = Date.now() - started;
if (result === "cutoff") return { status: "degraded", mode, reason: "timeout", latencyMs };
if (result.status === "off") return { status: "off" };
if (result.status === "empty") return { status: "not_sent", mode };
if (result.status === "degraded") {
return { status: "degraded", mode, reason: result.reason, latencyMs };
}
const { helps, sent, injectAny } = answersFor(result.response, result.context);
return { status: "ok", mode, latencyMs: result.latencyMs, helps, sent, injectAny };
},
};
}