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
17.8 KB
Raw Blame
/**
 * The fold engine and the concrete folds: duplicate delivery, fold order,
 * authority precedence, tombstones, kept history, derived counters and
 * the spec scenarios of the brain store.
 */
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { cpSync, mkdirSync } from "node:fs";
import { join } from "node:path";

import { appendRecord } from "../../../src/core/store/appender.ts";
import { prepareRecords } from "../../../src/core/store/fold.ts";
import { foldPinned } from "../../../src/core/store/fold-pinned.ts";
import {
  foldPreferences,
  preferencesFingerprint,
} from "../../../src/core/store/fold-preferences.ts";
import { canonicalJson } from "../../../src/core/integrity/digest.ts";
import { foldSettings, settingValue } from "../../../src/core/store/fold-settings.ts";
import { readShard } from "../../../src/core/store/reader.ts";
import { listShards } from "../../../src/core/store/shard-list.ts";
import { partitionDir } from "../../../src/core/store/store-paths.ts";
import { authored, rec } from "./fixtures/fold-records.ts";
import { makeTempStore, type TempStore } from "./fixtures/temp-store.ts";

const T = Date.UTC(2026, 10, 6, 12, 0, 0);

const prefSet = (
  device: string,
  physical: number,
  authority: "human" | "agent" | "model",
  fields: Record<string, unknown>,
  preference = "p1",
) =>
  rec({
    device,
    physical,
    kind: "preference-set",
    body: authored(authority, { preference, fields }),
  });

const fingerprint = (fold: ReturnType<typeof foldPreferences>): string =>
  canonicalJson(preferencesFingerprint(fold));

/** The folded topic-creation threshold of the settings shards in a partition. */
const threshold = (partitionRoot: string): unknown =>
  settingValue(
    foldSettings(
      listShards(partitionRoot, { stream: "settings" }).flatMap((shard) =>
        readShard(shard.path).records.map((r) => r.record),
      ),
    ),
    "topics.new_min_records",
  );

describe("prepareRecords", () => {
  test("applies a record delivered twice once, in fold order", () => {
    const a = rec({ device: "dev-b", physical: T + 2, kind: "x", body: {} });
    const b = rec({ device: "dev-a", physical: T + 2, kind: "x", body: {} });
    const c = rec({ device: "dev-c", physical: T + 1, kind: "x", body: {} });
    const prepared = prepareRecords([a, b, a, c, b]);
    expect(prepared.records.map((r) => r.id)).toEqual([c.id, b.id, a.id]);
    expect(prepared.duplicates).toBe(2);
    expect(prepared.conflicts).toEqual([]);
  });

  test("keeps the same version of a conflicting id in any delivery order", () => {
    const first = rec({ physical: T, kind: "x", body: { n: 1 } });
    const second = { ...rec({ physical: T, kind: "x", body: { n: 2 } }), id: first.id };
    const one = prepareRecords([first, second]);
    const two = prepareRecords([second, first]);
    expect(one.records).toEqual(two.records);
    expect(one.conflicts).toEqual([{ id: first.id, versions: 2 }]);
  });

  test("a delivery that conflicts is a conflict, not also a duplicate", () => {
    const original = rec({ device: "dev-a", physical: T, kind: "x", body: { v: 1 } });
    const altered = { ...original, body: { v: 2 } };
    const prepared = prepareRecords([original, altered, original, altered]);
    expect(prepared.conflicts).toEqual([{ id: original.id, versions: 2 }]);
    // The third and fourth deliveries repeat a version already seen.
    expect(prepared.duplicates).toBe(2);
    expect(prepareRecords([original, altered]).duplicates).toBe(0);
  });

  test("holds out a record whose body is a pending blob", () => {
    const inline = rec({ physical: T, kind: "x", body: {} });
    const pending = {
      ...inline,
      id: rec({ physical: T + 1, kind: "x", body: {} }).id,
      body: { $blob: inline.sum, bytes: 2 },
    };
    const prepared = prepareRecords([inline, pending]);
    expect(prepared.records.map((r) => r.id)).toEqual([inline.id]);
    expect(prepared.pending.map((r) => r.id)).toEqual([pending.id]);
  });
});

describe("authority precedence", () => {
  test("a human record beats a later agent record, which beats a later model record", () => {
    const human = prefSet("dev-a", T, "human", { principle: "human" });
    const agent = prefSet("dev-b", T + 10, "agent", { principle: "agent", scope: "coding" });
    const model = prefSet("dev-c", T + 20, "model", { principle: "model", scope: "model" });
    const state = foldPreferences([model, agent, human]).preferences.get("p1")!;
    expect(state.fields).toEqual({ principle: "human", scope: "coding" });
    expect(state.fieldWinners).toEqual({ principle: human.id, scope: agent.id });
  });

  test("within one authority the later clock wins, the device breaking a clock tie", () => {
    const early = prefSet("dev-z", T, "agent", { principle: "early" });
    const tieLow = prefSet("dev-a", T + 5, "agent", { principle: "tie-a" });
    const tieHigh = prefSet("dev-b", T + 5, "agent", { principle: "tie-b" });
    for (const order of [
      [early, tieLow, tieHigh],
      [tieHigh, early, tieLow],
    ]) {
      expect(foldPreferences(order).preferences.get("p1")!.fields["principle"]).toBe("tie-b");
    }
  });

  test("a record without an authority is rejected, never guessed from the agent name", () => {
    const bad = rec({
      physical: T,
      agent: "human",
      kind: "preference-set",
      body: { preference: "p1", fields: { principle: "x" } },
    });
    const fold = foldPreferences([bad]);
    expect(fold.preferences.size).toBe(0);
    expect(fold.rejected).toEqual([
      { id: bad.id, kind: "preference-set", reason: "missing or invalid authority" },
    ]);
  });
});

describe("preference fold", () => {
  test("a human retire beats later agent evidence and a later agent re-confirm (spec scenario)", () => {
    const created = prefSet("dev-a", T, "agent", { principle: "use tabs", status: "confirmed" });
    const retire = prefSet("dev-a", T + 100, "human", {
      status: "retired",
      retired_reason: "user-rejected",
    });
    const evidence = rec({
      device: "dev-b",
      physical: T + 200,
      kind: "preference-evidence",
      body: { preference: "p1", result: "applied", artifact: "[[x]]" },
    });
    const reconfirm = prefSet("dev-b", T + 300, "agent", { status: "confirmed" });
    const state = foldPreferences([reconfirm, evidence, retire, created]).preferences.get("p1")!;
    expect(state.fields["status"]).toBe("retired");
    expect(state.counters.applied_count).toBe(1);
    expect(state.history.map((r) => r.id)).toEqual([
      created.id,
      retire.id,
      evidence.id,
      reconfirm.id,
    ]);
  });

  test("counters come from evidence only and are never written back", () => {
    const set = prefSet("dev-a", T, "human", {
      principle: "p",
      applied_count: 99,
      violated_count: 7,
    });
    const evidence = ["applied", "violated", "applied", "outdated"].map((result, i) =>
      rec({
        device: "dev-b",
        physical: T + i + 1,
        kind: "preference-evidence",
        body: { preference: "p1", result },
      }),
    );
    const state = foldPreferences([set, ...evidence, evidence[0]!]).preferences.get("p1")!;
    expect(state.counters).toEqual({ applied_count: 2, violated_count: 1, outdated_count: 1 });
    expect(state.fields).toEqual({ principle: "p" });
  });

  test("a removal is a tombstone that keeps the records and drops the content from the fold", () => {
    const set = prefSet("dev-a", T, "agent", { principle: "p" });
    const remove = rec({
      physical: T + 1,
      kind: "preference-remove",
      body: authored("agent", { preference: "p1" }),
    });
    const state = foldPreferences([remove, set]).preferences.get("p1")!;
    expect(state).toMatchObject({
      exists: false,
      removed: true,
      // A forgotten preference shows its content nowhere (FORMAT.md, Removal).
      fields: {},
      existenceWinner: remove.id,
    });
    expect(state.history.map((r) => r.id)).toEqual([set.id, remove.id]);
    const revived = prefSet("dev-a", T + 2, "agent", { principle: "q" });
    expect(foldPreferences([set, remove, revived]).preferences.get("p1")).toMatchObject({
      exists: true,
      removed: false,
    });
  });

  test("a preference re-created after its removal carries none of the forgotten fields", () => {
    const set = prefSet("dev-a", T, "agent", {
      principle: "p",
      scope: "secret scope",
      text: "old prose",
    });
    const remove = rec({
      physical: T + 1,
      kind: "preference-remove",
      body: authored("agent", { preference: "p1" }),
    });
    const again = prefSet("dev-a", T + 2, "agent", { principle: "q" });
    const state = foldPreferences([set, remove, again]).preferences.get("p1")!;
    expect(state.exists).toBe(true);
    expect(state.fields).toEqual({ principle: "q" });
    // A removal that lost to a human set keeps every field of the human's.
    const human = prefSet("dev-a", T, "human", { principle: "p", scope: "s" });
    expect(foldPreferences([human, remove]).preferences.get("p1")!.fields).toEqual({
      principle: "p",
      scope: "s",
    });
  });

  test("a later tombstone that lost the existence register does not bring back forgotten fields", () => {
    // agent set A -> human remove R1 -> human set S -> agent remove R2: S
    // wins existence (human outranks agent), so the cut is R1, not R2.
    const first = prefSet("dev-a", T, "agent", { principle: "p", scope: "work" });
    const forget = rec({
      physical: T + 1,
      kind: "preference-remove",
      body: authored("human", { preference: "p1" }),
    });
    const again = prefSet("dev-a", T + 2, "human", { principle: "q" });
    const losing = rec({
      physical: T + 3,
      kind: "preference-remove",
      body: authored("agent", { preference: "p1" }),
    });
    const state = foldPreferences([first, forget, again, losing]).preferences.get("p1")!;
    expect(state.exists).toBe(true);
    expect(state.fields).toEqual({ principle: "q" });
  });

  test("an agent removal does not remove a preference a human set", () => {
    const human = prefSet("dev-a", T, "human", { principle: "p" });
    const remove = rec({
      physical: T + 1,
      kind: "preference-remove",
      body: authored("agent", { preference: "p1" }),
    });
    expect(foldPreferences([human, remove]).preferences.get("p1")).toMatchObject({
      exists: true,
      removed: false,
    });
  });

  test("evidence alone does not make a preference exist", () => {
    const evidence = rec({
      physical: T,
      kind: "preference-evidence",
      body: { preference: "p9", result: "violated" },
    });
    expect(foldPreferences([evidence]).preferences.get("p9")).toMatchObject({
      exists: false,
      removed: false,
      existenceWinner: null,
      counters: { violated_count: 1 },
    });
  });

  test("a set that names only derived counters is rejected and cannot undo a removal", () => {
    const set = prefSet("dev-a", T, "agent", { status: "confirmed" });
    const remove = rec({
      device: "dev-a",
      physical: T + 1,
      kind: "preference-remove",
      body: authored("agent", { preference: "p1" }),
    });
    const countersOnly = prefSet("dev-a", T + 2, "human", { applied_count: 3 });
    const fold = foldPreferences([set, remove, countersOnly]);
    expect(fold.preferences.get("p1")!.exists).toBe(false);
    expect(fold.rejected).toEqual([
      { id: countersOnly.id, kind: "preference-set", reason: "fields name only derived counters" },
    ]);
  });

  test("a preference id that is an Object.prototype key still counts in the fingerprint", () => {
    const plain = foldPreferences([prefSet("dev-a", T, "human", { status: "confirmed" }, "p1")]);
    const withProto = foldPreferences([
      prefSet("dev-a", T, "human", { status: "confirmed" }, "p1"),
      prefSet("dev-a", T + 1, "human", { status: "confirmed" }, "__proto__"),
    ]);
    expect(fingerprint(withProto)).not.toBe(fingerprint(plain));
    expect(fingerprint(withProto)).toContain('"__proto__"');
  });

  test("malformed preference records are rejected", () => {
    const records = [
      rec({
        physical: T,
        kind: "preference-evidence",
        body: { preference: "p1", result: "maybe" },
      }),
      rec({
        physical: T + 1,
        kind: "preference-set",
        body: authored("agent", { preference: "p1", fields: {} }),
      }),
      rec({
        physical: T + 2,
        kind: "preference-set",
        body: authored("agent", { preference: "p1", fields: { "Bad-Name": 1 } }),
      }),
      rec({
        physical: T + 3,
        kind: "preference-remove",
        body: authored("agent", { preference: "" }),
      }),
    ];
    const fold = foldPreferences(records);
    expect(fold.preferences.size).toBe(0);
    expect(fold.rejected.map((r) => r.reason)).toEqual([
      "evidence result must be one of applied, violated, outdated",
      "fields must be a non-empty object",
      'invalid field name "Bad-Name"',
      "missing or invalid preference id",
    ]);
  });
});

describe("pinned context fold", () => {
  test("concurrent replacements: the later clock wins on every machine, the other stays in history (spec scenario)", () => {
    const fromA = rec({
      device: "dev-a",
      physical: T,
      kind: "pinned-set",
      body: authored("agent", { content: "from A" }),
    });
    const fromB = rec({
      device: "dev-b",
      physical: T + 3,
      kind: "pinned-set",
      body: authored("agent", { content: "from B" }),
    });
    const onA = foldPinned([fromA, fromB]);
    const onB = foldPinned([fromB, fromA]);
    expect(onA).toEqual(onB);
    expect(onA.content).toBe("from B");
    expect(onA.history.map((e) => e.value)).toEqual(["from A", "from B"]);
  });

  test("a clear is a tombstone; a later set pins again", () => {
    const set = rec({ physical: T, kind: "pinned-set", body: authored("agent", { content: "x" }) });
    const clear = rec({ physical: T + 1, kind: "pinned-clear", body: authored("agent", {}) });
    expect(foldPinned([set, clear])).toMatchObject({
      content: null,
      cleared: true,
      winner: clear.id,
    });
    const again = rec({
      physical: T + 2,
      kind: "pinned-set",
      body: authored("agent", { content: "y" }),
    });
    expect(foldPinned([again, clear, set])).toMatchObject({ content: "y", cleared: false });
  });

  test("a human pin survives a later agent replacement", () => {
    const human = rec({
      physical: T,
      kind: "pinned-set",
      body: authored("human", { content: "mine" }),
    });
    const agent = rec({
      physical: T + 1,
      kind: "pinned-set",
      body: authored("agent", { content: "agent" }),
    });
    expect(foldPinned([agent, human]).content).toBe("mine");
  });

  test("nothing pinned folds to an empty state", () => {
    expect(foldPinned([])).toEqual({
      content: null,
      cleared: false,
      winner: null,
      history: [],
      rejected: [],
    });
  });
});

describe("settings fold", () => {
  test("defaults apply until a key is set, and again after it is unset", () => {
    const set = rec({
      physical: T,
      kind: "setting-set",
      body: authored("human", { key: "topics.new_min_records", value: 8 }),
    });
    const unset = rec({
      physical: T + 1,
      kind: "setting-unset",
      body: authored("human", { key: "topics.new_min_records" }),
    });
    expect(settingValue(foldSettings([]), "topics.new_min_records")).toBe(5);
    expect(settingValue(foldSettings([set]), "topics.new_min_records")).toBe(8);
    expect(settingValue(foldSettings([unset, set]), "topics.new_min_records")).toBe(5);
    expect(settingValue(foldSettings([]), "topics.new_min_sessions")).toBe(2);
    expect(settingValue(foldSettings([]), "view.language")).toBeNull();
  });

  test("an invalid value for a known key is rejected; an unknown key is kept as written", () => {
    const records = [
      rec({
        physical: T,
        kind: "setting-set",
        body: authored("human", { key: "view.language", value: "ru" }),
      }),
      rec({
        physical: T + 1,
        kind: "setting-set",
        body: authored("human", { key: "view.language", value: "not a tag" }),
      }),
      rec({
        physical: T + 2,
        kind: "setting-set",
        body: authored("agent", { key: "topics.new_min_records", value: 0 }),
      }),
      rec({
        physical: T + 3,
        kind: "setting-set",
        body: authored("agent", { key: "future.knob", value: { a: 1 } }),
      }),
    ];
    const fold = foldSettings(records);
    expect(settingValue(fold, "view.language")).toBe("ru");
    expect(settingValue(fold, "topics.new_min_records")).toBe(5);
    expect(settingValue(fold, "future.knob")).toEqual({ a: 1 });
    expect(fold.rejected.map((r) => r.reason)).toEqual([
      "view.language must be a language tag such as en or pt-BR",
      "topics.new_min_records must be a positive integer",
    ]);
  });
});

describe("a setting changed on one machine applies on another (spec scenario)", () => {
  let tmp: TempStore;
  beforeEach(() => {
    tmp = makeTempStore("osb-store-fold-");
  });
  afterEach(() => tmp.cleanup());

  test("machine B folds machine A's threshold record once it has the shard", () => {
    const a = tmp.open("dev-a");
    // Machine B has its own copy of the shared partition, filled only by sync.
    const bShared = partitionDir(join(tmp.parent, "machine-b"), "shared");
    mkdirSync(bShared, { recursive: true });
    expect(threshold(bShared)).toBe(5);
    appendRecord(
      a,
      {
        partition: "shared",
        stream: "settings",
        kind: "setting-set",
        agent: "cli",
        body: { authority: "human", key: "topics.new_min_records", value: 3 },
      },
      { now: () => T },
    );
    expect(threshold(partitionDir(tmp.root, "shared"))).toBe(3);
    // B still folds the default until the sync tool delivers A's shard.
    expect(threshold(bShared)).toBe(5);
    cpSync(join(partitionDir(tmp.root, "shared"), "settings"), join(bShared, "settings"), {
      recursive: true,
    });
    expect(threshold(bShared)).toBe(3);
  });
});