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.6 KB
Raw Blame
/**
 * `o2b brain hallways mine|show|promote|dismiss` (recall-quality wave,
 * Lane B / t_13a82a31). The CLI over the session-mined ledger: mine
 * derives the artifact and the reviewable proposals, show reads them
 * back, promote is the ONE bridge into the entity registry (thresholded,
 * through upsertEntity/relateEntities exclusively), dismiss silences a
 * key. Ambient mining never writes an entity page - only promote does.
 */

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

import { bootstrapBrain } from "../../src/core/brain/init.ts";
import { appendContinuityRecord } from "../../src/core/brain/continuity/store.ts";
import { SESSION_ENTITY_MENTION_KIND } from "../../src/core/brain/link-graph/session-mining.ts";
import {
  dismissHallwayKey,
  HALLWAYS_ARTIFACT_REL,
} from "../../src/core/brain/link-graph/hallways.ts";
import {
  deriveEntityLexicon,
  writeEntityLexicon,
  __clearEntityLexiconCache,
} from "../../src/core/brain/entities/lexicon.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;

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

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

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

/** One mined-mention ledger row (the import loop's on-disk shape). */
function mention(family: string, key: string, sessionRef: string): void {
  appendContinuityRecord(vault, {
    kind: SESSION_ENTITY_MENTION_KIND,
    createdAt: "2026-09-18T09:00:00Z",
    sourceRefs: [{ id: `${sessionRef}:u-0:${family}:${key}` }],
    payload: { family, key, session_ref: sessionRef, turn_id: "u-0" },
  });
}

/** Seed one key in `n` distinct sessions, plus a paired key beside it. */
function seedPair(n: number): void {
  for (let i = 1; i <= n; i++) {
    mention("symbol", "SessionStore", `s${i}.jsonl`);
    mention("symbol", "PayloadRegistry", `s${i}.jsonl`);
  }
}

/** The vault's entity page files, category by category. The lexicon
 * artifact (Brain/entities/lexicon.json) is a file, not a category. */
function entityFiles(): string[] {
  const root = join(vault, "Brain", "entities");
  if (!existsSync(root)) return [];
  const out: string[] = [];
  for (const category of readdirSync(root)) {
    const dir = join(root, category);
    if (!statSync(dir).isDirectory()) continue;
    out.push(...readdirSync(dir).map((f) => `${category}/${f}`));
  }
  return out;
}

describe("o2b brain hallways mine", () => {
  test("derives the artifact and the proposals, and writes no entity page", async () => {
    seedPair(3);

    const out = await runCli(["brain", "hallways", "mine", "--json"], { env: env() });

    expect(out.returncode).toBe(0);
    const payload = JSON.parse(out.stdout) as Record<string, unknown>;
    expect(payload["session_count"]).toBe(3);
    expect(payload["keys"]).toBe(2);
    expect(payload["pairs"]).toBe(1);
    expect(existsSync(join(vault, "Brain", "link-graph", "hallways.json"))).toBe(true);
    expect(existsSync(join(vault, "Brain", "proposals", "hallways.md"))).toBe(true);
    // Ambient mining NEVER writes the registry - promotion is the only
    // bridge into Brain/entities/, and it has not run here.
    expect(entityFiles()).toEqual([]);
    // The artifact is the derived one, not the co-occurrence graph's.
    expect(HALLWAYS_ARTIFACT_REL.split("\\").join("/")).toBe("Brain/link-graph/hallways.json");
    expect(existsSync(join(vault, "Brain", "link-graph", "co-occurrence.json"))).toBe(false);
  });

  test("an empty ledger mines an empty derivation and still says so", async () => {
    const out = await runCli(["brain", "hallways", "mine", "--json"], { env: env() });
    expect(out.returncode).toBe(0);
    const payload = JSON.parse(out.stdout) as Record<string, unknown>;
    expect(payload["session_count"]).toBe(0);
    expect(payload["keys"]).toBe(0);
  });

  test("the proposals file lists only keys at or above the session threshold", async () => {
    seedPair(3);
    mention("symbol", "OnceOnly", "s1.jsonl");

    const out = await runCli(["brain", "hallways", "mine"], { env: env() });
    expect(out.returncode).toBe(0);

    const body = readFileSync(join(vault, "Brain", "proposals", "hallways.md"), "utf8");
    expect(body).toContain("SessionStore");
    expect(body).toContain("PayloadRegistry");
    expect(body).not.toContain("OnceOnly");
  });
});

describe("o2b brain hallways show", () => {
  test("prints the proposals artifact when it exists", async () => {
    seedPair(3);
    await runCli(["brain", "hallways", "mine"], { env: env() });

    const out = await runCli(["brain", "hallways", "show", "--json"], { env: env() });

    expect(out.returncode).toBe(0);
    const payload = JSON.parse(out.stdout) as Record<string, unknown>;
    expect(payload["exists"]).toBe(true);
    expect(payload["path"]).toBe("Brain/proposals/hallways.md");
    expect(payload["proposals"]).toBe(2);
  });

  test("is fail-soft when nothing was mined yet", async () => {
    const out = await runCli(["brain", "hallways", "show", "--json"], { env: env() });
    expect(out.returncode).toBe(0);
    const payload = JSON.parse(out.stdout) as Record<string, unknown>;
    expect(payload["exists"]).toBe(false);
  });
});

describe("o2b brain hallways promote", () => {
  test("refuses a key below the session threshold, naming both counts", async () => {
    mention("symbol", "SessionStore", "s1.jsonl");

    const out = await runCli(["brain", "hallways", "promote", "symbol", "SessionStore"], {
      env: env(),
    });

    expect(out.returncode).toBe(1);
    expect(out.stderr).toContain("1");
    expect(out.stderr).toContain("3");
    expect(entityFiles()).toEqual([]);
  });

  test("refuses a dismissed key and names the real remedy", async () => {
    seedPair(3);
    dismissHallwayKey(vault, "symbol", "SessionStore");

    const out = await runCli(["brain", "hallways", "promote", "symbol", "SessionStore"], {
      env: env(),
    });

    expect(out.returncode).toBe(1);
    expect(out.stderr).toContain("dismissed");
    // The refusal names the working state, not a verb that does not exist:
    // a dismissal is final for this artifact, and the way back is the
    // persisted dismissal set itself.
    expect(out.stderr).toContain("final for this artifact");
    expect(out.stderr).toContain("Brain/proposals/hallways-dismissed.json");
    expect(out.stderr).not.toContain("to be undone first");
    expect(entityFiles()).toEqual([]);
  });

  test("a key at the threshold promotes through upsertEntity, not a raw write", async () => {
    seedPair(3);

    const out = await runCli(["brain", "hallways", "promote", "symbol", "SessionStore", "--json"], {
      env: env(),
    });

    expect(out.returncode).toBe(0);
    const payload = JSON.parse(out.stdout) as Record<string, unknown>;
    expect(payload["created"]).toBe(true);
    expect(payload["entity"]).toBe("ent-symbol-sessionstore");
    // The page exists because the REGISTRY wrote it: it reads back
    // through the registry's own lookup.
    const get = await runCli(["brain", "entity", "get", "SessionStore", "--json"], {
      env: env(),
    });
    expect(get.returncode).toBe(0);
    expect((JSON.parse(get.stdout) as Record<string, unknown>)["id"]).toBe(
      "ent-symbol-sessionstore",
    );
  });

  test("a lowered threshold admits a key the default refuses (--min-sessions)", async () => {
    seedPair(2);

    const refused = await runCli(["brain", "hallways", "promote", "symbol", "SessionStore"], {
      env: env(),
    });
    expect(refused.returncode).toBe(1);

    const okOut = await runCli(
      ["brain", "hallways", "promote", "symbol", "SessionStore", "--min-sessions", "2", "--json"],
      { env: env() },
    );
    expect(okOut.returncode).toBe(0);
    expect(entityFiles()).toEqual(["symbol/ent-symbol-sessionstore.md"]);
  });

  test("a partner already in the registry is related through relateEntities", async () => {
    seedPair(3);
    await runCli(["brain", "hallways", "promote", "symbol", "SessionStore"], { env: env() });

    const out = await runCli(
      ["brain", "hallways", "promote", "symbol", "PayloadRegistry", "--json"],
      { env: env() },
    );

    expect(out.returncode).toBe(0);
    const payload = JSON.parse(out.stdout) as Record<string, unknown>;
    expect(payload["related"]).toEqual(["ent-symbol-sessionstore"]);
    const page = readFileSync(
      join(vault, "Brain", "entities", "symbol", "ent-symbol-payloadregistry.md"),
      "utf8",
    );
    expect(page).toContain("related:");
    expect(page).toContain("[[ent-symbol-sessionstore]]");
  });

  test("a promoted key never relates a dismissed partner", async () => {
    seedPair(3);
    await runCli(["brain", "hallways", "promote", "symbol", "SessionStore"], { env: env() });
    dismissHallwayKey(vault, "symbol", "SessionStore");

    const out = await runCli(
      ["brain", "hallways", "promote", "symbol", "PayloadRegistry", "--json"],
      { env: env() },
    );

    expect(out.returncode).toBe(0);
    const payload = JSON.parse(out.stdout) as Record<string, unknown>;
    // The dismissed partner is already an entity, but the pair with a
    // dismissed side is not offered, so promote adds no edge to it.
    expect(payload["related"]).toEqual([]);
    const page = readFileSync(
      join(vault, "Brain", "entities", "symbol", "ent-symbol-payloadregistry.md"),
      "utf8",
    );
    expect(page).not.toContain("[[ent-symbol-sessionstore]]");
  });

  test("a pair partner under a family the fold does not mine contributes nothing", async () => {
    seedPair(3);
    // A person-family row is not a mention the scan can re-reach (the
    // fold mines symbol/url/path/qualified-ident only), so a hand-planted
    // person key never becomes a pair partner: the promote neither fails
    // nor relates, whatever the entity registry holds under that spelling.
    for (let i = 1; i <= 3; i++) mention("person", "smith robert", `s${i}.jsonl`);
    await runCli(["brain", "entity", "set", "people", "Robert Smith", "--json"], { env: env() });

    const out = await runCli(["brain", "hallways", "promote", "symbol", "SessionStore", "--json"], {
      env: env(),
    });

    expect(out.returncode).toBe(0);
    const payload = JSON.parse(out.stdout) as Record<string, unknown>;
    expect(payload["created"]).toBe(true);
    expect(payload["related"]).toEqual([]);
    expect(entityFiles()).toContain("symbol/ent-symbol-sessionstore.md");
  });

  test("promotes under the same bounded-wait deadline the mine fold carries", async () => {
    seedPair(3);
    // A clock that jumps a full day per reading, so any budget the safeguard
    // ladder resolves has elapsed by the fold's first checkpoint - the same
    // deterministic arm the MCP long-running-tools tests use against a real
    // createSafeguard. The fold is the expensive half of promote (it is the
    // same O(k^2) pass mine runs), so it takes the same deadline.
    let tick = 0;
    const spy = spyOn(Date, "now").mockImplementation(() => {
      tick += 1;
      return tick * 86_400_000;
    });
    try {
      const out = await runCli(["brain", "hallways", "promote", "symbol", "SessionStore"], {
        env: env(),
      });
      expect(out.returncode).toBe(1);
      expect(out.stderr).toContain("safeguard timeout");
      expect(out.stderr).toContain("sessions");
      expect(entityFiles()).toEqual([]);
    } finally {
      spy.mockRestore();
    }
  });

  test("a promoted label failing the tightened admission gate is refused BY THE GATE", async () => {
    // The pinned coupling: promotion's only writer is the registry's
    // admission path, so a mined key the tightened gate rejects
    // (recall-quality A2 - here a multi-token ALL-CAPS heading
    // residue, refused structurally regardless of the lexicon) never
    // becomes an entity page, however many sessions mention it.
    for (let i = 1; i <= 3; i++) mention("symbol", "QUICK BROWN FOX", `s${i}.jsonl`);
    // A resolving caseful handle is what arms the structural shout
    // verdict: seed one capitalised corpus page so the derived
    // artifact carries caseful=true and its own honest hash.
    mkdirSync(join(vault, "Notes"), { recursive: true });
    writeFileSync(
      join(vault, "Notes", "seed-corpus.md"),
      "# Corpus\nNarrative prose where Words arrive Capitalised.",
    );
    writeEntityLexicon(vault, deriveEntityLexicon(vault));
    __clearEntityLexiconCache();

    const out = await runCli(["brain", "hallways", "promote", "symbol", "QUICK BROWN FOX"], {
      env: env(),
    });

    expect(out.returncode).toBe(1);
    expect(out.stderr).toContain("shouted-heading");
    expect(entityFiles()).toEqual([]);
  });
});

describe("o2b brain hallways dismiss", () => {
  test("persists a dismissal and reports an already-dismissed key", async () => {
    const out = await runCli(["brain", "hallways", "dismiss", "symbol", "SessionStore", "--json"], {
      env: env(),
    });
    expect(out.returncode).toBe(0);
    expect((JSON.parse(out.stdout) as Record<string, unknown>)["added"]).toBe(true);
    expect(existsSync(join(vault, "Brain", "proposals", "hallways-dismissed.json"))).toBe(true);

    const again = await runCli(
      ["brain", "hallways", "dismiss", "symbol", "SessionStore", "--json"],
      { env: env() },
    );
    expect(again.returncode).toBe(0);
    expect((JSON.parse(again.stdout) as Record<string, unknown>)["added"]).toBe(false);
  });
});

describe("o2b brain hallways usage", () => {
  test("an unknown subcommand is a usage error, not a crash", async () => {
    const out = await runCli(["brain", "hallways", "transmogrify"], { env: env() });
    expect(out.returncode).toBe(2);
    expect(out.stderr).toContain("usage: o2b brain hallways");
  });

  test("promote without a key is a usage error", async () => {
    const out = await runCli(["brain", "hallways", "promote", "symbol"], { env: env() });
    expect(out.returncode).toBe(2);
  });

  test("an unknown family is a usage error", async () => {
    const out = await runCli(["brain", "hallways", "promote", "prose", "Whatever"], {
      env: env(),
    });
    expect(out.returncode).toBe(2);
  });
});