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
/**
* Hygiene surface: scan / apply / refresh / archive_get over the findings
* pipeline (continuity-hygiene-freshness suite; kanban t_698db8f7,
* t_da3f138f, t_db375a60, t_d9624ef6, t_fe490119; archive_get from the
* answer-trust wave).
*
* One tool, four modes:
* - `scan` (default): read-only digest of detector findings, with
* resolver verdicts attached when the operator configured
* `hygiene.resolver_cmd` in `_brain.yaml`;
* - `apply`: execute an explicit plan selected by finding ids -
* ids are REQUIRED, a bare apply never runs everything blindly;
* - `refresh`: the targeted-recompile path for stale derived pages
* (`dry_run` previews with zero writes);
* - `archive_get`: resolve an ingest summary's `source_archive_hash` to
* the archived (redacted) source bytes. LOCAL reach only - a remote
* caller gets the answer an absent entry gives, never the bytes, so
* the archive can never make a withheld source more reachable than
* the digest that names it.
*
* The resolver command comes exclusively from operator config - it is
* never accepted as a tool argument, so an MCP caller cannot make this
* server execute an arbitrary command.
*/
import { isAbsolute } from "node:path";
import { resolveAgentName } from "../../core/config.ts";
import { loadBrainConfig } from "../../core/brain/policy.ts";
import { gatedOwnerScopeView } from "../../core/brain/owner-scope-view.ts";
import { everyArtifactRefView } from "../../core/brain/artifact-ref-view.ts";
import { reachView } from "../../core/brain/reach-view.ts";
import { contextReach } from "../tool-contract.ts";
import { TRANSPORT_REACH } from "../../core/graph/transport-reach.ts";
import { applyHygienePlan } from "../../core/brain/hygiene/apply.ts";
import { annotateDedupFindings } from "../../core/brain/hygiene/dedup-verdicts.ts";
import { verdictFields } from "../../core/decision-model/pair-verdict.ts";
import { buildHygienePlan } from "../../core/brain/hygiene/plan.ts";
import { resolveConflictFindings } from "../../core/brain/hygiene/resolve-conflicts.ts";
import { runHygieneScan } from "../../core/brain/hygiene/scan.ts";
import {
DEFAULT_SCAN_IDS,
HYGIENE_DETECTOR_IDS,
isHygieneDetectorId,
type HygieneDetectorId,
type HygieneFinding,
type HygieneScanReport,
} from "../../core/brain/hygiene/types.ts";
import { executeRecompile, planRecompile } from "../../core/brain/recompile.ts";
import { resolveSearchConfig } from "../../core/search/index.ts";
import {
ARCHIVE_VERIFICATION,
isArchiveHash,
readSourceArchiveEntry,
sourceArchiveCitingPages,
} from "../../core/brain/provenance/source-archive.ts";
import {
DANGLING_LINK_DEFINITION,
measureFromIndex,
type LinkRatchetMeasurement,
type LinkRatchetUnmeasurableReason,
} from "../../core/search/link-ratchet.ts";
import { coerceBool, coerceStr } from "../coerce.ts";
import { redactErrorForCaller } from "../error-redaction.ts";
import { INVALID_PARAMS, MCPError } from "../protocol.ts";
import { MCP_PREVIEW_BUDGET } from "../preview-budget.ts";
import type { ServerContext, ToolDefinition } from "../tool-contract.ts";
import { enforceCountGuard, readCountGuardArgs, vaultRelativeSafe } from "./shared.ts";
import { toolPath } from "./device-path.ts";
import { readableAtContextReach, readableAtContextReachOrUndefined } from "./reach-readable.ts";
/**
* The prose of one error row in a scan, refresh or apply payload, stated
* for the caller's reach. These rows ride the SUCCESS channel, which the
* server's redactor never sees - it wraps thrown errors only - and a
* detector or executor failure forwards Node's fs text, which names
* absolute host paths, verbatim. Below local reach the same substitution
* a throw gets at this reach is applied here, so one class of text
* cannot be redacted on one channel and ride raw on the other; at local
* reach the row is unchanged, as a throw's is.
*/
function errorRowForCaller<E extends { readonly message: string }>(ctx: ServerContext, row: E): E {
const reach = contextReach(ctx);
if (reach === TRANSPORT_REACH.local) return row;
return { ...row, message: redactErrorForCaller(row.message, ctx.vault, reach) };
}
function coerceStringArray(args: Record<string, unknown>, key: string): string[] | undefined {
const raw = args[key];
if (raw === undefined) return undefined;
if (!Array.isArray(raw) || !raw.every((value) => typeof value === "string")) {
throw new MCPError(INVALID_PARAMS, `'${key}' must be an array of strings`);
}
return raw;
}
function resolverCmdFromConfig(vault: string): string | undefined {
try {
return loadBrainConfig(vault).hygiene?.resolver_cmd;
} catch {
return undefined; // a broken config never blocks a read-only scan
}
}
function scanWithResolver(
ctx: ServerContext,
detectors: HygieneDetectorId[] | undefined,
now: Date,
): HygieneScanReport {
const vault = ctx.vault;
const report = runHygieneScan(vault, {
...(detectors !== undefined && detectors.length > 0 ? { detectors } : {}),
now,
// A cited page the caller may not read at its reach answers as an absent one.
readable: readableAtContextReach(ctx),
});
const resolverCmd = resolverCmdFromConfig(vault);
if (resolverCmd === undefined) return report;
return Object.freeze({
...report,
findings: resolveConflictFindings(vault, report.findings, { resolverCmd }),
});
}
/**
* The artifacts one finding would disclose, as the owner-scope view
* spells references: an absolute path rendered vault-relative, anything
* else left as the Brain artifact id it already is.
*
* `isAbsolute`, not a leading-`/` test: a Windows page path
* (`C:\vault\Brain\x.md`) failed that test, went out as a host path,
* and reached the owner-scope view in a spelling no visibility rule
* matches. Exported for unit tests.
*
* @internal
*/
export function findingRefs(vault: string, finding: HygieneFinding): ReadonlyArray<string> {
return finding.targets.map((target) =>
isAbsolute(target) ? vaultRelativeSafe(vault, target) : target,
);
}
function findingView(vault: string, finding: HygieneFinding): Record<string, unknown> {
return {
id: finding.id,
detector: finding.detector,
severity: finding.severity,
title: finding.title,
targets: findingRefs(vault, finding),
proposed_action: finding.proposed_action,
evidence: finding.evidence,
};
}
/**
* The `link_integrity.reason` a scan reports below local reach, where the
* count is not taken at all (docs/mcp.md, `brain_hygiene`). It sits beside
* the reasons the measurement itself returns, in
* {@link LinkIntegrityReason}.
*/
export const LINK_INTEGRITY_REACH_REASON = "reach" as const;
/** Every `link_integrity.reason` a scan can report. */
export type LinkIntegrityReason =
| LinkRatchetUnmeasurableReason
| typeof LINK_INTEGRITY_REACH_REASON;
/**
* Vault-wide link integrity, reported beside the detector findings
* (context-integrity-gates, unit G).
*
* An ADDITIVE top-level key, not a fifth detector: `HYGIENE_DETECTOR_IDS`
* is a closed tuple validated in three places including this tool's own
* input-schema enum, so extending it would change the tool contract.
*
* `dangling` counts the link rows the READ-TIME resolution ladder
* leaves unresolved - broken as the reader of this vault experiences
* it, not as the raw `target_document_id` column reports it. The
* `definition` key names the rule that produced the number.
*
* Read-only over the index the operator's searches already use, and
* refused unless that index records a full resolution pass - so
* `measured: false` with a reason is a real outcome here, never
* flattened into a zero.
*/
async function linkIntegrityView(ctx: ServerContext): Promise<Record<string, unknown>> {
// The measurement is taken over the whole index, withheld pages
// included, so its counts would move when a page the caller may not
// read appears or goes. Below local reach the number is not taken at
// all, which is the same answer whether such a page exists or not.
if (contextReach(ctx) !== TRANSPORT_REACH.local) {
return {
definition: DANGLING_LINK_DEFINITION,
measured: false,
reason: LINK_INTEGRITY_REACH_REASON satisfies LinkIntegrityReason,
detail: "link integrity is measured over the whole index and is reported at local reach only",
};
}
let measurement: LinkRatchetMeasurement;
try {
measurement = await measureFromIndex(
resolveSearchConfig({
vault: ctx.vault,
...(ctx.configPath ? { configPath: ctx.configPath } : {}),
}),
);
} catch (e) {
// A read-only scan is never failed by the reporting layer.
return {
definition: DANGLING_LINK_DEFINITION,
measured: false,
reason: "index-unreadable" satisfies LinkIntegrityReason,
detail: e instanceof Error ? e.message : String(e),
};
}
if (!measurement.measurable) {
return {
definition: measurement.definition,
measured: false,
reason: measurement.reason satisfies LinkIntegrityReason,
detail: measurement.detail,
};
}
return {
definition: measurement.definition,
measured: true,
dangling: measurement.dangling,
links: measurement.links,
documents: measurement.documents,
};
}
/**
* Per-detector counts over the findings actually returned.
*
* Every detector that RAN keeps a key, so a detector with nothing to say
* is still reported as having run with zero - the distinction between
* "not run" and "found nothing" that `detectors_run` and `counts`
* together carry.
*/
function countByDetector(
detectorsRun: ReadonlyArray<HygieneDetectorId>,
findings: ReadonlyArray<HygieneFinding>,
): Record<string, number> {
const counts: Record<string, number> = {};
for (const detector of detectorsRun) counts[detector] = 0;
for (const finding of findings) {
counts[finding.detector] = (counts[finding.detector] ?? 0) + 1;
}
return counts;
}
async function toolBrainHygiene(
ctx: ServerContext,
args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
const mode = args["mode"] ?? "scan";
if (mode !== "scan" && mode !== "apply" && mode !== "refresh" && mode !== "archive_get") {
throw new MCPError(INVALID_PARAMS, "'mode' must be one of: scan, apply, refresh, archive_get");
}
if (mode === "archive_get") {
// The bounded-fetch posture of brain_artifact_get, one visibility rule
// tighter: the hash is the caller's argument and is validated as one
// before it names a path, an unknown hash is a NAMED miss (never an
// error a caller would retry), and the store answers at LOCAL reach
// only - a remote caller gets the answer an absent entry gives, so the
// response can neither confirm an entry's existence nor carry bytes.
const hash = coerceStr(args, "hash", true)!;
if (!isArchiveHash(hash)) {
throw new MCPError(INVALID_PARAMS, "'hash' must be a 64-hex sha-256 digest");
}
if (contextReach(ctx) !== TRANSPORT_REACH.local) {
return { hash, archive: ARCHIVE_VERIFICATION.missing };
}
// The owner boundary, the same one the scan applies to its report: a
// caller under an enforced owner scope reads pages only through the
// per-path view, so an entry whose every citing page is withheld
// answers exactly as an absent one. Answering its state or its bytes
// would let a scoped agent confirm a guess about evidence it may not
// read - the scan withholds those citing pages through the gated view,
// and this read would otherwise stand beside it as a confirm-a-guess
// oracle (the leak the design cites for refusing digests).
const readable = readableAtContextReachOrUndefined(ctx);
if (readable !== undefined && !sourceArchiveCitingPages(ctx.vault, hash).some(readable)) {
return { hash, archive: ARCHIVE_VERIFICATION.missing };
}
const entry = readSourceArchiveEntry(ctx.vault, hash);
if (entry === null) return { hash, archive: ARCHIVE_VERIFICATION.missing };
return {
hash,
archive: entry.state,
bytes: entry.bytes,
content: entry.text,
};
}
const now = new Date();
const dryRun = coerceBool(args, "dry_run") === true;
if (mode === "refresh") {
// A derived page the caller cannot read at its reach is treated as
// absent: it is neither planned, named nor re-derived or archived, so
// the plan and the result read as in a vault without it.
const readable = readableAtContextReachOrUndefined(ctx);
const fullPlan = planRecompile(ctx.vault);
const plan =
readable === undefined
? fullPlan
: Object.freeze({
entries: Object.freeze(
fullPlan.entries.filter((entry) =>
readable(vaultRelativeSafe(ctx.vault, entry.page)),
),
),
});
const result = await executeRecompile(ctx.vault, plan, {
dryRun,
agent: resolveAgentName(ctx.configPath ?? undefined),
now,
});
return {
mode,
dry_run: result.dry_run,
plan: plan.entries.map((entry) => ({
kind: entry.kind,
page: toolPath(ctx, entry.page),
reason: entry.reason,
})),
rederived: result.rederived.map((page) => toolPath(ctx, page)),
archived: result.archived.map((page) => toolPath(ctx, page)),
manual: result.manual.map((page) => toolPath(ctx, page)),
errors: result.errors.map((row) => errorRowForCaller(ctx, row)),
};
}
const detectorsRaw = coerceStringArray(args, "detectors");
const detectors = detectorsRaw?.filter(isHygieneDetectorId);
if (detectorsRaw !== undefined && detectors!.length !== detectorsRaw.length) {
throw new MCPError(
INVALID_PARAMS,
`'detectors' entries must be: ${HYGIENE_DETECTOR_IDS.join(", ")}`,
);
}
const scanned = scanWithResolver(ctx, detectors, now);
// The owner boundary is applied to the REPORT, once, before EITHER mode
// reads it. `findings[].targets` are artifact ids (or absolute paths
// rendered vault-relative) and the `title` spells the same artifact out
// in prose (a-label-is-not-a-boundary, U3, recon C2).
//
// Hoisted out of the `scan` branch on purpose. While it lived there,
// `apply` planned against the UNFILTERED report, so a caller scoped to
// one owner whose scan correctly returned nothing could still hand a
// finding id to `apply` and merge, retire or archive another owner's
// preference - and read both hidden ids back out of the applier's
// `detail`. Finding ids are derivable rather than secret
// (`hygiene/detectors/id.ts` hashes the sorted target list), so
// withholding them from the scan was never the boundary; this is.
//
// Filtering the report rather than the plan is also what makes a hidden
// finding IDENTICAL TO ABSENT: `buildHygienePlan` indexes what it is
// given, so an id it cannot see lands in `unknown_ids` exactly as an id
// nobody ever issued does. A separate "withheld" bucket - or a hidden
// id landing in `excluded_review` while a nonexistent one lands in
// `unknown_ids` - would be an existence oracle over the same
// population the scan just refused to enumerate
// (`preferences-collect.ts` states the convention).
// Both rules, ANDed, on the seam the owner rule already sits on. The
// detectors walk with `MAINTENANCE_LANE_REACH` - correct for a scan
// that must see the whole vault it is diagnosing - so the reserved
// pages are deliberately walked IN, and this is where they stop. Adding
// the rule here rather than threading it through four detector
// signatures also means a detector added later inherits it.
const view = everyArtifactRefView(
gatedOwnerScopeView(ctx.vault, ctx.agentName),
reachView(ctx.vault, contextReach(ctx)),
);
const findings = view.keep(scanned.findings, (f) => findingRefs(ctx.vault, f));
const report: HygieneScanReport = Object.freeze({ ...scanned, findings });
if (mode === "scan") {
// Optional decision-model verdicts on the visible dedup findings
// (use `dedup`). Off: null and the listing below is unchanged. The
// verdicts are advisory output only; `apply` never sees them.
const annotated = await annotateDedupFindings(ctx.vault, findings, {
configPath: ctx.configPath,
});
// `counts` is recomputed from the visible findings: a count over the
// unfiltered set would report how many findings were withheld.
return {
mode,
generated_at: report.generated_at,
detectors_run: report.detectors_run,
counts: countByDetector(report.detectors_run, findings),
findings:
annotated === null
? findings.map((finding) => findingView(ctx.vault, finding))
: annotated.map((a) => ({ ...findingView(ctx.vault, a.item), ...verdictFields(a) })),
errors: report.errors.map((row) => errorRowForCaller(ctx, row)),
link_integrity: await linkIntegrityView(ctx),
};
}
const ids = coerceStringArray(args, "ids");
if (ids === undefined || ids.length === 0) {
throw new MCPError(INVALID_PARAMS, "apply requires explicit finding 'ids' from a prior scan");
}
const plan = buildHygienePlan(report, { ids });
const { expect, strict } = readCountGuardArgs(args);
// Guard on the selected findings BEFORE applying so an unexpected blast
// radius aborts without touching the vault.
enforceCountGuard({
matched: plan.selected.length,
expect,
strict,
willMutate: !dryRun,
matchList: plan.selected.map((finding) => finding.id),
});
const result = await applyHygienePlan(ctx.vault, plan, {
dryRun,
agent: resolveAgentName(ctx.configPath ?? undefined),
now,
// The deny consult on the destructive retire route answers for the
// credential-minted subject, never for the config agent - the same
// threading every other destructive surface applies (write-side
// trust, Task 7).
...(ctx.requestIdentity !== undefined ? { subject: ctx.requestIdentity } : {}),
});
return {
mode,
dry_run: result.dry_run,
selected: plan.selected.map((finding) => finding.id),
excluded_review: plan.excluded_review,
unknown_ids: plan.unknown_ids,
planned: result.planned,
applied: result.applied,
// Honest matched-vs-changed: findings selected vs. findings actually applied.
matched: plan.selected.length,
changed: result.applied.length,
errors: result.errors.map((row) => errorRowForCaller(ctx, row)),
};
}
export const HYGIENE_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
{
name: "brain_hygiene",
kind: "write",
previewBudget: MCP_PREVIEW_BUDGET,
description:
"Memory hygiene. `scan`: contested truth slots, near-duplicate preferences, stale or orphaned pages, low-usefulness candidates, knowledge resting on url-only sources. `apply`: run selected finding ids. `refresh`: recompile stale pages. `archive_get`: archived source bytes by hash, local only.",
inputSchema: {
type: "object",
properties: {
mode: {
type: "string",
enum: ["scan", "apply", "refresh", "archive_get"],
description: "Pipeline stage: scan, apply, refresh, archive_get. Default `scan`.",
},
hash: {
type: "string",
description:
"The source_archive_hash to fetch (archive_get mode): the digest an ingest summary page stamps.",
},
detectors: {
type: "array",
items: { type: "string", enum: [...HYGIENE_DETECTOR_IDS] },
description: `Detector subset for scan/apply. Default: ${DEFAULT_SCAN_IDS.join(", ")} (all but the opt-in ones).`,
},
ids: {
type: "array",
items: { type: "string" },
description: "Finding ids to execute (apply mode; required there).",
},
dry_run: {
type: "boolean",
description: "Preview apply/refresh with zero writes.",
},
expect: {
type: "integer",
minimum: 0,
description:
"Count guard (apply mode): assert exactly N findings will be applied. On mismatch the apply aborts without writing.",
},
strict: {
type: "boolean",
description: "Refuse a guardless apply (no `expect`). Default false.",
},
},
additionalProperties: false,
},
handler: toolBrainHygiene,
},
]);