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
11.5 KB
Raw Blame
/**
 * `o2b brain clusters` CLI surface (t_4ba927ec): run detects
 * communities, materializes derived notes, records the communities
 * metric; list reads them back; the maintenance lane executes the
 * bridges and clusters tasks under its lease.
 */

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

import { bootstrapBrain } from "../../src/core/brain/init.ts";
import { indexVault } from "../../src/core/search/indexer.ts";
import { listMetrics } from "../../src/core/brain/metrics.ts";
import { makeConfig } from "../helpers/search-fixtures.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;

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), "o2b-cli-clusters-"));
  vault = join(tmp, "vault");
  mkdirSync(join(vault, "Brain"), { recursive: true });
  const group = ["team-a", "team-b", "team-c", "team-d"];
  for (const name of group) {
    const others = group
      .filter((g) => g !== name)
      .map((g) => `[[${g}]]`)
      .join(" ");
    writeFileSync(join(vault, `${name}.md`), `# ${name}\n\nSee ${others}.\n`);
  }
});

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

async function index(): Promise<void> {
  await indexVault(
    makeConfig({ vault, dbPath: join(vault, ".open-second-brain", "brain.sqlite") }),
  );
}

test("run on an unindexed vault exits 0 with a reason", async () => {
  const r = await runCli(["brain", "clusters", "run", "--vault", vault, "--json"]);
  expect(r.returncode).toBe(0);
  expect(JSON.parse(r.stdout)).toMatchObject({ communities: 0, reason: "index not built" });
});

test("run materializes the community, records the metric, list reads it back", async () => {
  await index();
  const run = await runCli(["brain", "clusters", "run", "--vault", vault, "--json"]);
  expect(run.returncode).toBe(0);
  const parsed = JSON.parse(run.stdout) as {
    communities: Array<{ id: string; size: number }>;
    written: string[];
    graph: { documents: number; linked_nodes: number; edges: number };
  };
  expect(parsed.communities).toHaveLength(1);
  expect(parsed.communities[0]!.size).toBe(4);
  expect(parsed.written).toHaveLength(1);
  // Unit 4: O(1) graph stats from the precomputed snapshot. The seeded
  // 4-clique has 4 linked nodes and 6 undirected edges.
  expect(parsed.graph.linked_nodes).toBe(4);
  expect(parsed.graph.edges).toBe(6);

  const metrics = listMetrics(vault, { surface: "communities" });
  expect(metrics).toHaveLength(1);
  expect(metrics[0]!.payload).toMatchObject({ communities: 1, written: 1 });

  const list = await runCli(["brain", "clusters", "list", "--vault", vault, "--json"]);
  const listed = JSON.parse(list.stdout) as { clusters: Array<{ size: number }> };
  expect(listed.clusters).toHaveLength(1);
  expect(listed.clusters[0]!.size).toBe(4);
});

test("min-size above the community suppresses it", async () => {
  await index();
  const run = await runCli([
    "brain",
    "clusters",
    "run",
    "--min-size",
    "5",
    "--vault",
    vault,
    "--json",
  ]);
  expect(JSON.parse(run.stdout)).toMatchObject({ communities: [] });
});

test("maintenance lane executes the bridges and clusters tasks", async () => {
  // dream needs an initialised Brain config.
  const configPath = join(tmp, "config.yaml");
  writeFileSync(configPath, `vault: ${vault}\n`);
  bootstrapBrain(vault, { configPath });
  const r = await runCli(["brain", "maintenance", "run", "--vault", vault, "--json"]);
  expect(r.returncode).toBe(0);
  const parsed = JSON.parse(r.stdout) as {
    verdict: string;
    tasks: Array<{ name: string; ok: boolean }>;
  };
  expect(parsed.verdict).toBe("run");
  const names = parsed.tasks.map((t) => t.name);
  expect(names).toEqual(["dream", "reindex", "bridges", "clusters", "relink"]);
  expect(parsed.tasks.every((t) => t.ok)).toBe(true);
  // The lane's reindex built the index, so both passes left a metric.
  expect(listMetrics(vault, { surface: "bridge_discovery" })).toHaveLength(1);
  expect(listMetrics(vault, { surface: "communities" })).toHaveLength(1);
});

test("run --batch-size returns per-batch results", async () => {
  await index();
  const run = await runCli([
    "brain",
    "clusters",
    "run",
    "--batch-size",
    "1",
    "--vault",
    vault,
    "--json",
  ]);
  expect(run.returncode).toBe(0);
  const parsed = JSON.parse(run.stdout) as {
    communities: unknown[];
    batches: Array<{ index: number; start: number; end: number; error?: string }>;
  };
  expect(parsed.communities).toHaveLength(1);
  expect(parsed.batches).toHaveLength(1);
  expect(parsed.batches[0]).toMatchObject({ index: 0, start: 0, end: 1 });
  expect(parsed.batches[0]!.error).toBeUndefined();
  expect(listMetrics(vault, { surface: "communities" })[0]!.payload).toMatchObject({
    batches: 1,
    failed_batches: 0,
  });
});

test("run without --batch-size omits the batches field", async () => {
  await index();
  const run = await runCli(["brain", "clusters", "run", "--vault", vault, "--json"]);
  expect(JSON.parse(run.stdout)).not.toHaveProperty("batches");
});

test("run --if-stale skips when outputs are already fresh (t_845fe240)", async () => {
  await index();
  const first = await runCli(["brain", "clusters", "run", "--vault", vault, "--json"]);
  expect(first.returncode).toBe(0);
  // Nothing changed since the materialization → outputs fresh → skip.
  const second = await runCli([
    "brain",
    "clusters",
    "run",
    "--vault",
    vault,
    "--if-stale",
    "--json",
  ]);
  expect(second.returncode).toBe(0);
  expect(JSON.parse(second.stdout)).toMatchObject({ skipped: "fresh" });
  // B4: the metric carries the verdict and its reason, not a
  // `skipped: "fresh"` that only ever gets written on one of the three
  // outcomes and therefore records nothing about the other two.
  const freshness = listMetrics(vault, { surface: "communities" }).map(
    (m) => (m.payload as { freshness?: string }).freshness,
  );
  expect(freshness).toContain("fresh");
});

test("run --if-stale recomputes when the wall-clock ceiling is exceeded (B4)", async () => {
  await index();
  await runCli(["brain", "clusters", "run", "--vault", vault]);
  // Move BOTH the inputs and the outputs into the distant past: nothing
  // is newer than anything else, so the only thing that can make this
  // stale is the ceiling. Before B4 this was fresh forever.
  const ancient = Date.now() / 1000 - 400 * 24 * 60 * 60;
  for (const rel of ["team-a.md", "team-b.md", "team-c.md", "team-d.md"]) {
    utimesSync(join(vault, rel), ancient, ancient);
  }
  const clustersDir = join(vault, "Brain", "clusters");
  for (const f of readdirSync(clustersDir)) {
    utimesSync(join(clustersDir, f), ancient, ancient);
  }
  const r = await runCli(["brain", "clusters", "run", "--vault", vault, "--if-stale", "--json"]);
  expect(r.returncode).toBe(0);
  expect(JSON.parse(r.stdout).skipped).toBeUndefined();
  const metrics = listMetrics(vault, { surface: "communities" }).map((m) => m.payload);
  expect(metrics).toContainEqual(
    expect.objectContaining({ freshness: "stale", freshness_reason: "ceiling_exceeded" }),
  );
});

test("run --if-stale reads the ceiling from the health block (B4)", async () => {
  await index();
  await runCli(["brain", "clusters", "run", "--vault", vault]);
  const ancient = Date.now() / 1000 - 400 * 24 * 60 * 60;
  for (const rel of ["team-a.md", "team-b.md", "team-c.md", "team-d.md"]) {
    utimesSync(join(vault, rel), ancient, ancient);
  }
  const clustersDir = join(vault, "Brain", "clusters");
  for (const f of readdirSync(clustersDir)) {
    utimesSync(join(clustersDir, f), ancient, ancient);
  }
  // A ceiling the ancient outputs are still inside of: same filesystem
  // state as the test above, opposite verdict, so the verdict really is
  // coming from the config and not from a constant in the module.
  writeFileSync(
    join(vault, "Brain", "_brain.yaml"),
    "schema_version: 1\nhealth:\n  materialize_max_age_days: 3650\n",
  );
  const r = await runCli(["brain", "clusters", "run", "--vault", vault, "--if-stale", "--json"]);
  expect(r.returncode).toBe(0);
  expect(JSON.parse(r.stdout)).toMatchObject({ skipped: "fresh" });
});

test("run --if-stale refuses a config it cannot read instead of claiming freshness", async () => {
  // The gate resolves its ceiling from the health block. Falling back to
  // the default on a config that will not parse let a broken vault report
  // `skipped: "fresh"` and exit 0, while every other verb refused the same
  // config loudly - the one path where an unreadable configuration became
  // a clean answer.
  await index();
  await runCli(["brain", "clusters", "run", "--vault", vault]);
  writeFileSync(
    join(vault, "Brain", "_brain.yaml"),
    "schema_version: 1\nhealth:\n  materialize_max_age_days: not-a-number\n",
  );
  const r = await runCli(["brain", "clusters", "run", "--vault", vault, "--if-stale", "--json"]);
  expect(r.returncode).not.toBe(0);
  expect(r.stdout + r.stderr).toContain("materialize_max_age_days");
});

test("run --if-stale recomputes and names the reason when freshness is unknown (B4)", async () => {
  await index();
  const first = await runCli(["brain", "clusters", "run", "--vault", vault, "--json"]);
  const written = (JSON.parse(first.stdout) as { written: string[] }).written;
  expect(written).toHaveLength(1);
  // Replace the materialized note with a listable-but-unstattable entry
  // of the SAME name: the directory walk still reports one output, and
  // the stat still fails. Before B4 that was reported as "not
  // materialized" - the same answer as an empty output directory.
  const notePath = join(vault, written[0]!);
  rmSync(notePath);
  symlinkSync(join(vault, "Brain", "clusters", "no-such-target"), notePath);
  const r = await runCli(["brain", "clusters", "run", "--vault", vault, "--if-stale", "--json"]);
  expect(r.returncode).toBe(0);
  const parsed = JSON.parse(r.stdout) as {
    skipped?: string;
    staleness?: { state: string; reason: string };
  };
  expect(parsed.skipped).toBeUndefined();
  expect(parsed.staleness).toEqual({ state: "unknown", reason: "outputs_unreadable" });
  const metrics = listMetrics(vault, { surface: "communities" }).map((m) => m.payload);
  expect(metrics).toContainEqual(
    expect.objectContaining({ freshness: "unknown", freshness_reason: "outputs_unreadable" }),
  );
});

test("run --if-stale recomputes after an input note changes (t_845fe240)", async () => {
  await index();
  await runCli(["brain", "clusters", "run", "--vault", vault]);
  // Make an input note strictly newer than the materialized outputs.
  const future = Date.now() / 1000 + 100;
  utimesSync(join(vault, "team-a.md"), future, future);
  const r = await runCli(["brain", "clusters", "run", "--vault", vault, "--if-stale", "--json"]);
  expect(r.returncode).toBe(0);
  expect(JSON.parse(r.stdout).skipped).toBeUndefined();
});

test("usage errors exit 2", async () => {
  const r = await runCli(["brain", "clusters", "nope", "--vault", vault]);
  expect(r.returncode).toBe(2);
  const bad = await runCli(["brain", "clusters", "run", "--min-size", "0", "--vault", vault]);
  expect(bad.returncode).toBe(2);
  const badBatch = await runCli([
    "brain",
    "clusters",
    "run",
    "--batch-size",
    "0",
    "--vault",
    vault,
  ]);
  expect(badBatch.returncode).toBe(2);
});