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
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 {
appendContinuityRecord,
appendContinuityRecords,
appendContinuitySourceInvalidation,
buildContinuityRecord,
continuityLogPath,
isCanonicalUtcTimestamp,
listContinuityRecords,
paginateContinuityRecords,
} from "../../../src/core/brain/continuity/store.ts";
import { CHMOD_CANNOT_DENY } from "../../helpers/platform.ts";
let vault: string;
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "o2b-continuity-store-"));
// 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("continuity store", () => {
test("appends redaction-safe records under the Brain continuity log", () => {
const record = appendContinuityRecord(vault, {
kind: "context_receipt",
createdAt: "2026-05-31T12:00:00Z",
sourceRefs: [{ id: "pref-alpha", path: "Brain/preferences/pref-alpha.md" }],
payload: {
query: "project setup",
text: "Keep this <private>do not persist</private> and token=secret-value",
},
});
expect(record.id).toStartWith("ctn_");
expect(record.payload).toEqual({
query: "project setup",
text: "Keep this ***PRIVATE*** and token=***REDACTED***",
});
expect(record.private).toBe(true);
expect(record.redacted).toBe(true);
const path = continuityLogPath(vault, "2026-05");
expect(existsSync(path)).toBe(true);
expect(readFileSync(path, "utf8")).toContain("context_receipt");
const listed = listContinuityRecords(vault, {
kind: "context_receipt",
sourceId: "pref-alpha",
});
expect(listed).toHaveLength(1);
expect(JSON.stringify(listed)).not.toContain("secret-value");
expect(JSON.stringify(listed)).not.toContain("do not persist");
});
test("paginates records with stable cursors", () => {
for (let index = 0; index < 3; index++) {
appendContinuityRecord(vault, {
kind: "recall_telemetry",
createdAt: `2026-05-31T12:00:0${index}Z`,
sourceRefs: [{ id: `query-${index}` }],
payload: { status: index === 2 ? "miss" : "hit", resultCount: index },
});
}
const first = paginateContinuityRecords(vault, { limit: 2 });
expect(first.records.map((record) => record.sourceRefs[0]!.id)).toEqual(["query-0", "query-1"]);
expect(first.nextCursor).not.toBeNull();
const second = paginateContinuityRecords(vault, {
limit: 2,
cursor: first.nextCursor!,
});
expect(second.records.map((record) => record.sourceRefs[0]!.id)).toEqual(["query-2"]);
expect(second.nextCursor).toBeNull();
});
test("serializes appends with the brain sync lock", () => {
const path = continuityLogPath(vault, "2026-05");
const handle = acquireLockSync(path);
try {
expect(() =>
appendContinuityRecord(vault, {
kind: "context_receipt",
createdAt: "2026-05-31T12:00:00Z",
sourceRefs: [],
payload: { event: "locked" },
}),
).toThrow("lock busy");
} finally {
handle.release();
}
const record = appendContinuityRecord(vault, {
kind: "context_receipt",
createdAt: "2026-05-31T12:00:01Z",
sourceRefs: [],
payload: { event: "unlocked" },
});
expect(record.id).toStartWith("ctn_");
});
test("records source invalidation markers without deleting history", () => {
appendContinuityRecord(vault, {
kind: "session_turn",
createdAt: "2026-05-31T12:00:00Z",
sourceRefs: [{ id: "session-a#turn-1", path: "sessions/a.jsonl" }],
payload: { role: "user", snippet: "Please remember this" },
});
const invalidation = appendContinuitySourceInvalidation(vault, {
createdAt: "2026-05-31T12:05:00Z",
source: { id: "session-a#turn-1", path: "sessions/a.jsonl" },
reason: "source-scoped forget dry run",
});
expect(invalidation.kind).toBe("source_invalidation");
const records = listContinuityRecords(vault, {
sourceId: "session-a#turn-1",
});
expect(records.map((record) => record.kind)).toEqual(["session_turn", "source_invalidation"]);
});
test("since/until shard-skip returns the same records as an unfiltered window", () => {
const months = ["2026-03", "2026-05", "2026-07", "2026-09"];
for (const month of months) {
appendContinuityRecord(vault, {
kind: "context_receipt",
createdAt: `${month}-15T12:00:00Z`,
sourceRefs: [{ id: `src-${month}` }],
payload: { query: month },
});
}
// A bounded window skips the 2026-03 and 2026-09 shards but returns
// exactly the in-window records, in ascending createdAt order.
const windowed = listContinuityRecords(vault, {
since: "2026-05-01T00:00:00Z",
until: "2026-07-31T23:59:59Z",
});
expect(windowed.map((r) => r.payload["query"])).toEqual(["2026-05", "2026-07"]);
// Boundary months are read in full: since exactly on a record's month.
const openEnded = listContinuityRecords(vault, { since: "2026-05-15T12:00:00Z" });
expect(openEnded.map((r) => r.payload["query"])).toEqual(["2026-05", "2026-07", "2026-09"]);
// No filter still reads every shard.
expect(listContinuityRecords(vault)).toHaveLength(4);
});
});
describe("continuity batch append", () => {
test("appends every record in a valid batch into the same month shard", () => {
const records = appendContinuityRecords(vault, [
{
kind: "session_turn",
createdAt: "2026-06-01T08:00:00Z",
sourceRefs: [{ id: "s#1" }],
payload: { role: "user", snippet: "one" },
},
{
kind: "session_turn",
createdAt: "2026-06-01T08:00:01Z",
sourceRefs: [{ id: "s#2" }],
payload: { role: "assistant", snippet: "two" },
},
]);
expect(records).toHaveLength(2);
const path = continuityLogPath(vault, "2026-06");
const lines = readFileSync(path, "utf8").trim().split("\n");
expect(lines).toHaveLength(2);
const listed = listContinuityRecords(vault, { kind: "session_turn" });
expect(listed.map((r) => r.sourceRefs[0]!.id)).toEqual(["s#1", "s#2"]);
});
test("an invalid record anywhere in the batch leaves the shard log unchanged", () => {
// Seed an existing record so we can prove the batch does not touch it.
appendContinuityRecord(vault, {
kind: "session_turn",
createdAt: "2026-06-01T07:00:00Z",
sourceRefs: [{ id: "pre-existing" }],
payload: { snippet: "before" },
});
const path = continuityLogPath(vault, "2026-06");
const before = readFileSync(path, "utf8");
expect(() =>
appendContinuityRecords(vault, [
{
kind: "session_turn",
createdAt: "2026-06-01T08:00:00Z",
sourceRefs: [{ id: "ok" }],
payload: { snippet: "valid" },
},
{
// Malformed createdAt → month prefix fails validation; the whole
// batch must abort before any line is written.
kind: "session_turn",
createdAt: "not-a-timestamp",
sourceRefs: [{ id: "bad" }],
payload: { snippet: "invalid" },
},
]),
).toThrow();
expect(readFileSync(path, "utf8")).toBe(before);
expect(listContinuityRecords(vault, {}).map((r) => r.sourceRefs[0]!.id)).toEqual([
"pre-existing",
]);
});
test("a single-month batch appends all lines under one lock acquisition", () => {
const path = continuityLogPath(vault, "2026-06");
const handle = acquireLockSync(path);
try {
// Lock held: the batch must fail to acquire and write nothing.
expect(() =>
appendContinuityRecords(vault, [
{
kind: "recall_telemetry",
createdAt: "2026-06-02T08:00:00Z",
sourceRefs: [{ id: "q1" }],
payload: { status: "hit" },
},
]),
).toThrow("lock busy");
} finally {
handle.release();
}
expect(existsSync(path)).toBe(false);
});
test("rejects an empty batch without writing", () => {
expect(() => appendContinuityRecords(vault, [])).toThrow();
expect(existsSync(continuityLogPath(vault, "2026-06"))).toBe(false);
});
});
describe("createdAt validation at the store boundary", () => {
const ACCEPT: string[] = [
"2026-05-31T12:00:00Z", // second precision
"2026-06-15T10:00:00.000Z", // millisecond precision
"2026-06-15T10:00:00.5Z", // sub-second, ≤3 digits
"2024-02-29T00:00:00Z", // real leap day
"2026-12-31T23:59:59.999Z",
];
const REJECT: Array<[string, unknown]> = [
["month out of range shards into junk", "2026-13-01T00:00:00Z"],
["day out of range for the month", "2026-02-30T00:00:00Z"],
["Feb 29 on a non-leap year", "2026-02-29T00:00:00Z"],
["numeric offset instead of Z mis-sorts", "2026-07-06T15:00:00+03:00"],
["no zone designator", "2026-07-06T15:00:00"],
["date only", "2026-07-06"],
["month prefix only", "2026-07"],
["free text", "not-a-timestamp"],
["empty string", ""],
["lowercase z", "2026-07-06T15:00:00z"],
["non-string number", 1_783_350_000_000],
["null", null],
];
test.each(ACCEPT)("accepts %s", (value) => {
expect(isCanonicalUtcTimestamp(value)).toBe(true);
const record = appendContinuityRecord(vault, {
kind: "session_turn",
createdAt: value,
sourceRefs: [{ id: "ok" }],
payload: { snippet: "valid" },
});
expect(record.createdAt).toBe(value);
});
test.each(REJECT)("rejects %s", (_label, value) => {
expect(isCanonicalUtcTimestamp(value)).toBe(false);
expect(() =>
appendContinuityRecord(vault, {
kind: "session_turn",
// eslint-disable-next-line @typescript-eslint/no-explicit-any
createdAt: value as any,
sourceRefs: [{ id: "bad" }],
payload: { snippet: "invalid" },
}),
).toThrow(/invalid continuity createdAt/);
// Nothing was written: no shard exists for a rejected timestamp.
expect(listContinuityRecords(vault, {})).toHaveLength(0);
});
});
/**
* Per-device shards (who-wrote-what, Task B / t_1814b9bf). Two devices
* syncing one vault must not append to the same month file, and a reader
* on either device must see the same merged sequence.
*/
describe("continuity per-device shards", () => {
const savedEnv: Record<string, string | undefined> = {};
let configHome: string;
beforeEach(() => {
configHome = mkdtempSync(join(tmpdir(), "o2b-continuity-shard-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;
}
});
function record(createdAt: string, snippet: string) {
return buildContinuityRecord({
kind: "session_turn",
createdAt,
sourceRefs: [{ id: snippet }],
payload: { snippet },
});
}
/** Write a shard directly, standing in for a file Syncthing delivered. */
function writeShard(month: string, shardId: string, snippets: ReadonlyArray<string>): void {
const path = continuityLogPath(vault, month, shardId);
mkdirSync(dirname(path), { recursive: true });
writeFileSync(
path,
snippets.map((s) => `${JSON.stringify(record(`${month}-01T10:00:0${s[0]}Z`, s))}\n`).join(""),
"utf8",
);
}
test("a device with an id writes its own shard and never the bare file", () => {
appendContinuityRecord(vault, {
kind: "session_turn",
createdAt: "2026-06-01T10:00:00Z",
payload: { snippet: "one" },
});
expect(existsSync(continuityLogPath(vault, "2026-06", "testdev1"))).toBe(true);
expect(existsSync(continuityLogPath(vault, "2026-06", ""))).toBe(false);
});
test("a batch append lands in the device shard too", () => {
appendContinuityRecords(vault, [
{ kind: "session_turn", createdAt: "2026-06-01T10:00:00Z", payload: { snippet: "a" } },
{ kind: "session_turn", createdAt: "2026-06-01T10:00:01Z", payload: { snippet: "b" } },
]);
const raw = readFileSync(continuityLogPath(vault, "2026-06", "testdev1"), "utf8");
expect(raw.trim().split("\n")).toHaveLength(2);
expect(existsSync(continuityLogPath(vault, "2026-06", ""))).toBe(false);
});
test("the reader merges the bare file and every device shard in one order", () => {
writeShard("2026-06", "", ["0-legacy"]);
writeShard("2026-06", "devb", ["2-otherdev"]);
writeShard("2026-06", "testdev1", ["1-mine"]);
expect(listContinuityRecords(vault, {}).map((r) => r.payload["snippet"])).toEqual([
"0-legacy",
"1-mine",
"2-otherdev",
]);
});
test("a sync-conflict copy is not a shard and is never merged", () => {
writeShard("2026-06", "testdev1", ["1-mine"]);
const dir = dirname(continuityLogPath(vault, "2026-06", ""));
writeFileSync(
join(dir, "2026-06.sync-conflict-20260601-120000-ABCDEFG.jsonl"),
`${JSON.stringify(record("2026-06-01T09:00:00Z", "conflict"))}\n`,
"utf8",
);
expect(listContinuityRecords(vault, {}).map((r) => r.payload["snippet"])).toEqual(["1-mine"]);
});
test("the month range-skip reads the parsed base of a sharded name", () => {
writeShard("2026-06", "testdev1", ["1-mine"]);
writeShard("2026-05", "testdev1", ["0-may"]);
const listed = listContinuityRecords(vault, { since: "2026-06-01T00:00:00Z" });
expect(listed.map((r) => r.payload["snippet"])).toEqual(["1-mine"]);
});
/**
* A shard this process cannot read is not an empty shard: a listing
* that silently drops it reports a shorter history as if it were the
* whole one.
*/
test("a line that parses but is no record is skipped, not read as one", () => {
writeShard("2026-06", "testdev1", ["1-mine"]);
const path = continuityLogPath(vault, "2026-06", "testdev1");
writeFileSync(path, 'null\n42\n"text"\n{"kind":"session_turn"}\n', { flag: "a" });
expect(listContinuityRecords(vault, {}).map((r) => r.payload["snippet"])).toEqual(["1-mine"]);
});
// chmod cannot deny access on Windows (read-only attribute only) or to root.
test.skipIf(CHMOD_CANNOT_DENY)("an unreadable shard is refused, not listed as absent", () => {
writeShard("2026-06", "testdev1", ["1-mine"]);
const path = continuityLogPath(vault, "2026-06", "testdev1");
chmodSync(path, 0o000);
try {
expect(() => listContinuityRecords(vault, {})).toThrow(/EACCES|EPERM/);
} finally {
chmodSync(path, 0o600);
}
});
});