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
/**
* `_brain.yaml` in the store (design D14 item 3): the import of the file
* into shared settings records and device config lines. Every key the
* Brain config validator reads is classified once, in
* `../brain/policy/settings-keys.ts` (re-exported here):
*
* - `shared` keys become `setting-set` records in the `settings` stream
* of `shared`, under `brain.<block>.<field>` (`brain.<key>` for a
* scalar).
* - `device` keys are reported: the migration never writes the user's
* config file, it prints the config key and value to add.
* - `drop` keys are skipped.
*
* Only values the user changed from the shipped default are carried over:
* such a value is user-authored config, so a shared one is seeded at
* `human` authority and a device one is reported. A value equal to its
* default is neither written nor reported; the store's settings reader
* falls back to the same default.
*
* The schema fields it writes (`brain.schema.<field>`) are attested by a
* baseline row in the store's audit ledger (task 3.12, design D19 item
* 1): no audited apply wrote them, and an apply refuses over a deciding
* record no row attests.
*
* `_permissions.yaml` rides along (review finding F461): its text becomes
* the operator-only `permissions.document` setting at `human` authority,
* never over a value the store already holds, so the deny rules stay in
* force once the legacy tree leaves the vault.
*/
import { existsSync, readFileSync } from "node:fs";
import { join } from "node:path";
import {
PERMISSIONS_DOCUMENT_REL,
PERMISSIONS_DOCUMENT_SETTING,
} from "../brain/permissions/document.ts";
import { brainConfigPath } from "../brain/paths.ts";
import { DEFAULT_BRAIN_CONFIG } from "../brain/policy/defaults.ts";
import { brainConfigKey, brainKeyHome, brainSettingKey } from "../brain/policy/settings-keys.ts";
import {
SCHEMA_DECIDED_RECORDS_FIELD,
SCHEMA_IMPORT_BASELINE_ACTION,
SCHEMA_MUTATION_AUDIT_DIR,
} from "../brain/schema-integrity.ts";
import { schemaRecordAttestation, STORE_SCHEMA_PACK_SOURCE } from "../brain/schema-pack-store.ts";
import { parseBrainYaml } from "../brain/yaml-parse.ts";
import { canonicalJson } from "../integrity/digest.ts";
import { appendRecord } from "../store/appender.ts";
import { AUTHORITY_FIELD, LEDGER_ROW_KIND, SETTING_SET_KIND } from "../store/constants.ts";
import { DUAL_WRITE_LEDGERS } from "../store/dual-write-records.ts";
import { foldSettings } from "../store/fold-settings.ts";
import type { StoreHandle } from "../store/store-open.ts";
import { heldRecords } from "./journal.ts";
// The classification lives in a leaf module so the settings reader
// (`brain/policy/settings-source.ts`) can import it without closing an
// import cycle through this module's record builders.
export {
BRAIN_YAML_KEYS,
brainConfigKey,
brainKeyHome,
brainSettingKey,
type BrainKeyHome,
type BrainKeyRule,
} from "../brain/policy/settings-keys.ts";
/**
* Whether `value` equals the shipped default of `block.field` (or of the
* scalar `block`). A key with no shipped default counts as changed.
*/
function isDefault(block: string, field: string | undefined, value: unknown): boolean {
const defaults = DEFAULT_BRAIN_CONFIG as unknown as Record<string, unknown>;
let fallback: unknown = defaults[block];
if (field !== undefined) {
fallback =
fallback !== null && typeof fallback === "object"
? (fallback as Record<string, unknown>)[field]
: undefined;
}
return fallback !== undefined && canonicalJson(fallback) === canonicalJson(value);
}
/** What the import did with one `_brain.yaml` file. */
export interface BrainSettingsImport {
/** Setting keys written as records. */
readonly written: ReadonlyArray<string>;
/**
* Setting keys the store already holds a record for (set or unset): the
* store's value wins, because after the first switch settings change
* only in the store and the synced file goes stale.
*/
readonly unchanged: ReadonlyArray<string>;
/** `_brain.yaml` keys whose value equals the shipped default, not carried over. */
readonly defaults: ReadonlyArray<string>;
/** Device keys, as `<config key>: <JSON value>` lines to add to the machine config. */
readonly device: ReadonlyArray<{ readonly yaml: string; readonly line: string }>;
/** Keys the table does not classify (a newer release's key, or a typo). */
readonly unknown: ReadonlyArray<string>;
}
/** Each set `(block, field, value)` of a parsed file; a scalar key has no field. */
function entries(parsed: Record<string, unknown>): Array<[string, string | undefined, unknown]> {
const out: Array<[string, string | undefined, unknown]> = [];
for (const [key, value] of Object.entries(parsed)) {
if (value !== null && typeof value === "object" && !Array.isArray(value)) {
for (const [field, inner] of Object.entries(value as Record<string, unknown>)) {
out.push([key, field, inner]);
}
} else {
out.push([key, undefined, value]);
}
}
return out;
}
/**
* Import `_brain.yaml` of `vault` into `store`: shared keys become
* `setting-set` records unless the store's settings fold already holds the
* key, whatever its value (a later machine, a resumed run, or a user's
* edit after the first switch, which a stale file must not undo); device
* keys are reported. A vault with no file imports nothing.
*/
export function importBrainSettings(
vault: string,
store: StoreHandle,
agent: string,
): BrainSettingsImport {
const path = brainConfigPath(vault);
const result = {
written: [] as string[],
unchanged: [] as string[],
defaults: [] as string[],
device: [] as Array<{ yaml: string; line: string }>,
unknown: [] as string[],
};
const fold = foldSettings(heldRecords(store));
const schemaAttestations: string[] = [];
// `_permissions.yaml` becomes the operator-only `permissions.document`
// setting (review finding F461): its text exactly as the file holds it,
// at human authority, so a deny rule stays in force once the legacy tree
// leaves the vault. An unreadable document is imported as it is: the
// reader refuses it, as it refuses the file (fail closed).
const permissions = join(vault, PERMISSIONS_DOCUMENT_REL);
if (existsSync(permissions)) {
if (fold.settings.has(PERMISSIONS_DOCUMENT_SETTING)) {
result.unchanged.push(PERMISSIONS_DOCUMENT_SETTING);
} else {
appendRecord(store, {
partition: "shared",
stream: "settings",
kind: SETTING_SET_KIND,
agent,
body: {
[AUTHORITY_FIELD]: "human",
key: PERMISSIONS_DOCUMENT_SETTING,
value: readFileSync(permissions, "utf8"),
},
});
result.written.push(PERMISSIONS_DOCUMENT_SETTING);
}
}
if (!existsSync(path)) return result;
const parsed = parseBrainYaml(readFileSync(path, "utf8")) as Record<string, unknown>;
for (const [block, field, value] of entries(parsed)) {
const yamlKey = field === undefined ? block : `${block}.${field}`;
const home = brainKeyHome(block, field);
if (home === undefined) {
result.unknown.push(yamlKey);
continue;
}
if (home === "drop" || value === null || value === undefined) continue;
if (isDefault(block, field, value)) {
result.defaults.push(yamlKey);
continue;
}
if (home === "device") {
result.device.push({
yaml: yamlKey,
line: `${brainConfigKey(block, field)}: ${JSON.stringify(value)}`,
});
continue;
}
const key = brainSettingKey(block, field);
if (fold.settings.has(key)) {
result.unchanged.push(key);
continue;
}
const written = appendRecord(store, {
partition: "shared",
stream: "settings",
kind: SETTING_SET_KIND,
agent,
body: { [AUTHORITY_FIELD]: "human", key, value },
});
result.written.push(key);
if (block === "schema") schemaAttestations.push(schemaRecordAttestation(written.record));
}
if (schemaAttestations.length > 0) appendSchemaBaseline(store, agent, schemaAttestations);
return result;
}
/**
* The baseline row attesting the schema records the import wrote, each
* bound to its content (`<id>:<digest>`), in `shared` like every apply's
* attesting row (`../brain/schema-mutate-store.ts`).
*/
function appendSchemaBaseline(store: StoreHandle, agent: string, attestations: string[]): void {
const record = {
timestamp: new Date().toISOString(),
actor: agent,
action: SCHEMA_IMPORT_BASELINE_ACTION,
target: STORE_SCHEMA_PACK_SOURCE,
ok: true,
details: { [SCHEMA_DECIDED_RECORDS_FIELD]: attestations },
};
appendRecord(store, {
partition: "shared",
stream: "ledgers",
ledger: DUAL_WRITE_LEDGERS.reliabilityAudit,
kind: LEDGER_ROW_KIND,
agent,
body: { row: { audit_dir: SCHEMA_MUTATION_AUDIT_DIR, record } },
});
}