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
/**
* C1 (t_213f356b): client-supplied idempotency-key ledger.
*
* The ledger maps a client key -> content hash under
* `Brain/logs/idempotency/<YYYY-MM>.jsonl` (month-sharded JSONL,
* mirroring the continuity store's append/list model). It answers three
* outcomes: `inserted` (first time), `duplicate_match` (same key + same
* hash), and `payload_mismatch` (same key + different hash — never a
* silent overwrite).
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import {
chmodSync,
existsSync,
mkdirSync,
mkdtempSync,
readFileSync,
rmSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join } from "node:path";
import { acquireLockSync } from "../../../src/core/brain/sync-lockfile.ts";
import {
computePayloadHash,
idempotencyLogPath,
lookupKey,
REMEMBER_KEY_STATUS,
rememberKey,
} from "../../../src/core/brain/idempotency-ledger.ts";
import { CHMOD_CANNOT_DENY } from "../../helpers/platform.ts";
let vault: string;
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "o2b-idempotency-"));
// A legacy Brain/ tree: an unswitched machine (a vault without one is store-only).
mkdirSync(join(vault, "Brain"), { recursive: true });
});
afterEach(() => {
rmSync(vault, { recursive: true, force: true });
});
describe("idempotency ledger", () => {
test("first remember inserts and persists under the month shard", () => {
const r = rememberKey(vault, {
key: "client-key-1",
contentHash: "hash-a",
createdAt: "2026-05-14T10:00:00Z",
});
expect(r.status).toBe(REMEMBER_KEY_STATUS.inserted);
expect(r.record.key).toBe("client-key-1");
expect(r.record.contentHash).toBe("hash-a");
const shard = idempotencyLogPath(vault, "2026-05");
expect(existsSync(shard)).toBe(true);
expect(readFileSync(shard, "utf8")).toContain("client-key-1");
});
test("same key + same hash is a deduped no-op (no second line)", () => {
rememberKey(vault, { key: "k", contentHash: "hash-a", createdAt: "2026-05-14T10:00:00Z" });
const shard = idempotencyLogPath(vault, "2026-05");
const before = readFileSync(shard, "utf8");
const r = rememberKey(vault, {
key: "k",
contentHash: "hash-a",
createdAt: "2026-05-14T10:05:00Z",
});
expect(r.status).toBe(REMEMBER_KEY_STATUS.duplicate_match);
// No new line appended — the shard is byte-identical.
expect(readFileSync(shard, "utf8")).toBe(before);
});
test("same key + different hash reports payload_mismatch and writes nothing", () => {
rememberKey(vault, { key: "k", contentHash: "hash-a", createdAt: "2026-05-14T10:00:00Z" });
const shard = idempotencyLogPath(vault, "2026-05");
const before = readFileSync(shard, "utf8");
const r = rememberKey(vault, {
key: "k",
contentHash: "hash-b",
createdAt: "2026-05-14T10:05:00Z",
});
expect(r.status).toBe(REMEMBER_KEY_STATUS.payload_mismatch);
// The stored (original) hash is surfaced, never overwritten.
expect(r.record.contentHash).toBe("hash-a");
expect(readFileSync(shard, "utf8")).toBe(before);
});
test("lookupKey finds a stored key across shards and returns null otherwise", () => {
rememberKey(vault, {
key: "k",
contentHash: "hash-a",
createdAt: "2026-04-30T23:59:00Z",
ref: { id: "sig-2026-04-30-topic" },
});
const found = lookupKey(vault, "k");
expect(found?.contentHash).toBe("hash-a");
expect(found?.ref).toEqual({ id: "sig-2026-04-30-topic" });
expect(lookupKey(vault, "absent")).toBeNull();
});
test("a dedupe survives across a fresh read (the retry-after-crash case)", () => {
rememberKey(vault, {
key: "retry-key",
contentHash: "hash-a",
createdAt: "2026-05-14T10:00:00Z",
});
// A brand-new call (no in-memory state) still sees the prior key.
const retry = rememberKey(vault, {
key: "retry-key",
contentHash: "hash-a",
createdAt: "2026-05-14T11:00:00Z",
});
expect(retry.status).toBe(REMEMBER_KEY_STATUS.duplicate_match);
});
test("an empty key is rejected", () => {
expect(() => rememberKey(vault, { key: " ", contentHash: "hash-a" })).toThrow();
});
test("computePayloadHash is deterministic and key-order-insensitive", () => {
const a = computePayloadHash({ topic: "t", principle: "p", scope: "s" });
const b = computePayloadHash({ scope: "s", principle: "p", topic: "t" });
expect(a).toBe(b);
const c = computePayloadHash({ topic: "t", principle: "different", scope: "s" });
expect(c).not.toBe(a);
});
});
/**
* Per-device shards (who-wrote-what, Task B / t_1814b9bf). A key
* remembered on one device must be honoured on another once Syncthing
* has delivered its shard - and neither device may write the other's
* file.
*/
describe("idempotency per-device shards", () => {
const savedEnv: Record<string, string | undefined> = {};
let configHome: string;
beforeEach(() => {
configHome = mkdtempSync(join(tmpdir(), "o2b-idempotency-cfg-"));
const configPath = join(configHome, "config.yaml");
savedEnv["OPEN_SECOND_BRAIN_CONFIG"] = process.env["OPEN_SECOND_BRAIN_CONFIG"];
savedEnv["O2B_DEVICE_ID"] = process.env["O2B_DEVICE_ID"];
process.env["OPEN_SECOND_BRAIN_CONFIG"] = configPath;
delete process.env["O2B_DEVICE_ID"];
writeFileSync(configPath, `vault: ${vault}\ndevice_id: "testdev1"\n`, "utf8");
});
afterEach(() => {
rmSync(configHome, { recursive: true, force: true });
for (const key of ["OPEN_SECOND_BRAIN_CONFIG", "O2B_DEVICE_ID"]) {
const value = savedEnv[key];
if (value === undefined) delete process.env[key];
else process.env[key] = value;
}
});
test("a device with an id writes its own shard and never the bare file", () => {
rememberKey(vault, { key: "k", contentHash: "hash-a", createdAt: "2026-05-14T10:00:00Z" });
expect(existsSync(idempotencyLogPath(vault, "2026-05", "testdev1"))).toBe(true);
expect(existsSync(idempotencyLogPath(vault, "2026-05", ""))).toBe(false);
});
test("lookupKey finds a key another device remembered", () => {
const path = idempotencyLogPath(vault, "2026-05", "devb");
mkdirSync(dirname(path), { recursive: true });
writeFileSync(
path,
`${JSON.stringify({ key: "remote", contentHash: "hash-r", createdAt: "2026-05-14T09:00:00Z" })}\n`,
"utf8",
);
expect(lookupKey(vault, "remote")?.contentHash).toBe("hash-r");
});
test("a key another device remembered dedupes this device's write", () => {
const path = idempotencyLogPath(vault, "2026-05", "devb");
mkdirSync(dirname(path), { recursive: true });
writeFileSync(
path,
`${JSON.stringify({ key: "shared", contentHash: "hash-a", createdAt: "2026-05-14T09:00:00Z" })}\n`,
"utf8",
);
const r = rememberKey(vault, {
key: "shared",
contentHash: "hash-a",
createdAt: "2026-05-14T10:00:00Z",
});
expect(r.status).toBe(REMEMBER_KEY_STATUS.duplicate_match);
expect(existsSync(idempotencyLogPath(vault, "2026-05", "testdev1"))).toBe(false);
});
test("a sync-conflict copy is not a shard and is never read", () => {
const dir = dirname(idempotencyLogPath(vault, "2026-05", ""));
mkdirSync(dir, { recursive: true });
writeFileSync(
join(dir, "2026-05.sync-conflict-20260514-120000-ABCDEFG.jsonl"),
`${JSON.stringify({ key: "conflict", contentHash: "hash-c", createdAt: "2026-05-14T09:00:00Z" })}\n`,
"utf8",
);
expect(lookupKey(vault, "conflict")).toBeNull();
});
/**
* A shard this process cannot read is not an empty shard. Answering
* "never seen" for one turns a retried write into a first write, which
* is the one outcome this ledger exists to prevent.
*/
// chmod cannot deny access on Windows (read-only attribute only) or to root.
test.skipIf(CHMOD_CANNOT_DENY)("an unreadable shard is refused, not read as empty", () => {
const path = idempotencyLogPath(vault, "2026-05", "testdev1");
mkdirSync(dirname(path), { recursive: true });
writeFileSync(
path,
`${JSON.stringify({ key: "k", contentHash: "hash-a", createdAt: "2026-05-14T09:00:00Z" })}\n`,
"utf8",
);
chmodSync(path, 0o000);
try {
expect(() => lookupKey(vault, "k")).toThrow(/EACCES|EPERM/);
} finally {
chmodSync(path, 0o600);
}
});
test("the lock this device takes is on its own shard", () => {
const own = idempotencyLogPath(vault, "2026-05", "testdev1");
const handle = acquireLockSync(own);
try {
expect(() =>
rememberKey(vault, { key: "k", contentHash: "hash-a", createdAt: "2026-05-14T10:00:00Z" }),
).toThrow("lock busy");
} finally {
handle.release();
}
});
});