Skip to content

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
20.1 KB
Raw Blame
/**
 * 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,
  },
]);