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.9 KB
Raw Blame
/**
 * A registered terminal state fires only where its claim holds
 * (no-dead-ends, phase 3, item 3).
 *
 * The registry entry a rail emission resolves is not just a command - it
 * is an assertion about the state the caller is in. `brain-empty` asserts
 * "Brain with nothing recorded in it"; `search-index-built` asserts
 * "search index up to date". Three emissions fired unconditionally and so
 * made those assertions in cases where they were false, which is exactly
 * the failure class this release exists to remove.
 *
 * Audited here, one test per emission that had to change, plus the
 * negative case for each - because "fires when true" is only half the
 * property and the half that regresses silently is the other one.
 */

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

import { writeCaptureNote } from "../../src/core/brain/capture/capture-note.ts";
import { bootstrapBrain } from "../../src/core/brain/init.ts";
import { NEXT_COMMAND_KEY, resolveNextStep } from "../../src/core/brain/next-step.ts";
import { writeSignal } from "../../src/core/brain/signal.ts";
import { resolveSearchConfig } from "../../src/core/search/index.ts";
import { indexVault } from "../../src/core/search/indexer.ts";
import { STORE_ROOT_ENV } from "../../src/core/store/constants.ts";
import { runCli } from "../helpers/run-cli.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;
const savedEnv: Record<string, string | undefined> = {};

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), "o2b-claim-truth-"));
  vault = join(tmp, "vault");
  configPath = join(tmp, "config.yaml");
  for (const key of ["VAULT_DIR", "OPEN_SECOND_BRAIN_CONFIG", "VAULT_AGENT_NAME"]) {
    savedEnv[key] = process.env[key];
    delete process.env[key];
  }
  writeFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);
});

afterEach(() => {
  rmSync(tmp, { recursive: true, force: true });
  for (const [key, value] of Object.entries(savedEnv)) {
    if (value === undefined) delete process.env[key];
    else process.env[key] = value;
  }
});

const FEEDBACK_EXIT = "next: o2b brain feedback";
const QUERY_EXIT = "next: o2b search query <text>";
const INDEX_EXIT = "next: o2b search index";

function seedSignal(): void {
  writeSignal(vault, {
    topic: "already-recorded",
    signal: "positive",
    agent: "claude",
    principle: "Something is already recorded here.",
    created_at: "2026-05-20T10:00:00Z",
    date: "2026-05-20",
    slug: "already-recorded-1",
    scope: "writing",
  });
}

describe("brain-empty claims the Brain is empty", () => {
  test("a first bootstrap does leave an empty Brain, so the exit fires", async () => {
    const r = await runCli(["brain", "init", "--vault", vault, "--config", configPath]);
    expect(r.returncode).toBe(0);
    expect(r.stdout).toContain(FEEDBACK_EXIT);
  });

  test("a re-run over a Brain that already holds a signal does not", async () => {
    bootstrapBrain(vault, { configPath });
    seedSignal();

    const r = await runCli(["brain", "init", "--vault", vault, "--config", configPath]);

    expect(r.returncode).toBe(0);
    // Every path was skipped and the Brain is not empty; asserting it is
    // would be a false claim.
    expect(r.stdout).toContain("exists:");
    expect(r.stdout).not.toContain(FEEDBACK_EXIT);
  });

  test("a re-run over a Brain that holds a preference does not", async () => {
    bootstrapBrain(vault, { configPath });
    writeFileSync(
      join(vault, "Brain", "preferences", "pref-recorded.md"),
      "---\nid: pref-recorded\nstatus: confirmed\n---\n\nRecorded.\n",
      "utf8",
    );

    const r = await runCli(["brain", "init", "--vault", vault, "--config", configPath]);

    expect(r.returncode).toBe(0);
    expect(r.stdout).not.toContain(FEEDBACK_EXIT);
  });

  test("a re-run over an empty Brain still fires - the claim is about content, not about a first run", async () => {
    bootstrapBrain(vault, { configPath });

    const r = await runCli(["brain", "init", "--vault", vault, "--config", configPath]);

    expect(r.returncode).toBe(0);
    expect(r.stdout).toContain(FEEDBACK_EXIT);
  });

  test("the machine stream stays clean either way", async () => {
    bootstrapBrain(vault, { configPath });
    seedSignal();
    const r = await runCli(["brain", "init", "--vault", vault, "--config", configPath, "--json"]);
    expect(r.returncode).toBe(0);
    expect(r.stdout).not.toContain("next: ");
    expect(() => JSON.parse(r.stdout)).not.toThrow();
  });
});

describe("search-index-built claims the index is up to date", () => {
  const dbPath = (): string => join(tmp, "index.db");

  function writeNote(name: string, body: string): void {
    writeFileSync(join(vault, name), body, "utf8");
  }

  beforeEach(() => {
    bootstrapBrain(vault, { configPath });
  });

  test("a clean run leaves it up to date, so the exit fires", async () => {
    writeNote("good.md", "---\ntitle: Good\n---\n\nSome body text.\n");
    const r = await runCli(["search", "index", "--vault", vault, "--db", dbPath()]);
    expect(r.returncode).toBe(0);
    expect(r.stdout).toContain(QUERY_EXIT);
  });

  test("a run that could not index every file does not claim it is up to date", async () => {
    writeNote("good.md", "---\ntitle: Good\n---\n\nSome body text.\n");
    // Frontmatter with no closing fence: the chunker reports it and the
    // run records the file under `errors`, meaning it did not index.
    writeNote("broken.md", "---\ntitle: Broken\n\nBody without a closing fence.\n");

    const r = await runCli(["search", "index", "--vault", vault, "--db", dbPath()]);

    expect(r.returncode).toBe(0);
    expect(r.stdout).toContain("broken.md");
    expect(r.stdout).not.toContain(QUERY_EXIT);
  });

  test("reindex holds the same property", async () => {
    writeNote("good.md", "---\ntitle: Good\n---\n\nSome body text.\n");
    const clean = await runCli(["search", "reindex", "--vault", vault, "--db", dbPath()]);
    expect(clean.stdout).toContain(QUERY_EXIT);

    writeNote("broken.md", "---\ntitle: Broken\n\nBody without a closing fence.\n");
    const dirty = await runCli(["search", "reindex", "--vault", vault, "--db", dbPath()]);
    expect(dirty.stdout).not.toContain(QUERY_EXIT);
  });

  test("the machine stream stays clean and parses in both cases", async () => {
    writeNote("broken.md", "---\ntitle: Broken\n\nBody without a closing fence.\n");
    const r = await runCli(["search", "index", "--vault", vault, "--db", dbPath(), "--json"]);
    expect(r.returncode).toBe(0);
    expect(r.stdout).not.toContain("next: ");
    expect(() => JSON.parse(r.stdout)).not.toThrow();
  });
});

describe("search-index-missing claims the index is not built", () => {
  test("o2b init on a vault with no index names the indexer", async () => {
    const r = await runCli(["init", "--vault", vault], {
      env: { OPEN_SECOND_BRAIN_CONFIG: configPath },
    });
    expect(r.returncode).toBe(0);
    expect(r.stdout).toContain(INDEX_EXIT);
  });

  test("o2b init on a vault that already has one does not", async () => {
    // Build the index where the resolver will look for it, then re-init.
    // The indexer refuses a vault directory that does not exist. A first
    // init creates the brain store of this fresh vault (design D14 item 1),
    // which is where the index of a store-only vault lives.
    mkdirSync(vault, { recursive: true });
    const storeRoot = join(tmp, "store");
    const first = await runCli(["init", "--vault", vault], {
      env: { OPEN_SECOND_BRAIN_CONFIG: configPath, [STORE_ROOT_ENV]: storeRoot },
    });
    expect(first.returncode).toBe(0);
    const built = await runCli(["search", "index", "--vault", vault], {
      env: { OPEN_SECOND_BRAIN_CONFIG: configPath, [STORE_ROOT_ENV]: storeRoot },
    });
    expect(built.returncode).toBe(0);

    const r = await runCli(["init", "--vault", vault], {
      env: { OPEN_SECOND_BRAIN_CONFIG: configPath, [STORE_ROOT_ENV]: storeRoot },
    });

    expect(r.returncode).toBe(0);
    // The checklist below it already reports this step as done; the
    // block above it must not contradict that in the same output.
    expect(r.stdout).toContain("Search:");
    expect(r.stdout).not.toContain(INDEX_EXIT);
  });
});

/**
 * The emissions that no other suite drives in BOTH directions. The rest
 * of the registered sites are held behaviourally elsewhere (the JSON
 * `next_command` field in `json-next-command.test.ts`, the terminal-state
 * suites); these three states had only a source-text check that some
 * guard string appeared somewhere earlier in the file, which a refactor
 * could satisfy while the emission itself lost its condition.
 */
describe("the remaining claims fire only where they hold", () => {
  const env = (): Record<string, string> => ({ OPEN_SECOND_BRAIN_CONFIG: configPath });

  /** The rail line a code prints, read from the registry, never retyped. */
  function railLine(code: string): string {
    const step = resolveNextStep(code);
    expect(`${code} is registered: ${step !== null}`).toBe(`${code} is registered: true`);
    return `next: ${step!.nextCommand}`;
  }

  beforeEach(() => {
    bootstrapBrain(vault, { configPath });
  });

  describe("tier-drift-restore claims an identity field drifted", () => {
    function writePref(id: string): void {
      writeFileSync(
        join(vault, "Brain", "preferences", "pref-spaces.md"),
        `---\nkind: brain-preference\nid: ${id}\ncreated_at: 2026-05-01T00:00:00Z\ntopic: style\n---\n\nUse spaces.\n`,
      );
    }

    test("an index with no hand-edits does not offer a restore", async () => {
      writePref("pref-spaces");
      await indexVault(resolveSearchConfig({ vault, configPath }));
      const r = await runCli(["brain", "tiers", "check", "--vault", vault], { env: env() });
      expect(r.returncode).toBe(0);
      expect(r.stdout).toContain("0 open finding(s)");
      expect(r.stdout).not.toContain(railLine("tier-drift-restore"));
      expect(r.stdout).not.toContain(railLine("tier-drift-accept"));
    });

    test("a hand-edited identity field offers both exits", async () => {
      const config = resolveSearchConfig({ vault, configPath });
      writePref("pref-spaces");
      await indexVault(config);
      writePref("pref-tabs");
      await indexVault(config);
      const r = await runCli(["brain", "tiers", "check", "--vault", vault], { env: env() });
      expect(r.returncode).toBe(0);
      expect(r.stdout).toContain("1 open finding(s)");
      expect(r.stdout).toContain(railLine("tier-drift-restore"));
      expect(r.stdout).toContain(railLine("tier-drift-accept"));
    });
  });

  describe("recall-tuning-absent claims nothing is tuned", () => {
    test("with no persisted tuning the exit fires", async () => {
      const r = await runCli(["brain", "tune", "status", "--vault", vault], { env: env() });
      expect(r.returncode).toBe(0);
      expect(r.stdout).toContain(railLine("recall-tuning-absent"));
    });

    test("with valid persisted tuning it does not, on either stream", async () => {
      mkdirSync(join(vault, "Brain", "search"), { recursive: true });
      writeFileSync(
        join(vault, "Brain", "search", "tuning.json"),
        JSON.stringify({
          chosen: { poolMultiplier: 3, traversalDepth: 1, learnedWeights: false, expansion: false },
        }),
      );
      const human = await runCli(["brain", "tune", "status", "--vault", vault], { env: env() });
      expect(human.returncode).toBe(0);
      expect(human.stdout).toContain("pool x3");
      expect(human.stdout).not.toContain(railLine("recall-tuning-absent"));

      const machine = await runCli(["brain", "tune", "status", "--vault", vault, "--json"], {
        env: env(),
      });
      expect(machine.returncode).toBe(0);
      expect(JSON.parse(machine.stdout)).not.toHaveProperty(NEXT_COMMAND_KEY);
    });
  });

  describe("staged-captures-pending claims captures await routing", () => {
    test("the human stream names the exit only while a capture is staged", async () => {
      const nothing = await runCli(["brain", "inbox-drain"], { env: env() });
      expect(nothing.returncode).toBe(0);
      expect(nothing.stdout).not.toContain(railLine("staged-captures-pending"));

      writeCaptureNote(vault, {
        body: "an atomic idea to keep",
        provenance: { source: "telegram", sender: "100", capturedAt: "2026-07-19T12:00:02Z" },
      });
      const staged = await runCli(["brain", "inbox-drain"], { env: env() });
      expect(staged.returncode).toBe(0);
      expect(staged.stdout).toContain(railLine("staged-captures-pending"));

      const applied = await runCli(["brain", "inbox-drain", "--apply"], { env: env() });
      expect(applied.returncode).toBe(0);
      expect(applied.stdout).not.toContain(railLine("staged-captures-pending"));
    });
  });
});