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

import {
  LEDGER_KEY_ACTIVE,
  LEDGER_KEY_RECALL,
  LEDGER_KEY_REGROUND,
  LEDGER_TTL_MS,
  RECALL_SET_MAX,
  beginInjectionEpoch,
  digestNotePaths,
  isRealSessionId,
  readActiveEmittedPaths,
  readRecallInjected,
  recordRecallInjected,
  takeRegroundPart,
} from "../../hooks/lib/injection-ledger.ts";
import {
  hookStateFilePath,
  readHookStamp,
  updateHookState,
  writeHookStamp,
} from "../../hooks/lib/session-state.ts";
import { _resetHeldLocksForTests } from "../../src/core/brain/sync-lockfile.ts";
import { IS_WINDOWS } from "../helpers/platform.ts";

let vault: string;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-ledger-"));
  // A legacy vault: it keeps its machine state. A vault with no `Brain/`
  // is store-only and keeps that state device-local instead.
  mkdirSync(join(vault, "Brain"), { recursive: true });
});

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

const NOW = 10_000_000;

function holdLock(sessionId: string): string {
  const lockPath = hookStateFilePath(vault, sessionId) + ".lock";
  mkdirSync(join(vault, ".open-second-brain", "hook-state"), { recursive: true });
  writeFileSync(lockPath, "held by another process\n");
  return lockPath;
}

/** How many times `run` sleeps through `Atomics.wait` (the lock retry's sleep). */
function countRetrySleeps(run: () => void): number {
  const original = Atomics.wait;
  let calls = 0;
  Atomics.wait = ((...args: Parameters<typeof Atomics.wait>) => {
    calls += 1;
    return original(...args);
  }) as typeof Atomics.wait;
  try {
    run();
  } finally {
    Atomics.wait = original;
  }
  return calls;
}

function seedQueue(sessionId: string, parts: ReadonlyArray<string>, epoch = "ep-1"): void {
  expect(
    beginInjectionEpoch(
      vault,
      sessionId,
      { epoch, emittedPaths: [], regroundParts: parts, partCeilingChars: 9000 },
      NOW,
    ),
  ).toBe(true);
}

describe("isRealSessionId", () => {
  test("accepts a non-empty string", () => {
    expect(isRealSessionId("sess-1")).toBe(true);
  });

  test("rejects undefined, null, empty, separator-only and non-strings", () => {
    for (const value of [undefined, null, "", "   ", "\t", "---", "::", 42, {}, ["s"]]) {
      expect(isRealSessionId(value)).toBe(false);
    }
  });
});

describe("recall injected set", () => {
  test("missing ledger reads as an empty set", () => {
    expect(readRecallInjected(vault, "sess-1", NOW).size).toBe(0);
  });

  test("records merge and read back until the TTL passes", () => {
    expect(recordRecallInjected(vault, "sess-1", ["k1", "k2"], NOW)).toBe(true);
    expect(recordRecallInjected(vault, "sess-1", ["k2", "k3"], NOW + 1000)).toBe(true);
    const live = readRecallInjected(vault, "sess-1", NOW + 2000);
    expect([...live].toSorted()).toEqual(["k1", "k2", "k3"]);
    // The TTL is refreshed on every write.
    expect(readRecallInjected(vault, "sess-1", NOW + 1000 + LEDGER_TTL_MS - 1).size).toBe(3);
    expect(readRecallInjected(vault, "sess-1", NOW + 1000 + LEDGER_TTL_MS).size).toBe(0);
  });

  test("an expired set is not merged into a new record", () => {
    recordRecallInjected(vault, "sess-1", ["old"], NOW);
    recordRecallInjected(vault, "sess-1", ["new"], NOW + LEDGER_TTL_MS + 1);
    expect([...readRecallInjected(vault, "sess-1", NOW + LEDGER_TTL_MS + 2)]).toEqual(["new"]);
  });

  test("the set keeps only the most recent RECALL_SET_MAX keys", () => {
    const keys = Array.from({ length: RECALL_SET_MAX + 5 }, (_, i) => `k${i}`);
    expect(recordRecallInjected(vault, "sess-1", keys.slice(0, 10), NOW)).toBe(true);
    expect(recordRecallInjected(vault, "sess-1", keys.slice(10), NOW + 1)).toBe(true);
    const live = readRecallInjected(vault, "sess-1", NOW + 2);
    expect(live.size).toBe(RECALL_SET_MAX);
    for (const dropped of keys.slice(0, 5)) expect(live.has(dropped)).toBe(false);
    expect(live.has(keys[5]!)).toBe(true);
    expect(live.has(keys.at(-1)!)).toBe(true);
  });

  test("a malformed payload reads as an empty set", () => {
    const path = hookStateFilePath(vault, "sess-1");
    mkdirSync(join(vault, ".open-second-brain", "hook-state"), { recursive: true });
    writeFileSync(
      path,
      JSON.stringify({ [LEDGER_KEY_RECALL]: { expiresAt: NOW + 5000, data: { keys: "nope" } } }),
    );
    expect(readRecallInjected(vault, "sess-1", NOW).size).toBe(0);
  });
});

describe("digestNotePaths", () => {
  test("maps every rendered preference bullet and dedupes repeats", () => {
    const paths = digestNotePaths({
      emittedText:
        "- `pref-alpha` (confidence: high) — rule\n- `pref-beta-2` — rule\n- `pref-alpha` (applied_in_window: 3)",
      activeBodyEmitted: false,
      lessonsBodyEmitted: false,
    });
    expect(paths).toEqual(["Brain/preferences/pref-alpha.md", "Brain/preferences/pref-beta-2.md"]);
  });

  test("adds active.md and lessons.md only when flagged", () => {
    const both = digestNotePaths({
      emittedText: "",
      activeBodyEmitted: true,
      lessonsBodyEmitted: true,
    });
    expect(both).toEqual(["Brain/active.md", "Brain/lessons.md"]);
    const lessonsOnly = digestNotePaths({
      emittedText: "- `pref-x` — rule",
      activeBodyEmitted: false,
      lessonsBodyEmitted: true,
    });
    expect(lessonsOnly).toEqual(["Brain/lessons.md", "Brain/preferences/pref-x.md"]);
  });

  test("a backticked pref token quoted in prose is not a delivered preference", () => {
    expect(
      digestNotePaths({
        emittedText: [
          "- `lesson-1` (tags: x) — remember `pref-x` when editing",
          "Quoted in active.md: see `pref-y` for details.",
          "  - `pref-z` nested quote",
          "- `pref-real` (confidence: high) — a rendered rule",
        ].join("\n"),
        activeBodyEmitted: false,
        lessonsBodyEmitted: false,
      }),
    ).toEqual(["Brain/preferences/pref-real.md"]);
  });

  test("ignores a pref word outside backticks", () => {
    expect(
      digestNotePaths({
        emittedText: "see pref-alpha in prose",
        activeBodyEmitted: false,
        lessonsBodyEmitted: false,
      }),
    ).toEqual([]);
  });
});

describe("beginInjectionEpoch", () => {
  test.skipIf(IS_WINDOWS)("writes the state file private (mode 0o600)", () => {
    seedQueue("sess-1", ["part-2"]);
    expect(statSync(hookStateFilePath(vault, "sess-1")).mode & 0o777).toBe(0o600);
  });

  test("sets the active set, clears the recall set and replaces the queue in one write", () => {
    recordRecallInjected(vault, "sess-1", ["k1"], NOW);
    seedQueue("sess-1", ["old-2", "old-3"], "ep-old");
    expect(
      beginInjectionEpoch(
        vault,
        "sess-1",
        {
          epoch: "ep-new",
          emittedPaths: ["Brain/active.md", "Brain/preferences/pref-a.md"],
          regroundParts: ["new-2"],
          partCeilingChars: 4000,
        },
        NOW + 10,
      ),
    ).toBe(true);
    expect([...readActiveEmittedPaths(vault, "sess-1", NOW + 20)]).toEqual([
      "Brain/active.md",
      "Brain/preferences/pref-a.md",
    ]);
    expect(readRecallInjected(vault, "sess-1", NOW + 20).size).toBe(0);
    expect(readHookStamp(vault, "sess-1", LEDGER_KEY_RECALL, NOW + 20)).toBeNull();
    const take = takeRegroundPart(vault, "sess-1", NOW + 30);
    expect(take).toEqual({
      status: "part",
      part: "new-2",
      index: 2,
      total: 2,
      epoch: "ep-new",
      partCeilingChars: 4000,
    });
  });

  test("an empty part list deletes the queue", () => {
    seedQueue("sess-1", ["p2"]);
    beginInjectionEpoch(
      vault,
      "sess-1",
      { epoch: "ep-2", emittedPaths: [], regroundParts: [], partCeilingChars: 9000 },
      NOW + 5,
    );
    expect(readHookStamp(vault, "sess-1", LEDGER_KEY_REGROUND, NOW + 6)).toBeNull();
    expect(takeRegroundPart(vault, "sess-1", NOW + 6)).toEqual({ status: "empty" });
  });

  test("repeated emitted paths are stored once", () => {
    beginInjectionEpoch(
      vault,
      "sess-1",
      {
        epoch: "e",
        emittedPaths: ["Brain/active.md", "Brain/active.md", "Brain/preferences/pref-a.md"],
        regroundParts: [],
        partCeilingChars: 9000,
      },
      NOW,
    );
    expect(readHookStamp(vault, "sess-1", LEDGER_KEY_ACTIVE, NOW)!.data!["paths"]).toEqual([
      "Brain/active.md",
      "Brain/preferences/pref-a.md",
    ]);
  });

  test("the active set expires after the TTL", () => {
    beginInjectionEpoch(
      vault,
      "sess-1",
      { epoch: "e", emittedPaths: ["Brain/active.md"], regroundParts: [], partCeilingChars: 9000 },
      NOW,
    );
    expect(readHookStamp(vault, "sess-1", LEDGER_KEY_ACTIVE, NOW)).not.toBeNull();
    expect(readActiveEmittedPaths(vault, "sess-1", NOW + LEDGER_TTL_MS).size).toBe(0);
  });
});

describe("takeRegroundPart", () => {
  test("returns parts 2..n in order, then empty", () => {
    seedQueue("sess-1", ["p2", "p3", "p4"]);
    const got = [1, 2, 3].map(() => takeRegroundPart(vault, "sess-1", NOW + 1));
    expect(got.map((t) => (t.status === "part" ? [t.part, t.index, t.total] : t.status))).toEqual([
      ["p2", 2, 4],
      ["p3", 3, 4],
      ["p4", 4, 4],
    ]);
    expect(takeRegroundPart(vault, "sess-1", NOW + 1)).toEqual({ status: "empty" });
    expect(takeRegroundPart(vault, "sess-1", NOW + 1)).toEqual({ status: "empty" });
  });

  test("taking the last part deletes the queue key", () => {
    seedQueue("sess-1", ["p2", "p3"]);
    takeRegroundPart(vault, "sess-1", NOW + 1);
    expect(readHookStamp(vault, "sess-1", LEDGER_KEY_REGROUND, NOW + 1)).not.toBeNull();
    expect(takeRegroundPart(vault, "sess-1", NOW + 2)).toMatchObject({ status: "part", index: 3 });
    expect(readStateKeys("sess-1")).not.toContain(LEDGER_KEY_REGROUND);
  });

  test("no queue reads as empty without creating a state file", () => {
    expect(takeRegroundPart(vault, "sess-1", NOW)).toEqual({ status: "empty" });
    expect(existsSync(hookStateFilePath(vault, "sess-1"))).toBe(false);
  });

  test("a queue whose cursor is not a non-negative integer reads as empty and is deleted", () => {
    for (const next of [-1, 1.5]) {
      seedQueue("sess-1", ["p2", "p3"]);
      const queue = readHookStamp(vault, "sess-1", LEDGER_KEY_REGROUND, NOW)!;
      writeHookStamp(vault, "sess-1", LEDGER_KEY_REGROUND, {
        expiresAt: queue.expiresAt,
        data: { ...queue.data, next },
      });
      expect(takeRegroundPart(vault, "sess-1", NOW + 1)).toEqual({ status: "empty" });
      expect(readStateKeys("sess-1")).not.toContain(LEDGER_KEY_REGROUND);
    }
  });

  test("a queue from an older epoch than the active one reads as empty and is deleted", () => {
    seedQueue("sess-1", ["p2", "p3"], "ep-a");
    writeHookStamp(vault, "sess-1", LEDGER_KEY_ACTIVE, {
      expiresAt: NOW + LEDGER_TTL_MS,
      data: { epoch: "ep-b", paths: [] },
    });
    expect(takeRegroundPart(vault, "sess-1", NOW + 1)).toEqual({ status: "empty" });
    expect(readStateKeys("sess-1")).not.toContain(LEDGER_KEY_REGROUND);
  });

  test("an expired queue reads as empty", () => {
    seedQueue("sess-1", ["p2"]);
    expect(takeRegroundPart(vault, "sess-1", NOW + LEDGER_TTL_MS)).toEqual({ status: "empty" });
  });

  test("busy while the lock is held, and the undelivered part survives", () => {
    seedQueue("sess-1", ["p2", "p3"]);
    const lockPath = holdLock("sess-1");
    try {
      // Count the retry sleeps instead of timing them: the bounded retry
      // sleeps between attempts through Atomics.wait, a try-once take never
      // sleeps. A count does not drift on a loaded runner the way latency does.
      const sleeps = countRetrySleeps(() => {
        expect(updateHookState(vault, "sess-1", (state) => ({ state, result: null }))).toEqual({
          status: "busy",
        });
      });
      expect(sleeps).toBeGreaterThan(0);
      expect(
        countRetrySleeps(() => {
          expect(takeRegroundPart(vault, "sess-1", NOW + 1)).toEqual({ status: "busy" });
        }),
      ).toBe(0);
    } finally {
      unlinkSync(lockPath);
      _resetHeldLocksForTests();
    }
    const next = takeRegroundPart(vault, "sess-1", NOW + 2);
    expect(next.status === "part" && next.index).toBe(2);
    const after = takeRegroundPart(vault, "sess-1", NOW + 3);
    expect(after.status === "part" && after.index).toBe(3);
    expect(takeRegroundPart(vault, "sess-1", NOW + 4)).toEqual({ status: "empty" });
  });
});

describe("session isolation", () => {
  test("a session id with separators, dots or NUL keeps its ledger inside hook-state", () => {
    const stateDir = join(vault, ".open-second-brain", "hook-state");
    for (const id of ["../../outside", "a/b\\c", "sess.1", "x\u0000y", ".hidden"]) {
      expect(isRealSessionId(id)).toBe(true);
      expect(recordRecallInjected(vault, id, [`k-${id.length}`], NOW)).toBe(true);
      const path = hookStateFilePath(vault, id);
      expect(dirname(path)).toBe(stateDir);
      // A lossy id gets the hashed scope name, still inside the scope-file shape.
      expect(basename(path)).toMatch(/^[a-z0-9-]{1,64}\.json$/);
      expect(readRecallInjected(vault, id, NOW).has(`k-${id.length}`)).toBe(true);
    }
    expect(readdirSync(vault).toSorted()).toEqual([".open-second-brain", "Brain"]);
    expect(readdirSync(stateDir).filter((name) => name.endsWith(".json"))).toHaveLength(5);
  });

  test("every key is scoped per session id", () => {
    recordRecallInjected(vault, "sess-a", ["k1"], NOW);
    beginInjectionEpoch(
      vault,
      "sess-a",
      {
        epoch: "e",
        emittedPaths: ["Brain/active.md"],
        regroundParts: ["p2"],
        partCeilingChars: 9000,
      },
      NOW,
    );
    recordRecallInjected(vault, "sess-a", ["k2"], NOW);
    expect(readRecallInjected(vault, "sess-b", NOW).size).toBe(0);
    expect(readActiveEmittedPaths(vault, "sess-b", NOW).size).toBe(0);
    expect(takeRegroundPart(vault, "sess-b", NOW)).toEqual({ status: "empty" });
    expect([...readRecallInjected(vault, "sess-a", NOW)]).toEqual(["k2"]);
    expect(readActiveEmittedPaths(vault, "sess-a", NOW).size).toBe(1);
    expect(takeRegroundPart(vault, "sess-a", NOW)).toMatchObject({ status: "part", index: 2 });
  });
});

function readStateKeys(sessionId: string): string[] {
  return Object.keys(
    JSON.parse(readFileSync(hookStateFilePath(vault, sessionId), "utf8")) as Record<
      string,
      unknown
    >,
  );
}