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
/**
 * MCP integration tests for the `brain_context` tool (v0.10.10).
 *
 * Drives §5 of `docs/plans/2026-05-20-v0.10.10-design.md` — the
 * read-only pull-bootstrap tool that returns `Brain/active.md`
 * verbatim plus counts for runtimes without a `SessionStart` hook
 * (Cursor, Aider, raw Claude API).
 *
 * Exercises the full server path (`MCPServer.handleRequest →
 * tools/call → handler`) so registration drift is caught here too.
 */

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

import { JSONRPC_VERSION, MCPServer, PROTOCOL_VERSION } from "../../src/mcp/index.ts";
import { buildToolTable } from "../../src/mcp/tools.ts";
import { TRANSPORT_REACH } from "../../src/core/graph/transport-reach.ts";
import { bootstrapBrain } from "../../src/core/brain/init.ts";
import { brainActivePath } from "../../src/core/brain/paths.ts";
import { writePreference } from "../../src/core/brain/preference.ts";
import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";
import { appendLogEvent } from "../../src/core/brain/log.ts";
import { BRAIN_LOG_EVENT_KIND } from "../../src/core/brain/types.ts";

let tmp: string;
let vault: string;
let configHome: string;
let configPath: string;
const savedEnv: Record<string, string | undefined> = {};

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), "o2b-mcp-brain-context-"));
  vault = join(tmp, "vault");
  configHome = mkdtempSync(join(tmpdir(), "o2b-mcp-brain-context-cfg-"));
  configPath = join(configHome, "config.yaml");
  for (const k of ["VAULT_AGENT_NAME", "VAULT_TIMEZONE", "VAULT_DIR", "OPEN_SECOND_BRAIN_CONFIG"]) {
    savedEnv[k] = process.env[k];
    delete process.env[k];
  }
  process.env["OPEN_SECOND_BRAIN_CONFIG"] = configPath;
  atomicWriteFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);
});

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

async function initialize(server: MCPServer): Promise<void> {
  await server.handleRequest({
    jsonrpc: JSONRPC_VERSION,
    id: 1,
    method: "initialize",
    params: {
      protocolVersion: PROTOCOL_VERSION,
      capabilities: {},
      clientInfo: { name: "brain-context-test", version: "0" },
    },
  });
  await server.handleRequest({
    jsonrpc: JSONRPC_VERSION,
    method: "notifications/initialized",
  });
}

async function callContext(server: MCPServer): Promise<Record<string, unknown>> {
  const r = (await server.handleRequest({
    jsonrpc: JSONRPC_VERSION,
    id: 7,
    method: "tools/call",
    params: { name: "brain_context", arguments: {} },
  })) as { result: { content: ReadonlyArray<{ type: string; text: string }> } };
  // Tool returns are wrapped as `content: [{type:"text", text:"<json>"}]`.
  const text = r.result.content[0]!.text;
  return JSON.parse(text);
}

describe("brain_context tool registration", () => {
  test("appears in the full tool table", () => {
    const tools = buildToolTable("full");
    expect(tools.find((t) => t.name === "brain_context")).toBeDefined();
  });

  test("appears in the writer scope (always-loaded)", () => {
    const tools = buildToolTable("writer");
    expect(tools.find((t) => t.name === "brain_context")).toBeDefined();
  });

  test("writer scope still hosts the Brain writers plus context", () => {
    const names = buildToolTable("writer")
      .map((t) => t.name)
      .toSorted();
    expect(names).toEqual(
      [
        "brain_apply_evidence",
        "brain_context",
        "brain_feedback",
        "brain_note",
        "brain_pinned_context",
      ].toSorted(),
    );
  });
});

describe("brain_context tool — Brain absent", () => {
  test("returns present:false with empty content and zero counts", async () => {
    // No bootstrapBrain — Brain/ does not exist.
    const server = new MCPServer({ vault, configPath });
    await initialize(server);
    const out = await callContext(server);
    expect(out["present"]).toBe(false);
    expect(out["content"]).toBe("");
    expect(out["generated_at"]).toBeNull();
    const counts = out["counts"] as Record<string, number>;
    expect(counts.confirmed).toBe(0);
    expect(counts.quarantine).toBe(0);
    expect(counts.retired_recent).toBe(0);
    expect(counts.most_applied_30d).toBe(0);
  });
});

describe("brain_context tool — Brain present", () => {
  beforeEach(() => {
    bootstrapBrain(vault, { configPath });
  });

  test("self-heals active.md when it is missing", async () => {
    // bootstrapBrain may already create active.md; remove it so we
    // exercise the regenerateActive self-heal path.
    const active = brainActivePath(vault);
    if (existsSync(active)) unlinkSync(active);

    const server = new MCPServer({ vault, configPath });
    await initialize(server);
    const out = await callContext(server);
    expect(out["present"]).toBe(true);
    expect(typeof out["content"]).toBe("string");
    expect(out["content"] as string).toContain("# Active Brain Preferences");
    expect(existsSync(active)).toBe(true);
  });

  test("returns the active.md body verbatim once it exists", async () => {
    writePreference(vault, {
      slug: "demo",
      topic: "demo",
      principle: "Demo principle",
      created_at: "2026-05-01T00:00:00Z",
      unconfirmed_until: "2026-05-30T00:00:00Z",
      status: "confirmed",
      confirmed_at: "2026-05-02T00:00:00Z",
      evidenced_by: [],
      applied_count: 0,
      violated_count: 0,
      last_evidence_at: null,
      confidence: "medium",
      scope: "writing",
    });

    // The verbatim-body contract is the LOCAL face (delivery-trust, lane
    // A): a remote reach now receives the fenced delivery, so the pin
    // names the reach it always meant - the operator's own reads. (An
    // absent reach resolves remote, fail closed.)
    const server = new MCPServer({ vault, configPath }, { reach: TRANSPORT_REACH.local });
    await initialize(server);
    const out = await callContext(server);
    const fromDisk = readFileSync(brainActivePath(vault), "utf8");
    expect(out["content"]).toBe(fromDisk);
    expect(typeof out["generated_at"]).toBe("string");
    const counts = out["counts"] as Record<string, number>;
    expect(counts.confirmed).toBe(1);
    expect(typeof counts.most_applied_30d).toBe("number");
  });

  test("two consecutive calls return byte-equal content", async () => {
    writePreference(vault, {
      slug: "demo",
      topic: "demo",
      principle: "Demo principle",
      created_at: "2026-05-01T00:00:00Z",
      unconfirmed_until: "2026-05-30T00:00:00Z",
      status: "confirmed",
      confirmed_at: "2026-05-02T00:00:00Z",
      evidenced_by: [],
      applied_count: 0,
      violated_count: 0,
      last_evidence_at: null,
      confidence: "medium",
    });

    const server = new MCPServer({ vault, configPath });
    await initialize(server);
    const first = await callContext(server);
    const second = await callContext(server);
    expect(second["content"]).toBe(first["content"]);
    expect(second["generated_at"]).toBe(first["generated_at"]);
  });
});

/**
 * `maintenance_overdue` (nothing-writes-silently, Unit D / t_6285e06f):
 * a cheap proxy bounded to the single newest `Brain/log/` day, never a
 * full history scan, since `brain_context` is always-loaded.
 */
describe("brain_context tool — maintenance_overdue (bounded, newest shard only)", () => {
  beforeEach(() => {
    bootstrapBrain(vault, { configPath });
  });

  test("no log history yet -> null (nothing to be overdue about)", async () => {
    const server = new MCPServer({ vault, configPath });
    await initialize(server);
    const out = await callContext(server);
    expect(out["maintenance_overdue"]).toBeNull();
  });

  test("newest day holds events but no dream -> true", async () => {
    appendLogEvent(vault, {
      timestamp: "2026-06-01T10:00:00Z",
      eventType: BRAIN_LOG_EVENT_KIND.note,
      agent: "tester",
      body: { text: "note" },
    });
    const server = new MCPServer({ vault, configPath });
    await initialize(server);
    const out = await callContext(server);
    expect(out["maintenance_overdue"]).toBe(true);
  });

  test("newest day holds a dream event -> false", async () => {
    appendLogEvent(vault, {
      timestamp: "2026-06-01T10:00:00Z",
      eventType: BRAIN_LOG_EVENT_KIND.dream,
      agent: "tester",
      body: {},
    });
    const server = new MCPServer({ vault, configPath });
    await initialize(server);
    const out = await callContext(server);
    expect(out["maintenance_overdue"]).toBe(false);
  });

  test("an older day's dream does not clear a newer day with no dream (bounded to newest only)", async () => {
    appendLogEvent(vault, {
      timestamp: "2026-06-01T10:00:00Z",
      eventType: BRAIN_LOG_EVENT_KIND.dream,
      agent: "tester",
      body: {},
    });
    appendLogEvent(vault, {
      timestamp: "2026-06-02T10:00:00Z",
      eventType: BRAIN_LOG_EVENT_KIND.note,
      agent: "tester",
      body: { text: "note" },
    });
    const server = new MCPServer({ vault, configPath });
    await initialize(server);
    const out = await callContext(server);
    expect(out["maintenance_overdue"]).toBe(true);
  });
});