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.3 KB
Raw Blame
/**
 * `o2b brain design-note` and `brain_design_note`
 * (salience-lifecycle-enrichment, unit 7, t_c87644b4). Claims pinned here:
 *
 *  1. The grounding phase's `--json` payload carries the three stores'
 *     matches, their counts, the NAMED empty stores, and one envelope.
 *  2. The commit phase's `--json` payload names the note and the single
 *     recommended alternative.
 *  3. A payload that does not recommend exactly one alternative exits 1
 *     with the refusal in `--json`, and writes nothing.
 *  4. A missing topic is a usage error (exit 2), and the verb has its own
 *     `--help`.
 *  5. The MCP tool answers over the same core, both phases, and the path
 *     it reports is vault-relative - no MCP response or CLI output carries
 *     the absolute host path.
 */

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

import { recordDecision } from "../../src/core/brain/decisions/record.ts";
import { buildToolTable, findTool } from "../../src/mcp/tools.ts";
import type { ServerContext } from "../../src/mcp/tool-contract.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);

const TOPIC = "vector index storage";
let tmp: string;
let vault: string;
let configPath: string;

function note(...flags: ReadonlyArray<boolean>): Record<string, unknown> {
  return {
    title: "Where the vector index lives",
    alternatives: flags.map((recommended, i) => ({
      name: `option-${i}`,
      approach: `Store the index with option-${i}.`,
      tradeoffs: "Write cost against read latency.",
      recommended,
    })),
  };
}

function run(args: ReadonlyArray<string>) {
  return runCli(["brain", "design-note", ...args, "--vault", vault], {
    env: { OPEN_SECOND_BRAIN_CONFIG: configPath },
  });
}

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), "o2b-cli-design-note-"));
  vault = join(tmp, "vault");
  mkdirSync(join(vault, "Brain"), { recursive: true });
  configPath = join(tmp, "config.yaml");
  writeFileSync(configPath, `vault: ${vault}\n`);
  recordDecision(vault, {
    title: "Vector index storage location",
    chosen: "Keep the index outside the vault",
    assumption: "Sync clients must not replicate a binary index",
    reviewDate: "2027-01-01",
    agent: "tester",
  });
});

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

test("the grounding phase --json carries counts, named empty stores and one envelope", async () => {
  const r = await run([TOPIC, "--json"]);
  expect(r.returncode).toBe(0);
  const payload = JSON.parse(r.stdout) as {
    ok: boolean;
    topic: string;
    target_path: string;
    grounding: {
      decisions: Array<{ title: string }>;
      counts: { tensions: number; decisions: number; truthSlots: number; conflicts: number };
      empty_stores: string[];
    };
    llm_step: { status: string; step: string; target_path: string };
  };
  expect(payload.ok).toBe(true);
  expect(payload.topic).toBe(TOPIC);
  expect(payload.grounding.decisions.map((d) => d.title)).toEqual([
    "Vector index storage location",
  ]);
  expect(payload.grounding.counts.decisions).toBe(1);
  // The decision store held something; the other two hold nothing at all
  // and say so by name.
  expect(payload.grounding.empty_stores.toSorted()).toEqual(["tensions", "truth"]);
  expect(payload.llm_step.status).toBe("needs-llm-step");
  expect(payload.llm_step.step).toBe("design-note");
  expect(payload.llm_step.target_path).toBe(payload.target_path);
});

test("the commit phase --json names the note and its one recommendation", async () => {
  const r = await run([TOPIC, "--payload", JSON.stringify(note(false, true)), "--json"]);
  expect(r.returncode).toBe(0);
  const payload = JSON.parse(r.stdout) as {
    ok: boolean;
    path: string;
    recommended: string;
    alternative_count: number;
  };
  expect(payload.ok).toBe(true);
  expect(payload.recommended).toBe("option-1");
  expect(payload.alternative_count).toBe(2);
  // Vault-relative, matching the distill house style and the MCP twin:
  // the absolute host path is the operator-supplied vault prefix composed
  // with a machine-derived subtree, and neither belongs in output that
  // lands in model context.
  expect(payload.path).toMatch(/^Brain[/\\]decisions[/\\]/);
  expect(existsSync(join(vault, payload.path))).toBe(true);
});

test("text mode names the note vault-relative on the wrote line", async () => {
  const r = await run([TOPIC, "--payload", JSON.stringify(note(false, true))]);
  expect(r.returncode).toBe(0);
  expect(r.stdout).toMatch(/^wrote Brain[/\\]decisions[/\\]design-/m);
  expect(r.stdout).not.toContain(tmp);
});

test("a payload recommending nothing exits 1, names the count, and writes nothing", async () => {
  const r = await run([TOPIC, "--payload", JSON.stringify(note(false, false)), "--json"]);
  expect(r.returncode).toBe(1);
  const payload = JSON.parse(r.stdout) as { ok: boolean; message: string };
  expect(payload.ok).toBe(false);
  expect(payload.message).toContain("exactly one");
  expect(payload.message).toContain("found 0 of 2");
});

test("a missing topic is a usage error", async () => {
  const r = await run([]);
  expect(r.returncode).toBe(2);
  expect(r.stderr).toContain("o2b brain design-note");
});

test("--help prints the verb's own usage", async () => {
  const r = await runCli(["brain", "design-note", "--help"], {
    env: { OPEN_SECOND_BRAIN_CONFIG: configPath },
  });
  expect(r.returncode).toBe(0);
  expect(r.stdout.startsWith("usage:")).toBe(true);
  expect(r.stdout).toContain("o2b brain design-note");
});

test("the MCP tool answers both phases over the same core", async () => {
  const ctx: ServerContext = { vault, configPath, repoRoot: null };
  const tool = findTool(buildToolTable("full"), "brain_design_note");

  const planned = (await tool.handler(ctx, { topic: TOPIC })) as {
    phase: string;
    grounding: { empty_stores: string[] };
    llm_step: { step: string };
  };
  expect(planned.phase).toBe("plan");
  expect(planned.llm_step.step).toBe("design-note");
  expect(planned.grounding.empty_stores.toSorted()).toEqual(["tensions", "truth"]);

  const committed = (await tool.handler(ctx, { topic: TOPIC, note: note(true) })) as {
    phase: string;
    recommended: string;
    path: string;
  };
  expect(committed.phase).toBe("commit");
  expect(committed.recommended).toBe("option-0");
  // Vault-relative on both surfaces, and neither response carries the host
  // path - the CLI's output and an MCP payload alike land in model context.
  expect(committed.path).toMatch(/^Brain[/\\]decisions[/\\]/);
  expect(existsSync(join(vault, committed.path))).toBe(true);
  expect(JSON.stringify(committed)).not.toContain(vault);

  await expect(
    Promise.resolve(tool.handler(ctx, { topic: "another topic", note: note(true, true) })),
  ).rejects.toThrow("exactly one");
});

test("is a full-tier tool, absent from the writer surface", () => {
  expect(buildToolTable("full").find((t) => t.name === "brain_design_note")).toBeDefined();
  expect(buildToolTable("writer").find((t) => t.name === "brain_design_note")).toBeUndefined();
});

describe("think-block strip (t_dac8bf7e)", () => {
  test("a <think>-prefixed payload succeeds, names the strip, and commits the same note", async () => {
    const r = await run([
      TOPIC,
      "--payload",
      `<think>weighing the options</think>${JSON.stringify(note(false, true))}`,
      "--json",
    ]);
    expect(r.returncode).toBe(0);
    const payload = JSON.parse(r.stdout) as {
      ok: boolean;
      note?: string;
      recommended: string;
      path: string;
    };
    expect(payload.ok).toBe(true);
    expect(payload.note).toContain("<think>");
    expect(payload.recommended).toBe("option-1");
    expect(existsSync(join(vault, payload.path))).toBe(true);
  });

  test("text mode names the strip too - never a silent strip", async () => {
    const r = await run([
      TOPIC,
      "--payload",
      `<think>weighing the options</think>${JSON.stringify(note(false, true))}`,
    ]);
    expect(r.returncode).toBe(0);
    expect(r.stdout).toContain("<think>");
  });

  test("garbage still exits 1 with the plain ok:false refusal", async () => {
    const r = await run([TOPIC, "--payload", "not json", "--json"]);
    expect(r.returncode).toBe(1);
    const payload = JSON.parse(r.stdout) as { ok: boolean; message: string };
    expect(payload.ok).toBe(false);
    expect(payload.message).toBe("payload must be valid JSON");
  });

  test("a payload that still does not parse after the strip names the attempt and exits 1", async () => {
    const r = await run([TOPIC, "--payload", "<think>r</think>not json", "--json"]);
    expect(r.returncode).toBe(1);
    const payload = JSON.parse(r.stdout) as { ok: boolean; message: string };
    expect(payload.ok).toBe(false);
    expect(payload.message).toContain("<think>");
  });

  test("a clean payload's --json output carries no note key", async () => {
    const r = await run([TOPIC, "--payload", JSON.stringify(note(false, true)), "--json"]);
    expect(r.returncode).toBe(0);
    const payload = JSON.parse(r.stdout) as Record<string, unknown>;
    expect("note" in payload).toBe(false);
  });
});