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
19.8 KB
Raw Blame
/**
 * Atomic-fact decomposition (t_cbd22536): deterministic, LLM-free
 * splitting of session/turn text into discrete single-sentence
 * assertions using markdown structure (heading context, list items,
 * sentence boundaries with an abbreviation guard), anchored to
 * canonical entities. Precision discipline mirrors fact-extract:
 * code, quotes, and frontmatter never produce assertions.
 */

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

import {
  anchorEntityForms,
  decomposeAtomicFacts,
  MAX_ASSERTION_CHARS,
  type AtomicEntityLike,
} from "../../../src/core/brain/atomic-facts.ts";
import { bootstrapBrain } from "../../../src/core/brain/init.ts";
import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";
import { writeFrontmatterAtomic } from "../../../src/core/vault.ts";
import { brainDirs } from "../../../src/core/brain/paths.ts";
import { assertValidEntityLabel } from "../../../src/core/brain/entities/canonical.ts";
import { buildEntityIndex } from "../../../src/core/brain/entities/index-builder.ts";
import {
  __clearEntityLexiconCache,
  deriveEntityLexicon,
  resolveEntityLexicon,
  writeEntityLexicon,
} from "../../../src/core/brain/entities/lexicon.ts";
import { buildAnchorables } from "../../../src/core/brain/fact-extract.ts";
import { diarize } from "../../../src/core/brain/diarization.ts";
import { appendStatedClaims } from "../../../src/core/brain/truth/stated-claims.ts";
import { withDeviceId } from "../../helpers/device-id.ts";

const ENTITIES: ReadonlyArray<AtomicEntityLike> = [
  { id: "ent-people-alice-mason", name: "Alice Mason", aliases: ["Alice"], status: "active" },
  { id: "ent-project-atlas", name: "Atlas", aliases: [], status: "active" },
];

describe("decomposeAtomicFacts", () => {
  test("empty and whitespace input decompose to nothing", () => {
    expect(decomposeAtomicFacts("")).toEqual([]);
    expect(decomposeAtomicFacts("   \n\n  ")).toEqual([]);
  });

  test("list items become individual assertions under their heading path", () => {
    const text = [
      "# Standup",
      "",
      "## Decisions",
      "",
      "- Alice Mason approves the deploy window for Atlas",
      "- The rollback plan stays unchanged for this release",
    ].join("\n");
    const out = decomposeAtomicFacts(text, { entities: ENTITIES });
    expect(out).toHaveLength(2);
    expect(out[0]!.text).toBe("Alice Mason approves the deploy window for Atlas");
    expect(out[0]!.headingPath).toEqual(["Standup", "Decisions"]);
    expect(out[0]!.kind).toBe("list_item");
    expect(out[0]!.entities).toEqual(["ent-people-alice-mason", "ent-project-atlas"]);
    expect(out[1]!.entities).toEqual([]);
  });

  test("prose paragraphs split into sentences", () => {
    const text =
      "The deploy window moved to Friday evening. Alice signed off on the change. " +
      "Nothing else in the runbook changed.";
    const out = decomposeAtomicFacts(text, { entities: ENTITIES });
    expect(out.map((a) => a.text)).toEqual([
      "The deploy window moved to Friday evening.",
      "Alice signed off on the change.",
      "Nothing else in the runbook changed.",
    ]);
    expect(out[1]!.entities).toEqual(["ent-people-alice-mason"]);
    expect(out[0]!.kind).toBe("sentence");
  });

  test("abbreviations and version numbers never split sentences", () => {
    const text =
      "The fix shipped in v0.42.0 e.g. the activation store now sweeps correctly. " +
      "Costs dropped to 3.5 USD per month.";
    const out = decomposeAtomicFacts(text);
    expect(out).toHaveLength(2);
    expect(out[0]!.text).toContain("e.g. the activation store");
    expect(out[1]!.text).toBe("Costs dropped to 3.5 USD per month.");
  });

  test("code blocks, inline code, quotes, and frontmatter are never assertions", () => {
    const text = [
      "---",
      "kind: note",
      "---",
      "",
      "> Quoted claim that must not extract.",
      "",
      "```",
      "Alice Mason inside a code fence.",
      "```",
      "",
      "Real statement about the `deploy` script behavior here.",
    ].join("\n");
    const out = decomposeAtomicFacts(text, { entities: ENTITIES });
    expect(out).toHaveLength(1);
    expect(out[0]!.text).toBe("Real statement about the script behavior here.");
    expect(out[0]!.entities).toEqual([]);
  });

  test("tiny fragments are dropped", () => {
    const out = decomposeAtomicFacts("Ok. Yes. The migration window opens on Monday morning.");
    expect(out).toHaveLength(1);
    expect(out[0]!.text).toBe("The migration window opens on Monday morning.");
  });

  test("line numbers point into the original input", () => {
    const text = [
      "# H",
      "",
      "First sentence lives here today.",
      "",
      "- A list item assertion",
    ].join("\n");
    const out = decomposeAtomicFacts(text);
    expect(out[0]!.line).toBe(3);
    expect(out[1]!.line).toBe(5);
  });

  test("assertions are capped in length", () => {
    const long = `The plan ${"very ".repeat(120)}long sentence about the rollout.`;
    const out = decomposeAtomicFacts(long);
    expect(out[0]!.text.length).toBeLessThanOrEqual(MAX_ASSERTION_CHARS);
  });

  test("deterministic: same input, deeply equal output", () => {
    const text = "# T\n\n- Alpha decided beta yesterday evening\n\nGamma follows delta now.";
    expect(decomposeAtomicFacts(text, { entities: ENTITIES })).toEqual(
      decomposeAtomicFacts(text, { entities: ENTITIES }),
    );
  });

  test("heading path resets correctly across sibling sections", () => {
    const text = [
      "# Root",
      "## A",
      "Statement under section A goes here.",
      "## B",
      "Statement under section B goes here.",
    ].join("\n");
    const out = decomposeAtomicFacts(text);
    expect(out[0]!.headingPath).toEqual(["Root", "A"]);
    expect(out[1]!.headingPath).toEqual(["Root", "B"]);
  });

  test("archived entities never anchor", () => {
    const out = decomposeAtomicFacts("Alice Mason approved the change for the team.", {
      entities: [{ ...ENTITIES[0]!, status: "archived" }],
    });
    expect(out[0]!.entities).toEqual([]);
  });
});

/**
 * Recall-quality A2: the store-learned lexicon gates the anchoring forms
 * the same way it gates creation. The only vocabulary in play is what a
 * corpus page teaches the artifact - nothing is hardcoded.
 */
describe("lexicon-gated anchoring (recall-quality A2)", () => {
  let vault: string;
  let configHome: string;
  const NOW = new Date("2026-10-11T12:00:00Z");

  beforeEach(() => {
    vault = mkdtempSync(join(tmpdir(), "o2b-atomic-lexicon-"));
    configHome = mkdtempSync(join(tmpdir(), "o2b-atomic-lexicon-cfg-"));
    const configPath = join(configHome, "config.yaml");
    atomicWriteFileSync(configPath, `vault: ${vault}\n`);
    bootstrapBrain(vault, { configPath });
  });

  afterEach(() => {
    rmSync(vault, { recursive: true, force: true });
    rmSync(configHome, { recursive: true, force: true });
    __clearEntityLexiconCache();
  });

  /** Write an entity node by hand, bypassing the creation gate. */
  function seedEntityNode(id: string, name: string, aliases: string[]): void {
    const dir = join(brainDirs(vault).entities, "people");
    mkdirSync(dir, { recursive: true });
    writeFrontmatterAtomic(
      join(dir, `${id}.md`),
      {
        kind: "brain-entity",
        entity_id: id,
        category: "people",
        name,
        ...(aliases.length > 0 ? { aliases } : {}),
        status: "active",
        created_at: "2026-10-11T00:00:00Z",
        updated_at: "2026-10-11T00:00:00Z",
        tags: ["brain", "brain/entity"],
      },
      `# ${name}`,
      { overwrite: true },
    );
  }

  /** Teach the lexicon from one corpus page and rebuild the artifact. */
  function seedLexicon(corpus: string): void {
    atomicWriteFileSync(join(vault, "corpus-page.md"), `${corpus}\n`);
    writeEntityLexicon(vault, deriveEntityLexicon(vault, { now: NOW }));
  }

  /** A stored junk-run name with a valid alias, plus the taught artifact. */
  function seedJunkEntityWithValidAlias(): void {
    // The junk name is CASEFUL ("The Of And"): the pinned predicate runs
    // the case-based verdicts for caseful labels only, and an
    // all-lowercase label admits on the structural gate alone. Its
    // normalised form is still "the of and", so the matchable text is
    // unchanged.
    seedEntityNode("ent-people-junk", "The Of And", ["Atlas Prime"]);
    // "Of" appears capitalised once, which makes the corpus caseful while
    // keeping every taught token lowercase-dominant (a learned common word).
    seedLexicon("the of and the Of and.");
  }

  test("anchorEntityForms skips a lexicon-rejected junk form; opt-in only", () => {
    seedJunkEntityWithValidAlias();
    const handle = resolveEntityLexicon(vault);
    expect(handle).not.toBeNull();
    const forms = ["The Of And", "Atlas Prime"];
    const text = "Atlas Prime and the of and were recorded today.";
    expect(anchorEntityForms(text, forms, { lexicon: handle })).toEqual(["atlas prime"]);
    // Without a handle the gate is byte-identical to the pre-lexicon form.
    expect(anchorEntityForms(text, forms)).toEqual(["the of and", "atlas prime"]);
  });

  test("decomposeAtomicFacts anchors junk-named entities only on valid aliases", () => {
    seedJunkEntityWithValidAlias();
    seedEntityNode("ent-people-ada", "Ada", []);
    const entities: ReadonlyArray<AtomicEntityLike> = buildEntityIndex(vault).entities.map((e) => ({
      id: e.id,
      name: e.name,
      aliases: e.aliases,
      status: e.status,
    }));
    const handle = resolveEntityLexicon(vault);
    const out = decomposeAtomicFacts("Atlas Prime met Ada and the of and were recorded today.", {
      entities,
      lexicon: handle,
    });
    const anchored = out.find((a) => a.entities.includes("ent-people-junk"));
    expect(anchored).toBeDefined(); // the valid alias still anchors the node
    expect(anchored!.entities).toContain("ent-people-ada");
    // The junk form alone never anchors its node.
    const junkOnly = decomposeAtomicFacts("the of and were recorded today.", {
      entities,
      lexicon: handle,
    });
    expect(junkOnly.every((a) => !a.entities.includes("ent-people-junk"))).toBe(true);
  });

  test("buildAnchorables keeps the alias forms and drops the junk name form", () => {
    seedJunkEntityWithValidAlias();
    const anchorables = buildAnchorables(vault, buildEntityIndex(vault), "test-agent", NOW);
    expect(anchorables).toHaveLength(1);
    expect(anchorables[0]!.id).toBe("ent-people-junk");
    // The surviving alias form, expanded once into its match variants
    // (note-change truth maintenance, F3; grid reduced per M2): the
    // canonical space join is the ONE variant the class answers to, the
    // haystack folds through the same join.
    expect(anchorables[0]!.forms).toEqual(["atlas prime"]);
  });
});

/**
 * Separator-tolerant anchoring (note-change truth maintenance, F3): the
 * occurrence kernel matches separator-variant match forms with BOTH sides
 * folded - runs of space, hyphen and underscore are interchangeable, a
 * slug-prefixed form also matches at a path-segment boundary, and a
 * word-boundary rule keeps the fold from planting mid-word hits literal
 * matching did not already have.
 */
describe("anchorEntityForms - separator-tolerant matching (F3)", () => {
  test("spaced text anchors a hyphenated form", () => {
    expect(anchorEntityForms("Ada Lovelace wrote the first notes.", ["ada-lovelace"])).toEqual([
      "ada-lovelace",
    ]);
  });

  test("spaced text anchors an underscored form", () => {
    expect(anchorEntityForms("Ada Lovelace wrote the first notes.", ["ada_lovelace"])).toEqual([
      "ada_lovelace",
    ]);
  });

  test("spaced text anchors a slug-prefixed form at the path-segment boundary", () => {
    expect(
      anchorEntityForms("Ada Lovelace wrote the first notes.", ["people/ada_lovelace"]),
    ).toEqual(["people/ada_lovelace"]);
  });

  test("hyphenated text anchors a spaced form (the haystack folds too)", () => {
    expect(anchorEntityForms("The ada-lovelace memoir survived.", ["Ada Lovelace"])).toEqual([
      "ada lovelace",
    ]);
  });

  test("underscored text anchors a hyphenated form", () => {
    expect(anchorEntityForms("the ada_lovelace memoir", ["ada-lovelace"])).toEqual([
      "ada-lovelace",
    ]);
  });

  test("a mid-word occurrence never anchors, literal or folded", () => {
    expect(anchorEntityForms("Canada borders three oceans.", ["Ada"])).toEqual([]);
    expect(anchorEntityForms("canada lovelace ruled the charts.", ["ada lovelace"])).toEqual([]);
  });

  test("forms shorter than the minimum never participate, folded or not", () => {
    expect(anchorEntityForms("ada-lovelace wrote.", ["lo"])).toEqual([]);
  });

  test("a boundary-occurring short form is refused by the length gate itself", () => {
    // "lo" sits at a word boundary here, so the word-boundary rule would
    // admit it - only MIN_ANCHOR_FORM_LENGTH refuses it. (The mid-word pin
    // above cannot see the gate: the boundary guard refuses that shape
    // with or without the floor.)
    expect(anchorEntityForms("the lo fixture ran its course.", ["lo"])).toEqual([]);
  });

  test("a mixed separator run in the text anchors (the haystack folds, not just the needle)", () => {
    // No variant of the needle occurs literally in the raw text - only the
    // haystack's own expansion turns "ada -_ lovelace" into a spellings the
    // needle's variant class answers to.
    expect(anchorEntityForms("the memoir of ada -_ lovelace survived.", ["ada-lovelace"])).toEqual([
      "ada-lovelace",
    ]);
  });

  test("a standalone slug tail below the minimum never anchors", () => {
    // The tail "dc" of "ac/dc" is shorter than the floor, so the entity's
    // only emitted variant is the full form - a standalone "dc" in a text
    // never anchors the band.
    expect(anchorEntityForms("dc opened for the headliners tonight.", ["AC/DC"])).toEqual([]);
  });

  test("a full slug form still anchors at its own boundaries", () => {
    expect(anchorEntityForms("the TCP/IP runbook lives in the wiki.", ["TCP/IP"])).toEqual([
      "tcp/ip",
    ]);
  });

  test("CJK text anchors a CJK form (no-space scripts need no word boundary)", () => {
    // "田中太郎は" has a kana letter touching the name directly; a script
    // written without word spaces never reads as a mid-word hit.
    expect(anchorEntityForms("田中太郎は会議に出席した。", ["田中太郎"])).toEqual(["田中太郎"]);
  });

  test("an inflected mention anchors the base form (the boundary binds the leading side only)", () => {
    // H1 (PR 268 review): Russian and German attach endings to names with
    // no space, and the two-sided boundary rule refused every inflected
    // spelling the literal `includes` matching used to anchor. Only the
    // character before the hit must be a token edge.
    expect(anchorEntityForms("Ивана повысили до директора.", ["Иван"])).toEqual(["иван"]);
    expect(anchorEntityForms("Встреча с Иваном перенесена.", ["Иван"])).toEqual(["иван"]);
    expect(anchorEntityForms("Annas Buch liegt auf dem Tisch.", ["Anna"])).toEqual(["anna"]);
  });

  test("an attached Korean particle does not block the anchor", () => {
    // 조사 attach to a noun with no space: "김철수는" is the name plus the
    // topic particle, not a longer word.
    expect(anchorEntityForms("김철수는 회의에 출석했다.", ["김철수"])).toEqual(["김철수"]);
  });
});

/**
 * Recall-quality M6: the store-learned lexicon reaches the SECOND
 * anchoring path too. The vault-aware callers (the decomposer verb, the
 * diarizer, the agent-stated claim verdicts) resolve the same handle
 * through `resolveEntityLexicon` and thread it into the shared kernel,
 * so no path anchors a form the creation gate refuses. With no artifact
 * every verdict stays byte-identical to the pre-lexicon behavior.
 */
describe("lexicon reaches the second anchoring paths (recall-quality M6)", () => {
  let vault: string;
  let configHome: string;
  const NOW = new Date("2026-10-11T12:00:00Z");

  beforeEach(() => {
    vault = mkdtempSync(join(tmpdir(), "o2b-atomic-m6-"));
    configHome = mkdtempSync(join(tmpdir(), "o2b-atomic-m6-cfg-"));
    const configPath = join(configHome, "config.yaml");
    atomicWriteFileSync(configPath, `vault: ${vault}\n`);
    bootstrapBrain(vault, { configPath });
  });

  afterEach(() => {
    rmSync(vault, { recursive: true, force: true });
    rmSync(configHome, { recursive: true, force: true });
    __clearEntityLexiconCache();
  });

  /**
   * Seed a stored junk SINGLE-TOKEN label ("Meeting": caseful, one
   * common word is already a run) by hand, bypassing the creation gate.
   */
  function seedMeetingEntity(): void {
    const dir = join(brainDirs(vault).entities, "people");
    mkdirSync(dir, { recursive: true });
    writeFrontmatterAtomic(
      join(dir, "ent-people-meeting.md"),
      {
        kind: "brain-entity",
        entity_id: "ent-people-meeting",
        category: "people",
        name: "Meeting",
        status: "active",
        created_at: "2026-10-11T00:00:00Z",
        updated_at: "2026-10-11T00:00:00Z",
        tags: ["brain", "brain/entity"],
      },
      "Meeting happens every Friday morning and reviews the week.",
      { overwrite: true },
    );
  }

  /** Teach the artifact that "meeting" is a common word; "Ada" makes the corpus caseful. */
  function seedMeetingLexicon(): void {
    atomicWriteFileSync(
      join(vault, "corpus-page.md"),
      "Ada said the meeting ran long. The meeting notes list every meeting.\n",
    );
    writeEntityLexicon(vault, deriveEntityLexicon(vault, { now: NOW }));
  }

  const STATED_PAYLOAD = {
    claims: [{ subject: "Meeting", relation: "extends", object: "Planning" }],
    text: "Meeting covers the planning agenda for the week.",
    agent: "test-agent",
    ts: "2026-10-11T12:00:00Z",
    source: "[[Brain/notes/standup.md]]",
  } as const;

  test("diarize drops the stated claim a junk label alone anchors, behind the resolved handle", () => {
    seedMeetingEntity();
    seedMeetingLexicon();
    const handle = resolveEntityLexicon(vault);
    expect(handle).not.toBeNull();
    // The resolved handle refuses the label exactly like the creation gate...
    expect(() => assertValidEntityLabel("Meeting", { lexicon: handle })).toThrow(
      /function-word-run/,
    );
    // ...so the diarization path skips the junk-form anchor as well.
    const report = diarize(vault, { query: "Meeting" }, { now: NOW, ownerScope: null });
    expect(report.statedVsEvidenced).toEqual([]);
  });

  test("diarize without an artifact keeps the pre-lexicon verdict byte-identical", () => {
    seedMeetingEntity();
    expect(resolveEntityLexicon(vault)).toBeNull();
    const report = diarize(vault, { query: "Meeting" }, { now: NOW, ownerScope: null });
    expect(report.statedVsEvidenced).toHaveLength(1);
    expect(report.statedVsEvidenced[0]!.kind).toBe("stated_unevidenced");
  });

  test("appendStatedClaims reports a junk-labeled subject unanchored, behind the resolved handle", () => {
    seedMeetingLexicon();
    const handle = resolveEntityLexicon(vault);
    expect(handle).not.toBeNull();
    const outcome = withDeviceId("", () => appendStatedClaims(vault, STATED_PAYLOAD));
    expect(outcome.committed).toEqual([]);
    expect(outcome.ungrounded).toHaveLength(1);
    expect(outcome.ungrounded[0]!.claim.subject).toBe("Meeting");
    expect(outcome.ungrounded[0]!.reasons).toEqual(["subject_unanchored"]);
  });

  test("appendStatedClaims without an artifact commits the same claim byte-identically", () => {
    expect(resolveEntityLexicon(vault)).toBeNull();
    const outcome = withDeviceId("", () => appendStatedClaims(vault, STATED_PAYLOAD));
    expect(outcome.ungrounded).toEqual([]);
    expect(outcome.committed).toHaveLength(1);
    expect(outcome.committed[0]!.event.entity).toBe("meeting");
  });
});