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.1 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

import { bootstrapBrain } from "../../../src/core/brain/init.ts";
import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";
import { buildEntityIndex } from "../../../src/core/brain/entities/index-builder.ts";
import {
  archiveEntity,
  getEntity,
  listEntities,
  relateEntities,
  upsertEntity,
} from "../../../src/core/brain/entities/registry.ts";
import { InvalidEntityLabelError } from "../../../src/core/brain/entities/canonical.ts";
import {
  deriveEntityLexicon,
  writeEntityLexicon,
} from "../../../src/core/brain/entities/lexicon.ts";

let vault: string;
let configHome: string;

const NOW = new Date("2026-06-02T12:00:00Z");
const LATER = new Date("2026-06-02T13:00:00Z");

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-entities-vault-"));
  configHome = mkdtempSync(join(tmpdir(), "o2b-entities-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 });
});

function seedAda() {
  return upsertEntity(vault, {
    category: "people",
    name: "Ada",
    aliases: ["Ада", "S.E."],
    agent: "claude-dev-agent",
    now: NOW,
  });
}

describe("upsertEntity", () => {
  test("creates a Markdown entity file under Brain/entities/<category>/", () => {
    const { entity, created } = seedAda();
    expect(created).toBe(true);
    expect(entity.id).toBe("ent-people-ada");
    expect(entity.path).toContain(join("Brain", "entities", "people", "ent-people-ada.md"));
    expect(existsSync(entity.path)).toBe(true);
    const raw = readFileSync(entity.path, "utf8");
    expect(raw).toContain("kind: brain-entity");
    expect(raw).toContain("name: Ada");
    expect(raw.startsWith("---\n")).toBe(true);
  });

  test("is idempotent: same input updates in place, never duplicates", () => {
    seedAda();
    const second = upsertEntity(vault, {
      category: "people",
      name: "ada", // case variant resolves to the same identity
      agent: "claude-dev-agent",
      now: LATER,
    });
    expect(second.created).toBe(false);
    expect(second.entity.id).toBe("ent-people-ada");
    expect(listEntities(vault)).toHaveLength(1);
  });

  test("upsert via an alias updates the canonical entity", () => {
    seedAda();
    const viaAlias = upsertEntity(vault, {
      category: "people",
      name: "Ада",
      agent: "claude-dev-agent",
      now: LATER,
      body: "## Current state\nOperator of the vault.",
    });
    expect(viaAlias.created).toBe(false);
    expect(viaAlias.entity.id).toBe("ent-people-ada");
    expect(viaAlias.entity.name).toBe("Ada");
    expect(readFileSync(viaAlias.entity.path, "utf8")).toContain("Operator of the vault.");
  });

  test("merges new aliases into the existing set", () => {
    seedAda();
    const updated = upsertEntity(vault, {
      category: "people",
      name: "Ada",
      aliases: ["the operator"],
      agent: "claude-dev-agent",
      now: LATER,
    });
    expect(updated.entity.aliases).toContain("Ада");
    expect(updated.entity.aliases).toContain("the operator");
  });

  test("refuses an alias already claimed by another active entity in the category", () => {
    seedAda();
    expect(() =>
      upsertEntity(vault, {
        category: "people",
        name: "Adam Petrov",
        aliases: ["Ада"],
        agent: "claude-dev-agent",
        now: LATER,
      }),
    ).toThrow(/alias/i);
  });

  test("same name in a different category is a distinct entity", () => {
    seedAda();
    const sys = upsertEntity(vault, {
      category: "systems",
      name: "Ada",
      agent: "claude-dev-agent",
      now: NOW,
    });
    expect(sys.created).toBe(true);
    expect(sys.entity.id).toBe("ent-systems-ada");
    expect(listEntities(vault)).toHaveLength(2);
  });

  test("distinct names mapping to one file slug get a suffixed filename", () => {
    const a = upsertEntity(vault, {
      category: "projects",
      name: "Foo Bar",
      agent: "claude-dev-agent",
      now: NOW,
    });
    const b = upsertEntity(vault, {
      category: "projects",
      name: "Foo/Bar", // different identity, same slugified stem
      agent: "claude-dev-agent",
      now: NOW,
    });
    expect(a.created).toBe(true);
    expect(b.created).toBe(true);
    expect(a.entity.id).not.toBe(b.entity.id);
    expect(listEntities(vault)).toHaveLength(2);
  });

  test("rejects empty names via the label quality gate", () => {
    // A1: an empty (post-strip) name is now rejected by the typed label
    // quality gate rather than the old bespoke "name must not be empty".
    expect(() =>
      upsertEntity(vault, {
        category: "people",
        name: "   ",
        agent: "claude-dev-agent",
        now: NOW,
      }),
    ).toThrow(/invalid entity label/i);
  });

  test("strips Markdown/punctuation decoration from the stored name (A1)", () => {
    const { entity } = upsertEntity(vault, {
      category: "projects",
      name: "**Mercury.**",
      agent: "claude-dev-agent",
      now: NOW,
    });
    expect(entity.name).toBe("Mercury");
    expect(entity.id).toBe("ent-projects-mercury");
  });

  test("rejects a structurally-junk name with a typed error (A1)", () => {
    expect(() =>
      upsertEntity(vault, {
        category: "people",
        name: "***",
        agent: "claude-dev-agent",
        now: NOW,
      }),
    ).toThrow(/invalid entity label/i);
  });
});

describe("lexicon-gated creation (recall-quality A2)", () => {
  /**
   * Teach the lexicon from a corpus page, then rebuild the artifact. The
   * only vocabulary in these tests is what the corpus teaches - no
   * hardcoded word list anywhere.
   */
  function seedLexicon(corpus: string): void {
    writeFileSync(join(vault, "corpus-page.md"), `${corpus}\n`);
    writeEntityLexicon(vault, deriveEntityLexicon(vault, { now: NOW }));
  }

  test("a single learned-common-word label is refused at creation with function-word-run", () => {
    // The corpus is caseful (capitalised sightings) - a caseless corpus
    // suppresses both case verdicts - and keeps `notes` lowercase-dominant,
    // so the handle learns it as a common word and nothing is hardcoded.
    seedLexicon("Notes about the setup. The runner kept notes. Notes ran, notes ran.");
    try {
      upsertEntity(vault, {
        category: "people",
        name: "Notes",
        agent: "claude-dev-agent",
        now: NOW,
      });
      throw new Error("expected the lexicon gate to refuse 'Notes'");
    } catch (exc) {
      expect(exc).toBeInstanceOf(InvalidEntityLabelError);
      expect((exc as InvalidEntityLabelError).reason).toBe("function-word-run");
    }
    expect(listEntities(vault)).toHaveLength(0);
  });

  test("a multi-token common-word run is advisory at creation, not a refusal", () => {
    // Caseful corpus (so the verdicts are live) where BOTH tokens of the
    // label are learned common words - the run fires, and the create-arm
    // policy still admits it because it spans more than one token.
    seedLexicon("the runner kept notes about the setup. The runner ran.");
    const out = upsertEntity(vault, {
      category: "people",
      name: "The Notes",
      agent: "claude-dev-agent",
      now: NOW,
    });
    expect(out.created).toBe(true);
  });

  test("a single-token all-caps brand label admits at creation (NASA-style)", () => {
    // Caseful corpus so the case verdicts are live, and the store holds no
    // prior occurrence of the label. `NASA` shouts, but a SINGLE-token shout
    // is a brand or an acronym-in-expansion, not pasted heading residue:
    // per the design split the hard gate keeps the MULTI-token shape and the
    // single-token shout stays advisory (the heal/doctor path), so creation
    // admits.
    seedLexicon("Atlas kept the weekly meeting notes about the setup.");
    const out = upsertEntity(vault, {
      category: "org",
      name: "NASA",
      agent: "claude-dev-agent",
      now: NOW,
    });
    expect(out.created).toBe(true);
  });

  test("a multi-token all-caps heading label is refused at creation with shouted-heading", () => {
    // The hard gate keeps the MULTI-token, prior-occurrence-free shout: a
    // two-word all-caps run is pasted `# HEADING` residue, not a brand.
    seedLexicon("Atlas kept the weekly meeting notes about the setup.");
    try {
      upsertEntity(vault, {
        category: "projects",
        name: "MEETING NOTES",
        agent: "claude-dev-agent",
        now: NOW,
      });
      throw new Error("expected the lexicon gate to refuse 'MEETING NOTES'");
    } catch (exc) {
      expect(exc).toBeInstanceOf(InvalidEntityLabelError);
      expect((exc as InvalidEntityLabelError).reason).toBe("shouted-heading");
    }
  });

  test("an all-caps label with a prior stored occurrence is admitted", () => {
    seedLexicon("Atlas kept the weekly meeting notes about the setup.");
    // The lowercase form first: a multi-token run is advisory, so it is
    // created - and it is the prior occurrence that vouches for the form.
    upsertEntity(vault, {
      category: "people",
      name: "meeting notes",
      agent: "claude-dev-agent",
      now: NOW,
    });
    const out = upsertEntity(vault, {
      category: "org",
      name: "MEETING NOTES",
      agent: "claude-dev-agent",
      now: NOW,
    });
    expect(out.created).toBe(true);
  });

  test("the update arm is unaffected by the tightened verdicts", () => {
    // No artifact yet: the structural gate alone, so the name is created.
    const seeded = upsertEntity(vault, {
      category: "people",
      name: "Meeting Notes",
      agent: "claude-dev-agent",
      now: NOW,
    });
    expect(seeded.created).toBe(true);
    // The lexicon lands and would refuse a NEW common-word label (caseful
    // corpus; `meeting` and `notes` both lowercase-dominant).
    seedLexicon("The meeting ran about notes and setup. Notes ran, notes ran again.");
    const updated = upsertEntity(vault, {
      category: "people",
      name: "Meeting Notes",
      agent: "claude-dev-agent",
      now: LATER,
    });
    expect(updated.created).toBe(false);
    expect(updated.entity.id).toBe(seeded.entity.id);
    // A NEW single-token learned-common-word label is refused on the create
    // arm. The label is caseful ("Notes"): the pinned predicate runs the
    // case-based verdicts for caseful labels only, so an all-lowercase
    // label admits on the structural gate alone.
    expect(() =>
      upsertEntity(vault, {
        category: "people",
        name: "Notes",
        agent: "claude-dev-agent",
        now: LATER,
      }),
    ).toThrow(InvalidEntityLabelError);
  });

  test("code-shaped labels still admit beside the lexicon", () => {
    // Caseful corpus so the case verdicts are live; the code shapes bypass
    // them regardless.
    seedLexicon("Notes about the setup. The runner kept notes.");
    const fts = upsertEntity(vault, {
      category: "systems",
      name: "FTS5",
      agent: "claude-dev-agent",
      now: NOW,
    });
    const snake = upsertEntity(vault, {
      category: "systems",
      name: "foo_bar",
      agent: "claude-dev-agent",
      now: NOW,
    });
    expect(fts.created).toBe(true);
    expect(snake.created).toBe(true);
  });

  test("without a lexicon artifact the creation gate is unchanged (fail-open)", () => {
    const out = upsertEntity(vault, {
      category: "people",
      name: "Notes",
      agent: "claude-dev-agent",
      now: NOW,
    });
    expect(out.created).toBe(true);
  });
});

describe("getEntity", () => {
  test("resolves by canonical name, case-insensitively", () => {
    seedAda();
    const hit = getEntity(vault, { category: "people", query: "ADA" });
    expect(hit?.id).toBe("ent-people-ada");
  });

  test("resolves by alias", () => {
    seedAda();
    const hit = getEntity(vault, { category: "people", query: "s.e." });
    expect(hit?.id).toBe("ent-people-ada");
  });

  test("resolves without category when unambiguous", () => {
    seedAda();
    const hit = getEntity(vault, { query: "Ада" });
    expect(hit?.id).toBe("ent-people-ada");
  });

  test("returns null for unknown names", () => {
    seedAda();
    expect(getEntity(vault, { category: "people", query: "nobody" })).toBeNull();
  });
});

describe("listEntities", () => {
  test("filters by category and sorts by id", () => {
    seedAda();
    upsertEntity(vault, {
      category: "projects",
      name: "Open Second Brain",
      agent: "claude-dev-agent",
      now: NOW,
    });
    const all = listEntities(vault);
    expect(all.map((e) => e.id)).toEqual(["ent-people-ada", "ent-projects-open-second-brain"]);
    const people = listEntities(vault, { category: "people" });
    expect(people).toHaveLength(1);
  });
});

describe("relateEntities", () => {
  test("writes a typed relation edge readable from frontmatter", () => {
    seedAda();
    upsertEntity(vault, {
      category: "projects",
      name: "Open Second Brain",
      agent: "claude-dev-agent",
      now: NOW,
    });
    const updated = relateEntities(vault, {
      from: { category: "people", query: "Ada" },
      relation: "related",
      to: { category: "projects", query: "Open Second Brain" },
      now: LATER,
    });
    expect(updated.relations).toEqual([
      { relation: "related", target: "ent-projects-open-second-brain" },
    ]);
    const raw = readFileSync(updated.path, "utf8");
    expect(raw).toContain("ent-projects-open-second-brain");
  });

  test("rejects relations outside the known vocabulary", () => {
    seedAda();
    upsertEntity(vault, {
      category: "projects",
      name: "Open Second Brain",
      agent: "claude-dev-agent",
      now: NOW,
    });
    expect(() =>
      relateEntities(vault, {
        from: { category: "people", query: "Ada" },
        relation: "loves",
        to: { category: "projects", query: "Open Second Brain" },
        now: LATER,
      }),
    ).toThrow(/relation/i);
  });

  test("relating twice is idempotent", () => {
    seedAda();
    upsertEntity(vault, {
      category: "projects",
      name: "Open Second Brain",
      agent: "claude-dev-agent",
      now: NOW,
    });
    const args = {
      from: { category: "people", query: "Ada" },
      relation: "related",
      to: { category: "projects", query: "Open Second Brain" },
      now: LATER,
    } as const;
    relateEntities(vault, args);
    const second = relateEntities(vault, args);
    expect(second.relations).toHaveLength(1);
  });
});

describe("archiveEntity", () => {
  test("removes the entity from active lookup but keeps the file", () => {
    const { entity } = seedAda();
    const archived = archiveEntity(vault, { category: "people", query: "Ada" }, { now: LATER });
    expect(archived.status).toBe("archived");
    expect(archived.archived_at).toBe("2026-06-02T13:00:00Z");
    expect(existsSync(entity.path)).toBe(true);
    expect(getEntity(vault, { category: "people", query: "Ada" })).toBeNull();
    expect(listEntities(vault, { status: "archived" })).toHaveLength(1);
  });

  test("restore returns the entity to active lookup", () => {
    seedAda();
    archiveEntity(vault, { category: "people", query: "Ada" }, { now: LATER });
    const restored = archiveEntity(
      vault,
      { category: "people", query: "Ada" },
      { now: LATER, restore: true },
    );
    expect(restored.status).toBe("active");
    expect(restored.archived_at).toBeUndefined();
    expect(getEntity(vault, { category: "people", query: "Ada" })?.id).toBe("ent-people-ada");
  });

  test("upsert refuses a name held by an archived entity and names the remedy", () => {
    seedAda();
    archiveEntity(vault, { category: "people", query: "Ada" }, { now: LATER });
    expect(() => seedAda()).toThrow(/archived/i);
  });
});

describe("buildEntityIndex", () => {
  test("rebuilds identically from the Markdown files alone", () => {
    seedAda();
    upsertEntity(vault, {
      category: "projects",
      name: "Open Second Brain",
      aliases: ["o2b vault"],
      agent: "claude-dev-agent",
      now: NOW,
    });
    const first = buildEntityIndex(vault);
    const second = buildEntityIndex(vault);
    expect(second.entities.map((e) => e.id)).toEqual(first.entities.map((e) => e.id));
    expect([...second.byAlias.keys()].toSorted()).toEqual([...first.byAlias.keys()].toSorted());
    expect(first.byKey.get("people:ada")?.id).toBe("ent-people-ada");
    expect(first.byAlias.get("o2b vault")?.id).toBe("ent-projects-open-second-brain");
  });

  test("reports duplicate identity claims from hand-authored files as conflicts", () => {
    const { entity } = seedAda();
    // Simulate a sync/hand-edit duplicate claiming the same (category, name).
    const dupPath = join(entity.path, "..", "ent-people-ada-dup.md");
    atomicWriteFileSync(
      dupPath,
      [
        "---",
        "kind: brain-entity",
        "entity_id: ent-people-ada-dup",
        "category: people",
        "name: ada",
        "status: active",
        "created_at: 2026-06-02T12:30:00Z",
        "updated_at: 2026-06-02T12:30:00Z",
        "---",
        "",
        "# ada",
        "",
      ].join("\n"),
    );
    const index = buildEntityIndex(vault);
    expect(index.conflicts.length).toBeGreaterThanOrEqual(1);
    expect(index.conflicts[0]!.kind).toBe("duplicate-name");
    expect(index.conflicts[0]!.paths).toHaveLength(2);
  });

  test("skips malformed entity files without aborting the walk", () => {
    const { entity } = seedAda();
    atomicWriteFileSync(join(entity.path, "..", "broken.md"), "not frontmatter at all");
    const index = buildEntityIndex(vault);
    expect(index.entities).toHaveLength(1);
  });

  test("memoizes: an unchanged registry returns the same index object", () => {
    seedAda();
    const first = buildEntityIndex(vault);
    const second = buildEntityIndex(vault);
    expect(second).toBe(first); // same reference: no rebuild when nothing changed
  });

  test("invalidates the memo when a new entity is written", () => {
    seedAda();
    const before = buildEntityIndex(vault);
    expect(before.byKey.has("projects:open second brain")).toBe(false);
    upsertEntity(vault, {
      category: "projects",
      name: "Open Second Brain",
      agent: "claude-dev-agent",
      now: LATER,
    });
    const after = buildEntityIndex(vault);
    expect(after).not.toBe(before); // rebuilt after the write
    expect(after.byKey.get("projects:open second brain")?.id).toBe(
      "ent-projects-open-second-brain",
    );
  });

  test("invalidates the memo when an entity file is edited in place", () => {
    seedAda();
    expect(buildEntityIndex(vault).byAlias.has("newnym")).toBe(false);
    // Idempotent upsert rewrites the SAME file (same path) with an added
    // alias; the memo must notice via mtime/size and not serve the stale
    // index despite the unchanged file set.
    upsertEntity(vault, {
      category: "people",
      name: "Ada",
      aliases: ["Ада", "S.E.", "Newnym"],
      agent: "claude-dev-agent",
      now: LATER,
    });
    expect(buildEntityIndex(vault).byAlias.get("newnym")?.id).toBe("ent-people-ada");
  });
});