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
5.3 KB
Raw Blame
/**
 * The shape every doctor check shares.
 *
 * The checks have nothing to do with one another - a malformed
 * timestamp and an escaping symlink are unrelated conditions - so what
 * holds the pass together is this contract rather than any shared logic:
 * each check reads the one context the pass built and writes findings
 * into the two streams the report is partitioned from. A new check joins
 * the pass by being added to the registry array in `doctor.ts`.
 */

import type { TransportReach } from "../../graph/transport-reach.ts";
import type { BrainConfig, DoctorIssue } from "../types.ts";
import type { LogRecord, PreferenceRecord, UnreadableLogDay } from "./records.ts";
import type { DoctorUncertainEntry } from "./report.ts";

/**
 * Everything the checks read, resolved once per pass.
 *
 * The two record snapshots and the basename universe are built up-front
 * rather than per check: several checks walk the same directories, and
 * re-parsing them once per lint is what this context exists to prevent.
 */
export interface DoctorCheckContext {
  readonly vault: string;
  /** Wall clock for the age-based lints, so tests can pin it. */
  readonly now: Date;
  /** Resolved `_brain.yaml`, or absent when it could not be loaded. */
  readonly config: BrainConfig | undefined;
  /**
   * Search-index path for index-backed checks. When absent, the store
   * integrity check skips itself and the embeddings-health check falls
   * back to the path the search configuration resolves.
   */
  readonly dbPath: string | undefined;
  /**
   * The `o2b` config file the pass was invoked against (C1).
   *
   * Carried on the context rather than discovered by the check that
   * needs it, so a check reading a runtime gate is testable without
   * mutating process environment. Absent means the caller named none and
   * the resolver falls back to its own default discovery - the same
   * answer the runtime itself would get.
   */
  readonly configPath: string | undefined;
  /**
   * Whether the caller may read a vault-relative path, for the checks
   * that count before any finding is filtered: a page it rejects spends
   * no slot of a cap and moves no count. Absent means every page counts.
   */
  readonly readable?: (rel: string) => boolean;
  /**
   * How far the caller had to reach, for the checks whose findings carry
   * whole-vault figures: those figures move when a page the caller may
   * not read appears or goes, so below local reach such a check answers
   * in the uncertain stream, by name and without the figures. Absent
   * reads as local - the shell caller, which already holds the
   * filesystem. A wire surface resolves its caller's reach and passes it
   * here; it never leaves this absent.
   */
  readonly reach?: TransportReach;
  /**
   * The caller is below local reach: the broken-backlinks check ignores
   * references made only by log events of the store's `private` partition,
   * and the store check reports nothing about that partition. Absent reads
   * as false (the operator's own shell).
   */
  readonly withholdsPrivate?: boolean;
  /** Every valid wikilink target inside `Brain/`, keyed by basename. */
  readonly knownBasenames: ReadonlySet<string>;
  /**
   * Frontmatter ids to the files that declare them. The record checks
   * fill it as they walk and the duplicate-id check reads it once they
   * are done, which is why it is the one mutable member here - the
   * ordering that makes it work is the registry's ordering.
   */
  readonly idIndex: Map<string, string[]>;
  readonly preferences: ReadonlyArray<PreferenceRecord>;
  readonly logs: ReadonlyArray<LogRecord>;
  /**
   * Log days the snapshot above could not read. Optional so a context
   * built by hand stays valid; absent reads as none.
   */
  readonly unreadableLogDays?: ReadonlyArray<UnreadableLogDay>;
}

/**
 * The two streams a check writes into. `issues` is partitioned by
 * severity into the report's warnings and errors; `uncertain` carries
 * sub-operations the doctor attempted but cannot claim it verified.
 */
export interface DoctorFindings {
  readonly issues: DoctorIssue[];
  readonly uncertain: DoctorUncertainEntry[];
}

/**
 * The context a store-side check reads (design D14, task 2.10): the parts
 * of {@link DoctorCheckContext} that do not come from a vault, with the
 * vault itself `null` when none is configured. A store-side check runs in
 * the vault pass and in the no-vault pass alike.
 */
export interface StoreSideCheckContext extends Pick<
  DoctorCheckContext,
  "now" | "dbPath" | "configPath" | "readable" | "reach" | "withholdsPrivate"
> {
  readonly vault: string | null;
}

/** A check over the brain store and this machine's state, not the vault's files. */
export interface StoreSideDoctorCheck {
  readonly failSoft: boolean;
  run(ctx: StoreSideCheckContext, out: DoctorFindings): void;
}

export interface DoctorCheck {
  /**
   * True when a throw from `run` is swallowed by the pass, so one
   * broken scan cannot mask the findings of every check after it.
   *
   * False for the checks over the store's structural core - the config,
   * the record frontmatter, the id index, the logs, the backlinks. A
   * failure there does not leave the report incomplete, it leaves it
   * wrong, so the throw propagates out of `runDoctor` instead.
   */
  readonly failSoft: boolean;
  run(ctx: DoctorCheckContext, out: DoctorFindings): void;
}