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
13.8 KB
Raw Blame
/**
 * The shared brain settings writer (task 2.11 follow-up, design D4 and
 * D14 item 3): a store-only machine writes `setting-set` / `setting-unset`
 * records and never a byte under `Brain/`; an unswitched machine edits
 * `_brain.yaml` as before. Only shared keys are written; a device key is
 * answered with the machine-config key to set instead; values pass the
 * `_brain.yaml` validator in both modes.
 */
import { afterEach, describe, expect, test } from "bun:test";
import { readFileSync, rmSync } from "node:fs";
import { join } from "node:path";

import { brainConfigPath } from "../../../src/core/brain/paths.ts";
import { DEFAULT_BRAIN_CONFIG } from "../../../src/core/brain/policy/defaults.ts";
import { loadBrainConfig } from "../../../src/core/brain/policy/load.ts";
import {
  BrainSettingError,
  getBrainSetting,
  listBrainSettings,
  parseSettingValue,
  setBrainSetting,
  unsetBrainSetting,
} from "../../../src/core/brain/policy/settings-write.ts";
import { SETTING_SET_KIND, SETTING_UNSET_KIND } from "../../../src/core/store/constants.ts";
import { appendRecord } from "../../../src/core/store/appender.ts";
import { openStore } from "../../../src/core/store/store-open.ts";
import { makeStoreEnv, type StoreEnv } from "../store/fixtures/store-env.ts";
import { brainTreeDigest, partitionRecords, switchDevice } from "./store-only/fixtures.ts";

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

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

function switched(prefix: string): StoreEnv {
  const e = makeStoreEnv(prefix);
  switchDevice(e.storeRoot);
  return e;
}

function errorOf(fn: () => unknown): BrainSettingError {
  try {
    fn();
  } catch (err) {
    if (err instanceof BrainSettingError) return err;
    throw err;
  }
  throw new Error("expected a BrainSettingError");
}

describe("store-only machine", () => {
  test("set writes one human setting-set record and nothing under Brain/", () => {
    env = switched("osb-setw-store-");
    const before = brainTreeDigest(env.vault);
    const result = setBrainSetting(
      { vault: env.vault, authority: "human", agent: "tester" },
      "dream.candidate_threshold",
      7,
    );
    expect(result).toMatchObject({
      name: "dream.candidate_threshold",
      key: "brain.dream.candidate_threshold",
      value: 7,
      changed: true,
      mode: "store",
    });
    expect(result.record).toMatch(/^[0-9A-Z]{26}$/);
    expect(brainTreeDigest(env.vault)).toBe(before);
    const records = settingRecords(env);
    expect(records).toHaveLength(1);
    expect(records[0]!.body).toMatchObject({
      authority: "human",
      key: "brain.dream.candidate_threshold",
      value: 7,
    });
    expect(records[0]!.id).toBe(result.record!);
    expect(loadBrainConfig(env.vault).dream.candidate_threshold).toBe(7);
  });

  test("works with no vault configured", () => {
    env = makeStoreEnv("osb-setw-novault-", { legacyTree: false, configureVault: false });
    setBrainSetting({ vault: null, authority: "human", agent: "t" }, "primary_agent", "claude");
    expect(loadBrainConfig(null).primary_agent).toBe("claude");
    expect(getBrainSetting({ vault: null }, "primary_agent")).toMatchObject({
      set: true,
      value: "claude",
      authority: "human",
      source: "store",
    });
  });

  test("the same value again writes nothing", () => {
    env = switched("osb-setw-same-");
    const ctx = { vault: env.vault, authority: "human" as const, agent: "t" };
    setBrainSetting(ctx, "notes.read_paths", ["Projects/"]);
    const again = setBrainSetting(ctx, "notes.read_paths", ["Projects/"]);
    expect(again.changed).toBe(false);
    expect(settingRecords(env)).toHaveLength(1);
  });

  test("unset writes a tombstone and the default comes back", () => {
    env = switched("osb-setw-unset-");
    const ctx = { vault: env.vault, authority: "human" as const, agent: "t" };
    setBrainSetting(ctx, "dream.candidate_threshold", 9);
    const result = unsetBrainSetting(ctx, "dream.candidate_threshold");
    expect(result.changed).toBe(true);
    expect(settingRecords(env).at(-1)!.kind).toBe(SETTING_UNSET_KIND);
    expect(loadBrainConfig(env.vault).dream.candidate_threshold).toBe(
      DEFAULT_BRAIN_CONFIG.dream.candidate_threshold,
    );
    expect(unsetBrainSetting(ctx, "dream.candidate_threshold").changed).toBe(false);
  });

  test("an agent cannot override or unset a human value; nothing is written", () => {
    env = switched("osb-setw-auth-");
    setBrainSetting(
      { vault: env.vault, authority: "human", agent: "u" },
      "dream.heal_enrich_enabled",
      true,
    );
    const agent = { vault: env.vault, authority: "agent" as const, agent: "a" };
    expect(errorOf(() => setBrainSetting(agent, "dream.heal_enrich_enabled", false)).code).toBe(
      "human_value_in_force",
    );
    expect(errorOf(() => unsetBrainSetting(agent, "dream.heal_enrich_enabled")).code).toBe(
      "human_value_in_force",
    );
    expect(settingRecords(env)).toHaveLength(1);
  });

  test("an agent cannot change a setting while the shard of the human value is gone", () => {
    env = switched("osb-setw-gone-");
    // The operator's value sits in a peer's settings shard.
    const shard = appendRecord(openStore({ root: env.storeRoot, device: "dev-b" }), {
      partition: "shared",
      stream: "settings",
      kind: SETTING_SET_KIND,
      agent: "u",
      body: { authority: "human", key: "brain.dream.heal_enrich_enabled", value: true },
    }).path;
    const agent = { vault: env.vault, authority: "agent" as const, agent: "a" };
    expect(errorOf(() => setBrainSetting(agent, "dream.heal_enrich_enabled", false)).code).toBe(
      "human_value_in_force",
    );
    rmSync(shard);
    const before = settingRecords(env).length;
    expect(errorOf(() => setBrainSetting(agent, "dream.heal_enrich_enabled", false)).code).toBe(
      "settings_unreadable",
    );
    expect(settingRecords(env)).toHaveLength(before);
  });

  test("an agent cannot change a setting while the switched machine's store cannot be opened", () => {
    env = switched("osb-setw-nostore-");
    setBrainSetting(
      { vault: env.vault, authority: "human", agent: "u" },
      "dream.heal_enrich_enabled",
      true,
    );
    const agent = { vault: env.vault, authority: "agent" as const, agent: "a" };
    expect(errorOf(() => setBrainSetting(agent, "dream.heal_enrich_enabled", false)).code).toBe(
      "human_value_in_force",
    );
    rmSync(join(env.storeRoot, "shared", "store.json"));
    rmSync(join(env.storeRoot, "private", "store.json"));
    expect(errorOf(() => setBrainSetting(agent, "dream.heal_enrich_enabled", false)).code).toBe(
      "settings_unreadable",
    );
  });

  test("an agent value lands with agent authority and a human one replaces it", () => {
    env = switched("osb-setw-agent-");
    setBrainSetting(
      { vault: env.vault, authority: "agent", agent: "a" },
      "dream.candidate_threshold",
      4,
    );
    expect(settingRecords(env)[0]!.body["authority"]).toBe("agent");
    setBrainSetting(
      { vault: env.vault, authority: "human", agent: "u" },
      "dream.candidate_threshold",
      6,
    );
    expect(loadBrainConfig(env.vault).dream.candidate_threshold).toBe(6);
  });

  test("list names every shared setting that is set, with its authority", () => {
    env = switched("osb-setw-list-");
    setBrainSetting(
      { vault: env.vault, authority: "human", agent: "u" },
      "primary_agent",
      "claude",
    );
    setBrainSetting(
      { vault: env.vault, authority: "agent", agent: "a" },
      "guardrails.derived_fact_synthesis",
      true,
    );
    const list = listBrainSettings({ vault: env.vault });
    expect(list.mode).toBe("store");
    expect(list.settings.map((s) => [s.name, s.value, s.authority])).toEqual([
      ["guardrails.derived_fact_synthesis", true, "agent"],
      ["primary_agent", "claude", "human"],
    ]);
  });
});

describe("unswitched machine", () => {
  test("set edits _brain.yaml in place and writes no settings record", () => {
    env = makeStoreEnv("osb-setw-legacy-");
    const path = brainConfigPath(env.vault);
    const before = readFileSync(path, "utf8");
    const result = setBrainSetting(
      { vault: env.vault, authority: "human", agent: "t" },
      "dream.candidate_threshold",
      11,
    );
    expect(result).toMatchObject({ mode: "legacy", changed: true, value: 11 });
    expect(result.record).toBeUndefined();
    const after = readFileSync(path, "utf8");
    expect(after).not.toBe(before);
    expect(after).toContain("candidate_threshold: 11");
    // Every other line is kept, comments included.
    expect(after.split("\n").length).toBe(before.split("\n").length);
    expect(loadBrainConfig(env.vault).dream.candidate_threshold).toBe(11);
    expect(settingRecords(env)).toHaveLength(0);
  });

  test("a list value and a new field are written in the file's layout", () => {
    env = makeStoreEnv("osb-setw-legacy-list-");
    const ctx = { vault: env.vault, authority: "human" as const, agent: "t" };
    setBrainSetting(ctx, "notes.read_paths", ["Projects/", "Areas/x y"]);
    expect(loadBrainConfig(env.vault).notes?.read_paths).toEqual(["Projects/", "Areas/x y"]);
    setBrainSetting(ctx, "notes.read_paths", ["Only/"]);
    expect(loadBrainConfig(env.vault).notes?.read_paths).toEqual(["Only/"]);
    expect(getBrainSetting({ vault: env.vault }, "notes.read_paths")).toMatchObject({
      set: true,
      value: ["Only/"],
      source: "brain-yaml",
    });
  });

  test("unset removes the field and the default comes back", () => {
    env = makeStoreEnv("osb-setw-legacy-unset-");
    const ctx = { vault: env.vault, authority: "human" as const, agent: "t" };
    setBrainSetting(ctx, "primary_agent", "claude");
    expect(loadBrainConfig(env.vault).primary_agent).toBe("claude");
    expect(unsetBrainSetting(ctx, "primary_agent").changed).toBe(true);
    expect(loadBrainConfig(env.vault).primary_agent).toBeNull();
    setBrainSetting(ctx, "dream.candidate_threshold", 12);
    unsetBrainSetting(ctx, "dream.candidate_threshold");
    expect(loadBrainConfig(env.vault).dream.candidate_threshold).toBe(
      DEFAULT_BRAIN_CONFIG.dream.candidate_threshold,
    );
  });

  test("an invalid value leaves the file untouched", () => {
    env = makeStoreEnv("osb-setw-legacy-bad-");
    const path = brainConfigPath(env.vault);
    const before = readFileSync(path, "utf8");
    const err = errorOf(() =>
      setBrainSetting(
        { vault: env!.vault, authority: "human", agent: "t" },
        "dream.candidate_threshold",
        -3,
      ),
    );
    expect(err.code).toBe("invalid_setting_value");
    expect(readFileSync(path, "utf8")).toBe(before);
  });

  test("a vault without _brain.yaml is told to run brain init", () => {
    env = makeStoreEnv("osb-setw-legacy-nofile-");
    rmSync(brainConfigPath(env.vault));
    const err = errorOf(() =>
      setBrainSetting({ vault: env!.vault, authority: "human", agent: "t" }, "primary_agent", "x"),
    );
    expect(err.code).toBe("no_settings_file");
  });
});

describe("key classification and value validation (both modes)", () => {
  for (const mode of ["store", "legacy"] as const) {
    const make = (): StoreEnv =>
      mode === "store" ? switched(`osb-setw-cls-${mode}-`) : makeStoreEnv(`osb-setw-cls-${mode}-`);

    test(`${mode}: a device key answers with the machine-config key to set`, () => {
      env = make();
      const err = errorOf(() =>
        setBrainSetting(
          { vault: env!.vault, authority: "human", agent: "t" },
          "snapshots.retention_count",
          3,
        ),
      );
      expect(err.code).toBe("device_setting");
      expect(err.configKey).toBe("brain_snapshots_retention_count");
      expect(err.message).toContain("brain_snapshots_retention_count: 3");
      const field = errorOf(() =>
        setBrainSetting(
          { vault: env!.vault, authority: "human", agent: "t" },
          "decision_model.provider",
          "x",
        ),
      );
      expect(field.code).toBe("device_setting");
      expect(field.configKey).toBe("brain_decision_model_provider");
    });

    test(`${mode}: unknown keys, schema_version and a whole block are refused`, () => {
      env = make();
      const ctx = { vault: env.vault, authority: "human" as const, agent: "t" };
      expect(errorOf(() => setBrainSetting(ctx, "nope.field", 1)).code).toBe("unknown_setting");
      expect(errorOf(() => setBrainSetting(ctx, "dream.no_such_field", 1)).code).toBe(
        "unknown_setting",
      );
      expect(errorOf(() => setBrainSetting(ctx, "schema_version", 2)).code).toBe("not_a_setting");
      expect(errorOf(() => setBrainSetting(ctx, "dream", 1)).code).toBe("field_required");
    });

    test(`${mode}: a value the validator rejects is refused`, () => {
      env = make();
      const ctx = { vault: env.vault, authority: "human" as const, agent: "t" };
      expect(errorOf(() => setBrainSetting(ctx, "dream.candidate_threshold", "many")).code).toBe(
        "invalid_setting_value",
      );
      expect(errorOf(() => setBrainSetting(ctx, "notes.read_paths", { a: 1 })).code).toBe(
        "invalid_setting_value",
      );
    });
  }

  test("the brain. prefix is accepted and dropped", () => {
    env = switched("osb-setw-prefix-");
    const r = setBrainSetting(
      { vault: env.vault, authority: "human", agent: "t" },
      "brain.dream.candidate_threshold",
      5,
    );
    expect(r.name).toBe("dream.candidate_threshold");
  });
});

describe("parseSettingValue", () => {
  test("JSON first, else the bare string", () => {
    expect(parseSettingValue("5")).toBe(5);
    expect(parseSettingValue("true")).toBe(true);
    expect(parseSettingValue('["a","b"]')).toEqual(["a", "b"]);
    expect(parseSettingValue('"5"')).toBe("5");
    expect(parseSettingValue("claude")).toBe("claude");
  });
});