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
/**
* A parse failure carries its file as a field, not inside its prose
* (signals-that-survive, task 2).
*
* `o2b brain doctor` renders `<code>: <message> (<path>)` — the path is
* appended by the renderer from the finding's structured `path` field.
* The preference / retired parsers used to embed the same path inside
* the message as well, so every parse-error line named the file twice.
*
* The fix is a typed error that carries `path` structurally and exposes
* the location-free prose as `detail`, which is what the doctor reports.
* The `message` a bare caller reads is still composed through ONE shared
* formatter ({@link withLocation}), so no surface that prints
* `(exc as Error).message` loses the location.
*
* Every parse-error code the doctor can classify is pinned here — the
* two `*-missing-field` codes and the two `*-invalid` codes — because
* the classification is a regex over the message, and shortening the
* message is exactly the change that could break it.
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { DEFAULT_BRAIN_CONFIG_YAML } from "../../../src/core/brain/config-template.ts";
import { runDoctor } from "../../../src/core/brain/doctor.ts";
import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";
import { BrainParseError, withLocation } from "../../../src/core/brain/parse-error.ts";
import { brainConfigPath, brainDirs } from "../../../src/core/brain/paths.ts";
import {
BrainStatusFolderMismatchError,
parsePreference,
parseRetired,
} from "../../../src/core/brain/preference.ts";
import type { DoctorIssue } from "../../../src/core/brain/types.ts";
let tmp: string;
beforeEach(() => {
tmp = mkdtempSync(join(tmpdir(), "o2b-parse-error-"));
const dirs = brainDirs(tmp);
for (const d of [
dirs.brain,
dirs.inbox,
dirs.processed,
dirs.preferences,
dirs.retired,
dirs.log,
dirs.snapshots,
]) {
mkdirSync(d, { recursive: true });
}
atomicWriteFileSync(brainConfigPath(tmp), DEFAULT_BRAIN_CONFIG_YAML);
});
afterEach(() => {
rmSync(tmp, { recursive: true, force: true });
});
/** Write `lines` as a Brain artifact at `path` and return the path. */
function seed(path: string, lines: ReadonlyArray<string>): string {
writeFileSync(path, [...lines, ""].join("\n"), "utf8");
return path;
}
/** A preference file whose frontmatter omits `created_at`. */
function seedPreferenceMissingField(): string {
return seed(join(brainDirs(tmp).preferences, "pref-no-created-at.md"), [
"---",
"kind: brain-preference",
"id: pref-no-created-at",
"_confirmed_at: null",
"unconfirmed_until: 2026-05-28T10:42:00Z",
"tags: [brain, brain/preference]",
"topic: broken",
"_status: unconfirmed",
"principle: A rule with no birthday",
"_evidenced_by: []",
"---",
]);
}
/** A preference file whose `_confidence` is outside the enum. */
function seedPreferenceInvalid(): string {
return seed(join(brainDirs(tmp).preferences, "pref-bad-confidence.md"), [
"---",
"kind: brain-preference",
"id: pref-bad-confidence",
"created_at: 2026-05-14T10:42:00Z",
"_confirmed_at: null",
"unconfirmed_until: 2026-05-28T10:42:00Z",
"tags: [brain, brain/preference]",
"topic: broken",
"_status: unconfirmed",
"principle: A rule with an unknown confidence band",
"_evidenced_by: []",
"_confidence: hilarious",
"---",
]);
}
/** A retired file whose frontmatter omits `retired_at`. */
function seedRetiredMissingField(): string {
return seed(join(brainDirs(tmp).retired, "ret-no-retired-at.md"), [
"---",
"kind: brain-retired",
"id: ret-no-retired-at",
"created_at: 2026-05-14T10:42:00Z",
"tags: [brain, brain/retired]",
"topic: broken",
"_status: retired",
"retired_reason: superseded",
"retired_by: [[Brain/log/2026-05-14]]",
"principle: A rule with no retirement date",
"---",
]);
}
/** A retired file whose `retired_reason` is outside the enum. */
function seedRetiredInvalid(): string {
return seed(join(brainDirs(tmp).retired, "ret-bad-reason.md"), [
"---",
"kind: brain-retired",
"id: ret-bad-reason",
"created_at: 2026-05-14T10:42:00Z",
"retired_at: 2026-06-14T10:42:00Z",
"tags: [brain, brain/retired]",
"topic: broken",
"_status: retired",
"retired_reason: hilarious",
"retired_by: [[Brain/log/2026-06-14]]",
"principle: A rule retired for an unknown reason",
"---",
]);
}
/** A preference file whose optional `_applied_count` is not a number. */
function seedPreferenceBadAppliedCount(): string {
return seed(join(brainDirs(tmp).preferences, "pref-bad-applied-count.md"), [
"---",
"kind: brain-preference",
"id: pref-bad-applied-count",
"created_at: 2026-05-14T10:42:00Z",
"_confirmed_at: null",
"unconfirmed_until: 2026-05-28T10:42:00Z",
"tags: [brain, brain/preference]",
"topic: broken",
"_status: unconfirmed",
"principle: A rule with an uncountable apply count",
"_evidenced_by: []",
"_applied_count: abc",
"---",
]);
}
/** A preference file filed under `preferences/` with `_status: retired`. */
function seedStatusFolderMismatch(): string {
return seed(join(brainDirs(tmp).preferences, "pref-mismatch.md"), [
"---",
"kind: brain-preference",
"id: pref-mismatch",
"created_at: 2026-05-14T10:42:00Z",
"_confirmed_at: null",
"unconfirmed_until: 2026-05-28T10:42:00Z",
"tags: [brain, brain/preference]",
"topic: broken",
"_status: retired",
"principle: A rule filed under the wrong folder",
"_evidenced_by: []",
"---",
]);
}
/** The single doctor finding carrying `code`. */
function finding(issues: ReadonlyArray<DoctorIssue>, code: string): DoctorIssue {
const hits = issues.filter((i) => i.code === code);
expect(hits).toHaveLength(1);
return hits[0]!;
}
describe("the typed parse error carries the path as a field", () => {
test("a missing required field throws BrainParseError with path and detail as fields", () => {
const path = seedPreferenceMissingField();
expect(() => parsePreference(path)).toThrow(BrainParseError);
try {
parsePreference(path);
throw new Error("parsePreference did not throw");
} catch (err) {
expect(err).toBeInstanceOf(BrainParseError);
const e = err as BrainParseError;
expect(e.path).toBe(path);
expect(e.detail).toBe("preference missing field: created_at");
expect(e.detail).not.toContain(path);
}
});
test("a caller that surfaces the message directly still receives the path", () => {
const path = seedPreferenceInvalid();
let surfaced = "";
try {
parsePreference(path);
} catch (exc) {
// Exactly what `o2b brain reject`, `brain merge` and the pin path do.
surfaced = (exc as Error).message;
}
expect(surfaced).toContain(path);
expect(surfaced).toBe(
withLocation(
"preference field 'confidence' must be one of low, medium, high; got \"hilarious\"",
path,
),
);
});
test("the located message is composed by the one shared formatter", () => {
const path = seedRetiredInvalid();
try {
parseRetired(path);
throw new Error("parseRetired did not throw");
} catch (err) {
const e = err as BrainParseError;
expect(e.message).toBe(withLocation(e.detail, e.path));
}
});
test("the status-folder mismatch keeps its own fields and its bare detail", () => {
const path = seedStatusFolderMismatch();
try {
parsePreference(path);
throw new Error("parsePreference did not throw");
} catch (err) {
expect(err).toBeInstanceOf(BrainStatusFolderMismatchError);
expect(err).toBeInstanceOf(BrainParseError);
const e = err as BrainStatusFolderMismatchError;
expect(e.path).toBe(path);
expect(e.status).toBe("retired");
expect(e.folder).toBe("preferences");
expect(e.detail).not.toContain(path);
expect(e.message).toContain(path);
}
});
});
describe("what the composed sentence promises, precisely", () => {
test("the status-folder mismatch sentence keeps its historical byte layout", () => {
const path = seedStatusFolderMismatch();
let surfaced = "";
try {
parsePreference(path);
} catch (exc) {
// `o2b brain reject` prints this string bare; an operator may match on it.
surfaced = (exc as Error).message;
}
expect(surfaced).toBe(
"preference file frontmatter status does not match preferences/ folder " +
`(path=${path}, status=retired, folder=preferences)`,
);
});
test("an optional-field failure that carried no location now carries one", () => {
const path = seedPreferenceBadAppliedCount();
try {
parsePreference(path);
throw new Error("parsePreference did not throw");
} catch (err) {
expect(err).toBeInstanceOf(BrainParseError);
const e = err as BrainParseError;
expect(e.detail).toBe(
"preference field 'applied_count' must be a finite number; got \"abc\"",
);
expect(e.path).toBe(path);
expect(e.message).toBe(withLocation(e.detail, path));
}
});
});
describe("the doctor reports the path once, as a field", () => {
test("preference-missing-field names the file in `path` and not in `message`", () => {
const path = seedPreferenceMissingField();
const issue = finding(runDoctor(tmp).errors, "preference-missing-field");
expect(issue.path).toBe(path);
expect(issue.message).toBe("preference missing field: created_at");
expect(issue.message).not.toContain(path);
});
test("preference-invalid names the file in `path` and not in `message`", () => {
const path = seedPreferenceInvalid();
const issue = finding(runDoctor(tmp).errors, "preference-invalid");
expect(issue.path).toBe(path);
expect(issue.message).not.toContain(path);
});
test("retired-missing-field names the file in `path` and not in `message`", () => {
const path = seedRetiredMissingField();
const issue = finding(runDoctor(tmp).errors, "retired-missing-field");
expect(issue.path).toBe(path);
expect(issue.message).toBe("preference missing field: retired_at");
expect(issue.message).not.toContain(path);
});
test("retired-invalid names the file in `path` and not in `message`", () => {
const path = seedRetiredInvalid();
const issue = finding(runDoctor(tmp).errors, "retired-invalid");
expect(issue.path).toBe(path);
expect(issue.message).not.toContain(path);
});
test("status-folder-mismatch names the file in `path` and not in `message`", () => {
const path = seedStatusFolderMismatch();
const issue = finding(runDoctor(tmp).warnings, "status-folder-mismatch");
expect(issue.path).toBe(path);
expect(issue.message).not.toContain(path);
// The structural facts the class carries stay in the sentence: they
// have no field of their own on a `DoctorIssue`.
expect(issue.message).toContain("status=retired");
expect(issue.message).toContain("folder=preferences");
});
test("all four parse-error codes still classify from the shortened message", () => {
seedPreferenceMissingField();
seedPreferenceInvalid();
seedRetiredMissingField();
seedRetiredInvalid();
const codes = runDoctor(tmp)
.errors.map((e) => e.code)
.toSorted();
expect(codes).toEqual([
"preference-invalid",
"preference-missing-field",
"retired-invalid",
"retired-missing-field",
]);
});
});