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
/**
* Operator summary composer (v0.10.16).
*
* One read-only call that aggregates the three independent brain
* surfaces - doctor, dream, vault metadata - into a unified envelope:
*
* - `trust_verdict` - `clean | watch | investigate`
* - `digest_summary` - preference status counts
* - `doctor_summary` - warning / error counts
* - `dream_summary` - warning / uncertain / quarantined counts
* - `verification_delta` - confirmed / drift / regression / missing
* - `top_actions` - ranked maintenance action list
* - `instruction_file_warnings`- ceiling breaches at vault root
*
* The composer never mutates the vault. It accepts a precomputed
* dream summary so callers can choose between "run dream first" and
* "skip dream entirely"; verification delta falls back to all-zero
* counts when no dream is supplied.
*/
import { existsSync, readdirSync, statSync } from "node:fs";
import { join, relative } from "node:path";
import { toPosix } from "../../path-safety.ts";
import { memoryFromStore, storePagesIn } from "../memory-pages.ts";
import { runDoctor, type RunDoctorResult } from "../doctor.ts";
import type { DreamRunSummary } from "../dream.ts";
import {
closedCollectError,
collectMaintenanceActions,
type MaintenanceCollectSignal,
} from "../maintenance/collect.ts";
import type { ActionItem } from "../maintenance/action-scorer.ts";
import type { DoctorIssueNaming } from "../diagnostics.ts";
import { brainDirs } from "../paths.ts";
import { BRAIN_GUARDRAIL_DEFAULTS } from "../policy.ts";
import type {
DoctorIssue,
InstructionFileCeilingWarning,
ResolvedBrainGuardrailConfig,
TrustVerdict,
} from "../types.ts";
import {
computeVerificationDelta,
type VerificationDeltaEntry,
type VerificationDeltaResult,
} from "./compute-verification-delta.ts";
import { computeTrustVerdict } from "./compute-trust-verdict.ts";
import { checkInstructionFileCeiling } from "./instruction-file-ceiling.ts";
export interface OperatorSummary {
readonly trust_verdict: TrustVerdict;
readonly digest_summary: DigestSummary;
readonly doctor_summary: DoctorSummary;
readonly dream_summary: DreamSummary;
readonly verification_delta: VerificationDeltaResult;
readonly top_actions: ReadonlyArray<ActionItem>;
readonly instruction_file_warnings: ReadonlyArray<InstructionFileCeilingWarning>;
/**
* The maintenance scans that refused while the actions were collected
* (review M10), rendered as `{scan, message}` rows - the same shape the
* digest and doctor rows carry. A thin `top_actions` list must be
* readable as healthy rather than indistinguishable from a scan that
* failed. Present only when at least one scan refused.
*/
readonly collect_errors?: ReadonlyArray<{
readonly scan: MaintenanceCollectSignal;
readonly message: string;
}>;
}
export interface DigestSummary {
readonly preference_count: number;
readonly retired_count: number;
readonly inbox_count: number;
}
export interface DoctorSummary {
readonly warning_count: number;
readonly error_count: number;
readonly warnings: ReadonlyArray<DoctorIssue>;
readonly errors: ReadonlyArray<DoctorIssue>;
}
export interface DreamSummary {
readonly warning_count: number;
readonly uncertain_count: number;
readonly quarantined_count: number;
}
export interface BuildOperatorSummaryOptions {
/**
* Recent dream-pass summary. Verification delta is computed
* against this; when omitted, all verification counts default to
* zero.
*/
readonly dreamSummary?: DreamRunSummary;
/**
* Resolved guardrail config. Drives the instruction-file ceiling
* check. Defaults to `BRAIN_GUARDRAIL_DEFAULTS`.
*/
readonly guardrails?: ResolvedBrainGuardrailConfig;
/** Top-N cap on the maintenance action list. */
readonly topActionsN?: number;
/**
* Whether the caller may see a doctor finding. The doctor counts and
* the trust verdict are taken over the findings it keeps. Omitted,
* every finding counts (the operator's own shell).
*/
readonly keepIssue?: (issue: DoctorIssueNaming) => boolean;
/**
* Whether the caller may read a vault-relative path. The digest counts
* only the records it may read, and the doctor pass counts its capped
* and pre-filter totals over them. Omitted, every record counts.
*/
readonly readable?: (rel: string) => boolean;
/**
* Whether the caller may see a maintenance action. Applied before the
* top-N slice, so a withheld action takes no slot. Omitted, every
* action is ranked.
*/
readonly keepAction?: (action: ActionItem) => boolean;
/**
* Whether the caller may see an artifact reference - a page id, a
* vault-relative path, or a wikilink-spelled one. Threaded into the
* maintenance collector so it applies to the candidate inputs BEFORE
* the scorer caps: a hidden top-ranked action takes no slot a visible
* one could fill, and a dedup count excludes hidden secondaries.
* Omitted, every candidate is ranked. `keepAction` stays as the
* per-row filter beside it.
*/
readonly visibleRef?: (ref: string | null | undefined) => boolean;
/**
* Whether the caller may see a verification-delta entry. The entries
* and their summary counts - and the trust verdict over them - are
* taken over the entries it keeps. Omitted, every entry counts.
*/
readonly keepVerification?: (entry: VerificationDeltaEntry) => boolean;
/**
* The caller is below local reach: the maintenance actions and the
* doctor pass leave out the log events of the store's `private`
* partition (the token footprint's log bucket, the broken-backlink
* check). Default false.
*/
readonly withholdsPrivate?: boolean;
}
const DEFAULT_TOP_ACTIONS_N = 5;
export function buildOperatorSummary(
vault: string,
opts: BuildOperatorSummaryOptions,
): OperatorSummary {
const guardrails = opts.guardrails ?? BRAIN_GUARDRAIL_DEFAULTS;
const dreamSummary = opts.dreamSummary;
const doctorResult = keptDoctorResult(
safeDoctor(vault, guardrails, dreamSummary, opts.readable, opts.withholdsPrivate === true),
opts.keepIssue,
);
const dreamCounts = summariseDream(dreamSummary);
const digestCounts = collectDigestCounts(vault, opts.readable);
const verification = dreamSummary
? keptVerification(computeVerificationDelta(vault, dreamSummary), opts.keepVerification)
: zeroVerification();
const instructionWarnings = checkInstructionFileCeiling(vault, {
maxLines: guardrails.instruction_file_max_lines,
...(opts.readable !== undefined ? { readable: opts.readable } : {}),
});
const collectErrors: { scan: MaintenanceCollectSignal; message: string }[] = [];
const topActions = safeTopActions(
vault,
opts.topActionsN ?? DEFAULT_TOP_ACTIONS_N,
opts.keepAction,
collectErrors,
opts.readable !== undefined,
opts.visibleRef,
opts.withholdsPrivate === true,
);
const trust = computeTrustVerdict({
doctorWarnings: doctorResult.warnings,
doctorErrors: doctorResult.errors,
dreamWarnings: dreamSummary?.warnings ?? [],
verification: verification.summary,
});
return Object.freeze({
trust_verdict: trust,
digest_summary: digestCounts,
doctor_summary: Object.freeze({
warning_count: doctorResult.warnings.length,
error_count: doctorResult.errors.length,
warnings: doctorResult.warnings,
errors: doctorResult.errors,
}),
dream_summary: dreamCounts,
verification_delta: verification,
top_actions: topActions,
instruction_file_warnings: instructionWarnings,
...(collectErrors.length > 0 ? { collect_errors: Object.freeze(collectErrors) } : {}),
});
}
/**
* Markdown rendering of the operator summary. Sections mirror the
* JSON envelope; no headings for sections that are entirely empty.
*/
export function renderOperatorSummaryMarkdown(summary: OperatorSummary): string {
const out: string[] = [];
out.push("# Operator summary");
out.push("");
out.push(`Trust: **${summary.trust_verdict}**`);
out.push("");
out.push(
`Doctor: ${summary.doctor_summary.warning_count} warning(s), ${summary.doctor_summary.error_count} error(s)`,
);
out.push(
`Dream: ${summary.dream_summary.warning_count} warning(s), ${summary.dream_summary.uncertain_count} uncertain, ${summary.dream_summary.quarantined_count} quarantined`,
);
out.push(
`Verification: ${summary.verification_delta.summary.confirmed} confirmed, ${summary.verification_delta.summary.drift} drift, ${summary.verification_delta.summary.regression} regression, ${summary.verification_delta.summary.missing_evidence} missing_evidence`,
);
out.push("");
out.push(
`Vault: ${summary.digest_summary.preference_count} preferences, ${summary.digest_summary.retired_count} retired, ${summary.digest_summary.inbox_count} inbox`,
);
if (summary.instruction_file_warnings.length > 0) {
out.push("");
out.push("## Instruction file warnings");
out.push("");
for (const w of summary.instruction_file_warnings) {
out.push(`- \`${w.path}\` - ${w.lines} lines (ceiling ${w.ceiling})`);
}
}
if (summary.top_actions.length > 0) {
out.push("");
out.push("## Top actions");
out.push("");
for (const a of summary.top_actions) {
out.push(`- ${a.category}: ${a.title}`);
}
}
if (summary.collect_errors !== undefined && summary.collect_errors.length > 0) {
out.push("");
out.push("## Collection errors");
out.push("");
for (const e of summary.collect_errors) {
out.push(`- ${e.scan}: ${e.message}`);
}
}
out.push("");
return out.join("\n");
}
// ----- Internals -----------------------------------------------------------
function safeDoctor(
vault: string,
guardrails: ResolvedBrainGuardrailConfig,
dreamSummary: DreamRunSummary | undefined,
readable: BuildOperatorSummaryOptions["readable"],
withholdsPrivate: boolean,
): RunDoctorResult {
try {
return runDoctor(vault, {
guardrails,
...(dreamSummary ? { dreamSummary } : {}),
...(readable !== undefined ? { readable } : {}),
...(withholdsPrivate ? { withholdsPrivate: true } : {}),
});
} catch {
return Object.freeze({ warnings: [], errors: [] });
}
}
/** The doctor's warnings and errors the caller may see. */
function keptDoctorResult(
result: RunDoctorResult,
keepIssue: BuildOperatorSummaryOptions["keepIssue"],
): RunDoctorResult {
if (keepIssue === undefined) return result;
return Object.freeze({
...result,
warnings: Object.freeze(result.warnings.filter(keepIssue)),
errors: Object.freeze(result.errors.filter(keepIssue)),
});
}
/** The verification entries the caller may see, with the counts taken over them. */
function keptVerification(
result: VerificationDeltaResult,
keep: BuildOperatorSummaryOptions["keepVerification"],
): VerificationDeltaResult {
if (keep === undefined) return result;
const entries = result.entries.filter(keep);
const count = (state: VerificationDeltaEntry["state"]): number =>
entries.filter((entry) => entry.state === state).length;
return Object.freeze({
entries: Object.freeze(entries),
summary: Object.freeze({
confirmed: count("confirmed"),
drift: count("drift"),
regression: count("regression"),
missing_evidence: count("missing_evidence"),
}),
});
}
function summariseDream(dream: DreamRunSummary | undefined): DreamSummary {
if (dream === undefined) {
return Object.freeze({
warning_count: 0,
uncertain_count: 0,
quarantined_count: 0,
});
}
return Object.freeze({
warning_count: dream.warnings.length,
uncertain_count: dream.uncertain.length,
quarantined_count: dream.quarantined.length,
});
}
function collectDigestCounts(
vault: string,
readable: BuildOperatorSummaryOptions["readable"],
): DigestSummary {
const dirs = brainDirs(vault);
return Object.freeze({
preference_count: countMarkdownFiles(vault, dirs.preferences, readable),
retired_count: countMarkdownFiles(vault, dirs.retired, readable),
inbox_count: countMarkdownFiles(vault, dirs.inbox, readable),
});
}
function countMarkdownFiles(
vault: string,
dir: string,
readable: BuildOperatorSummaryOptions["readable"],
): number {
if (memoryFromStore(vault)) {
// Store-only (task 2.10): the fold's records whose page sat in `dir`.
// Best effort like the folder count below: a fold that cannot be built
// counts 0 rather than failing the whole summary.
try {
return storePagesIn(vault, dir).filter((p) => readable === undefined || readable(p.rel))
.length;
} catch {
return 0;
}
}
if (!existsSync(dir)) return 0;
try {
let n = 0;
for (const name of readdirSync(dir)) {
if (!name.endsWith(".md")) continue;
if (readable !== undefined && !readable(toPosix(relative(vault, join(dir, name))))) {
continue;
}
try {
const s = statSync(join(dir, name));
if (s.isFile()) n += 1;
} catch {
// Race: skip
}
}
return n;
} catch {
return 0;
}
}
function safeTopActions(
vault: string,
topN: number,
keepAction: BuildOperatorSummaryOptions["keepAction"],
collectErrors: { scan: MaintenanceCollectSignal; message: string }[],
restricted: boolean,
visibleRef?: BuildOperatorSummaryOptions["visibleRef"],
withholdsPrivate = false,
): ReadonlyArray<ActionItem> {
try {
const all = collectMaintenanceActions(vault, {
// Below local reach the raised message (which can carry a host
// path) is replaced by the closed scan-and-code form.
onError: (e) => {
const shown = restricted ? closedCollectError(e) : e;
collectErrors.push({ scan: shown.signal, message: shown.message });
},
// Candidate-level visibility, before the scorer caps: the same
// predicate brain_doctor's suggested_actions and the digest's
// actions ask, so the sinks cannot disagree about what a scoped
// caller is shown.
...(visibleRef !== undefined ? { visible: visibleRef } : {}),
withholdsPrivate,
});
const kept = keepAction === undefined ? all : all.filter(keepAction);
return Object.freeze(kept.slice(0, Math.max(0, topN)));
} catch {
return Object.freeze([]);
}
}
function zeroVerification(): VerificationDeltaResult {
return Object.freeze({
entries: Object.freeze([]),
summary: Object.freeze({
confirmed: 0,
drift: 0,
regression: 0,
missing_evidence: 0,
}),
});
}