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
10.1 KB
Raw Blame
/**
 * The conditional `entityFacts` pack section (dated commitments,
 * t_43b0a379): canonical-scope entities anchored from the pack query,
 * each rolling up the ids of candidates the pack already kept whose
 * bodies anchor the entity. Off, every pack is byte-identical - the
 * report member exists only when the caller opted in.
 */

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

import { packContext } from "../../../src/core/brain/context-pack.ts";
import { archiveEntity, upsertEntity } from "../../../src/core/brain/entities/registry.ts";

const NOW = new Date("2026-06-01T00:00:00Z");
const AGENT = "test-agent";

let vault: string;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-pack-entity-facts-"));
  mkdirSync(join(vault, "Brain", "preferences"), { recursive: true });
  mkdirSync(join(vault, "Brain", "retired"), { recursive: true });
});
afterEach(() => {
  rmSync(vault, { recursive: true, force: true });
});

function writePref(slug: string, body: string, createdAt = "2026-05-01T00:00:00Z"): void {
  writeFileSync(
    join(vault, "Brain", "preferences", `pref-${slug}.md`),
    [
      "---",
      `id: pref-${slug}`,
      "topic: project notes",
      `principle: ${slug}`,
      "tier: core",
      `created_at: ${createdAt}`,
      "---",
      "",
      body,
    ].join("\n"),
  );
}

function seedPerson(name: string, aliases: string[] = []): string {
  const { entity } = upsertEntity(vault, {
    category: "people",
    name,
    ...(aliases.length > 0 ? { aliases } : {}),
    agent: AGENT,
    now: NOW,
  });
  return entity.id;
}

describe("packContext entityFacts", () => {
  test("the option absent and false both keep the report byte-identical", () => {
    seedPerson("Ada Lovelace");
    writePref("notes", "Pair with Ada Lovelace on the engine");
    const absent = packContext(vault, { maxTokens: 10_000 });
    const off = packContext(vault, { maxTokens: 10_000, entityFacts: false });
    expect(off.entityFacts).toBeUndefined();
    expect(JSON.stringify(off)).toBe(JSON.stringify(absent));
  });

  test("on, ranked mode: entities anchor from the query and roll up kept item ids", () => {
    seedPerson("Ada Lovelace");
    writePref("notes", "Pair with Ada Lovelace on the engine");
    writePref("other", "An unrelated page about caching");
    const r = packContext(vault, {
      maxTokens: 10_000,
      query: "prepare the meeting with Ada Lovelace",
      queryMode: "ranked",
      entityFacts: true,
    });
    expect(r.entityFacts).toBeDefined();
    expect([...r.entityFacts!.entities]).toEqual([
      {
        entityId: "ent-people-ada-lovelace",
        name: "Ada Lovelace",
        itemIds: ["pref-notes"],
      },
    ]);
  });

  test("an alias anchors the entity too", () => {
    seedPerson("Ada Lovelace", ["the Countess"]);
    writePref("notes", "The Countess reviewed the draft");
    const r = packContext(vault, {
      maxTokens: 10_000,
      query: "ask the Countess for the review notes",
      queryMode: "ranked",
      entityFacts: true,
    });
    expect(r.entityFacts!.entities.map((e) => e.entityId)).toEqual(["ent-people-ada-lovelace"]);
  });

  test("a body anchors the entity through any of its forms, not only the query's", () => {
    seedPerson("Ada Lovelace", ["the Countess"]);
    // The query names the alias; the kept body names the display name. The
    // rollup asks whether the body anchors the ENTITY, so whichever name
    // the query used must not decide the item ids.
    writePref("notes", "Pair with Ada Lovelace on the engine");
    const r = packContext(vault, {
      maxTokens: 10_000,
      query: "ask the Countess for the review notes",
      queryMode: "ranked",
      entityFacts: true,
    });
    expect(r.entityFacts!.entities[0]!.itemIds).toEqual(["pref-notes"]);
  });

  test("substring mode: a query that keeps the candidates anchors the same way", () => {
    seedPerson("Grace Hopper");
    // Substring mode filters candidates on topic + principle, so the page
    // names the entity there too and the same query both keeps and rolls
    // it up.
    writeFileSync(
      join(vault, "Brain", "preferences", "pref-grace.md"),
      [
        "---",
        "id: pref-grace",
        "topic: Grace Hopper compiler notes",
        "principle: compilers",
        "tier: core",
        "created_at: 2026-05-01T00:00:00Z",
        "---",
        "",
        "Grace Hopper preferred the compiler notes",
      ].join("\n"),
    );
    const r = packContext(vault, {
      maxTokens: 10_000,
      query: "Grace Hopper",
      entityFacts: true,
    });
    expect(r.items.map((i) => i.id)).toEqual(["pref-grace"]);
    expect(r.entityFacts!.entities.map((e) => e.entityId)).toEqual(["ent-people-grace-hopper"]);
    expect(r.entityFacts!.entities[0]!.itemIds).toEqual(["pref-grace"]);
  });

  test("a quarantined entity never appears", () => {
    upsertEntity(vault, {
      category: "people",
      name: "Quarantined Person",
      agent: AGENT,
      now: NOW,
      untrustedOrigin: true,
    });
    writePref("notes", "Quarantined Person sent a message");
    const r = packContext(vault, {
      maxTokens: 10_000,
      query: "Quarantined Person",
      queryMode: "ranked",
      entityFacts: true,
    });
    expect([...r.entityFacts!.entities]).toEqual([]);
  });

  test("an archived entity never appears", () => {
    const id = seedPerson("Retired Person");
    archiveEntity(vault, { query: "Retired Person" }, { now: NOW });
    writePref("notes", "Retired Person used to own the build");
    const r = packContext(vault, {
      maxTokens: 10_000,
      query: "Retired Person",
      queryMode: "ranked",
      entityFacts: true,
    });
    expect(r.entityFacts!.entities.map((e) => e.entityId)).not.toContain(id);
    expect([...r.entityFacts!.entities]).toEqual([]);
  });

  test("an entity page failing the caller's view is treated as absent", () => {
    const id = seedPerson("Hidden Person");
    writePref("notes", "Hidden Person owns the deploy pipeline");
    const entityPath = join(vault, "Brain", "entities", "people", "ent-people-hidden-person.md");
    const r = packContext(vault, {
      maxTokens: 10_000,
      query: "Hidden Person",
      queryMode: "ranked",
      entityFacts: true,
      visible: (abs) => abs !== entityPath,
    });
    expect(r.entityFacts!.entities.map((e) => e.entityId)).not.toContain(id);
    expect([...r.entityFacts!.entities]).toEqual([]);
  });

  test("item ids draw only from kept candidates", () => {
    seedPerson("Kept Person");
    // Both bodies anchor the entity; the tiny token budget keeps only one.
    writePref("small", "Kept Person likes short notes");
    writePref(
      "large",
      `Kept Person ${"filler prose about nothing in particular ".repeat(60)}`,
      "2026-05-02T00:00:00Z",
    );
    const r = packContext(vault, {
      maxTokens: 60,
      query: "Kept Person",
      queryMode: "ranked",
      entityFacts: true,
    });
    const keptIds = r.items.map((i) => i.id);
    expect(keptIds).toContain("pref-small");
    expect(keptIds).not.toContain("pref-large");
    expect(r.entityFacts!.entities[0]!.itemIds).toEqual(["pref-small"]);
  });

  test("the section respects the view the items respect", () => {
    seedPerson("Withheld Person");
    writePref("notes", "Withheld Person runs the oncall rotation");
    const withheld = join(vault, "Brain", "preferences", "pref-notes.md");
    const r = packContext(vault, {
      maxTokens: 10_000,
      query: "Withheld Person",
      queryMode: "ranked",
      entityFacts: true,
      visible: (abs) => abs !== withheld,
    });
    expect(r.items.map((i) => i.id)).toEqual([]);
    expect([...r.entityFacts!.entities]).toEqual([
      { entityId: "ent-people-withheld-person", name: "Withheld Person", itemIds: [] },
    ]);
  });

  test("an anchored entity with no kept item still lists, with empty item ids", () => {
    seedPerson("Solo Person");
    writePref("notes", "Nothing about anyone relevant here");
    const r = packContext(vault, {
      maxTokens: 10_000,
      query: "Solo Person",
      queryMode: "ranked",
      entityFacts: true,
    });
    expect([...r.entityFacts!.entities]).toEqual([
      { entityId: "ent-people-solo-person", name: "Solo Person", itemIds: [] },
    ]);
  });

  test("at most three entities anchor, deterministically by entity id", () => {
    seedPerson("Aaa Person");
    seedPerson("Bbb Person");
    seedPerson("Ccc Person");
    seedPerson("Ddd Person");
    writePref("notes", "Aaa Person Bbb Person Ccc Person Ddd Person in one page");
    const r = packContext(vault, {
      maxTokens: 10_000,
      query: "Aaa Person Bbb Person Ccc Person Ddd Person",
      queryMode: "ranked",
      entityFacts: true,
    });
    expect(r.entityFacts!.entities.map((e) => e.entityId)).toEqual([
      "ent-people-aaa-person",
      "ent-people-bbb-person",
      "ent-people-ccc-person",
    ]);
  });

  test("a pack without a query anchors nothing", () => {
    seedPerson("Ada Lovelace");
    writePref("notes", "Pair with Ada Lovelace on the engine");
    const r = packContext(vault, { maxTokens: 10_000, entityFacts: true });
    expect([...r.entityFacts!.entities]).toEqual([]);
  });

  test("a broken entity store leaves the pack answered, with an empty rollup", () => {
    seedPerson("Ada Lovelace");
    writePref("notes", "Pair with Ada Lovelace on the engine");
    // The entity store stops being a directory, so the index build throws
    // where the rollup reads it.
    rmSync(join(vault, "Brain", "entities"), { recursive: true, force: true });
    writeFileSync(join(vault, "Brain", "entities"), "not a directory\n");
    const r = packContext(vault, {
      maxTokens: 10_000,
      query: "prepare the meeting with Ada Lovelace",
      queryMode: "ranked",
      entityFacts: true,
    });
    // The rollup is an OPTIONAL section, so a broken entity store must not
    // fail the pack: the pack still answers, and the section is present
    // and empty.
    expect(r.entityFacts).toBeDefined();
    expect([...r.entityFacts!.entities]).toEqual([]);
    expect(r.items.map((i) => i.id)).toEqual(["pref-notes"]);
  });
});