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
/**
* Reading `<vault>/Brain/_brain.yaml` off disk, and the fallback policy
* for vaults where that read cannot succeed.
*
* One reason to change: what happens when the config file is missing,
* unreadable, or malformed. Those are TWO conditions, not one, and every
* entry point here splits on the same predicate:
*
* - ABSENT - a vault that has never run `o2b brain init`. There are no
* operator settings to contradict, so the documented defaults are the
* configuration. The `*Safe` entry points exist for exactly this, so
* a freshly-cloned vault keeps working.
* - PRESENT BUT UNREADABLE - malformed YAML, a block that does not
* validate, a permission error, a directory in the file's place. The
* operator's settings exist and are not in force; answering with the
* defaults would revert them silently and leave the vault looking
* healthy. The `*Safe` entry points do not absorb this.
*
* The strict entry point ({@link loadBrainConfig}) throws on both.
*
* On a store-only machine (design D14 item 3, task 2.10), and with no
* vault at all, there is no `_brain.yaml` to read: every entry point here
* answers from the single store-backed settings reader
* (`./settings-source.ts`), the folded shared settings records plus the
* device keys of the machine config over the defaults. There the settings
* are never ABSENT; they are the defaults until a record says otherwise,
* and folded values that do not validate are UNREADABLE settings.
*/
import { existsSync, readFileSync } from "node:fs";
import type { BrainConfig, BrainInstallConfig, ResolvedBrainIntegrityConfig } from "../types.ts";
import { parseBrainYaml, type ParsedBlock } from "../yaml-parse.ts";
import { brainConfigPath } from "../paths.ts";
import {
BrainConfigError,
BrainSettingsUnreadableError,
type BrainConfigLoadWarning,
} from "./errors.ts";
import { validateBrainConfigDetailed } from "./validate.ts";
import { DEFAULT_BRAIN_CONFIG } from "./defaults.ts";
import { readBrainSettingsFromStore } from "./settings-source.ts";
import { isStoreOnly } from "../../store/store-only.ts";
import { BRAIN_STORAGE_DEFAULTS, resolveStorage } from "./blocks/storage.ts";
import { BRAIN_MOST_APPLIED_DEFAULTS, resolveMostApplied } from "./blocks/active.ts";
import { BRAIN_NOTES_DEFAULTS, resolveNotes } from "./blocks/notes.ts";
import { BRAIN_TEMPORAL_DEFAULTS, resolveTemporal } from "./blocks/temporal.ts";
import { BRAIN_GUARDRAIL_DEFAULTS, resolveGuardrails } from "./blocks/guardrails.ts";
import { BRAIN_MAINTENANCE_DEFAULTS, resolveMaintenance } from "./blocks/maintenance.ts";
import {
BRAIN_INTEGRITY_DEFAULTS,
BRAIN_INTEGRITY_STRICT_FALLBACK,
resolveIntegrity,
} from "./blocks/integrity.ts";
export interface LoadBrainConfigResult {
readonly config: BrainConfig;
readonly warnings: ReadonlyArray<BrainConfigLoadWarning>;
readonly path: string;
}
/**
* Read and validate `<vault>/Brain/_brain.yaml`.
*
* Throws {@link BrainConfigError} on:
* - missing file
* - YAML shape errors
* - unsupported `schema_version`
* - non-integer / out-of-range thresholds
* - non-integer / non-positive `snapshots.retention_count`
*
* Unknown top-level keys are reported as warnings, not errors.
*/
export function loadBrainConfig(vault: string | null): BrainConfig {
return loadBrainConfigDetailed(vault).config;
}
/**
* Whether the settings of `vault` come from the store rather than its
* `_brain.yaml`: with no vault, or on a store-only machine.
*/
export function brainSettingsFromStore(vault: string | null, configPath?: string): boolean {
if (vault === null || vault.trim() === "") return true;
return isStoreOnly({ vault, ...(configPath !== undefined ? { configPath } : {}) });
}
/**
* Same as {@link loadBrainConfig} but also returns parser warnings (for
* the future `o2b brain doctor` integration).
*/
export function loadBrainConfigDetailed(vault: string | null): LoadBrainConfigResult {
if (vault === null || brainSettingsFromStore(vault)) {
const read = readBrainSettingsFromStore();
return { config: read.config, warnings: read.warnings, path: read.source };
}
const path = brainConfigPath(vault);
if (!existsSync(path)) {
throw new BrainConfigError(
"config file does not exist; run `o2b brain init` first",
null,
path,
);
}
let text: string;
try {
text = readFileSync(path, "utf8");
} catch (err) {
throw new BrainSettingsUnreadableError(
`failed to read: ${(err as Error).message ?? String(err)}`,
path,
);
}
let parsed: ParsedBlock;
try {
parsed = parseBrainYaml(text);
} catch (err) {
throw new BrainConfigError((err as Error).message, null, path);
}
const { config, warnings } = validateBrainConfigDetailed(parsed, path);
return { config, warnings, path };
}
/**
* Whether `<vault>/Brain/_brain.yaml` is there at all.
*
* The ONE predicate every reader in this module splits on, so "absent"
* cannot come to mean two different things on two surfaces. It is
* deliberately existence and nothing more: a file that exists but cannot
* be opened is present, and its contents are not the defaults. Settings
* read from the store are always present (see the module docblock).
*/
function brainConfigExists(vault: string | null): boolean {
if (vault === null || brainSettingsFromStore(vault)) return true;
return existsSync(brainConfigPath(vault));
}
/**
* Factory for the "resolve a block, tolerating a vault that has never
* run `o2b brain init`" pattern repeated at every `load*ConfigSafe`
* below.
*
* Exactly ONE condition is absorbed, and it is named: `_brain.yaml` is
* ABSENT. A vault with no config has no operator settings to contradict,
* so the block defaults ARE the configuration, and these read surfaces
* keep working on a freshly-cloned vault.
*
* Every other failure propagates as a {@link BrainConfigError}: malformed
* YAML, a block that parses but does not validate, a permission error, a
* directory where the file should be. All four mean the operator's
* settings exist and are NOT the ones in force, and answering with the
* defaults would make that vault indistinguishable from a healthy one
* while silently reverting whatever they configured. This is the same
* split {@link loadIntegrityConfigSafe} makes; it differs only in what it
* does with the unreadable case, and says why at its own site.
*/
function makeAbsentTolerantLoader<T>(
resolveFn: (config: BrainConfig) => T,
fallback: T,
): (vault: string | null) => T {
return (vault: string | null): T => {
if (!brainConfigExists(vault)) return fallback;
return resolveFn(loadBrainConfig(vault));
};
}
/**
* Load + resolve the `notes:` block, falling back to
* `BRAIN_NOTES_DEFAULTS` when the config file is absent. Used by
* `scan-inline` and every other note walk so a freshly-cloned vault that
* has not been `brain init`-ed still produces a clean "no user folders to
* read" result. On an unreadable config it raises: an empty root list is
* indistinguishable from a scan that found nothing, and a scanner that
* silently walks the wrong folders is worse than one that stops.
*/
export const loadNotesConfigSafe = makeAbsentTolerantLoader(resolveNotes, BRAIN_NOTES_DEFAULTS);
/**
* Load + resolve the `temporal:` block, falling back to
* `BRAIN_TEMPORAL_DEFAULTS` when the config file is absent. Used by every
* temporal consumer (MCP wrappers, CLI verbs) so a freshly-initialised
* vault still produces a useful report; each of those callers is a verb
* or a tool that can report the raise on an unreadable config, and the
* operator snapshot already degrades its own way rather than reading
* all-clear.
*/
export const loadTemporalConfigSafe = makeAbsentTolerantLoader(
resolveTemporal,
BRAIN_TEMPORAL_DEFAULTS,
);
/**
* Load + resolve the `guardrails:` block, falling back to
* `BRAIN_GUARDRAIL_DEFAULTS` when the config file is absent. Used by
* agent-facing surfaces (e.g. the context pack) that must work on a vault
* without a full `brain init`; the opt-in toggles therefore default off
* there. They must NOT default off on a vault where the operator turned
* one on and then broke the file: every flag in this block is a
* containment or isolation switch, so a quiet revert to `false` is the
* gate silently opening.
*/
export const loadGuardrailsConfigSafe = makeAbsentTolerantLoader(
resolveGuardrails,
BRAIN_GUARDRAIL_DEFAULTS,
);
/**
* Load the configured `feedback.default_scope`, or `undefined` when the
* config file is absent or carries no feedback block. Used by the
* feedback write surfaces so a vault without a full `brain init` stays
* scope-less (byte-identical to pre-feature behaviour) instead of
* throwing when the signal is recorded. An unreadable config raises
* before the write: a signal recorded under the wrong scope is a durable
* record no later fix reaches.
*/
export const loadFeedbackDefaultScopeSafe = makeAbsentTolerantLoader(
(config: BrainConfig) => config.feedback?.default_scope,
undefined as string | undefined,
);
/**
* Load the configured snapshot `retention_count`, falling back to the
* default when the config file is absent, so a vault that has not run
* `brain init` still prunes to a sane bound. This is the SAME
* `snapshots.retention_count` the dream pass reads via
* {@link loadBrainConfig}.
*
* An unreadable config raises, and the prune is the one caller that most
* needs it to: pruning is destructive, and doing it at a GUESSED
* retention deletes archives the operator asked to keep. The
* destructive-snapshot gate already catches a prune failure and warns on
* stderr with the operation's result intact, so the raise costs a
* deferred cleanup and buys a named cause.
*/
export const loadSnapshotRetentionSafe = makeAbsentTolerantLoader(
(config: BrainConfig) => config.snapshots.retention_count,
DEFAULT_BRAIN_CONFIG.snapshots.retention_count,
);
/**
* Derived-store coverage as the archiver consumes it: whether to include
* the store, and the ceiling above which inclusion is refused.
*
* A pair rather than two loaders because the two are never useful apart
* - the ceiling only means anything when inclusion is on, and reading
* them from two config loads would let one call see a file the other
* did not.
*/
export interface BrainDerivedStorePolicy {
readonly include: boolean;
readonly maxBytes: number;
}
/**
* Load `snapshots.include_derived_store` and
* `snapshots.derived_store_max_bytes`, falling back to the defaults when
* the config file is absent so a vault that has never run `brain init`
* still snapshots its Markdown tree (with coverage off, which is what
* the defaults say).
*
* An unreadable config raises, exactly as it does for the retention
* count beside it: coverage is what an operator turned ON, and answering
* with the default `false` would silently strip the store out of every
* recovery point on a vault whose `_brain.yaml` merely has a typo.
*/
export const loadSnapshotDerivedStorePolicySafe = makeAbsentTolerantLoader<BrainDerivedStorePolicy>(
(config: BrainConfig) => ({
include: config.snapshots.include_derived_store,
maxBytes: config.snapshots.derived_store_max_bytes,
}),
Object.freeze({
include: DEFAULT_BRAIN_CONFIG.snapshots.include_derived_store,
maxBytes: DEFAULT_BRAIN_CONFIG.snapshots.derived_store_max_bytes,
}),
);
/**
* Load + resolve the `maintenance:` block, falling back to
* `BRAIN_MAINTENANCE_DEFAULTS` when the config file is absent — which
* leaves the host-pressure gate unconfigured, exactly as an operator who
* has never run `o2b brain init` has never asked for it.
*
* An unreadable config raises, and that is the point: both knobs here
* decide whether heavy work starts, so answering with the defaults would
* run a pass the operator had gated and retry a task the operator's
* limit had refused, on a vault that otherwise looks healthy.
*/
export const loadMaintenanceConfigSafe = makeAbsentTolerantLoader(
resolveMaintenance,
BRAIN_MAINTENANCE_DEFAULTS,
);
/**
* Load + resolve the `storage:` block, falling back to
* `BRAIN_STORAGE_DEFAULTS` when the config file is absent - which leaves
* the vault unbounded, exactly as an operator who has never configured a
* cap has never asked for the gate.
*
* An unreadable config raises, and that is the point here as it is for
* the maintenance loader: both outcomes decide whether writes are
* refused, so answering with the defaults would run - or refuse - work
* the operator's own file gates differently, on a vault that otherwise
* looks healthy.
*/
export const loadStorageConfigSafe = makeAbsentTolerantLoader(
resolveStorage,
BRAIN_STORAGE_DEFAULTS,
);
/**
* Load the RAW `install:` block, or `undefined` when the config file is
* absent or declares no block.
*
* The one loader here that hands back the unresolved block rather than a
* resolved value, because its consumer
* (`src/core/install/settings.ts`) sits in the middle of a four-tier
* ladder: the committed vault tier outranks the machine-local
* `config.yaml`, so "the block set this key" and "the block did not" must
* stay distinguishable. Resolving here would fold them together and hand
* the compiled default a victory over a user-level key that should have
* won.
*
* An unreadable config raises, and for this reader that is the whole
* point rather than a side effect: generated install and hook content is
* a WRITER, and it cannot infer an operator's intent from a file it could
* not parse. Defaulting would silently regenerate the shipped timeout
* over a vault whose `_brain.yaml` merely has a typo, and the
* re-construction check would then report the operator's own file as
* drift on every other machine.
*/
export const loadInstallBlockSafe = makeAbsentTolerantLoader(
(config: BrainConfig) => config.install,
undefined as BrainInstallConfig | undefined,
);
/**
* Load + resolve `active.most_applied`, falling back to
* `BRAIN_MOST_APPLIED_DEFAULTS` when the config file is absent, so a vault
* that has never run `brain init` still renders its most-applied section
* over the documented window. Read by `active.md` and by the digest, which
* report the same section and must agree on its window.
*
* An unreadable config raises: the section is the operator's own list of
* the rules they lean on, and re-windowing it silently would change WHICH
* rules appear while the digest looks entirely healthy. Both callers have
* a channel for the raise - the CLI verb reports `digest failed: …`, the
* MCP tool returns the error - so neither has to guess a window.
*/
export const loadActiveMostAppliedSafe = makeAbsentTolerantLoader(
resolveMostApplied,
BRAIN_MOST_APPLIED_DEFAULTS,
);
/**
* Why `_brain.yaml` could not be read, or `null` when it reads fine or
* does not exist.
*
* Exists so the unreadable-config condition is NAMEABLE on a surface
* rather than only inferable from a gate that suddenly refuses. The
* runtime-notice channel reports it; `loadIntegrityConfigSafe` uses the
* same distinction to choose its fallback.
*/
export function brainConfigReadFailure(vault: string | null): string | null {
if (!brainConfigExists(vault)) return null;
try {
loadBrainConfig(vault);
return null;
} catch (err) {
return err instanceof Error ? err.message : String(err);
}
}
/**
* The one-line operator-facing statement of {@link brainConfigReadFailure},
* or `null` when the config is absent or reads fine.
*
* One formulation, because the condition now reaches an operator on more
* than one surface: the runtime-notice channel pushes it at SessionStart
* and `vault_health`, and a delivery surface that DEGRADED because of it
* carries it on its own result. Two hand-written copies of the same
* sentence would drift, and an operator who saw one would not recognise
* the other as the same fault.
*
* It names no command on purpose. The repair is an edit to the YAML the
* parser just rejected and no `o2b` verb performs it, which is why
* `brain_config_unreadable` is deliberately absent from
* `DIAGNOSTIC_SIGNALS` - see the notice that raises it. The cause the
* parser gave IS the actionable part, so it is quoted verbatim.
*/
export function brainConfigUnreadableReport(vault: string | null): string | null {
const failure = brainConfigReadFailure(vault);
if (failure === null) return null;
const fromStore = vault === null || brainSettingsFromStore(vault);
const what = fromStore ? "The brain settings" : "Brain/_brain.yaml";
// Store-backed settings have no file to fix: the value is corrected
// through the settings verb, or in the machine config for a device key.
const remedy = fromStore
? "Correct the value with `o2b brain settings set <name> <value>` (or `unset <name>`), " +
"or fix its `brain_*` line in the machine config, then re-run."
: "Fix the file, then re-run.";
return (
`${what} could not be read, so configured settings are not in force ` +
`and the integrity gates fall back to their strictest mode (${failure}). ${remedy}`
);
}
/**
* Load + resolve the `integrity:` block.
*
* Two failure modes, deliberately NOT collapsed into one:
*
* - CONFIG ABSENT - a vault that has never run `o2b brain init`. The
* search layer reads its gate on a store open and must keep working
* there, so the gates land on `BRAIN_INTEGRITY_DEFAULTS`. This is the
* case the safe-loader pattern legitimately defends.
* - CONFIG PRESENT BUT UNREADABLE - a bad gate token, or any unrelated
* syntax error anywhere else in the file. Falling back to the
* defaults here would silently turn an operator's
* `owner_scope_delivery: fail` into `off`. It resolves to
* {@link BRAIN_INTEGRITY_STRICT_FALLBACK} instead, and
* {@link brainConfigReadFailure} names the cause.
*
* This is the one reader that resolves rather than raises on the second
* case, and the reason is its caller: the search layer reads its gate on
* every store open, including inside a fail-soft path, so a throw there
* would take out recall instead of tightening it. Resolving STRICT is
* what makes that safe - the unreadable config cannot loosen a gate, it
* can only close one.
*/
export function loadIntegrityConfigSafe(vault: string | null): ResolvedBrainIntegrityConfig {
try {
return resolveIntegrity(loadBrainConfig(vault));
} catch {
return brainConfigExists(vault) ? BRAIN_INTEGRITY_STRICT_FALLBACK : BRAIN_INTEGRITY_DEFAULTS;
}
}
/**
* Load + resolve the `integrity:` block for a WRITER.
*
* The reader/writer asymmetry, stated on the side it belongs to. This
* sits on the WRITE side, and it is the absent-tolerant loader every
* other block already uses ({@link makeAbsentTolerantLoader}) - absent
* config resolves to the documented defaults, an unreadable one raises.
*
* It is NOT {@link loadIntegrityConfigSafe}, and the difference is the
* point. That loader's strict fallback has a rationale scoped entirely
* to READERS: "the unreadable config cannot loosen a gate, it can only
* close one". Closing a gate a reader cannot read is conservative -
* the reader withholds more than it had to, and nothing on disk
* changes. Handing the same strict verdict to a writer inverts it:
* `owner_scope_delivery` in its strict reading STAMPS, so one bad token
* anywhere in `_brain.yaml` made a preference writer start marking new
* pages `owner: <whoever wrote them>` - permanently, because ownership
* is carried forward and never re-derived, so the pages outlived the
* repair of the typo that caused them. On an install with no resolvable
* identity the same typo turned every preference write into a hard
* failure instead.
*
* A writer cannot infer an operator's intent to enable ownership from a
* file it could not read, so it does not try. It raises, naming the
* parse failure, and writes nothing: never a silent stamp, never a
* silent skip.
*/
export const loadIntegrityConfigForWrite = makeAbsentTolerantLoader(
resolveIntegrity,
BRAIN_INTEGRITY_DEFAULTS,
);