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
/**
* The note-write reader (who-wrote-what, Task A / t_662f4e82).
*
* The filters, the newest-first order, and the one fact that cannot come
* from the payload: the device, which the reader takes off the log shard
* the entry was read from.
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join } from "node:path";
import { appendLogEvent } from "../../../../src/core/brain/log.ts";
import { listNoteWrites } from "../../../../src/core/brain/notes/write-log.ts";
import { NOTE_WRITE_OP } from "../../../../src/core/brain/notes/write-record.ts";
import { BRAIN_LOG_EVENT_KIND } from "../../../../src/core/brain/types.ts";
let vault: string;
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "o2b-write-log-"));
// 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 }));
interface SeedInput {
readonly timestamp: string;
readonly agent: string;
readonly target: string;
readonly op?: string;
readonly deviceId?: string;
readonly writeId?: string;
}
function seed(input: SeedInput): void {
appendLogEvent(
vault,
{
timestamp: input.timestamp,
eventType: BRAIN_LOG_EVENT_KIND.noteWrite,
agent: input.agent,
body: {
write_id: input.writeId ?? `nw_${input.timestamp.replace(/\D/g, "")}_${input.target}`,
op: input.op ?? NOTE_WRITE_OP.update,
target: input.target,
hash_before: "a".repeat(64),
hash_after: "b".repeat(64),
bytes_before: "10",
bytes_after: "20",
agent: input.agent,
},
},
{ deviceId: input.deviceId ?? "" },
);
}
describe("listNoteWrites", () => {
test("returns every recorded write newest first", () => {
seed({ timestamp: "2026-03-04T01:00:00Z", agent: "a", target: "One.md" });
seed({ timestamp: "2026-03-05T02:00:00Z", agent: "b", target: "Two.md" });
seed({ timestamp: "2026-03-04T03:00:00Z", agent: "a", target: "Three.md" });
const { writes, warnings } = listNoteWrites(vault);
expect(warnings).toEqual([]);
expect(writes.map((w) => w.target)).toEqual(["Two.md", "Three.md", "One.md"]);
});
test("projects the recorded fields, parsing the byte counts back to numbers", () => {
seed({
timestamp: "2026-03-04T01:00:00Z",
agent: "agent-a",
target: "Notes/One.md",
op: NOTE_WRITE_OP.append,
writeId: "nw_20260304010000_0123456789abcdef",
});
const record = listNoteWrites(vault).writes[0]!;
expect(record.write_id).toBe("nw_20260304010000_0123456789abcdef");
expect(record.op).toBe(NOTE_WRITE_OP.append);
expect(record.target).toBe("Notes/One.md");
expect(record.agent).toBe("agent-a");
expect(record.bytes_before).toBe(10);
expect(record.bytes_after).toBe(20);
expect(record.hash_before).toBe("a".repeat(64));
// The appender stamps the channel; the reader carries it through.
expect(record.origin_channel).not.toBeNull();
});
test("the device comes off the shard the entry was read from", () => {
seed({ timestamp: "2026-03-04T01:00:00Z", agent: "a", target: "One.md", deviceId: "laptop" });
seed({ timestamp: "2026-03-04T02:00:00Z", agent: "a", target: "Two.md", deviceId: "desktop" });
seed({ timestamp: "2026-03-04T03:00:00Z", agent: "a", target: "Three.md" });
const byTarget = new Map(listNoteWrites(vault).writes.map((w) => [w.target, w.device]));
expect(byTarget.get("One.md")).toBe("laptop");
expect(byTarget.get("Two.md")).toBe("desktop");
// The legacy un-sharded pair is the empty device, which is an answer.
expect(byTarget.get("Three.md")).toBe("");
});
test("filters by agent, device, path and op", () => {
seed({ timestamp: "2026-03-04T01:00:00Z", agent: "a", target: "One.md", deviceId: "laptop" });
seed({ timestamp: "2026-03-04T02:00:00Z", agent: "b", target: "One.md", deviceId: "laptop" });
seed({
timestamp: "2026-03-04T03:00:00Z",
agent: "a",
target: "Two.md",
deviceId: "desktop",
op: NOTE_WRITE_OP.create,
});
expect(listNoteWrites(vault, { agent: "a" }).writes.map((w) => w.target)).toEqual([
"Two.md",
"One.md",
]);
expect(listNoteWrites(vault, { device: "desktop" }).writes.map((w) => w.target)).toEqual([
"Two.md",
]);
expect(listNoteWrites(vault, { path: "One.md" }).writes.map((w) => w.agent)).toEqual([
"b",
"a",
]);
expect(listNoteWrites(vault, { op: NOTE_WRITE_OP.create }).writes).toHaveLength(1);
expect(listNoteWrites(vault, { agent: "a", path: "One.md" }).writes).toHaveLength(1);
});
test("a bare --until date covers the whole day it names", () => {
seed({ timestamp: "2026-03-04T23:59:00Z", agent: "a", target: "Late.md" });
seed({ timestamp: "2026-03-05T00:00:01Z", agent: "a", target: "Next.md" });
expect(listNoteWrites(vault, { until: "2026-03-04" }).writes.map((w) => w.target)).toEqual([
"Late.md",
]);
expect(listNoteWrites(vault, { since: "2026-03-05" }).writes.map((w) => w.target)).toEqual([
"Next.md",
]);
expect(
listNoteWrites(vault, { since: "2026-03-04T23:59:30Z" }).writes.map((w) => w.target),
).toEqual(["Next.md"]);
});
test("a whole-second until excludes a fractional foreign entry, and since includes it", () => {
// The writer stamps whole seconds, but a hand-appended JSONL line can
// carry sub-second precision, and "…56.789Z" sorts BEFORE "…56Z" in a
// plain string compare ('.' < 'Z') - so an until at second 56 wrongly
// admitted the entry and a since at second 56 wrongly dropped it.
const abs = join(vault, "Brain", "log", "2026-03-04.jsonl");
const row = JSON.stringify({
ts: "2026-03-04T12:34:56.789Z",
kind: "note-write",
payload: {
write_id: "nw_fractional",
op: "update",
target: "Fractional.md",
hash_before: "a".repeat(64),
hash_after: "b".repeat(64),
bytes_before: "1",
bytes_after: "2",
agent: "foreign",
},
});
mkdirSync(dirname(abs), { recursive: true });
writeFileSync(abs, `${row}\n`, "utf8");
expect(listNoteWrites(vault, { until: "2026-03-04T12:34:56Z" }).writes).toEqual([]);
expect(
listNoteWrites(vault, { since: "2026-03-04T12:34:56Z" }).writes.map((w) => w.write_id),
).toEqual(["nw_fractional"]);
});
test("a fractional bound orders a whole-second log entry as an instant", () => {
seed({ timestamp: "2026-03-04T12:34:56Z", agent: "a", target: "Whole.md" });
expect(
listNoteWrites(vault, { until: "2026-03-04T12:34:56.789Z" }).writes.map((w) => w.target),
).toEqual(["Whole.md"]);
expect(listNoteWrites(vault, { since: "2026-03-04T12:34:56.789Z" }).writes).toEqual([]);
});
test("events of other kinds are not note writes", () => {
appendLogEvent(
vault,
{
timestamp: "2026-03-04T01:00:00Z",
eventType: BRAIN_LOG_EVENT_KIND.note,
agent: "a",
body: { text: "a milestone" },
},
{ deviceId: "" },
);
expect(listNoteWrites(vault).writes).toEqual([]);
});
test("a note-write line missing its target is not projected as a blank row", () => {
appendLogEvent(
vault,
{
timestamp: "2026-03-04T01:00:00Z",
eventType: BRAIN_LOG_EVENT_KIND.noteWrite,
agent: "a",
body: { write_id: "nw_1_x", op: NOTE_WRITE_OP.update },
},
{ deviceId: "" },
);
expect(listNoteWrites(vault).writes).toEqual([]);
});
test("an empty vault reports no writes and no warnings", () => {
expect(listNoteWrites(vault)).toEqual({ writes: [], warnings: [] });
});
});