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
/**
* 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;
}