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

import {
  appendLogEvent,
  logChainHash,
  parseLogDay,
  type BrainLogEntry,
} from "../../src/core/brain/log.ts";
import { brainDirs, logJsonlPath, logPath } from "../../src/core/brain/paths.ts";
import { useUnshardedLegacyLog } from "../helpers/device-id.ts";

// The legacy day log and ledgers are read under their un-sharded names.
useUnshardedLegacyLog();

let tmp: string;

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), "o2b-brain-log-"));
  // A legacy Brain/ tree: an unswitched machine (a vault without one is store-only).
  mkdirSync(join(tmp, "Brain"), { recursive: true });
});

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

describe("appendLogEvent — create-on-first-event", () => {
  test("creates the file with a canonical header and the first event", () => {
    const event: BrainLogEntry = {
      timestamp: "2026-05-14T10:42:00Z",
      eventType: "dream",
      body: {
        run_id: "dream-2026-05-14-104200",
        input_signals: "7",
        new_unconfirmed: ["[[pref-no-internal-abbrev]] (signal_balance: -3)"],
        confirmed: "0",
        retired: "0",
      },
    };
    const res = appendLogEvent(tmp, event);
    expect(res.logPath).toBe(logPath(tmp, "2026-05-14"));
    expect(existsSync(res.logPath)).toBe(true);
    const bytes = readFileSync(res.logPath, "utf8");
    expect(bytes).toContain("---\nkind: brain-log\ndate: 2026-05-14");
    expect(bytes).toContain("tags: [brain, brain/log]");
    expect(bytes).toContain("# Brain log — 2026-05-14");
    expect(bytes).toContain("## 10:42:00Z — dream");
    expect(bytes).toContain("- run_id: dream-2026-05-14-104200");
    expect(bytes).toContain("- new_unconfirmed:");
    expect(bytes).toContain("  - [[pref-no-internal-abbrev]] (signal_balance: -3)");
  });

  test("parseLogDay returns the single event", () => {
    appendLogEvent(tmp, {
      timestamp: "2026-05-14T10:42:00Z",
      eventType: "dream",
      body: { run_id: "dream-2026-05-14-104200", confirmed: "0" },
    });
    const { entries, warnings } = parseLogDay(tmp, "2026-05-14");
    expect(warnings).toEqual([]);
    expect(entries).toHaveLength(1);
    expect(entries[0]!.eventType).toBe("dream");
    expect(entries[0]!.timestamp).toBe("2026-05-14T10:42:00Z");
    expect(entries[0]!.body["run_id"]).toBe("dream-2026-05-14-104200");
  });

  test("parseLogDay returns [] for a missing file (no Brain log for that day)", () => {
    const { entries, warnings } = parseLogDay(tmp, "2099-01-01");
    expect(entries).toEqual([]);
    expect(warnings).toEqual([]);
  });
});

describe("appendLogEvent — multi-event same day", () => {
  test("two appends produce two parseable events in stable order", () => {
    appendLogEvent(tmp, {
      timestamp: "2026-05-14T10:42:00Z",
      eventType: "dream",
      body: { run_id: "dream-2026-05-14-104200" },
    });
    appendLogEvent(tmp, {
      timestamp: "2026-05-14T14:22:00Z",
      eventType: "apply-evidence",
      body: {
        preference: "[[pref-no-internal-abbrev]]",
        artifact: "[[Daily/2026.05.14#section-blog-post]]",
        agent: "claude",
        result: "applied",
        note: "Expanded OSB on first use.",
      },
    });
    const { entries, warnings } = parseLogDay(tmp, "2026-05-14");
    expect(warnings).toEqual([]);
    expect(entries).toHaveLength(2);
    expect(entries[0]!.eventType).toBe("dream");
    expect(entries[1]!.eventType).toBe("apply-evidence");
    expect(entries[1]!.body["result"]).toBe("applied");
    expect(entries[1]!.body["preference"]).toBe("[[pref-no-internal-abbrev]]");
  });

  test("two events at the exact same UTC second land in order of call", () => {
    appendLogEvent(tmp, {
      timestamp: "2026-05-14T10:42:00Z",
      eventType: "feedback",
      body: { signal: "[[sig-a]]" },
    });
    appendLogEvent(tmp, {
      timestamp: "2026-05-14T10:42:00Z",
      eventType: "feedback",
      body: { signal: "[[sig-b]]" },
    });
    const { entries } = parseLogDay(tmp, "2026-05-14");
    expect(entries).toHaveLength(2);
    expect(entries[0]!.body["signal"]).toBe("[[sig-a]]");
    expect(entries[1]!.body["signal"]).toBe("[[sig-b]]");
  });

  test("the original file bytes are preserved verbatim across appends (append-only)", () => {
    const a = appendLogEvent(tmp, {
      timestamp: "2026-05-14T10:42:00Z",
      eventType: "dream",
      body: { run_id: "dream-2026-05-14-104200" },
    });
    const firstBytes = readFileSync(a.logPath, "utf8");
    appendLogEvent(tmp, {
      timestamp: "2026-05-14T14:22:00Z",
      eventType: "apply-evidence",
      body: {
        preference: "[[pref-foo]]",
        artifact: "[[bar]]",
        agent: "claude",
        result: "applied",
      },
    });
    const secondBytes = readFileSync(a.logPath, "utf8");
    // The second file must start with the first file's full content
    // (trailing whitespace tolerated) — i.e. nothing earlier was edited.
    const stripTrailing = (s: string): string => s.replace(/\s+$/, "");
    expect(secondBytes.startsWith(stripTrailing(firstBytes))).toBe(true);
    expect(secondBytes.length).toBeGreaterThan(firstBytes.length);
  });
});

describe("parseLogDay — malformed entry tolerance", () => {
  test("returns only the valid entries and reports warnings for the rest", () => {
    const dirs = brainDirs(tmp);
    mkdirSync(dirs.log, { recursive: true });
    const path = logPath(tmp, "2026-05-14");
    const content = [
      "---",
      "kind: brain-log",
      "date: 2026-05-14",
      "tags: [brain, brain/log]",
      "---",
      "",
      "# Brain log — 2026-05-14",
      "",
      "## 10:42:00Z — dream",
      "- run_id: dream-2026-05-14-104200",
      "- confirmed: 0",
      "",
      "## 11:00:00 NOT-A-VALID-HEADER", // broken header
      "- this: should be ignored",
      "",
      "## 12:00:00Z — apply-evidence",
      "- preference: [[pref-foo]]",
      "- artifact: [[bar]]",
      "- agent: claude",
      "- result: applied",
      "",
      "## 13:00:00Z — totally-bogus-kind", // unknown event kind
      "- foo: bar",
      "",
      "## 14:00:00Z — feedback",
      "- signal: [[sig-x]]",
      "garbage line that is not a bullet", // malformed bullet inside a valid block
      "- topic: foo",
    ].join("\n");
    writeFileSync(path, content, "utf8");

    const { entries, warnings } = parseLogDay(tmp, "2026-05-14");
    // Only the three well-formed entries (dream, apply-evidence,
    // feedback) survive.
    expect(entries).toHaveLength(3);
    expect(entries.map((e) => e.eventType)).toEqual(["dream", "apply-evidence", "feedback"]);
    // The broken header and bogus kind both produce warnings; the
    // stray bullet does too.
    expect(warnings.length).toBeGreaterThanOrEqual(2);
    const messages = warnings.map((w) => w.message).join("\n");
    expect(messages).toMatch(/malformed event header|unknown event kind/);
  });
});

describe("ISO timestamp round-trip", () => {
  test("appended timestamp parses back verbatim", () => {
    const ts = "2026-05-14T07:08:09Z";
    appendLogEvent(tmp, {
      timestamp: ts,
      eventType: "promote",
      body: { preference: "[[pref-foo]]" },
    });
    const { entries } = parseLogDay(tmp, "2026-05-14");
    expect(entries).toHaveLength(1);
    expect(entries[0]!.timestamp).toBe(ts);
  });

  test("sub-second precision is truncated to seconds in the heading", () => {
    appendLogEvent(tmp, {
      timestamp: "2026-05-14T07:08:09.123Z",
      eventType: "promote",
      body: { preference: "[[pref-foo]]" },
    });
    const { entries } = parseLogDay(tmp, "2026-05-14");
    expect(entries).toHaveLength(1);
    // The serialised form drops sub-seconds; the parser reconstructs
    // a clean `HH:MM:SSZ`.
    expect(entries[0]!.timestamp).toBe("2026-05-14T07:08:09Z");
  });

  test("invalid timestamp shape is rejected at append time", () => {
    expect(() =>
      appendLogEvent(tmp, {
        timestamp: "2026-05-14 10:42:00",
        eventType: "promote",
        body: {},
      }),
    ).toThrow(/ISO-8601 UTC/);
  });

  test("unknown event kind is rejected at append time", () => {
    expect(() =>
      appendLogEvent(tmp, {
        timestamp: "2026-05-14T10:42:00Z",
        eventType: "totally-bogus" as unknown as "dream",
        body: {},
      }),
    ).toThrow(/unknown event kind/);
  });
});

describe("appendLogEvent — JSONL sidecar (§23, v0.10.8)", () => {
  test("writes the same event to both .md and .jsonl", () => {
    const entry: BrainLogEntry = {
      timestamp: "2026-05-19T10:00:00Z",
      eventType: "feedback",
      body: { signal: "[[sig-x]]", topic: "x", sign: "positive" },
    };
    const res = appendLogEvent(tmp, entry);
    const jsonlPath = logJsonlPath(tmp, "2026-05-19");

    expect(existsSync(res.logPath)).toBe(true);
    expect(existsSync(jsonlPath)).toBe(true);

    const jsonl = readFileSync(jsonlPath, "utf8");
    const lines = jsonl.trim().split("\n");
    expect(lines).toHaveLength(1);
    const parsed = JSON.parse(lines[0]!);
    // `origin_channel` is the server-derived channel of the writing
    // process (Unit C of the nothing-writes-silently wave), folded into
    // the body the same way `agent` is so the markdown block and this row
    // stay one-to-one. `unset` because a test harness is not one of the
    // entry points that claims a channel - the explicit literal for that,
    // never a guessed `cli`.
    //
    // `prev` and `h` are the per-shard hash chain (who-wrote-what, Task
    // E). This is the first line of the shard, so it anchors the chain
    // with `prev: null`; `h` is asserted against the recomputation
    // rather than a literal, because a hard-coded digest here would
    // re-key silently the day the projection gains a field.
    const { h, ...withoutHash } = parsed as Record<string, unknown>;
    expect(withoutHash).toEqual({
      ts: "2026-05-19T10:00:00Z",
      kind: "feedback",
      payload: {
        signal: "[[sig-x]]",
        topic: "x",
        sign: "positive",
        origin_channel: "unset",
      },
      prev: null,
    });
    expect(h).toBe(
      logChainHash(null, "2026-05-19T10:00:00Z", "feedback", {
        signal: "[[sig-x]]",
        topic: "x",
        sign: "positive",
        origin_channel: "unset",
      }),
    );
  });

  test("appends a second event to both files", () => {
    appendLogEvent(tmp, {
      timestamp: "2026-05-19T10:00:00Z",
      eventType: "feedback",
      body: { signal: "[[sig-a]]", topic: "a", sign: "positive" },
    });
    appendLogEvent(tmp, {
      timestamp: "2026-05-19T10:00:01Z",
      eventType: "apply-evidence",
      body: {
        preference: "[[pref-a]]",
        artifact: "[[file.ts]]",
        agent: "@x",
        result: "applied",
      },
    });
    const jsonlPath = logJsonlPath(tmp, "2026-05-19");
    const jsonl = readFileSync(jsonlPath, "utf8");
    const lines = jsonl.trim().split("\n");
    expect(lines).toHaveLength(2);
    expect(JSON.parse(lines[0]!).kind).toBe("feedback");
    expect(JSON.parse(lines[1]!).kind).toBe("apply-evidence");
  });

  test("encodes array payloads as JSON arrays", () => {
    appendLogEvent(tmp, {
      timestamp: "2026-05-19T10:00:00Z",
      eventType: "dream",
      body: {
        run_id: "dream-1",
        new_unconfirmed: ["[[pref-a]]", "[[pref-b]]"],
      },
    });
    const jsonlPath = logJsonlPath(tmp, "2026-05-19");
    const jsonl = readFileSync(jsonlPath, "utf8");
    const parsed = JSON.parse(jsonl.trim());
    expect(parsed.payload.new_unconfirmed).toEqual(["[[pref-a]]", "[[pref-b]]"]);
    expect(parsed.payload.run_id).toBe("dream-1");
  });

  test("creates the JSONL sidecar even when the .md already exists by hand", () => {
    // Simulate a pre-v0.10.8 day: markdown present, sidecar absent.
    const mdPath = logPath(tmp, "2026-05-10");
    mkdirSync(brainDirs(tmp).log, { recursive: true });
    writeFileSync(
      mdPath,
      `---
kind: brain-log
date: 2026-05-10
tags: [brain, brain/log]
---

# Brain log — 2026-05-10

## 09:00:00Z — feedback
- signal: [[sig-old]]
- topic: old
- sign: positive
`,
      "utf8",
    );

    appendLogEvent(tmp, {
      timestamp: "2026-05-10T10:00:00Z",
      eventType: "feedback",
      body: { signal: "[[sig-new]]", topic: "new", sign: "positive" },
    });

    const jsonlPath = logJsonlPath(tmp, "2026-05-10");
    expect(existsSync(jsonlPath)).toBe(true);
    const lines = readFileSync(jsonlPath, "utf8").trim().split("\n");
    // Only the new event lands in JSONL — backfill of the pre-existing
    // markdown block is intentionally out of scope (lazy fallback in
    // readLogDay handles historical markdown).
    expect(lines).toHaveLength(1);
    expect(JSON.parse(lines[0]!).payload.topic).toBe("new");
  });
});