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
/**
* createNote primitive (Brain Portability & Interop suite, Unit D).
*
* The shared write primitive behind the `brain_create_note` MCP tool and
* the SDK `createNote` method. Writes a Markdown note atomically under
* `ensureInsideVault`, honouring vault-scope ignore rules and refusing
* the Brain machinery root, path traversal, and clobbering an existing
* file - every refusal is a typed `CreateNoteError`, never a silent skip.
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import {
existsSync,
mkdtempSync,
readFileSync,
readdirSync,
rmSync,
symlinkSync,
writeFileSync,
mkdirSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { createNote, CreateNoteError } from "../../../../src/core/brain/notes/create-note.ts";
let vault: string;
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "o2b-create-note-"));
});
afterEach(() => rmSync(vault, { recursive: true, force: true }));
describe("createNote", () => {
test("writes a note with frontmatter and body, returns the vault-relative path", () => {
const res = createNote(vault, {
path: "Notes/New.md",
frontmatter: { title: "New", tags: ["a", "b"] },
content: "Hello body.",
});
expect(res.created).toBe(true);
expect(res.path).toBe("Notes/New.md");
const written = readFileSync(join(vault, "Notes/New.md"), "utf8");
expect(written).toContain("title: New");
expect(written).toContain("Hello body.");
});
test("creates intermediate directories", () => {
createNote(vault, { path: "A/B/C/Deep.md", content: "x" });
expect(existsSync(join(vault, "A/B/C/Deep.md"))).toBe(true);
});
test("allows a note with no frontmatter and no content", () => {
const res = createNote(vault, { path: "Notes/Empty.md" });
expect(res.created).toBe(true);
expect(existsSync(join(vault, "Notes/Empty.md"))).toBe(true);
});
test("rejects a non-.md path with a typed error", () => {
expect(() => createNote(vault, { path: "Notes/data.json", content: "x" })).toThrow(
CreateNoteError,
);
});
test("rejects path traversal with a typed error", () => {
expect(() => createNote(vault, { path: "../escape.md", content: "x" })).toThrow(
CreateNoteError,
);
expect(existsSync(join(vault, "..", "escape.md"))).toBe(false);
});
test("rejects an absolute path with a typed error", () => {
expect(() => createNote(vault, { path: "/etc/evil.md", content: "x" })).toThrow(
CreateNoteError,
);
});
test("refuses to write into the Brain machinery root", () => {
expect(() => createNote(vault, { path: "Brain/sneaky.md", content: "x" })).toThrow(
CreateNoteError,
);
expect(existsSync(join(vault, "Brain/sneaky.md"))).toBe(false);
});
test("refuses the Brain root under any case spelling", () => {
// `brain/` opens `Brain/` on the case-insensitive macOS and Windows
// defaults, so a case-sensitive compare is not a wall there.
for (const path of ["brain/sneaky.md", "BRAIN/sneaky.md", "bRaIn/deep/sneaky.md"]) {
expect(() => createNote(vault, { path, content: "x" })).toThrow(/Brain machinery root/);
}
expect(existsSync(join(vault, "brain"))).toBe(false);
expect(existsSync(join(vault, "BRAIN"))).toBe(false);
});
test("refuses a vault-scope excluded path, naming the key and the entry", () => {
expect(() => createNote(vault, { path: ".obsidian/plugins/x.md", content: "x" })).toThrow(
/excluded by vault\.ignore_paths \(\.obsidian\)/,
);
expect(() => createNote(vault, { path: ".obsidian/plugins/x.md", content: "x" })).toThrow(
CreateNoteError,
);
});
test("refuses a path outside vault.include_paths, naming THAT polarity", () => {
// One policy, every consumer. The message has to say which of the two
// keys refused, because "excluded by vault scope" sends an operator
// to read the wrong list.
mkdirSync(join(vault, "Brain"), { recursive: true });
writeFileSync(
join(vault, "Brain", "_brain.yaml"),
"schema_version: 1\nvault:\n include_paths:\n - Notes\n",
"utf8",
);
expect(() => createNote(vault, { path: "Archive/x.md", content: "x" })).toThrow(
/outside vault\.include_paths \(Notes\)/,
);
expect(existsSync(join(vault, "Archive/x.md"))).toBe(false);
// Inside the allowlist the same write lands.
expect(createNote(vault, { path: "Notes/x.md", content: "x" }).created).toBe(true);
});
test("refuses to clobber an existing note (no overwrite)", () => {
mkdirSync(join(vault, "Notes"), { recursive: true });
writeFileSync(join(vault, "Notes/Dup.md"), "original", "utf8");
expect(() => createNote(vault, { path: "Notes/Dup.md", content: "new" })).toThrow(
CreateNoteError,
);
// The original content is untouched.
expect(readFileSync(join(vault, "Notes/Dup.md"), "utf8")).toBe("original");
});
test("the typed error carries a machine-readable code", () => {
try {
createNote(vault, { path: "../escape.md", content: "x" });
throw new Error("expected throw");
} catch (err) {
expect(err).toBeInstanceOf(CreateNoteError);
expect((err as CreateNoteError).code).toBe("invalid_path");
}
});
});
describe("a caller-named path is read with this host's separator only", () => {
// Defect 2 of the v1.43.0 security review, reproduced at the envelope.
// On POSIX a backslash is an ordinary filename character, and three
// layers disagreed about it: the write-binding matcher split on it, the
// result renderer rewrote it to `/`, and the Brain-root and vault-scope
// checks treated it as literal. The envelope refuses the path rather
// than picking one reading.
//
// On Windows the backslash IS the host separator, so the ambiguity does
// not exist: `Projects\evil.md` has one reading (a note under Projects)
// and `Brain\x.md` is refused as the Brain root it plainly names. Only
// the traversal case keeps the same answer there.
for (const [label, path, windowsToo] of [
["a backslash inside a segment", "Projects\\evil.md", false],
["a backslash traversal", "Projects\\..\\..\\..\\etc\\x.md", true],
["a backslash-hidden Brain root", "Brain\\x.md", false],
] as const) {
test.skipIf(process.platform === "win32" && !windowsToo)(
`${label} is refused, not reinterpreted`,
() => {
let caught: CreateNoteError | null = null;
try {
createNote(vault, { path, content: "x" });
} catch (err) {
caught = err as CreateNoteError;
}
expect(caught).toBeInstanceOf(CreateNoteError);
expect(caught!.code).toBe("invalid_path");
expect(readdirSync(vault)).toEqual([]);
},
);
}
test("a POSIX path with the same segments is still created", () => {
const res = createNote(vault, { path: "Projects/evil.md", content: "x" });
expect(res.path).toBe("Projects/evil.md");
expect(existsSync(join(vault, "Projects", "evil.md"))).toBe(true);
});
});
describe("createNote refuses a target it cannot resolve on disk", () => {
function refusal(path: string): CreateNoteError {
try {
createNote(vault, { path, content: "x" });
} catch (err) {
if (err instanceof CreateNoteError) return err;
throw err;
}
throw new Error("expected CreateNoteError");
}
test("a note used as a folder is an invalid_path refusal, not an I/O crash", () => {
writeFileSync(join(vault, "existing.md"), "x\n");
const err = refusal("existing.md/x.md");
expect(err.code).toBe("invalid_path");
expect(err.message).toContain("cannot be resolved");
});
test("a symlink loop is an invalid_path refusal", () => {
symlinkSync(join(vault, "loop-b"), join(vault, "loop-a"));
symlinkSync(join(vault, "loop-a"), join(vault, "loop-b"));
const err = refusal("loop-a/x.md");
expect(err.code).toBe("invalid_path");
expect(existsSync(join(vault, "loop-a", "x.md"))).toBe(false);
});
});