Skip to content

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
7.9 KB
Raw Blame
import { test, expect, beforeEach, afterEach } from "bun:test";
import { mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

import { parseFrontmatter, writeFrontmatter } from "../../../../src/core/vault.ts";
import { regenerateActive } from "../../../../src/core/brain/active.ts";
import { readLogDay } from "../../../../src/core/brain/log-jsonl.ts";
import { resolveAppendShardId } from "../../../../src/core/brain/ledger-shards.ts";
import { logShardJsonlPath } from "../../../../src/core/brain/paths.ts";
import { BRAIN_LOG_EVENT_KIND } from "../../../../src/core/brain/types.ts";
import {
  TombstoneError,
  isTombstoned,
  readLifecycleState,
  resolveChainTip,
  resolveChainTipInVault,
  supersede,
  tombstone,
} from "../../../../src/core/brain/lifecycle/tombstone.ts";

let vault: string;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-tombstone-"));
  mkdirSync(join(vault, "Brain", "preferences"), { recursive: true });
  mkdirSync(join(vault, "Brain", "inbox"), { recursive: true });
});
afterEach(() => {
  rmSync(vault, { recursive: true, force: true });
});

function writePref(slug: string, extra: Record<string, string> = {}, body = "Prose."): string {
  const rel = join("Brain", "preferences", `pref-${slug}.md`);
  writeFrontmatter(
    join(vault, rel),
    {
      kind: "brain-preference",
      id: `pref-${slug}`,
      _status: "confirmed",
      topic: slug,
      principle: `principle for ${slug}`,
      tags: ["brain"],
      created_at: "2026-01-01T00:00:00Z",
      unconfirmed_until: "2026-02-01T00:00:00Z",
      ...extra,
    },
    body,
  );
  return rel;
}

const NOW = new Date("2026-07-18T12:00:00Z");

test("tombstone sets lifecycle frontmatter without deleting the file and preserves the body", () => {
  const rel = writePref("alpha", {}, "This is the human prose body.");
  const digest = regenerateActive(vault, { now: NOW }).path;
  expect(readFileSync(digest, "utf8")).toContain("## Confirmed (1)");
  const res = tombstone({ vault, path: rel, reason: "wrong belief", agent: "tester", now: NOW });

  expect(res.changed).toBe(true);
  expect(res.state.tombstoned).toBe(true);
  expect(res.state.tombstoneReason).toBe("wrong belief");
  expect(res.state.tombstonedAt).toBe("2026-07-18T12:00:00Z");

  const [meta, body] = parseFrontmatter(join(vault, rel));
  expect(meta["_status"]).toBe("tombstoned");
  expect(meta["tombstoned_at"]).toBe("2026-07-18T12:00:00Z");
  expect(meta["tombstone_reason"]).toBe("wrong belief");
  expect(body).toBe("This is the human prose body.");
  expect(readFileSync(digest, "utf8")).toContain("## Confirmed (0)");
  expect(readFileSync(digest, "utf8")).not.toContain("pref-alpha");
});

test("updates the digest if the tombstone saves but the audit append fails", () => {
  const rel = writePref("log-failure");
  const digest = regenerateActive(vault, { now: NOW }).path;
  expect(readFileSync(digest, "utf8")).toContain("pref-log-failure");
  const logPath = logShardJsonlPath(vault, "2026-07-18", resolveAppendShardId());
  mkdirSync(logPath, { recursive: true });
  expect(() => tombstone({ vault, path: rel, reason: "wrong", agent: "tester", now: NOW })).toThrow(
    "EISDIR",
  );
  expect(parseFrontmatter(join(vault, rel))[0]["_status"]).toBe("tombstoned");
  expect(readFileSync(digest, "utf8")).not.toContain("pref-log-failure");
});

test("re-issuing a tombstone is a byte-identical no-op returning the existing state", () => {
  const rel = writePref("beta");
  tombstone({ vault, path: rel, reason: "first", agent: "tester", now: NOW });
  const after1 = readFileSync(join(vault, rel), "utf8");

  const res2 = tombstone({
    vault,
    path: rel,
    reason: "different reason",
    agent: "tester",
    now: new Date("2026-07-19T00:00:00Z"),
  });
  const after2 = readFileSync(join(vault, rel), "utf8");

  expect(res2.changed).toBe(false);
  expect(res2.state.tombstoneReason).toBe("first");
  expect(after2).toBe(after1);
});

test("tombstone logs exactly one tombstone event on the changing write and none on the no-op", () => {
  const rel = writePref("gamma");
  tombstone({ vault, path: rel, reason: "obsolete", agent: "tester", now: NOW });
  tombstone({ vault, path: rel, reason: "obsolete", agent: "tester", now: NOW });

  const { entries } = readLogDay(vault, "2026-07-18");
  const tombstones = entries.filter((e) => e.eventType === BRAIN_LOG_EVENT_KIND.tombstone);
  expect(tombstones.length).toBe(1);
  expect(tombstones[0]!.body["reason"]).toBe("obsolete");
  expect(tombstones[0]!.body["prior_status"]).toBe("confirmed");
});

test("tombstone throws a typed error when the target does not exist", () => {
  expect(() =>
    tombstone({ vault, path: "Brain/preferences/pref-missing.md", reason: "x", now: NOW }),
  ).toThrow(TombstoneError);
});

test("tombstone throws a typed error on an empty reason", () => {
  const rel = writePref("delta");
  expect(() => tombstone({ vault, path: rel, reason: "   ", now: NOW })).toThrow(TombstoneError);
});

test("supersede tombstones the predecessor and records the replacement pointer", () => {
  const oldRel = writePref("old-fact");
  writePref("new-fact");

  const res = supersede({
    vault,
    predecessor: oldRel,
    successor: "pref-new-fact",
    agent: "tester",
    now: NOW,
  });

  expect(res.changed).toBe(true);
  expect(res.state.tombstoned).toBe(true);
  expect(res.state.supersededBy).toBe("[[pref-new-fact]]");

  const [meta] = parseFrontmatter(join(vault, oldRel));
  expect(meta["_status"]).toBe("tombstoned");
  expect(meta["superseded_by"]).toBe("[[pref-new-fact]]");
});

test("isTombstoned reads both the prefixed and normalized status key", () => {
  expect(isTombstoned({ _status: "tombstoned" })).toBe(true);
  expect(isTombstoned({ status: "tombstoned" })).toBe(true);
  expect(isTombstoned({ _status: "confirmed" })).toBe(false);
  expect(isTombstoned({})).toBe(false);
});

test("readLifecycleState reports the superseded_by pointer normalized", () => {
  const state = readLifecycleState({ _status: "tombstoned", superseded_by: "[[pref-x]]" });
  expect(state.tombstoned).toBe(true);
  expect(state.supersededBy).toBe("[[pref-x]]");
});

function mapLookup(
  map: Record<string, string | null>,
): (link: string) => { supersededBy: string | null } | null {
  return (link) => (link in map ? { supersededBy: map[link]! } : null);
}

test("resolveChainTip walks a chain of superseded_by links to the live tip", () => {
  const res = resolveChainTip(
    "[[pref-a]]",
    mapLookup({ "pref-a": "[[pref-b]]", "pref-b": "[[pref-c]]", "pref-c": null }),
  );
  expect(res.tip).toBe("pref-c");
  expect(res.steps).toBe(2);
  expect(res.cycle).toBe(false);
  expect(res.resolvedAll).toBe(true);
});

test("resolveChainTip detects a cycle instead of looping forever", () => {
  const res = resolveChainTip(
    "pref-a",
    mapLookup({ "pref-a": "[[pref-b]]", "pref-b": "[[pref-a]]" }),
  );
  expect(res.cycle).toBe(true);
});

test("resolveChainTip returns the start unchanged when it has no successor", () => {
  const res = resolveChainTip("pref-solo", () => ({ supersededBy: null }));
  expect(res.tip).toBe("pref-solo");
  expect(res.steps).toBe(0);
});

test("resolveChainTipInVault follows real supersede chains on disk", () => {
  const oldRel = writePref("v1");
  writePref("v2");
  supersede({ vault, predecessor: oldRel, successor: "pref-v2", now: NOW });

  const res = resolveChainTipInVault(vault, "pref-v1");
  expect(res.tip).toBe("pref-v2");
});

test("tombstone works cross-type on a signal file", () => {
  const rel = join("Brain", "inbox", "sig-2026-01-01-note.md");
  writeFrontmatter(
    join(vault, rel),
    { kind: "brain-signal", id: "sig-2026-01-01-note", topic: "note", signal: "positive" },
    "signal body",
  );
  const res = tombstone({ vault, path: rel, reason: "captured in error", now: NOW });
  expect(res.changed).toBe(true);
  const [meta, body] = parseFrontmatter(join(vault, rel));
  expect(meta["_status"]).toBe("tombstoned");
  expect(body).toBe("signal body");
});