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
/**
* `writePreferenceTxn` - the single chokepoint that wraps every
* preference write. Acquires the sync lock, re-reads the current
* file state, runs an expectations chain that can raise typed
* `BrainCollisionError`, then mutates via `writeFrontmatterAtomic`.
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { brainDirs, preferencePath } from "../../../src/core/brain/paths.ts";
import { parsePreference } from "../../../src/core/brain/preference.ts";
import {
BrainCollisionError,
BRAIN_COLLISION_KIND,
noRevisionRewind,
writePreferenceTxn,
type WritePreferenceExpectation,
} from "../../../src/core/brain/preference-txn.ts";
import { acquireLockSync } from "../../../src/core/brain/sync-lockfile.ts";
import { BRAIN_PREFERENCE_STATUS } from "../../../src/core/brain/types.ts";
let tmpRoot: string;
let vault: string;
beforeEach(() => {
tmpRoot = mkdtempSync(join(tmpdir(), "osb-pref-txn-"));
vault = tmpRoot;
// Ensure Brain/preferences/ exists so the writer can drop the file.
require("node:fs").mkdirSync(brainDirs(vault).preferences, {
recursive: true,
});
});
afterEach(() => {
if (tmpRoot) rmSync(tmpRoot, { recursive: true, force: true });
});
const baseInput = (overrides: Record<string, unknown> = {}) => ({
slug: "test-rule",
topic: "test-topic",
principle: "do the right thing in production code",
created_at: "2026-05-26T12:00:00Z",
unconfirmed_until: "2026-06-02T12:00:00Z",
status: BRAIN_PREFERENCE_STATUS.unconfirmed,
evidenced_by: [] as ReadonlyArray<string>,
...overrides,
});
describe("BRAIN_COLLISION_KIND", () => {
test("exposes the four discriminant string values", () => {
expect(BRAIN_COLLISION_KIND.staleUpdate).toBe("StaleUpdate");
expect(BRAIN_COLLISION_KIND.unsafeShrink).toBe("UnsafeShrink");
expect(BRAIN_COLLISION_KIND.sourceLock).toBe("SourceLock");
expect(BRAIN_COLLISION_KIND.duplicateWrite).toBe("DuplicateWrite");
});
});
describe("BrainCollisionError", () => {
test("kind field is preserved on instances", () => {
const err = new BrainCollisionError(BRAIN_COLLISION_KIND.staleUpdate, "test message");
expect(err).toBeInstanceOf(Error);
expect(err.kind).toBe("StaleUpdate");
expect(err.name).toBe("BrainCollisionError");
expect(err.message).toBe("test message");
});
});
describe("writePreferenceTxn", () => {
test("with empty expectations writes a preference identical to writePreference", () => {
const result = writePreferenceTxn(vault, baseInput(), [], {});
expect(result.id).toBe("pref-test-rule");
expect(existsSync(result.path)).toBe(true);
// Lock file must be cleaned up after the txn returns.
expect(existsSync(result.path + ".lock")).toBe(false);
const parsed = parsePreference(result.path);
expect(parsed.principle).toBe("do the right thing in production code");
expect(parsed.topic).toBe("test-topic");
});
test("raises BrainCollisionError(SourceLock) when the lock is already held", () => {
const path = preferencePath(vault, "held-rule");
const handle = acquireLockSync(path);
try {
let caught: unknown;
try {
writePreferenceTxn(vault, baseInput({ slug: "held-rule" }), [], {});
} catch (err) {
caught = err;
}
expect(caught).toBeInstanceOf(BrainCollisionError);
expect((caught as BrainCollisionError).kind).toBe("SourceLock");
} finally {
handle.release();
}
});
test("runs expectations chain in order; first failure short-circuits", () => {
// First write to seed the on-disk state.
writePreferenceTxn(vault, baseInput({ slug: "chain-rule" }), [], {});
const calls: string[] = [];
const ok: WritePreferenceExpectation = () => {
calls.push("ok");
};
const fail: WritePreferenceExpectation = () => {
calls.push("fail");
throw new BrainCollisionError(BRAIN_COLLISION_KIND.staleUpdate, "deliberate failure");
};
const never: WritePreferenceExpectation = () => {
calls.push("never");
};
let caught: unknown;
try {
writePreferenceTxn(
vault,
baseInput({
slug: "chain-rule",
principle: "updated principle text",
}),
[ok, fail, never],
{ overwrite: true },
);
} catch (err) {
caught = err;
}
expect(caught).toBeInstanceOf(BrainCollisionError);
expect((caught as BrainCollisionError).kind).toBe("StaleUpdate");
expect(calls).toEqual(["ok", "fail"]); // `never` was not invoked
});
test("releases the lock even when an expectation throws", () => {
writePreferenceTxn(vault, baseInput({ slug: "release-rule" }), [], {});
const failingExpectation: WritePreferenceExpectation = () => {
throw new BrainCollisionError(BRAIN_COLLISION_KIND.duplicateWrite, "blocked");
};
let caught: unknown;
try {
writePreferenceTxn(vault, baseInput({ slug: "release-rule" }), [failingExpectation], {
overwrite: true,
});
} catch (err) {
caught = err;
}
expect(caught).toBeInstanceOf(BrainCollisionError);
// Lock must be released even though the write was aborted.
const lockPath = preferencePath(vault, "release-rule") + ".lock";
expect(existsSync(lockPath)).toBe(false);
// A follow-up write with empty expectations must succeed.
const ok = writePreferenceTxn(vault, baseInput({ slug: "release-rule" }), [], {
overwrite: true,
});
expect(existsSync(ok.path)).toBe(true);
});
test("expectation receives the existing preference when overwriting", () => {
writePreferenceTxn(
vault,
baseInput({ slug: "ctx-rule", principle: "original principle text" }),
[],
{},
);
const observed: { principle: string | null } = { principle: null };
const inspect: WritePreferenceExpectation = (ctx) => {
observed.principle = ctx.existing?.principle ?? null;
};
writePreferenceTxn(
vault,
baseInput({ slug: "ctx-rule", principle: "replacement principle text" }),
[inspect],
{ overwrite: true },
);
expect(observed.principle).toBe("original principle text");
});
test("expectation context shows existing=null on first write", () => {
const observed: { existing: unknown } = { existing: "unset" };
const inspect: WritePreferenceExpectation = (ctx) => {
observed.existing = ctx.existing;
};
writePreferenceTxn(vault, baseInput({ slug: "first-rule" }), [inspect], {});
expect(observed.existing).toBeNull();
});
test("file bytes match what writePreference would have produced (no txn overhead)", () => {
const result = writePreferenceTxn(
vault,
baseInput({ slug: "bytewise-rule", principle: "exact bytes please" }),
[],
{},
);
const text = readFileSync(result.path, "utf8");
expect(text).toContain("principle: exact bytes please");
expect(text).toContain("kind: brain-preference");
expect(text).toContain("_status: unconfirmed");
});
});
/**
* `noRevisionRewind` (bank-bundle restore, unit E2). A restore replays a
* record captured at some revision into a vault that has kept moving.
* Without a gate the replay is decided by whichever write lands last,
* which is the one thing a restore must never do to a rule the operator
* has since edited.
*/
describe("noRevisionRewind", () => {
test("allows a first write, whatever revision the incoming record carries", () => {
expect(() =>
writePreferenceTxn(vault, baseInput({ slug: "fresh-rule", revision: 5 }), [
noRevisionRewind(5),
]),
).not.toThrow();
expect(parsePreference(preferencePath(vault, "fresh-rule")).revision).toBe(5);
});
test("allows an incoming record that is ahead of the on-disk one", () => {
writePreferenceTxn(vault, baseInput({ slug: "ahead-rule", revision: 2 }), []);
writePreferenceTxn(
vault,
baseInput({ slug: "ahead-rule", revision: 8, principle: "the newer text of the rule" }),
[noRevisionRewind(8)],
{ overwrite: true },
);
expect(parsePreference(preferencePath(vault, "ahead-rule")).revision).toBe(8);
});
test("refuses a rewind with the StaleUpdate discriminant", () => {
writePreferenceTxn(vault, baseInput({ slug: "rewind-rule", revision: 9 }), []);
let caught: unknown;
try {
writePreferenceTxn(
vault,
baseInput({ slug: "rewind-rule", revision: 4, principle: "an older text of the rule" }),
[noRevisionRewind(4)],
{ overwrite: true },
);
} catch (exc) {
caught = exc;
}
expect(caught).toBeInstanceOf(BrainCollisionError);
expect((caught as BrainCollisionError).kind).toBe(BRAIN_COLLISION_KIND.staleUpdate);
expect(parsePreference(preferencePath(vault, "rewind-rule")).principle).toBe(
baseInput().principle as string,
);
});
test("refuses divergent content at an equal revision", () => {
writePreferenceTxn(vault, baseInput({ slug: "diverged-rule", revision: 3 }), []);
expect(() =>
writePreferenceTxn(
vault,
baseInput({ slug: "diverged-rule", revision: 3, principle: "a different text entirely" }),
[noRevisionRewind(3)],
{ overwrite: true },
),
).toThrow(BrainCollisionError);
});
test("accepts an identical record at an equal revision (a replayed restore)", () => {
writePreferenceTxn(vault, baseInput({ slug: "replay-rule", revision: 3 }), []);
expect(() =>
writePreferenceTxn(
vault,
baseInput({ slug: "replay-rule", revision: 3 }),
[noRevisionRewind(3)],
{ overwrite: true },
),
).not.toThrow();
});
});