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
15.1 KB
Raw Blame
/**
 * Frontmatter invariants of the three Brain record kinds.
 *
 * One reason to change: the record schema. Required fields, ISO-8601
 * timestamps, wikilink targets, the id-to-filename agreement, id
 * uniqueness across the store, and the classification of a parse
 * failure into a doctor code all follow from it.
 */

import { join } from "node:path";

import {
  INBOX_FOLDER_STATES,
  memoryFromStore,
  type MemoryPageKind,
  signalPageRaw,
  type StoreMemoryPage,
  storeRecordPages,
} from "../memory-pages.ts";
import { extractWikilinks } from "../../vault.ts";
import { BrainParseError } from "../parse-error.ts";
import { brainDirs } from "../paths.ts";
import {
  BrainStatusFolderMismatchError,
  parsePreference,
  parsePreferenceMeta,
  parseRetired,
  parseRetiredMeta,
} from "../preference.ts";
import { parseSignal, parseStoreSignal } from "../signal.ts";
import { principleNeedsRepair } from "../text/sanitize-principle.ts";
import type { DoctorIssue } from "../types.ts";
import { normaliseWikilinkTarget } from "../wikilink.ts";
import type { DoctorCheck } from "./check.ts";
import type { DoctorUncertainEntry } from "./report.ts";
import { readSweptDir, SWEEP_ORIGIN, type SweptPath } from "./unreadable-path.ts";

// ----- Signal check ---------------------------------------------------------

export const signalCheck: DoctorCheck = {
  failSoft: false,
  run({ vault, idIndex }, { issues, uncertain }) {
    const dirs = brainDirs(vault);
    const swept = recordSweep("signal", uncertain);
    const fromStore = memoryFromStore(vault);
    const pages = fromStore ? memoryPagesOf(vault, "signal") : null;
    for (const dir of fromStore ? [dirs.inbox] : [dirs.inbox, dirs.processed, dirs.archived]) {
      forEachRecord(pages, dir, "sig-", swept, (path, filename, page) => {
        try {
          const sig =
            page === null
              ? parseSignal(path)
              : parseStoreSignal(path, page.meta, signalPageRaw(page));
          registerId(idIndex, sig.id, path);
          checkIso(path, "created_at", sig.created_at, issues);
          const expectedId = filename.slice(0, -".md".length);
          if (sig.id !== expectedId) {
            issues.push({
              severity: "warning",
              code: "id-filename-mismatch",
              path,
              message: `signal id '${sig.id}' differs from filename basename '${expectedId}'`,
            });
          }
        } catch (err) {
          issues.push({
            severity: "error",
            code: "signal-invalid",
            path,
            message: (err as Error).message ?? String(err),
          });
        }
      });
    }
  },
};

// ----- Preference check -----------------------------------------------------

export const preferenceCheck: DoctorCheck = {
  failSoft: false,
  run({ vault, idIndex, knownBasenames }, { issues, uncertain }) {
    const dirs = brainDirs(vault);
    const pages = memoryFromStore(vault) ? memoryPagesOf(vault, "preference") : null;
    const swept = recordSweep("preference", uncertain);
    forEachRecord(pages, dirs.preferences, "pref-", swept, (path, _filename, page) => {
      try {
        const pref = page === null ? parsePreference(path) : parsePreferenceMeta(page.meta, path);
        registerId(idIndex, pref.id, path);
        checkIso(path, "created_at", pref.created_at, issues);
        checkIso(path, "unconfirmed_until", pref.unconfirmed_until, issues);
        if (pref.confirmed_at !== null) {
          checkIso(path, "confirmed_at", pref.confirmed_at, issues);
        }
        if (pref.last_evidence_at !== null) {
          checkIso(path, "last_evidence_at", pref.last_evidence_at, issues);
        }
        // Status invariant — the parser already enforces the canonical
        // values via the enum; a non-canonical value would have thrown
        // BrainStatusFolderMismatchError, caught below. Reaching here
        // means the status is valid; nothing more to check.
        checkWikilinks(path, "evidenced_by", pref.evidenced_by, knownBasenames, issues);
        if (pref.supersedes) {
          checkWikilinks(path, "supersedes", [pref.supersedes], knownBasenames, issues);
        }
        // Principle corruption (token-diet, t_40eb1de7): leaked tool-call
        // fragments or escape-amplified quote chains written before the
        // sanitizing write seam shipped. `o2b brain upgrade --apply`
        // repairs these in place.
        if (principleNeedsRepair(pref.principle)) {
          issues.push({
            severity: "warning",
            code: "principle-corrupted",
            path,
            message:
              "principle carries leaked tool-call fragments or escape-amplified quotes; run `o2b brain upgrade --apply` to repair",
          });
        }
      } catch (err) {
        classifyParseError(err, path, "preference", issues);
      }
    });
  },
};

// ----- Retired check --------------------------------------------------------

export const retiredCheck: DoctorCheck = {
  failSoft: false,
  run({ vault, idIndex, knownBasenames }, { issues, uncertain }) {
    const dirs = brainDirs(vault);
    const pages = memoryFromStore(vault) ? memoryPagesOf(vault, "retired") : null;
    const swept = recordSweep("retired", uncertain);
    forEachRecord(pages, dirs.retired, "ret-", swept, (path, _filename, page) => {
      try {
        const ret = page === null ? parseRetired(path) : parseRetiredMeta(page.meta, path);
        registerId(idIndex, ret.id, path);
        checkIso(path, "created_at", ret.created_at, issues);
        checkIso(path, "retired_at", ret.retired_at, issues);
        if (ret.last_evidence_at !== null) {
          checkIso(path, "last_evidence_at", ret.last_evidence_at, issues);
        }
        checkWikilinks(path, "evidenced_by", ret.evidenced_by, knownBasenames, issues);
        checkWikilinks(path, "retired_by", [ret.retired_by], knownBasenames, issues);
        if (ret.superseded_by) {
          checkWikilinks(path, "superseded_by", [ret.superseded_by], knownBasenames, issues);
        }
      } catch (err) {
        classifyParseError(err, path, "retired", issues);
      }
    });
  },
};

// ----- Duplicate id ---------------------------------------------------------

/**
 * Two distinct files claiming one frontmatter id. Reads the index the
 * three record checks filled, so it has to run after them.
 */
export const duplicateIdCheck: DoctorCheck = {
  failSoft: false,
  run({ idIndex }, { issues }) {
    for (const [id, paths] of idIndex.entries()) {
      if (paths.length > 1) {
        issues.push({
          severity: "error",
          code: "duplicate-id",
          message: `duplicate id '${id}' across files: ${paths.join(", ")}`,
        });
      }
    }
  },
};

// ----- Helpers --------------------------------------------------------------

function registerId(idIndex: Map<string, string[]>, id: string, path: string): void {
  const list = idIndex.get(id);
  if (list) list.push(path);
  else idIndex.set(id, [path]);
}

/** Subsystem name a record sweep reports an unreadable directory under. */
const RECORD_SITE = "brain.doctor.records";

/** What a record kind's checks can no longer claim, as one clause. */
function recordSweep(kind: string, uncertain: DoctorUncertainEntry[]): SweptPath {
  return {
    site: RECORD_SITE,
    consequence:
      `no ${kind} record in it was validated, so a malformed one - or an id it duplicates - ` +
      "is missing from this report",
    uncertain,
  };
}

/**
 * Iterate the `<prefix>*.md` files directly inside `dir` (non-recursive),
 * invoking `cb(path, filename)` for each. Absent `dir` is a no-op - the
 * per-kind checks all treat a missing Brain subdirectory as "nothing to
 * check", not an error.
 *
 * A directory that exists and cannot be listed is neither: these checks
 * are the pass's structural core and do not fail soft, so an unreadable
 * `Brain/preferences` used to end the run with no findings whatsoever.
 * It is now the same uncertainty every other sweep reports.
 */
function forEachBrainFile(
  dir: string,
  prefix: string,
  swept: SweptPath,
  cb: (path: string, filename: string) => void,
): void {
  const entries = readSweptDir(dir, swept, SWEEP_ORIGIN.root);
  if (entries === null) return;
  for (const entry of entries) {
    if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
    if (!entry.name.startsWith(prefix)) continue;
    cb(join(dir, entry.name), entry.name);
  }
}

/**
 * The records of one kind a check validates: the legacy folder's files on
 * an unswitched machine (`pages` is `null`), the fold's records seen as
 * pages on a store-only one (task 2.10), where the legacy folder is not
 * read and its absence is no finding.
 */
function forEachRecord(
  pages: ReadonlyArray<StoreMemoryPage> | null,
  dir: string,
  prefix: string,
  swept: SweptPath,
  cb: (path: string, filename: string, page: StoreMemoryPage | null) => void,
): void {
  if (pages === null) {
    forEachBrainFile(dir, prefix, swept, (path, filename) => cb(path, filename, null));
    return;
  }
  for (const page of pages) cb(page.path, `${page.id}.md`, page);
}

const KIND_SETS: Readonly<Record<MemoryPageKind, ReadonlySet<MemoryPageKind>>> = Object.freeze({
  preference: new Set<MemoryPageKind>(["preference"]),
  retired: new Set<MemoryPageKind>(["retired"]),
  signal: new Set<MemoryPageKind>(["signal"]),
});

/** The fold's records of `kind` as pages; signals in the states the inbox folders held. */
function memoryPagesOf(vault: string, kind: MemoryPageKind): ReadonlyArray<StoreMemoryPage> {
  return storeRecordPages(vault, { kinds: KIND_SETS[kind], signalStates: INBOX_FOLDER_STATES });
}

/** Record kinds whose parse failures this module classifies. */
type ParsedRecordKind = "preference" | "retired";

const PREFERENCE_MISSING_FIELD_CODE = "preference-missing-field";
const PREFERENCE_INVALID_CODE = "preference-invalid";
const RETIRED_MISSING_FIELD_CODE = "retired-missing-field";
const RETIRED_INVALID_CODE = "retired-invalid";
const ISO_INVALID_CODE = "iso-invalid";

/**
 * The parse-failure codes, per record kind, written out.
 *
 * These four used to be built by concatenating the kind onto a suffix,
 * which meant they appeared nowhere in this module as readable strings -
 * so the doctor's own code population could not be enumerated from its
 * source, and the exit census (`tests/core/brain/doctor-exit-census.test.ts`)
 * could not see them to demand a classification.
 */
const PARSE_ERROR_CODES: Readonly<
  Record<ParsedRecordKind, { readonly missingField: string; readonly invalid: string }>
> = Object.freeze({
  preference: Object.freeze({
    missingField: PREFERENCE_MISSING_FIELD_CODE,
    invalid: PREFERENCE_INVALID_CODE,
  }),
  retired: Object.freeze({
    missingField: RETIRED_MISSING_FIELD_CODE,
    invalid: RETIRED_INVALID_CODE,
  }),
});

/** Which of the three parse-failure codes `msg` from `kind` reports. */
function parseErrorCode(kind: ParsedRecordKind, msg: string): string {
  if (/missing field/.test(msg)) return PARSE_ERROR_CODES[kind].missingField;
  if (/ISO-8601/i.test(msg)) return ISO_INVALID_CODE;
  return PARSE_ERROR_CODES[kind].invalid;
}

/**
 * Classify a parse-time error into a `DoctorIssue` and push it. Shared by
 * the preference and retired checks, which previously carried
 * byte-identical copies of this regex-based classification - a change to
 * a parser's error wording would otherwise reclassify issues in one path
 * without the other noticing.
 *
 * A {@link BrainParseError} - which both parsers now raise, and which
 * `BrainStatusFolderMismatchError` extends - reports its location from
 * the `path` field and its prose from `detail`, which carries none. The
 * human renderer appends ` (<path>)` from the issue's own field, so a
 * message that embedded the path as well named the file twice on every
 * parse-error line: prose carrying data the record already holds. An
 * untyped throw (a frontmatter read, a vocabulary guard owned by another
 * module) keeps its message verbatim against the walked path - that
 * message is not ours to shorten.
 *
 * What changed for a caller that prints `(exc as Error).message` bare,
 * stated exactly: a throw site whose message already carried the path
 * composes the same sentence as before, the status-folder mismatch
 * included (it supplies its own composition, keeping the location inside
 * the `(path=…, status=…, folder=…)` group). The four optional-field
 * helpers in `preference.ts` carried no location at all and now do -
 * a gain, and the only wording change in the set.
 */
function classifyParseError(
  err: unknown,
  path: string,
  kindPrefix: ParsedRecordKind,
  issues: DoctorIssue[],
): void {
  if (err instanceof BrainStatusFolderMismatchError) {
    issues.push({
      severity: "warning",
      code: "status-folder-mismatch",
      path: err.path,
      message: err.detail,
    });
    return;
  }
  const typed = err instanceof BrainParseError ? err : null;
  const msg = typed ? typed.detail : ((err as Error).message ?? String(err));
  issues.push({
    severity: "error",
    code: parseErrorCode(kindPrefix, msg),
    path: typed ? typed.path : path,
    message: msg,
  });
}

// ISO-8601 UTC: YYYY-MM-DDTHH:MM:SS(.fff)?Z. Lenient — we accept the
// shorter date-only form too (created_at is sometimes a date-only string
// in hand-authored signals).
const ISO_RE = /^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z)?$/;

function checkIso(path: string, field: string, value: string, issues: DoctorIssue[]): void {
  if (!ISO_RE.test(value)) {
    issues.push({
      severity: "error",
      code: ISO_INVALID_CODE,
      path,
      message: `field '${field}' is not a valid ISO-8601 timestamp: ${JSON.stringify(value)}`,
    });
    return;
  }
  // Confirm the calendar date is real (Date.parse accepts garbage on
  // some engines — but verifying via Date round-trip catches it).
  const ts = Date.parse(value);
  if (!Number.isFinite(ts)) {
    issues.push({
      severity: "error",
      code: ISO_INVALID_CODE,
      path,
      message: `field '${field}' could not be parsed as a date: ${JSON.stringify(value)}`,
    });
  }
}

function checkWikilinks(
  path: string,
  field: string,
  values: ReadonlyArray<string>,
  knownBasenames: ReadonlySet<string>,
  issues: DoctorIssue[],
): void {
  for (const raw of values) {
    if (!raw) continue;
    // Extract any wikilinks via the shared parser. A bare `[[target]]`
    // produces one match; an already-stripped basename produces zero,
    // in which case we treat the raw string itself as the candidate.
    const matches = extractWikilinks(raw);
    const candidates = matches.length > 0 ? matches : [raw];
    for (const candidate of candidates) {
      const target = normaliseWikilinkTarget(candidate);
      if (!target) continue;
      if (!knownBasenames.has(target)) {
        issues.push({
          severity: "warning",
          code: "broken-wikilink",
          path,
          // no-dead-ends, task 12: the field and the target ride as
          // fields as well as inside the sentence, so a consumer acts on
          // values rather than on a regex over prose. The message is
          // unchanged - the human surface still reads it.
          field,
          target,
          message: `field '${field}' references missing basename '${target}'`,
        });
      }
    }
  }
}