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
19.8 KB
Raw Blame
/**
 * `o2b brain writes` (who-wrote-what, Task A / t_662f4e82).
 *
 * The operator surface over the note-write record: the default listing,
 * the filters, and the image prune with its dry run - which is the one
 * place a wrong verb in the output would cost real bytes.
 */

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

import { bootstrapBrain } from "../../src/core/brain/init.ts";
import { appendLogEvent } from "../../src/core/brain/log.ts";
import { recordNoteWrite, storeBeforeImage } from "../../src/core/brain/notes/write-record.ts";
import { writeImagePath } from "../../src/core/brain/paths.ts";
import { BRAIN_LOG_EVENT_KIND } from "../../src/core/brain/types.ts";
import { runCli } from "../helpers/run-cli.ts";
import { splitPosixShellWords } from "../helpers/posix-shell-words.ts";
import { CLI_SPAWN_BUDGET_MS } from "../helpers/cli-timeout.ts";

// Tests here spawn processes; see tests/helpers/cli-timeout.ts.
setDefaultTimeout(CLI_SPAWN_BUDGET_MS);

let tmp: string;
let vault: string;
let configPath: string;

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), "o2b-brain-writes-cli-"));
  vault = join(tmp, "vault");
  configPath = join(tmp, "config.yaml");
  writeFileSync(configPath, `vault: ${vault}\nagent_name: test\n`);
  bootstrapBrain(vault, { configPath });
});

afterEach(() => {
  rmSync(tmp, { recursive: true, force: true });
});

const env = () => ({ OPEN_SECOND_BRAIN_CONFIG: configPath });

function seedWrite(opts: {
  readonly timestamp: string;
  readonly agent: string;
  readonly target: string;
  readonly op: string;
  readonly deviceId?: string;
}): void {
  appendLogEvent(
    vault,
    {
      timestamp: opts.timestamp,
      eventType: BRAIN_LOG_EVENT_KIND.noteWrite,
      agent: opts.agent,
      body: {
        write_id: `nw_${opts.timestamp.replace(/\D/g, "")}_${"0".repeat(16)}`,
        op: opts.op,
        target: opts.target,
        hash_before: "a".repeat(64),
        hash_after: "b".repeat(64),
        bytes_before: "10",
        bytes_after: "20",
        agent: opts.agent,
      },
    },
    { deviceId: opts.deviceId ?? "" },
  );
}

describe("o2b brain writes", () => {
  test("lists every recorded write newest first, with no subcommand typed", async () => {
    seedWrite({ timestamp: "2026-03-04T01:00:00Z", agent: "claude", target: "A.md", op: "create" });
    seedWrite({ timestamp: "2026-03-04T02:00:00Z", agent: "codex", target: "B.md", op: "update" });

    const res = await runCli(["brain", "writes"], { env: env() });
    expect(res.returncode).toBe(0);
    const lines = res.stdout.trim().split("\n");
    expect(lines[0]).toContain("B.md");
    expect(lines[1]).toContain("A.md");
    // Every column of the row: when, what, who, where, and both digests.
    expect(lines[0]).toContain("2026-03-04T02:00:00Z");
    expect(lines[0]).toContain("update");
    expect(lines[0]).toContain("codex");
    expect(lines[0]).toContain("aaaaaaaa -> bbbbbbbb");
  });

  test("a legacy un-sharded log prints an absent device, not an invented one", async () => {
    seedWrite({ timestamp: "2026-03-04T01:00:00Z", agent: "claude", target: "A.md", op: "create" });
    const res = await runCli(["brain", "writes", "list"], { env: env() });
    expect(res.returncode).toBe(0);
    expect(res.stdout).toContain(" - ");
  });

  test("--json carries the full record, the count and the device", async () => {
    seedWrite({
      timestamp: "2026-03-04T01:00:00Z",
      agent: "claude",
      target: "A.md",
      op: "append",
      deviceId: "laptop",
    });
    const res = await runCli(["brain", "writes", "--json"], { env: env() });
    expect(res.returncode).toBe(0);
    const payload = JSON.parse(res.stdout) as {
      count: number;
      writes: Array<Record<string, unknown>>;
    };
    expect(payload.count).toBe(1);
    expect(payload.writes[0]).toMatchObject({
      op: "append",
      target: "A.md",
      agent: "claude",
      device: "laptop",
      bytes_before: 10,
      bytes_after: 20,
    });
  });

  test("filters by agent, path and op", async () => {
    seedWrite({ timestamp: "2026-03-04T01:00:00Z", agent: "claude", target: "A.md", op: "create" });
    seedWrite({ timestamp: "2026-03-04T02:00:00Z", agent: "codex", target: "B.md", op: "update" });

    const byAgent = await runCli(["brain", "writes", "--agent", "codex"], { env: env() });
    expect(byAgent.stdout).toContain("B.md");
    expect(byAgent.stdout).not.toContain("A.md");

    const byPath = await runCli(["brain", "writes", "--path", "A.md"], { env: env() });
    expect(byPath.stdout).toContain("A.md");
    expect(byPath.stdout).not.toContain("B.md");

    const byOp = await runCli(["brain", "writes", "--op", "create"], { env: env() });
    expect(byOp.stdout).toContain("A.md");
    expect(byOp.stdout).not.toContain("B.md");
  });

  test("an empty history says so rather than printing nothing", async () => {
    const res = await runCli(["brain", "writes"], { env: env() });
    expect(res.returncode).toBe(0);
    expect(res.stdout).toContain("no recorded note writes");
  });

  test("a bounded window excludes a shape-valid but unparseable timestamp", async () => {
    // The JSONL reader admits a timestamp by shape, so a foreign line can
    // carry an impossible instant (hour 99) that `Date.parse` turns into
    // NaN. The window must treat that as outside every bounded read, not
    // let NaN's all-false comparisons wave it into the plan.
    seedWrite({ timestamp: "2026-03-04T01:00:00Z", agent: "claude", target: "A.md", op: "create" });
    seedWrite({
      timestamp: "2026-03-04T99:99:99Z",
      agent: "claude",
      target: "B.md",
      op: "update",
    });

    const res = await runCli(
      ["brain", "writes", "list", "--since", "2026-03-03", "--until", "2026-03-05", "--json"],
      { env: env() },
    );
    expect(res.returncode).toBe(0);
    const payload = JSON.parse(res.stdout) as {
      count: number;
      writes: ReadonlyArray<Record<string, unknown>>;
    };
    expect(payload.count).toBe(1);
    expect(payload.writes[0]).toMatchObject({ target: "A.md" });
  });

  test("a bare-date --until includes the day's last fractional second", async () => {
    // The reader admits sub-second foreign lines, so an entry inside the
    // bound day's final second can carry a fraction; `--until 2026-03-04`
    // promises "through the end of the fourth" and must keep it.
    seedWrite({
      timestamp: "2026-03-04T23:59:59.500Z",
      agent: "claude",
      target: "A.md",
      op: "append",
    });

    const res = await runCli(["brain", "writes", "list", "--until", "2026-03-04", "--json"], {
      env: env(),
    });
    expect(res.returncode).toBe(0);
    expect(JSON.parse(res.stdout)).toMatchObject({ count: 1 });
  });

  test("an unknown --op is refused by name and lists the vocabulary", async () => {
    const res = await runCli(["brain", "writes", "--op", "delete"], { env: env() });
    expect(res.returncode).toBe(2);
    expect(res.stderr).toContain("--op must be one of create|update|append|revert");
  });

  test("an unknown subcommand names the four that exist", async () => {
    const res = await runCli(["brain", "writes", "purge"], { env: env() });
    expect(res.returncode).toBe(2);
    expect(res.stderr).toContain("expected list, destinations, revert or prune-images");
  });
});

describe("o2b brain writes prune-images", () => {
  test("--dry-run lists what would go and removes nothing", async () => {
    const image = storeBeforeImage(vault, "prior bytes");
    const res = await runCli(
      ["brain", "writes", "prune-images", "--older-than-days", "0", "--dry-run"],
      { env: env() },
    );
    expect(res.returncode).toBe(0);
    expect(res.stdout).toContain("would remove 1");
    expect(res.stdout).toContain(image.sha256);
    expect(existsSync(writeImagePath(vault, image.sha256))).toBe(true);
  });

  test("--older-than-days 0 removes them", async () => {
    const image = storeBeforeImage(vault, "prior bytes");
    const res = await runCli(["brain", "writes", "prune-images", "--older-than-days", "0"], {
      env: env(),
    });
    expect(res.returncode).toBe(0);
    expect(res.stdout).toContain("removed 1");
    expect(existsSync(writeImagePath(vault, image.sha256))).toBe(false);
  });

  test("the default window keeps a fresh image, and --json reports it", async () => {
    storeBeforeImage(vault, "prior bytes");
    const res = await runCli(["brain", "writes", "prune-images", "--json"], { env: env() });
    expect(res.returncode).toBe(0);
    expect(JSON.parse(res.stdout)).toMatchObject({
      removed: [],
      removed_count: 0,
      kept: 1,
      dry_run: false,
      older_than_days: 30,
    });
  });

  test("a negative window is refused by name before anything is read", async () => {
    const res = await runCli(["brain", "writes", "prune-images", "--older-than-days", "-1"], {
      env: env(),
    });
    expect(res.returncode).toBe(2);
    expect(res.stderr).toContain("--older-than-days must be a non-negative integer");
  });

  test("a name the store did not write is named, not removed and not fatal", async () => {
    const image = storeBeforeImage(vault, "prior bytes");
    const stray = join(dirname(writeImagePath(vault, image.sha256)), "readme.txt");
    writeFileSync(stray, "not an image", "utf8");

    const res = await runCli(["brain", "writes", "prune-images", "--older-than-days", "0"], {
      env: env(),
    });
    expect(res.returncode).toBe(0);
    expect(res.stdout).toContain("removed 1");
    expect(res.stdout).toContain("skipped 1 name(s) that are not before-images");
    expect(res.stdout).toContain("readme.txt");
    expect(existsSync(writeImagePath(vault, image.sha256))).toBe(false);
    expect(existsSync(stray)).toBe(true);
  });
});

describe("o2b brain writes revert", () => {
  /** Do what the write seams do, so the plan reads a real history. */
  function seedNote(opts: {
    readonly target: string;
    readonly bytes: string;
    readonly agent: string;
    readonly at: string;
  }): void {
    const abs = join(vault, opts.target);
    const before = existsSync(abs) ? readFileSync(abs, "utf8") : null;
    mkdirSync(dirname(abs), { recursive: true });
    if (before !== null) storeBeforeImage(vault, before);
    writeFileSync(abs, opts.bytes);
    recordNoteWrite(vault, {
      op: before === null ? "create" : "update",
      target: opts.target,
      before: before === null ? null : { bytes: before },
      after: { bytes: opts.bytes },
      timestamp: opts.at,
      agent: opts.agent,
    });
  }

  const TARGET = "notes/A.md";

  function seedTwoUpdatesByA(): void {
    seedNote({ target: TARGET, bytes: "v0", agent: "seed", at: "2026-03-04T01:00:00Z" });
    seedNote({ target: TARGET, bytes: "v1", agent: "claude", at: "2026-03-04T02:00:00Z" });
    seedNote({ target: TARGET, bytes: "v2", agent: "claude", at: "2026-03-04T03:00:00Z" });
  }

  /** One raw note-write row appended to a named device's shard. */
  function seedWriteOnDevice(opts: {
    readonly timestamp: string;
    readonly target: string;
    readonly deviceId: string;
  }): void {
    appendLogEvent(
      vault,
      {
        timestamp: opts.timestamp,
        eventType: BRAIN_LOG_EVENT_KIND.noteWrite,
        agent: "claude",
        body: {
          write_id: `nw_${opts.timestamp.replace(/\D/g, "")}_${opts.deviceId}_${opts.target}`,
          op: "update",
          target: opts.target,
          hash_before: "a".repeat(64),
          hash_after: "b".repeat(64),
          bytes_before: "10",
          bytes_after: "20",
          agent: "claude",
        },
      },
      { deviceId: opts.deviceId },
    );
  }

  test('revert --device "" is a bounded selector scoped to the legacy un-sharded pair', async () => {
    // normalizeFlagString treats emptiness as absence, so the empty device
    // used to fall out of the selector: a bare `--device ""` was refused
    // as unbounded, and `--device "" --path X` silently reverted X's
    // writes from EVERY device. The empty string is a filter value - the
    // same contract `list` and `destinations` already keep.
    seedWriteOnDevice({ timestamp: "2026-03-04T01:00:00Z", target: TARGET, deviceId: "" });
    seedWriteOnDevice({ timestamp: "2026-03-04T02:00:00Z", target: TARGET, deviceId: "laptop" });

    const res = await runCli(["brain", "writes", "revert", "--device", "", "--json"], {
      env: env(),
    });
    expect(res.returncode).toBe(0);
    const payload = JSON.parse(res.stdout) as {
      selector: Record<string, unknown>;
      entries: ReadonlyArray<{ writes: ReadonlyArray<string> }>;
    };
    expect(payload.selector).toEqual({ device: "" });
    // Only the un-sharded write is selected; the laptop write on the same
    // target is not part of this plan.
    expect(payload.entries).toHaveLength(1);
    expect(payload.entries[0]!.writes).toHaveLength(1);
  });

  test('revert --device "" beside --path keeps the device filter, not just the path', async () => {
    seedWriteOnDevice({ timestamp: "2026-03-04T01:00:00Z", target: TARGET, deviceId: "" });
    seedWriteOnDevice({ timestamp: "2026-03-04T02:00:00Z", target: TARGET, deviceId: "laptop" });

    const res = await runCli(
      ["brain", "writes", "revert", "--device", "", "--path", TARGET, "--json"],
      { env: env() },
    );
    expect(res.returncode).toBe(0);
    const payload = JSON.parse(res.stdout) as {
      selector: Record<string, unknown>;
      entries: ReadonlyArray<{ writes: ReadonlyArray<string> }>;
    };
    expect(payload.selector).toEqual({ device: "", path: TARGET });
    // The filter is pinned by its SELECTION, not its echo: the plan reads
    // `plan.selector` back verbatim, so an echoed selector proves nothing
    // about what the read selected. Only the un-sharded write may be
    // planned - the laptop write on the same target would ride in here if
    // the device filter were dropped between the echo and the read.
    expect(payload.entries).toHaveLength(1);
    expect(payload.entries[0]!.writes).toHaveLength(1);
  });

  test("the echoed --apply invocation quotes an empty --device", async () => {
    seedWriteOnDevice({ timestamp: "2026-03-04T01:00:00Z", target: TARGET, deviceId: "" });
    const res = await runCli(["brain", "writes", "revert", "--device", ""], { env: env() });
    expect(res.returncode).toBe(0);
    // Unquoted, the echo renders `--device ` - an invocation that pastes
    // back with the flag dropped and plans every device on re-read. The
    // echo quotes POSIX-style, so the empty value renders as two single
    // quotes.
    expect(res.stdout).toContain("revert --device ''");
  });

  test("the echoed --apply invocation quotes words bash would leave bare", async () => {
    // `+` rides bash's own safe-word list, so a per-verb escaper that
    // copied that list left `claude+v2` bare. The shared escaper's plain
    // set is deliberately narrower - one set, one behavior to audit -
    // so anything outside it costs one quoting spell.
    seedWrite({
      timestamp: "2026-03-04T01:00:00Z",
      agent: "claude+v2",
      target: TARGET,
      op: "update",
    });
    const res = await runCli(["brain", "writes", "revert", "--agent", "claude+v2"], { env: env() });
    expect(res.returncode).toBe(0);
    expect(res.stdout).toContain("revert --agent 'claude+v2'");
  });

  test("the echoed --apply invocation round-trips a hostile --agent", async () => {
    // A bang, spaces and both quote kinds in one value: the echo must
    // paste back into exactly the selector that was planned, which the
    // parse side of the round-trip checks word by word.
    const hostile = `cl'aude "the" younger!`;
    seedWrite({ timestamp: "2026-03-04T01:00:00Z", agent: hostile, target: TARGET, op: "update" });
    const res = await runCli(["brain", "writes", "revert", "--agent", hostile], { env: env() });
    expect(res.returncode).toBe(0);
    const apply = res.stdout.split("\n").find((l) => l.startsWith("o2b brain writes revert"))!;
    const words = splitPosixShellWords(apply);
    expect(words.slice(0, 6)).toEqual(["o2b", "brain", "writes", "revert", "--agent", hostile]);
    expect(words[6]).toBe("--apply");
    expect(words[7]).toMatch(/^[0-9a-f]{64}$/);
  });

  test("prints the plan, the digest and the exact --apply invocation", async () => {
    seedTwoUpdatesByA();
    const res = await runCli(["brain", "writes", "revert", "--agent", "claude"], { env: env() });
    expect(res.returncode).toBe(0);
    expect(res.stdout).toContain(TARGET);
    expect(res.stdout).toContain("restore");
    expect(res.stdout).toMatch(/digest: [0-9a-f]{64}/);
    const digest = res.stdout
      .split("\n")
      .find((l) => l.startsWith("digest:"))!
      .slice("digest:".length)
      .trim();
    expect(res.stdout).toContain(`o2b brain writes revert --agent claude --apply ${digest}`);
    // A plan is a report: nothing moved.
    expect(readFileSync(join(vault, TARGET), "utf8")).toBe("v2");
  });

  test("a selector naming nobody and nothing is refused, and exits 1", async () => {
    const res = await runCli(["brain", "writes", "revert", "--since", "2026-03-04"], {
      env: env(),
    });
    expect(res.returncode).toBe(1);
    expect(res.stderr).toContain("unbounded_selector");
  });

  test("a plan that refuses every target is a report, not a failure", async () => {
    seedTwoUpdatesByA();
    writeFileSync(join(vault, TARGET), "drifted");
    const res = await runCli(["brain", "writes", "revert", "--agent", "claude"], { env: env() });
    expect(res.returncode).toBe(0);
    expect(res.stdout).toContain("drift");
  });

  test("--apply restores the bytes and names the snapshot it took", async () => {
    seedTwoUpdatesByA();
    const plan = await runCli(["brain", "writes", "revert", "--agent", "claude", "--json"], {
      env: env(),
    });
    const digest = (JSON.parse(plan.stdout) as { digest: string }).digest;

    const res = await runCli(
      ["brain", "writes", "revert", "--agent", "claude", "--apply", digest],
      { env: env() },
    );
    expect(res.returncode).toBe(0);
    expect(res.stdout).toContain("note-revert-");
    expect(res.stdout).toContain(`restore  ${TARGET}`);
    expect(readFileSync(join(vault, TARGET), "utf8")).toBe("v0");
  });

  test("a stale digest is refused by name and exits 1", async () => {
    seedTwoUpdatesByA();
    const res = await runCli(
      ["brain", "writes", "revert", "--agent", "claude", "--apply", "f".repeat(64)],
      { env: env() },
    );
    expect(res.returncode).toBe(1);
    expect(res.stderr).toContain("digest_mismatch");
    expect(readFileSync(join(vault, TARGET), "utf8")).toBe("v2");
  });

  test("a plan with nothing to apply is refused by name and exits 1", async () => {
    seedTwoUpdatesByA();
    writeFileSync(join(vault, TARGET), "drifted");
    const plan = await runCli(["brain", "writes", "revert", "--agent", "claude", "--json"], {
      env: env(),
    });
    const digest = (JSON.parse(plan.stdout) as { digest: string }).digest;
    const res = await runCli(
      ["brain", "writes", "revert", "--agent", "claude", "--apply", digest],
      { env: env() },
    );
    expect(res.returncode).toBe(1);
    expect(res.stderr).toContain("nothing_to_apply");
  });

  test("--json carries the entries and the digest", async () => {
    seedTwoUpdatesByA();
    const res = await runCli(["brain", "writes", "revert", "--path", TARGET, "--json"], {
      env: env(),
    });
    expect(res.returncode).toBe(0);
    const payload = JSON.parse(res.stdout) as {
      digest: string;
      entries: ReadonlyArray<Record<string, unknown>>;
      selector: Record<string, unknown>;
    };
    expect(payload.selector).toEqual({ path: TARGET });
    expect(payload.entries).toHaveLength(1);
    // A path with no agent selects EVERY write on that note, including
    // the one that created it, so undoing them all removes the note.
    expect(payload.entries[0]!["action"]).toBe("delete");
  });
});