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
9.6 KB
Raw Blame
/**
 * The note-write record (who-wrote-what, Task A / t_662f4e82).
 *
 * Covers the three artifacts the module owns - the write id, the
 * content-addressed before-image store, and the one `note-write` log
 * event - plus the property the whole design turns on: a log-append
 * failure costs the audit line and NOT the write, and says so by name.
 */

import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import {
  chmodSync,
  existsSync,
  mkdirSync,
  mkdtempSync,
  readFileSync,
  rmSync,
  utimesSync,
  writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

import {
  NOTE_WRITE_NO_PRIOR,
  NOTE_WRITE_OP,
  WRITE_IMAGE_RETENTION_DAYS,
  isNoteWriteOp,
  noteWriteId,
  pruneWriteImages,
  recordNoteWrite,
  storeBeforeImage,
} from "../../../../src/core/brain/notes/write-record.ts";
import { writeImagePath, writeImagesDir } from "../../../../src/core/brain/paths.ts";
import { readLogDay } from "../../../../src/core/brain/log-jsonl.ts";
import { sha256Hex } from "../../../../src/core/integrity/digest.ts";
import { BRAIN_LOG_EVENT_KIND } from "../../../../src/core/brain/types.ts";
import { CHMOD_CANNOT_DENY } from "../../../helpers/platform.ts";

const AGENT = "agent-a";
const TS = "2026-03-04T05:06:07Z";
const DATE = "2026-03-04";

let vault: string;
beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-write-record-"));
  // A legacy Brain/ tree: an unswitched machine (a vault without one is store-only).
  mkdirSync(join(vault, "Brain"), { recursive: true });
});
afterEach(() => rmSync(vault, { recursive: true, force: true }));

describe("noteWriteId", () => {
  test("carries the timestamp digits and a 16-hex body digest", () => {
    const id = noteWriteId({
      timestamp: TS,
      op: NOTE_WRITE_OP.update,
      target: "Notes/A.md",
      hash_before: sha256Hex("old"),
      hash_after: sha256Hex("new"),
      agent: AGENT,
    });
    expect(id).toMatch(/^nw_\d{14}_[0-9a-f]{16}$/);
    expect(id.slice(3, 17)).toBe("20260304050607");
  });

  test("is a pure function of the body: same facts, same id", () => {
    const body = {
      timestamp: TS,
      op: NOTE_WRITE_OP.create,
      target: "Notes/A.md",
      hash_before: NOTE_WRITE_NO_PRIOR,
      hash_after: sha256Hex("new"),
      agent: AGENT,
    } as const;
    expect(noteWriteId(body)).toBe(noteWriteId(body));
    expect(noteWriteId({ ...body, agent: "agent-b" })).not.toBe(noteWriteId(body));
  });
});

describe("isNoteWriteOp", () => {
  test("admits the four declared operations and nothing else", () => {
    for (const op of Object.values(NOTE_WRITE_OP)) expect(isNoteWriteOp(op)).toBe(true);
    expect(isNoteWriteOp("delete")).toBe(false);
    expect(isNoteWriteOp(null)).toBe(false);
  });
});

describe("storeBeforeImage", () => {
  test("writes the bytes under their sha256 and reports it stored", () => {
    const image = storeBeforeImage(vault, "prior body");
    expect(image.sha256).toBe(sha256Hex("prior body"));
    expect(image.stored).toBe(true);
    expect(image.path).toBe(writeImagePath(vault, image.sha256));
    expect(readFileSync(image.path, "utf8")).toBe("prior body");
  });

  test("a second image of identical content writes nothing", () => {
    const first = storeBeforeImage(vault, "same");
    const second = storeBeforeImage(vault, "same");
    expect(second.stored).toBe(false);
    expect(second.path).toBe(first.path);
  });

  test("distinct content gets distinct files", () => {
    storeBeforeImage(vault, "one");
    storeBeforeImage(vault, "two");
    expect(pruneWriteImages(vault, { olderThanDays: 0, dryRun: true }).removed).toHaveLength(2);
  });

  test("an image stamped in the future is zero days old, not minus one", () => {
    // `nowMs` is sampled once before the sweep, and mtime granularity on
    // a synced or networked filesystem can round a write made just
    // before it up past it. Unfloored, `msToWholeDays` turns that -1ms
    // into -1 whole day, which is below every window including zero, so
    // the image is kept forever. This is the condition that flaked the
    // `olderThanDays: 0` cases in CI on one image of two, staged here
    // deterministically rather than waited for.
    storeBeforeImage(vault, "one");
    const ahead = storeBeforeImage(vault, "two");
    const future = Date.now() / 1000 + 0.05;
    utimesSync(ahead.path, future, future);
    expect(pruneWriteImages(vault, { olderThanDays: 0, dryRun: true }).removed).toHaveLength(2);
  });
});

describe("recordNoteWrite", () => {
  test("appends exactly one note-write event with the design's fields", () => {
    const receipt = recordNoteWrite(vault, {
      op: NOTE_WRITE_OP.update,
      target: "Notes/A.md",
      before: { bytes: "old" },
      after: { bytes: "newer" },
      timestamp: TS,
      agent: AGENT,
    });
    const writeId = receipt.write_id;
    expect(writeId).toMatch(/^nw_\d{14}_[0-9a-f]{16}$/);

    const day = readLogDay(vault, DATE);
    const events = day.entries.filter((e) => e.eventType === BRAIN_LOG_EVENT_KIND.noteWrite);
    expect(events).toHaveLength(1);
    const body = events[0]!.body;
    expect(body["write_id"]).toBe(writeId!);
    expect(body["op"]).toBe(NOTE_WRITE_OP.update);
    expect(body["target"]).toBe("Notes/A.md");
    expect(body["hash_before"]).toBe(sha256Hex("old"));
    expect(body["hash_after"]).toBe(sha256Hex("newer"));
    expect(body["bytes_before"]).toBe("3");
    expect(body["bytes_after"]).toBe("5");
    expect(body["agent"]).toBe(AGENT);
    expect(events[0]!.agent).toBe(AGENT);
  });

  test("a null before is recorded as absent, not as the digest of nothing", () => {
    recordNoteWrite(vault, {
      op: NOTE_WRITE_OP.create,
      target: "Notes/A.md",
      before: null,
      after: { bytes: "body" },
      timestamp: TS,
      agent: AGENT,
    });
    const body = readLogDay(vault, DATE).entries[0]!.body;
    expect(body["hash_before"]).toBe(NOTE_WRITE_NO_PRIOR);
    expect(body["hash_before"]).not.toBe(sha256Hex(""));
    expect(body["bytes_before"]).toBe("0");
  });

  test("an absolute target inside the vault is recorded vault-relative", () => {
    recordNoteWrite(vault, {
      op: NOTE_WRITE_OP.append,
      target: join(vault, "Notes", "A.md"),
      before: { bytes: "a" },
      after: { bytes: "ab" },
      timestamp: TS,
      agent: AGENT,
    });
    expect(readLogDay(vault, DATE).entries[0]!.body["target"]).toBe("Notes/A.md");
  });

  // chmod cannot make a directory refuse new files on Windows (or as root).
  test.skipIf(CHMOD_CANNOT_DENY)(
    "a log-append failure returns a named audit_reason and never throws",
    () => {
      // An unwritable log directory is the shape a full disk, a permission
      // flip and a sync-locked tree all present as. The note is already on
      // disk by the time this runs, so a throw here would report a failure
      // for a write that succeeded.
      const logDir = join(vault, "Brain", "log");
      mkdirSync(logDir, { recursive: true });
      chmodSync(logDir, 0o500);
      try {
        const receipt = recordNoteWrite(vault, {
          op: NOTE_WRITE_OP.update,
          target: "Notes/A.md",
          before: { bytes: "old" },
          after: { bytes: "new" },
          timestamp: TS,
          agent: AGENT,
        });
        expect(receipt.write_id).toBeNull();
        expect(receipt.audit_reason).toContain("note-write event not recorded");
      } finally {
        chmodSync(logDir, 0o700);
      }
    },
  );
});

describe("pruneWriteImages", () => {
  test("the default window is the declared retention constant", () => {
    storeBeforeImage(vault, "fresh");
    expect(WRITE_IMAGE_RETENTION_DAYS).toBe(30);
    expect(pruneWriteImages(vault).removed).toEqual([]);
    expect(pruneWriteImages(vault).kept).toBe(1);
  });

  test("--older-than-days 0 removes every image; a dry run removes none", () => {
    const image = storeBeforeImage(vault, "gone");
    const preview = pruneWriteImages(vault, { olderThanDays: 0, dryRun: true });
    expect(preview.removed).toEqual([image.sha256]);
    expect(preview.dry_run).toBe(true);
    expect(existsSync(image.path)).toBe(true);

    const applied = pruneWriteImages(vault, { olderThanDays: 0 });
    expect(applied.removed).toEqual([image.sha256]);
    expect(applied.kept).toBe(0);
    expect(existsSync(image.path)).toBe(false);
  });

  test("an absent store is an empty result, not a fault", () => {
    expect(existsSync(writeImagesDir(vault))).toBe(false);
    expect(pruneWriteImages(vault)).toEqual({ removed: [], kept: 0, skipped: [], dry_run: false });
  });

  test("a negative window is refused by name", () => {
    expect(() => pruneWriteImages(vault, { olderThanDays: -1 })).toThrow(/non-negative integer/);
  });

  /**
   * The store is a directory on a synced filesystem, so a name that is
   * not a digest arrives there without anybody putting it there. The
   * prune is the ONLY bound on the store, so it must survive one.
   */
  test("a name that is not a digest is skipped and reported, not thrown on", () => {
    const image = storeBeforeImage(vault, "gone");
    const dir = writeImagesDir(vault);
    writeFileSync(join(dir, "readme.txt"), "not an image", "utf8");
    writeFileSync(join(dir, "x.sync-conflict-20260910-000000-ABCDEF"), "conflict copy", "utf8");

    const result = pruneWriteImages(vault, { olderThanDays: 0 });
    expect(result.removed).toEqual([image.sha256]);
    expect(existsSync(image.path)).toBe(false);
    expect(result.skipped.toSorted()).toEqual([
      "readme.txt",
      "x.sync-conflict-20260910-000000-ABCDEF",
    ]);
    expect(result.kept).toBe(0);
    // Skipped is not kept and not removed: a foreign name is neither an
    // image this prune spared nor one it took.
    expect(existsSync(join(dir, "readme.txt"))).toBe(true);
  });
});