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 and lifecycle tools answer for a page the caller may not
* read at its reach exactly as for an absent one.
*
* `brain_note_lifecycle`, `brain_append_note`, `brain_update_note` and the
* update and append operations of `brain_write_batch` name an EXISTING
* page. A page that reserved itself raises the same refusal a missing
* path raises, before any plan is built or any byte is written, so a
* caller that cannot read the page can neither learn that it exists nor
* change it. `brain_create_note` keeps its occupied-target refusal: it
* cannot answer "created" without overwriting the page or reporting a
* write that did not happen, so it refuses and leaves the page alone.
*/
import { afterEach, describe, expect, test } from "bun:test";
import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { bootstrapBrain } from "../../src/core/brain/init.ts";
import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";
import { TRANSPORT_REACH } from "../../src/core/graph/transport-reach.ts";
import { MCPServer } from "../../src/mcp/server.ts";
const PRIVATE_PATH = "Notes/secret.md";
const SECRET_BODY = "---\nvisibility: private\n---\n# Secret plan\nThe PIN is 4711.\n";
const bases: string[] = [];
afterEach(() => {
for (const base of bases.splice(0)) rmSync(base, { recursive: true, force: true });
});
interface Fixture {
readonly vault: string;
readonly server: MCPServer;
}
/**
* One vault holding the private page, or one where it never existed. With
* no `reach`, the server mints none, which fails closed to remote.
*/
function fixture(withSecret: boolean, reach?: typeof TRANSPORT_REACH.local): Fixture {
const base = mkdtempSync(join(tmpdir(), "o2b-note-write-reach-"));
bases.push(base);
const vault = join(base, "vault");
mkdirSync(join(vault, "Notes"), { recursive: true });
const configPath = join(base, "config.yaml");
atomicWriteFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);
bootstrapBrain(vault, { configPath });
writeFileSync(join(vault, "Notes/open.md"), "# Open\nSee [[secret]].\n");
writeFileSync(join(vault, "Notes/other.md"), "# Other\nSee [[Notes/secret]].\n");
if (withSecret) writeFileSync(join(vault, PRIVATE_PATH), SECRET_BODY);
const server = new MCPServer({ vault, configPath }, reach !== undefined ? { reach } : undefined);
return { vault, server };
}
/** The answer (or the refusal) with the vault path normalised. */
async function answer(f: Fixture, tool: string, args: Record<string, unknown>): Promise<string> {
let raw: string;
try {
raw = `ok: ${JSON.stringify(await f.server.callTool(tool, args))}`;
} catch (err) {
const e = err as Error & { code?: unknown; data?: unknown };
raw = `error: ${e.message} ${JSON.stringify(e.code)} ${JSON.stringify(e.data)}`;
}
return raw.split(f.vault).join("<vault>");
}
/** The answer with the per-write receipt id normalised. */
async function receipt(f: Fixture, tool: string, args: Record<string, unknown>): Promise<string> {
return (await answer(f, tool, args)).replace(/nw_\d{14}_[0-9a-f]{16}/g, "<nw>");
}
const CALLS: ReadonlyArray<readonly [string, Record<string, unknown>]> = [
["brain_note_lifecycle", { action: "delete", path: PRIVATE_PATH }],
["brain_note_lifecycle", { action: "delete", path: PRIVATE_PATH, apply: true, confirm: true }],
["brain_note_lifecycle", { action: "move", path: PRIVATE_PATH, to: "Other/secret.md" }],
["brain_note_lifecycle", { action: "rename", path: PRIVATE_PATH, to: "Notes/renamed.md" }],
["brain_note_lifecycle", { action: "archive", path: PRIVATE_PATH, apply: true }],
["brain_append_note", { path: PRIVATE_PATH, content: "appended" }],
["brain_update_note", { path: PRIVATE_PATH, frontmatter: { visibility: "public" } }],
["brain_update_note", { path: PRIVATE_PATH, content: "replaced" }],
["brain_write_batch", { operations: [{ op: "append_note", path: PRIVATE_PATH, content: "x" }] }],
[
"brain_write_batch",
{
operations: [
{ op: "update_note", path: PRIVATE_PATH, frontmatter: { visibility: "public" } },
],
},
],
];
describe("a page the caller cannot read answers as an absent one", () => {
for (const [tool, args] of CALLS) {
test(`${tool} ${JSON.stringify(args)}`, async () => {
const hidden = fixture(true);
const absent = fixture(false);
expect(await answer(hidden, tool, args)).toBe(await answer(absent, tool, args));
expect(readFileSync(join(hidden.vault, PRIVATE_PATH), "utf8")).toBe(SECRET_BODY);
});
}
test("a create onto it is refused and leaves the page as it was", async () => {
const hidden = fixture(true);
const out = await answer(hidden, "brain_create_note", { path: PRIVATE_PATH, content: "mine" });
expect(out).toContain("note already exists");
expect(readFileSync(join(hidden.vault, PRIVATE_PATH), "utf8")).toBe(SECRET_BODY);
});
});
describe("at local reach the page is planned and written", () => {
test("lifecycle plan and append", async () => {
const local = fixture(true, TRANSPORT_REACH.local);
const plan = await local.server.callTool("brain_note_lifecycle", {
action: "delete",
path: PRIVATE_PATH,
});
expect(JSON.stringify(plan)).toContain('"from":"Notes/secret.md"');
await local.server.callTool("brain_append_note", { path: PRIVATE_PATH, content: "appended" });
expect(readFileSync(join(local.vault, PRIVATE_PATH), "utf8")).toContain("appended");
});
});
/**
* The write receipt's near-duplicate hint answers at the caller's reach.
* A body that copies the private page would be named as its near
* duplicate at local reach; at a reach that withholds the page, every
* note-write tool answers exactly as if the page never existed.
*/
describe("the near-duplicate receipt hint never names a withheld sibling", () => {
const COPIED_BODY = "# Secret plan\nThe PIN is 4711.\n";
const DRAFT_PATH = "Notes/draft.md";
/** A fixture with an empty-bodied draft to append to. */
function writeFixture(withSecret: boolean, reach?: typeof TRANSPORT_REACH.local): Fixture {
const f = fixture(withSecret, reach);
writeFileSync(join(f.vault, DRAFT_PATH), "---\ntitle: Draft\n---\n");
return f;
}
const WRITES: ReadonlyArray<readonly [string, Record<string, unknown>]> = [
["brain_create_note", { path: "Notes/mine.md", content: COPIED_BODY }],
["brain_update_note", { path: "Notes/open.md", content: COPIED_BODY }],
["brain_append_note", { path: DRAFT_PATH, content: COPIED_BODY }],
[
"brain_write_batch",
{ operations: [{ op: "create_note", path: "Notes/mine.md", content: COPIED_BODY }] },
],
];
for (const [tool, args] of WRITES) {
test(`${tool} answers as if the page were absent`, async () => {
const hidden = await receipt(writeFixture(true), tool, args);
expect(hidden).not.toContain(PRIVATE_PATH);
expect(hidden).toBe(await receipt(writeFixture(false), tool, args));
});
test(`${tool} names the page at local reach`, async () => {
const local = await receipt(writeFixture(true, TRANSPORT_REACH.local), tool, args);
expect(local).toContain("near-duplicate");
expect(local).toContain(PRIVATE_PATH);
});
}
});
/**
* The receipt's wikilink and merged-link findings answer at the caller's
* reach as well. A preference that reserved itself is reported the way a
* preference that never existed is: a link to it reads as broken, and a
* merge chain through it ends at its id without naming where it points.
*/
describe("the receipt's link findings never reach past a withheld page", () => {
const PREFS = join("Brain", "preferences");
function writePref(f: Fixture, slug: string, fields: string): void {
writeFileSync(
join(f.vault, PREFS, `pref-${slug}.md`),
`---\nid: pref-${slug}\ntopic: x\nprinciple: y\n${fields}---\n`,
);
}
/** A vault with a public pref merged into `pref-held`, private or absent. */
function linkFixture(withHeld: boolean, reach?: typeof TRANSPORT_REACH.local): Fixture {
const f = fixture(false, reach);
writePref(f, "canon", "");
writePref(f, "dup", "merged_into: pref-held\n");
if (withHeld) writePref(f, "held", "visibility: private\nmerged_into: pref-canon\n");
return f;
}
const LINKS = ["[[pref-held]]", "[[pref-dup]]"];
for (const link of LINKS) {
const args = { path: "Notes/mine.md", content: `see ${link}\n` };
test(`a link ${link} answers as if the page were absent`, async () => {
const hidden = await receipt(linkFixture(true), "brain_create_note", args);
expect(hidden).not.toContain("pref-canon");
expect(hidden).toBe(await receipt(linkFixture(false), "brain_create_note", args));
});
}
test("at local reach the chain is followed to its canonical end", async () => {
const args = { path: "Notes/mine.md", content: "see [[pref-dup]]\n" };
const local = await receipt(
linkFixture(true, TRANSPORT_REACH.local),
"brain_create_note",
args,
);
expect(local).toContain("merged into pref-canon");
});
});