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
/**
* Topic pages, reports and sources in the human view (task 3.2, spec
* `topics`): `topics/<date>-<slug>/topic.md` rendered through the phase 2
* render protocol in the fixed section order, the page budget with its
* companion archive, a rename that moves the folder and keeps the id, the
* user's edits landing as human topic records, and `reports/` and
* `sources/` pages from their lane entries. Snapshots in English and
* Russian.
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
import { join } from "node:path";
import { readPartition } from "../../../src/core/store/state-digest.ts";
import type { StoreHandle } from "../../../src/core/store/store-open.ts";
import { newUlid } from "../../../src/core/store/ulid.ts";
import { foldTopics } from "../../../src/core/topics/fold.ts";
import { runViewPass } from "../../../src/core/view/render.ts";
import { claimViewWriter } from "../../../src/core/view/writer.ts";
import { makeMachines, type Machines } from "./fixtures/machines.ts";
import { seedLaneEntry, seedLaneRemove, seedSetting, seedTopicRecord } from "./fixtures/seed.ts";
const T0 = Date.UTC(2026, 10, 2, 9, 0, 0);
let clock = T0;
const now = () => clock;
let m: Machines;
let a: StoreHandle;
let topic: string;
let other: string;
beforeEach(() => {
clock = T0;
m = makeMachines(["dev-a", "dev-b"]);
a = m.open("dev-a");
topic = newUlid(T0);
other = newUlid(T0 + 1);
});
afterEach(() => m.cleanup());
type Opts = Parameters<typeof seedTopicRecord>[5] & { topic?: string; on?: StoreHandle };
function rec(kind: string, body: Record<string, unknown>, opts: Opts = {}): string {
clock += 60_000;
return seedTopicRecord(opts.on ?? a, clock, kind, opts.topic ?? topic, body, opts);
}
function createTopic(extra: Record<string, unknown> = {}, opts: Opts = {}): void {
rec(
"topic-create",
{
title: "Brain store",
scope: "project:o2b",
goal: "Move machine data out of the vault",
...extra,
},
{ authority: "human", ...opts },
);
}
function render(passes = 2): void {
claimViewWriter(a, { agent: "t", now });
for (let i = 0; i < passes; i++) {
clock += 1000;
runViewPass(a, { target: m.view("dev-a"), vault: null, agent: "t", now });
}
}
const view = (rel = "") => join(m.view("dev-a"), ...rel.split("/").filter(Boolean));
function page(rel: string): string {
return readFileSync(view(rel), "utf8").replaceAll(a.storeId, "<store>").replaceAll(topic, "<id>");
}
const topicDir = "topics/2026-11-02-brain-store";
function seedFull(): void {
createTopic({ description: "Store outside the vault" });
rec("topic-create", { title: "Docs", scope: "project:o2b" }, { topic: other });
rec("milestone", { item: "m1", text: "Store core" });
rec("milestone", { item: "m2", text: "Migration" });
rec("milestone", { item: "m3", text: "Topics" });
rec("milestone-done", { milestone: "m1", evidence: "PR 289 merged" });
rec("milestone-done", { milestone: "m2" }, { authority: "model" });
rec("decision", { text: "Monthly shards per device", serves: ["m1"] });
rec("open-question", { text: "Where do phones get the view?" });
rec("log-entry", { text: "Ran the tests and they passed", class: "routine" });
rec("log-entry", { text: "Sync conflicts on pinned.md", class: "blocker" });
rec("log-entry", { text: "One file per writer", class: "rejected", reason: "devices churn" });
rec("topic-goal", { goal: "Ship it all" }, { agent: "planner" });
rec("link", { to: other });
}
describe("topic pages", () => {
test("a new topic: title, description, Status: Active, the goal and related, no empty section", () => {
createTopic();
render();
expect(page(`${topicDir}/topic.md`)).toBe(
[
`<!-- open-second-brain-view store=<store> page=${topicDir}/topic.md topic=<id> -->`,
"",
"# Brain store",
"",
"No description yet.",
"",
"Status: Active",
"",
"## Goal",
"",
"Move machine data out of the vault",
"",
"## Related",
"",
"- Project: o2b",
"",
].join("\n"),
);
});
test("English snapshot: fixed section order, earned log only, proposals as open questions", () => {
seedFull();
render();
expect(page(`${topicDir}/topic.md`)).toBe(
[
`<!-- open-second-brain-view store=<store> page=${topicDir}/topic.md topic=<id> -->`,
"",
"# Brain store",
"",
"Store outside the vault",
"",
"Status: Active",
"",
"## Goal",
"",
"Move machine data out of the vault",
"",
"## Milestones",
"",
"- [ ] Migration (looks done, confirm)",
"- [ ] Topics",
"- [x] Store core (done 2026-11-02)",
"",
"## Decisions",
"",
"- Monthly shards per device (serves: Store core)",
"",
"## Open questions",
"",
"- Where do phones get the view?",
"- Goal proposed by planner: Ship it all",
"",
"## Log",
"",
"- 2026-11-02, rejected approach: One file per writer, because devices churn",
"- 2026-11-02, blocker: Sync conflicts on pinned.md",
"",
"## Related",
"",
"- Project: o2b",
"- [Docs](../2026-11-02-docs/topic.md)",
"",
].join("\n"),
);
});
test("Russian snapshot: generated prose in Russian, quoted lines as written", () => {
seedSetting(a, T0, "view.language", "ru");
seedFull();
render();
const text = page(`${topicDir}/topic.md`);
expect(text.split("\n").slice(6)).toEqual([
"Статус: Активна",
"",
"## Цель",
"",
"Move machine data out of the vault",
"",
"## Вехи",
"",
"- [ ] Migration (похоже, готово, подтвердите)",
"- [ ] Topics",
"- [x] Store core (готово 2026-11-02)",
"",
"## Решения",
"",
"- Monthly shards per device (служит: Store core)",
"",
"## Открытые вопросы",
"",
"- Where do phones get the view?",
"- Цель, предложенная planner: Ship it all",
"",
"## Журнал",
"",
"- 2026-11-02, отвергнутый подход: One file per writer, потому что devices churn",
"- 2026-11-02, блокер: Sync conflicts on pinned.md",
"",
"## Связанное",
"",
"- Проект: o2b",
"- [Docs](../2026-11-02-docs/topic.md)",
"",
]);
});
test("budget overflow: the oldest done milestones and log entries move to archive.md", () => {
createTopic();
for (let i = 1; i <= 12; i++) {
rec("milestone", { item: `m${i}`, text: `Milestone ${i}` });
rec("milestone-done", { milestone: `m${i}` }, { authority: "human" });
}
for (let i = 1; i <= 17; i++) rec("log-entry", { text: `Blocker ${i}`, class: "blocker" });
render();
const main = page(`${topicDir}/topic.md`);
expect(main.match(/^- \[x\]/gm)!.length).toBe(10);
expect(main.match(/, blocker: /g)!.length).toBe(15);
expect(main).not.toContain("Milestone 1 ");
expect(main).not.toContain("Blocker 2\n");
expect(main.trimEnd().endsWith("- [Older entries](archive.md)")).toBe(true);
expect(page(`${topicDir}/archive.md`)).toBe(
[
`<!-- open-second-brain-view store=<store> page=${topicDir}/archive.md topic=<id> -->`,
"",
"# Brain store: archive",
"",
"Entries that moved off the topic page, newest first.",
"",
"[Back to the topic](topic.md)",
"",
"## Milestones",
"",
"- [x] Milestone 2 (done 2026-11-02)",
"- [x] Milestone 1 (done 2026-11-02)",
"",
"## Log",
"",
"- 2026-11-02, blocker: Blocker 2",
"- 2026-11-02, blocker: Blocker 1",
"",
].join("\n"),
);
});
test("a rename moves the folder, keeps the id and takes the user's companion files along", () => {
createTopic();
rec("decision", { text: "Keep JSONL" });
render();
writeFileSync(view(`${topicDir}/notes.md`), "my notes\n");
rec("topic-rename", { title: "Store and topics" }, { authority: "human" });
render(1);
const moved = "topics/2026-11-02-store-and-topics";
expect(existsSync(view(topicDir))).toBe(false);
expect(readdirSync(view(moved)).toSorted()).toEqual(["notes.md", "topic.md"]);
const text = page(`${moved}/topic.md`);
expect(text).toContain("topic=<id> -->");
expect(text).toContain("# Store and topics");
expect(text).toContain("- Keep JSONL");
});
test("the user's goal on the page wins, and a later agent goal shows as its open question", () => {
createTopic();
render();
const path = view(`${topicDir}/topic.md`);
writeFileSync(
path,
readFileSync(path, "utf8").replace("Move machine data out of the vault", "Ship phase 3"),
);
render(1);
rec("topic-goal", { goal: "Ship everything at once" }, { agent: "planner" });
render(1);
const goals = readPartition(join(m.root("dev-a"), "shared"))
.flatMap((s) => s.records)
.filter((r) => r.kind === "topic-goal")
.map((r) => [r.body["authority"], r.body["goal"], r.topic]);
expect(goals).toEqual([
["human", "Ship phase 3", topic],
["agent", "Ship everything at once", topic],
]);
const text = page(`${topicDir}/topic.md`);
expect(text).toContain("## Goal\n\nShip phase 3\n");
expect(text).toContain("- Goal proposed by planner: Ship everything at once");
});
test("an item the user deletes or adds on the page becomes a human topic record", () => {
createTopic();
rec("decision", { item: "d1", text: "Keep JSONL" });
rec("decision", { item: "d2", text: "Use SQLite" });
render();
const path = view(`${topicDir}/topic.md`);
const edit = (from: string, to: string): void => {
writeFileSync(path, readFileSync(path, "utf8").replace(from, to));
render(1);
};
edit("- Keep JSONL\n", "");
edit("- Use SQLite\n", "- Use SQLite\n- Mirror nothing to phones\n");
const records = readPartition(join(m.root("dev-a"), "shared")).flatMap((s) => s.records);
const fold = foldTopics(records).topics.get(topic)!;
expect(fold.items.map((i) => [i.text, i.author.authority])).toEqual([
["Use SQLite", "agent"],
["Mirror nothing to phones", "human"],
]);
expect(page(`${topicDir}/topic.md`)).toContain(
"## Decisions\n\n- Mirror nothing to phones\n- Use SQLite\n",
);
});
test("a milestone unticked on the page is open again on the next render", () => {
createTopic();
rec("milestone", { item: "m1", text: "Store core" });
rec("milestone-done", { milestone: "m1" }, { authority: "human" });
render();
const path = view(`${topicDir}/topic.md`);
writeFileSync(
path,
readFileSync(path, "utf8").replace("- [x] Store core (done 2026-11-02)", "- [ ] Store core"),
);
render(2);
expect(page(`${topicDir}/topic.md`)).toContain("## Milestones\n\n- [ ] Store core\n");
});
test("two machines' events for one topic land on one page, with no conflict copy", () => {
createTopic();
const b = m.open("dev-b");
rec("log-entry", { text: "Found on A", class: "blocker" });
rec("log-entry", { text: "Found on B", class: "reframing" }, { on: b });
render();
m.sync();
render();
expect(page(`${topicDir}/topic.md`)).toContain(
"## Log\n\n- 2026-11-02, reframing: Found on B\n- 2026-11-02, blocker: Found on A\n",
);
expect(readdirSync(view(topicDir))).toEqual(["topic.md"]);
});
test("a merged topic's page is removed; its items and name show on the topic it joined", () => {
createTopic();
rec(
"topic-create",
{ title: "Docs", scope: "project:o2b" },
{ topic: other, authority: "human" },
);
rec("decision", { text: "Write the guide" }, { topic: other });
render();
expect(existsSync(view("topics/2026-11-02-docs/topic.md"))).toBe(true);
rec("merge", { into: topic }, { topic: other, authority: "human" });
render(1);
expect(existsSync(view("topics/2026-11-02-docs"))).toBe(false);
const text = page(`${topicDir}/topic.md`);
expect(text).toContain("- Write the guide");
expect(text).toContain("- Merged from: Docs");
});
test("a folder taken by a title that ends in another topic's id tail is never shared", () => {
const tail = "01KA0000000000000000ABCDEF";
rec(
"topic-create",
{ title: "alpha-abcdef", scope: "project:o2b" },
{ topic: newUlid(T0 + 5), authority: "human" },
);
rec(
"topic-create",
{ title: "alpha", scope: "project:o2b" },
{ topic: newUlid(T0 + 6), authority: "human" },
);
rec(
"topic-create",
{ title: "alpha", scope: "project:o2b" },
{ topic: tail, authority: "human" },
);
render();
expect(readdirSync(view("topics"))).toHaveLength(3);
});
test("a private topic and a shared record carrying a private region stay off the view", () => {
rec(
"topic-create",
{ title: "Health", scope: "personal" },
{ partition: "private", topic: other },
);
createTopic();
rec("decision", { text: "Ask <private>Dr. X</private> first" });
render();
expect(readdirSync(view("topics"))).toEqual(["2026-11-02-brain-store"]);
expect(page(`${topicDir}/topic.md`)).not.toContain("Dr. X");
});
});
describe("report and source pages", () => {
test("ids that differ only in case render one page, and a device name renders none", () => {
for (const entry of ["2026-11-02-vector", "2026-11-02-Vector", "con", "nul.txt"]) {
seedLaneEntry(a, (clock += 1000), "reports", entry, { title: entry }, `Body of ${entry}.`);
}
render();
expect(readdirSync(view("reports"))).toEqual(["2026-11-02-Vector.md"]);
});
test("a report and a source summary render from their lane entries; a removed one goes", () => {
seedLaneEntry(
a,
T0,
"reports",
"2026-11-02-vector-stores",
{ title: "Vector stores", report_date: "2026-11-02" },
"# Vector stores\n\n## Findings\n\n- SQLite is enough (cites: [[notes/sqlite|SQLite notes]])\n",
);
seedLaneEntry(
a,
T0 + 1,
"sources",
"src-paper-abc123",
{ source_path: "Papers/hlc.pdf", updated_at: "2026-11-03T10:00:00Z" },
"Hybrid logical clocks order events across machines.",
);
render();
expect(page("reports/2026-11-02-vector-stores.md")).toBe(
[
"<!-- open-second-brain-view store=<store> page=reports/2026-11-02-vector-stores.md -->",
"",
"# Vector stores",
"",
"Research report of 2026-11-02.",
"",
"## Findings",
"",
"- SQLite is enough (cites: SQLite notes)",
"",
].join("\n"),
);
expect(page("sources/src-paper-abc123.md")).toBe(
[
"<!-- open-second-brain-view store=<store> page=sources/src-paper-abc123.md -->",
"",
"# Source: Papers/hlc.pdf",
"",
"Summary of a source, updated 2026-11-03.",
"",
"Hybrid logical clocks order events across machines.",
"",
].join("\n"),
);
clock += 1000;
seedLaneRemove(a, clock, "reports", "2026-11-02-vector-stores");
render(1);
expect(existsSync(view("reports"))).toBe(false);
});
});