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
/**
* `--delete-linked`: a note delete that may also remove the files whose
* whole reason to exist was that note (unit 3a / t_5e338af1).
*
* The defect this closes. A note delete removes one file and reports the
* inbound references it strands. When the note was an imported source,
* those references are not navigation aids - they are a summary page, a
* signal and a preference that say nothing except what that note said, and
* an operator removing the note had to hand-chase every one of them. The
* remedy already exists for the ingest side (`deleteBySource`) and is
* deliberately narrow, and that narrowness is the whole design: only a
* single-purpose derived file tracing SOLELY to the subject is ever
* deleted; anything else that merely references it is REPORTED.
*
* Claims pinned here:
*
* 1. Without the flag, delete is byte-identical to before: no cascade is
* computed and no derived file is touched.
* 2. A dry run with the flag lists the deletion set (the note plus its
* solely-derived files) and the report-only references SEPARATELY, and
* writes nothing.
* 3. The derived-set fold walks `Brain/` and SAYS SO on the response, so a
* caller can tell a scope boundary from an empty result - user notes
* are outside the fold by construction and are reported, never deleted.
* 4. A Brain page citing a SECOND source is reported and preserved, even
* under confirm. The module header's commitment - a delete rewrites
* nothing and reports what it strands - stands for everything outside
* the solely-derived set.
* 5. Confirm removes exactly the listed set, behind ONE recovery point
* covering the Brain half of it, with the verdict saying that the note
* itself is outside every archive.
* 6. The count guard asserts the DELETION SET size under the flag (not the
* inbound-reference count), and a mismatch aborts before any unlink.
* 7. The flag belongs to delete alone; on any other action it is refused
* by name rather than ignored.
* 8. A Brain page that only MENTIONS the note - a `[[wikilink]]` in prose
* and no `source:` array - is reported and never deleted, however
* derived-looking the directory it sits in. The solely-derived test is
* vacuously true for a page declaring no provenance at all, so the
* cascade demands declared provenance on top of it.
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { bootstrapBrain } from "../../../../src/core/brain/init.ts";
import {
DERIVED_SET_SCOPE,
NOTE_LIFECYCLE_ACTION,
noteLifecycle,
NoteLifecycleError,
} from "../../../../src/core/brain/notes/lifecycle.ts";
import { CountGuardError } from "../../../../src/core/brain/count-guard.ts";
import { RECOVERABILITY_STATE } from "../../../../src/core/brain/gates/recoverability.ts";
import { writePreference } from "../../../../src/core/brain/preference.ts";
import { writeSignal } from "../../../../src/core/brain/signal.ts";
import { atomicWriteFileSync } from "../../../../src/core/fs-atomic.ts";
let vault: string;
let configHome: string;
const TARGET = "Imports/Benchmark.md";
const OTHER = "Imports/Legit.md";
const NOW = new Date("2026-06-01T00:00:00Z");
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "o2b-delete-linked-"));
configHome = mkdtempSync(join(tmpdir(), "o2b-delete-linked-cfg-"));
const configPath = join(configHome, "config.yaml");
atomicWriteFileSync(configPath, `vault: ${vault}\n`);
bootstrapBrain(vault, { configPath });
});
afterEach(() => {
rmSync(vault, { recursive: true, force: true });
rmSync(configHome, { recursive: true, force: true });
});
function note(rel: string, body: string): void {
const abs = join(vault, rel);
mkdirSync(join(abs, ".."), { recursive: true });
writeFileSync(abs, body);
}
/**
* A vault where the note under test has one solely-derived signal, one
* preference folded from it, one signal that also cites a second note, and
* one ordinary user note that merely links to it.
*/
function seed(): { solelyDerived: string; shared: string } {
note(TARGET, "---\ntitle: Benchmark\n---\n\nrows\n");
note(OTHER, "---\ntitle: Legit\n---\n\nprose\n");
note("Projects/Reader.md", `See [[${"Imports/Benchmark"}]] for the numbers.\n`);
const solely = writeSignal(vault, {
topic: "bench",
signal: "positive",
agent: "tester",
principle: "Only the benchmark note says this.",
created_at: "2026-06-01T00:00:00Z",
date: "2026-06-01",
slug: "bench-only",
source: ["[[Imports/Benchmark]]"],
});
const shared = writeSignal(vault, {
topic: "bench",
signal: "positive",
agent: "tester",
principle: "Two notes say this.",
created_at: "2026-06-01T00:00:00Z",
date: "2026-06-01",
slug: "bench-shared",
source: ["[[Imports/Benchmark]]", "[[Imports/Legit]]"],
});
writePreference(vault, {
slug: "bench-pref",
topic: "bench",
principle: "Folded from the benchmark signal alone.",
created_at: "2026-06-01T00:00:00Z",
unconfirmed_until: "2026-06-08T00:00:00Z",
status: "confirmed",
evidenced_by: [`[[${solely.id}]]`],
});
return { solelyDerived: solely.path, shared: shared.path };
}
/** `Brain/inbox/sig-x.md` from an absolute path. */
function vaultRel(abs: string): string {
return abs
.slice(vault.length + 1)
.split("\\")
.join("/");
}
describe("the flag is opt-in", () => {
test("a delete without it computes no cascade and touches no derived file", async () => {
const { solelyDerived } = seed();
const res = await noteLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.delete,
path: TARGET,
apply: true,
confirm: true,
now: NOW,
});
expect(res.cascade).toBeNull();
expect(existsSync(solelyDerived)).toBe(true);
});
test("it is refused by name on an action that is not a delete", async () => {
seed();
await expect(
noteLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.rename,
path: TARGET,
to: "Imports/Renamed.md",
deleteLinked: true,
apply: true,
}),
).rejects.toThrow(NoteLifecycleError);
expect(existsSync(join(vault, TARGET))).toBe(true);
});
});
describe("the dry run", () => {
test("lists the deletion set and the report-only references separately", async () => {
const { solelyDerived, shared } = seed();
const res = await noteLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.delete,
path: TARGET,
deleteLinked: true,
now: NOW,
});
expect(res.applied).toBe(false);
expect(res.cascade).not.toBeNull();
const cascade = res.cascade!;
// The note itself is first; the derived files follow, sorted.
expect(cascade.deletionSet[0]).toBe(TARGET);
expect(cascade.deletionSet).toContain(vaultRel(solelyDerived));
// The preference folded solely from that signal rides along.
expect(cascade.deletionSet.some((p) => p.includes("pref-bench-pref"))).toBe(true);
// The shared signal and the user note are reported, never in the set.
expect(cascade.deletionSet).not.toContain(vaultRel(shared));
expect(cascade.reportedFiles).toContain(vaultRel(shared));
expect(cascade.reportedFiles).toContain("Projects/Reader.md");
// Nothing overlaps: a path is either deleted or reported, never both.
for (const path of cascade.reportedFiles) {
expect(cascade.deletionSet).not.toContain(path);
}
// And nothing was written.
expect(existsSync(join(vault, TARGET))).toBe(true);
expect(existsSync(solelyDerived)).toBe(true);
expect(res.snapshot).toBeNull();
});
test("names the scope the derived-set fold actually walked", async () => {
seed();
const res = await noteLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.delete,
path: TARGET,
deleteLinked: true,
now: NOW,
});
expect(res.cascade!.scannedScope).toBe(DERIVED_SET_SCOPE);
// A user note outside that scope is reported rather than folded in.
expect(res.cascade!.reportedFiles).toContain("Projects/Reader.md");
});
});
describe("a prose mention is not a derivation", () => {
/**
* A Brain page inside a derivation directory whose only tie to the note
* is a `[[wikilink]]` in its body: no `source:` array, no `source_path`,
* nothing declaring where it came from.
*/
const PROSE_ONLY = "Brain/inbox/sig-2026-06-01-prose-mention.md";
function seedProseMention(): void {
note(
PROSE_ONLY,
[
"---",
"id: sig-2026-06-01-prose-mention",
"topic: bench",
"signal: positive",
"---",
"",
"The operator compared this against [[Imports/Benchmark]] once.",
"",
].join("\n"),
);
}
test("the dry run reports it and leaves it out of the deletion set", async () => {
seed();
seedProseMention();
const res = await noteLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.delete,
path: TARGET,
deleteLinked: true,
now: NOW,
});
expect(res.cascade!.deletionSet).not.toContain(PROSE_ONLY);
expect(res.cascade!.reportedFiles).toContain(PROSE_ONLY);
});
test("confirm leaves it on disk", async () => {
const { solelyDerived } = seed();
seedProseMention();
const res = await noteLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.delete,
path: TARGET,
deleteLinked: true,
apply: true,
confirm: true,
now: NOW,
});
expect(res.applied).toBe(true);
// The page that DECLARED the note as its source is gone; the one that
// only wrote its name in a sentence is not.
expect(existsSync(solelyDerived)).toBe(false);
expect(existsSync(join(vault, PROSE_ONLY))).toBe(true);
});
});
describe("confirm", () => {
test("removes exactly the listed set and preserves every shared reference", async () => {
const { solelyDerived, shared } = seed();
const plan = await noteLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.delete,
path: TARGET,
deleteLinked: true,
now: NOW,
});
const planned = [...plan.cascade!.deletionSet];
const res = await noteLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.delete,
path: TARGET,
deleteLinked: true,
apply: true,
confirm: true,
now: NOW,
});
expect(res.applied).toBe(true);
expect([...res.cascade!.deletionSet]).toEqual(planned);
for (const path of planned) expect(existsSync(join(vault, path))).toBe(false);
// The shared signal and the user note survive, unrewritten.
expect(existsSync(shared)).toBe(true);
expect(existsSync(join(vault, "Projects/Reader.md"))).toBe(true);
expect(res.references.filesRewritten).toBe(0);
expect(existsSync(solelyDerived)).toBe(false);
});
test("takes ONE recovery point and says what it does not cover", async () => {
seed();
const res = await noteLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.delete,
path: TARGET,
deleteLinked: true,
apply: true,
confirm: true,
now: NOW,
});
expect(res.snapshot).not.toBeNull();
expect(existsSync(res.snapshot!.path)).toBe(true);
// The Brain half of the set is inside the archive; the note is not.
expect(res.recoverability.state).toBe(RECOVERABILITY_STATE.partial);
expect(res.recoverability.blockers).toContain("outside_brain_root");
});
});
describe("the count guard", () => {
test("asserts the deletion-set size and aborts before any unlink", async () => {
const { solelyDerived } = seed();
await expect(
noteLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.delete,
path: TARGET,
deleteLinked: true,
apply: true,
confirm: true,
expect: 1,
now: NOW,
}),
).rejects.toThrow(CountGuardError);
expect(existsSync(join(vault, TARGET))).toBe(true);
expect(existsSync(solelyDerived)).toBe(true);
const plan = await noteLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.delete,
path: TARGET,
deleteLinked: true,
now: NOW,
});
const res = await noteLifecycle(vault, {
action: NOTE_LIFECYCLE_ACTION.delete,
path: TARGET,
deleteLinked: true,
apply: true,
confirm: true,
expect: plan.cascade!.deletionSet.length,
now: NOW,
});
expect(res.applied).toBe(true);
});
});