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.0 KB
Raw Blame
/**
 * `brain_settings`, the MCP twin of `o2b brain settings`: agent-authority
 * records on a store-only machine (and on a server with no vault), the
 * operator's value never outvoted, device keys answered with the config
 * key, the settings file edited on an unswitched machine.
 */
import { afterEach, describe, expect, test } from "bun:test";
import { existsSync, readFileSync, rmSync } from "node:fs";
import { join } from "node:path";

import { brainConfigPath } from "../../src/core/brain/paths.ts";
import { setBrainSetting } from "../../src/core/brain/policy/settings-write.ts";
import { TRANSPORT_REACH, type TransportReach } from "../../src/core/graph/transport-reach.ts";
import { SETTING_SET_KIND } from "../../src/core/store/constants.ts";
import { JSONRPC_VERSION, MCPServer, PROTOCOL_VERSION } from "../../src/mcp/index.ts";
import {
  brainTreeDigest,
  partitionRecords,
  switchDevice,
} from "../core/brain/store-only/fixtures.ts";
import { makeStoreEnv, type StoreEnv } from "../core/store/fixtures/store-env.ts";

let env: StoreEnv | null = null;
afterEach(() => {
  env?.cleanup();
  env = null;
});

interface Answer {
  readonly result?: Record<string, unknown>;
  readonly error?: { readonly message: string; readonly data?: Record<string, unknown> };
}

async function call(server: MCPServer, args: Record<string, unknown>): Promise<Answer> {
  const r = (await server.handleRequest({
    jsonrpc: JSONRPC_VERSION,
    id: 2,
    method: "tools/call",
    params: { name: "brain_settings", arguments: args },
  })) as {
    result?: { content: ReadonlyArray<{ text: string }>; isError?: boolean };
    error?: { message: string; data?: Record<string, unknown> };
  };
  if (r.error) return { error: r.error };
  const text = r.result!.content[0]!.text;
  if (r.result!.isError) return { error: { message: text } };
  return { result: JSON.parse(text) as Record<string, unknown> };
}

async function serverFor(
  vault: string | null,
  configPath: string,
  reach?: TransportReach,
): Promise<MCPServer> {
  const server = new MCPServer({
    vault,
    configPath,
    ...(reach !== undefined ? { reach } : {}),
  });
  await server.handleRequest({
    jsonrpc: JSONRPC_VERSION,
    id: 1,
    method: "initialize",
    params: {
      protocolVersion: PROTOCOL_VERSION,
      capabilities: {},
      clientInfo: { name: "t", version: "0" },
    },
  });
  return server;
}

function sets(e: StoreEnv) {
  return partitionRecords(e.storeRoot, "shared").filter((r) => r.kind === SETTING_SET_KIND);
}

describe("brain_settings on a store-only machine", () => {
  test("set writes an agent-authority record and nothing under Brain/", async () => {
    env = makeStoreEnv("osb-settool-store-");
    switchDevice(env.storeRoot);
    const before = brainTreeDigest(env.vault);
    const server = await serverFor(env.vault, env.configPath);
    const { result } = await call(server, {
      action: "set",
      name: "guardrails.derived_fact_synthesis",
      value: true,
    });
    expect(result).toMatchObject({ changed: true, mode: "store", value: true });
    expect(sets(env)[0]!.body).toMatchObject({
      authority: "agent",
      key: "brain.guardrails.derived_fact_synthesis",
      value: true,
    });
    const got = await call(server, { action: "get", name: "guardrails.derived_fact_synthesis" });
    expect(got.result).toMatchObject({ set: true, value: true, authority: "agent" });
    const listed = await call(server, { action: "list" });
    expect(listed.result?.["settings"]).toHaveLength(1);
    expect(brainTreeDigest(env.vault)).toBe(before);
  });

  test("a record is attributed to the agent the transport minted, not the config's", async () => {
    env = makeStoreEnv("osb-settool-identity-");
    switchDevice(env.storeRoot);
    const server = await serverFor(env.vault, env.configPath);
    const reply = await server.handleRequest(
      {
        jsonrpc: JSONRPC_VERSION,
        id: 3,
        method: "tools/call",
        params: {
          name: "brain_settings",
          arguments: { action: "set", name: "guardrails.derived_fact_synthesis", value: true },
        },
      },
      { agent: "edge-agent", via: "token" },
    );
    expect(JSON.stringify(reply)).toContain('\\"changed\\": true');
    expect(sets(env)[0]!.agent).toBe("edge-agent");
  });

  test("an operator value is refused, not outvoted", async () => {
    env = makeStoreEnv("osb-settool-human-");
    switchDevice(env.storeRoot);
    setBrainSetting(
      { vault: env.vault, authority: "human", agent: "operator" },
      "dream.heal_enrich_enabled",
      true,
    );
    const server = await serverFor(env.vault, env.configPath);
    const { error } = await call(server, {
      action: "set",
      name: "dream.heal_enrich_enabled",
      value: false,
    });
    expect(error?.message).toContain("o2b brain settings set dream.heal_enrich_enabled");
    expect(error?.data?.["code"]).toBe("human_value_in_force");
    expect(sets(env)).toHaveLength(1);
    // An agent unset would remove the operator's value: refused the same way.
    const unset = await call(server, { action: "unset", name: "dream.heal_enrich_enabled" });
    expect(unset.error?.data?.["code"]).toBe("human_value_in_force");
    expect(
      partitionRecords(env.storeRoot, "shared").filter(
        (r) => r.kind !== SETTING_SET_KIND && r.kind.startsWith("setting"),
      ),
    ).toEqual([]);
    expect(sets(env)).toHaveLength(1);
    const got = await call(server, { action: "get", name: "dream.heal_enrich_enabled" });
    expect(got.result).toMatchObject({ set: true, value: true, authority: "human" });
  });

  test("a device key names the config key; an invalid value is refused", async () => {
    env = makeStoreEnv("osb-settool-device-");
    switchDevice(env.storeRoot);
    const server = await serverFor(env.vault, env.configPath);
    const device = await call(server, {
      action: "set",
      name: "embeddings.sunset_model",
      value: "m",
    });
    expect(device.error?.data).toMatchObject({
      code: "device_setting",
      config_key: "brain_embeddings_sunset_model",
    });
    const bad = await call(server, { action: "set", name: "dream.candidate_threshold", value: 0 });
    expect(bad.error?.data?.["code"]).toBe("invalid_setting_value");
    const missing = await call(server, { action: "set", name: "primary_agent" });
    expect(missing.error?.message).toContain("needs value");
    expect(sets(env)).toHaveLength(0);
  });

  test("a server with no vault reads and writes the store", async () => {
    env = makeStoreEnv("osb-settool-novault-", { legacyTree: false, configureVault: false });
    const server = await serverFor(null, env.configPath);
    const set = await call(server, { action: "set", name: "primary_agent", value: "codex" });
    expect(set.result).toMatchObject({ changed: true, mode: "store" });
    const got = await call(server, { action: "get", name: "primary_agent" });
    expect(got.result).toMatchObject({ set: true, value: "codex" });
  });
});

describe("brain_settings on an unswitched machine", () => {
  test("set edits the settings file and writes no record", async () => {
    env = makeStoreEnv("osb-settool-legacy-");
    const server = await serverFor(env.vault, env.configPath);
    const { result } = await call(server, {
      action: "set",
      name: "dream.candidate_threshold",
      value: 7,
    });
    expect(result).toMatchObject({ changed: true, mode: "legacy" });
    expect(readFileSync(brainConfigPath(env.vault), "utf8")).toContain("candidate_threshold: 7");
    expect(sets(env)).toHaveLength(0);
  });

  test("an agent cannot unset a value that differs from the default; the file is unchanged", async () => {
    env = makeStoreEnv("osb-settool-legacy-unset-");
    const server = await serverFor(env.vault, env.configPath);
    await call(server, { action: "set", name: "dream.candidate_threshold", value: 7 });
    const before = readFileSync(brainConfigPath(env.vault), "utf8");
    // `_brain.yaml` records no authority: a value off the shipped default
    // counts as the operator's (\`o2b brain settings unset\` removes it).
    const { error } = await call(server, { action: "unset", name: "dream.candidate_threshold" });
    expect(error?.data?.["code"]).toBe("human_value_in_force");
    expect(readFileSync(brainConfigPath(env.vault), "utf8")).toBe(before);
    expect(sets(env)).toHaveLength(0);
  });

  test("an operator-only setting is refused with operator_only_setting", async () => {
    env = makeStoreEnv("osb-settool-operator-");
    const before = readFileSync(brainConfigPath(env.vault), "utf8");
    const server = await serverFor(env.vault, env.configPath);
    const { error } = await call(server, {
      action: "set",
      name: "integrity.owner_scope_delivery",
      value: "off",
    });
    expect(error?.data?.["code"]).toBe("operator_only_setting");
    expect(error?.message).toContain("o2b brain settings set integrity.owner_scope_delivery");
    expect(readFileSync(brainConfigPath(env.vault), "utf8")).toBe(before);
  });
});

describe("brain_settings on a switched machine whose store cannot be opened", () => {
  test("a remote agent's refusal names neither the lost partition nor the leave remedy", async () => {
    env = makeStoreEnv("osb-settool-remote-redact-");
    switchDevice(env.storeRoot);
    setBrainSetting(
      { vault: env.vault, authority: "human", agent: "u" },
      "dream.heal_enrich_enabled",
      true,
    );
    // A switched machine that lost the identity file of the private
    // partition it holds: the store-open error names `private/store.json`
    // and the leave verb, but none of that may reach the remote caller.
    // Only `private/store.json` is removed: the raw text keeps the leave
    // remedy here, so the assertions below have something to catch.
    rmSync(join(env.storeRoot, "private", "store.json"));
    const before = sets(env).length;
    const server = await serverFor(env.vault, env.configPath, TRANSPORT_REACH.remote);
    const reply = await server.handleRequest({
      jsonrpc: JSONRPC_VERSION,
      id: 4,
      method: "tools/call",
      params: {
        name: "brain_settings",
        arguments: { action: "set", name: "dream.heal_enrich_enabled", value: false },
      },
    });
    // The write fails closed; the whole answer - prose, codes, data -
    // names neither the partition's identity file nor the remedy.
    expect(JSON.stringify(reply)).not.toContain("private/");
    expect(JSON.stringify(reply)).not.toContain("partition leave private");
    const err = (reply as { error?: { message: string; data?: Record<string, unknown> } }).error;
    expect(err?.data?.["code"]).toBe("settings_unreadable");
    expect(err?.message).toContain("dream.heal_enrich_enabled cannot be changed by an agent");
    expect(sets(env)).toHaveLength(before);
  });

  test("a refused remote note write names neither the lost partition nor the remedy", async () => {
    env = makeStoreEnv("osb-settool-remote-permissions-");
    switchDevice(env.storeRoot);
    setBrainSetting(
      { vault: env.vault, authority: "human", agent: "u" },
      "dream.heal_enrich_enabled",
      true,
    );
    // The same state as above, reached through a note write:
    // `brain_create_note` is refused before any write (the settings read
    // refuses first), and the refusal must not carry the store-open
    // cause's raw text. The permissions gate's own text is pinned in
    // `tests/core/brain/permissions/document-source.test.ts`.
    rmSync(join(env.storeRoot, "private", "store.json"));
    const server = await serverFor(env.vault, env.configPath, TRANSPORT_REACH.remote);
    const reply = await server.handleRequest({
      jsonrpc: JSONRPC_VERSION,
      id: 5,
      method: "tools/call",
      params: {
        name: "brain_create_note",
        arguments: { path: "Notes/Blocked.md", content: "never written" },
      },
    });
    const text = JSON.stringify(reply);
    expect(text).toContain("could not be opened");
    expect(text).not.toContain("private/");
    expect(text).not.toContain("partition leave");
    expect(existsSync(join(env.vault, "Notes", "Blocked.md"))).toBe(false);
  });
});