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

import { bootstrapBrain } from "../../src/core/brain/init.ts";
import { brainDirsForWrite, brainPinnedPath } from "../../src/core/brain/paths.ts";
import { acquireLockSync, LOCK_WAIT_BUDGET_MS } from "../../src/core/brain/sync-lockfile.ts";
import {
  resetVaultIdentityPins,
  VaultIdentityMismatchError,
  vaultIdentityPath,
  writeVaultIdentity,
} from "../../src/core/brain/vault-identity.ts";
import {
  MAX_PINNED_CONTEXT_LEN,
  PinnedBatchError,
  applyPinnedOperations,
  appendPinnedContext,
  clearPinnedContext,
  readPinnedContext,
  writePinnedContext,
} from "../../src/core/brain/pinned.ts";
import { PRIVATE_REGION_PLACEHOLDER } from "../../src/core/redactor.ts";
import { CHMOD_CANNOT_DENY } from "../helpers/platform.ts";

let vault: string;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-pinned-"));
  // A legacy tree: these tests pin the page layout of an unswitched
  // machine (a vault with no `Brain/` is store-only, task 2.10).
  mkdirSync(join(vault, "Brain"), { recursive: true });
});

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

describe("pinned context paths", () => {
  test("uses Brain/pinned.md under the vault", () => {
    expect(brainPinnedPath(vault)).toBe(join(vault, "Brain", "pinned.md"));
  });
});

describe("pinned context core", () => {
  test("reads missing pinned context as empty", () => {
    const pinned = readPinnedContext(vault);
    expect(pinned.present).toBe(false);
    expect(pinned.content).toBe("");
    expect(pinned.path).toBe(brainPinnedPath(vault));
  });

  test("writes sanitised content atomically", () => {
    const pinned = writePinnedContext(
      vault,
      "Remember api_key=abc\n<private>do not store this</private>",
    );
    expect(pinned.present).toBe(true);
    expect(pinned.content).toContain("api_key=***REDACTED***");
    expect(pinned.content).toContain(PRIVATE_REGION_PLACEHOLDER);
    expect(pinned.content).not.toContain("do not store this");
    expect(readFileSync(brainPinnedPath(vault), "utf8")).toBe(`${pinned.content}\n`);
  });

  test("appends content with a blank-line separator", () => {
    writePinnedContext(vault, "First fact");
    const pinned = appendPinnedContext(vault, "Second fact");
    expect(pinned.content).toBe("First fact\n\nSecond fact");
  });

  test("clear leaves an empty pinned file", () => {
    writePinnedContext(vault, "Temporary fact");
    const pinned = clearPinnedContext(vault);
    expect(pinned.present).toBe(true);
    expect(pinned.content).toBe("");
    expect(existsSync(brainPinnedPath(vault))).toBe(true);
    expect(readFileSync(brainPinnedPath(vault), "utf8")).toBe("");
  });

  // POSIX modes only, and root reads a 0000 file anyway.
  test.skipIf(CHMOD_CANNOT_DENY)(
    "with dual writes off a clear does not read the file it clears",
    () => {
      writePinnedContext(vault, "Temporary fact");
      chmodSync(brainPinnedPath(vault), 0o000);
      const pinned = clearPinnedContext(vault);
      expect(pinned.content).toBe("");
      expect(readFileSync(brainPinnedPath(vault), "utf8")).toBe("");
    },
  );
});

describe("pinned context single-op budget honesty", () => {
  test("write rejects over-budget content with a structured signal and no write", () => {
    const huge = "x".repeat(MAX_PINNED_CONTEXT_LEN + 100);

    let captured: PinnedBatchError | undefined;
    try {
      writePinnedContext(vault, huge);
    } catch (err) {
      captured = err as PinnedBatchError;
    }
    expect(captured).toBeInstanceOf(PinnedBatchError);
    expect(captured?.code).toBe("budget_exceeded");
    expect(captured?.details["budget"]).toBe(MAX_PINNED_CONTEXT_LEN);
    expect(captured?.details["length"]).toBe(huge.length);
    expect(captured?.details["operation"]).toBe("write");
    // No silent truncated success: nothing was persisted.
    expect(existsSync(brainPinnedPath(vault))).toBe(false);
    expect(readPinnedContext(vault).content).toBe("");
  });

  test("write at exactly the budget still succeeds", () => {
    const exact = "y".repeat(MAX_PINNED_CONTEXT_LEN);
    const pinned = writePinnedContext(vault, exact);
    expect(pinned.content).toBe(exact);
    expect(pinned.content.length).toBe(MAX_PINNED_CONTEXT_LEN);
  });

  test("append rejects when the combined result would exceed budget, leaving the file unchanged", () => {
    writePinnedContext(vault, "seed");
    const before = readFileSync(brainPinnedPath(vault), "utf8");
    const huge = "z".repeat(MAX_PINNED_CONTEXT_LEN);

    let captured: PinnedBatchError | undefined;
    try {
      appendPinnedContext(vault, huge);
    } catch (err) {
      captured = err as PinnedBatchError;
    }
    expect(captured).toBeInstanceOf(PinnedBatchError);
    expect(captured?.code).toBe("budget_exceeded");
    expect(captured?.details["operation"]).toBe("append");
    expect(readFileSync(brainPinnedPath(vault), "utf8")).toBe(before);
    expect(readPinnedContext(vault).content).toBe("seed");
  });
});

describe("pinned context batch operations", () => {
  test("applies write/append/replace operations in order, all-or-nothing", () => {
    const result = applyPinnedOperations(vault, [
      { op: "write", content: "alpha" },
      { op: "append", content: "beta" },
      { op: "replace", find: "alpha", replace: "ALPHA" },
    ]);
    expect(result.content).toBe("ALPHA\n\nbeta");
    expect(result.applied).toBe(3);
    expect(result.done).toBe(true);
    expect(readFileSync(brainPinnedPath(vault), "utf8")).toBe("ALPHA\n\nbeta\n");
  });

  test("clear inside a batch resets accumulated content", () => {
    writePinnedContext(vault, "old");
    const result = applyPinnedOperations(vault, [
      { op: "append", content: "transient" },
      { op: "clear" },
      { op: "write", content: "fresh" },
    ]);
    expect(result.content).toBe("fresh");
    expect(readFileSync(brainPinnedPath(vault), "utf8")).toBe("fresh\n");
  });

  test("a malformed middle operation leaves the pinned file byte-for-byte unchanged", () => {
    writePinnedContext(vault, "seed content");
    const before = readFileSync(brainPinnedPath(vault), "utf8");

    expect(() =>
      applyPinnedOperations(vault, [
        { op: "append", content: "should-not-persist" },
        { op: "bogus" as unknown as "write" },
        { op: "append", content: "also-should-not-persist" },
      ]),
    ).toThrow(PinnedBatchError);

    expect(readFileSync(brainPinnedPath(vault), "utf8")).toBe(before);
    expect(readPinnedContext(vault).content).toBe("seed content");
  });

  test("a replace whose target is absent aborts the whole batch without writing", () => {
    writePinnedContext(vault, "seed content");
    const before = readFileSync(brainPinnedPath(vault), "utf8");

    let captured: PinnedBatchError | undefined;
    try {
      applyPinnedOperations(vault, [
        { op: "append", content: "more" },
        { op: "replace", find: "NOT-PRESENT", replace: "x" },
      ]);
    } catch (err) {
      captured = err as PinnedBatchError;
    }
    expect(captured).toBeInstanceOf(PinnedBatchError);
    expect(captured?.code).toBe("replace_target_missing");
    expect(captured?.index).toBe(1);
    expect(readFileSync(brainPinnedPath(vault), "utf8")).toBe(before);
  });

  test("an over-budget final projection is rejected without writing", () => {
    writePinnedContext(vault, "seed");
    const before = readFileSync(brainPinnedPath(vault), "utf8");
    const huge = "x".repeat(MAX_PINNED_CONTEXT_LEN + 100);

    let captured: PinnedBatchError | undefined;
    try {
      applyPinnedOperations(vault, [{ op: "write", content: huge }]);
    } catch (err) {
      captured = err as PinnedBatchError;
    }
    expect(captured).toBeInstanceOf(PinnedBatchError);
    expect(captured?.code).toBe("budget_exceeded");
    expect(readFileSync(brainPinnedPath(vault), "utf8")).toBe(before);
  });

  test("rejects an empty operations array without writing", () => {
    expect(() => applyPinnedOperations(vault, [])).toThrow(PinnedBatchError);
    expect(existsSync(brainPinnedPath(vault))).toBe(false);
  });
});

describe("pinned context on a vault the identity guard refuses", () => {
  // The guard runs before the pinned lock is taken, so a refused vault
  // never waits on (or creates) that lock.
  for (const [name, write] of [
    ["write", (v: string) => writePinnedContext(v, "guarded")],
    ["append", (v: string) => appendPinnedContext(v, "guarded")],
  ] as const) {
    test(`${name} refuses without waiting on a held lock`, () => {
      resetVaultIdentityPins();
      bootstrapBrain(vault);
      brainDirsForWrite(vault);
      rmSync(vaultIdentityPath(vault));
      writeVaultIdentity(vault);
      const held = acquireLockSync(brainPinnedPath(vault));
      const started = Date.now();
      try {
        expect(() => write(vault)).toThrow(VaultIdentityMismatchError);
      } finally {
        held.release();
        resetVaultIdentityPins();
      }
      expect(Date.now() - started).toBeLessThan(LOCK_WAIT_BUDGET_MS);
    });
  }
});