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
/**
* Registry-aware entity alias expansion (Memory Integrity Suite).
*
* Unit level: a query entity matching a registered alias expands to the
* canonical name forms (and vice versa). End to end: a query naming an
* ALIAS boosts the document that names the CANONICAL entity, and the
* result explains the canonical hop in its reasons.
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { mkdirSync, writeFileSync } from "node:fs";
import { join } from "node:path";
import { indexVault, search } from "../../../src/core/search/index.ts";
import { makeConfig, createTempVault } from "../../helpers/search-fixtures.ts";
import {
DERIVED_PERSON_AMBIGUITY_CODE,
expandQueryEntities,
PERSON_NICKNAMES_ARTIFACT_REL,
} from "../../../src/core/search/entity-alias.ts";
import { RETRIEVAL_DETAIL_IDENTIFIER } from "../../../src/core/search/retrieval-trail.ts";
import { archiveEntity, upsertEntity } from "../../../src/core/brain/entities/registry.ts";
let tmp: ReturnType<typeof createTempVault>;
const NOW = new Date("2026-06-02T12:00:00Z");
beforeEach(() => {
tmp = createTempVault("entity-alias");
});
afterEach(() => {
tmp.cleanup();
});
function seedRegistry(): void {
upsertEntity(tmp.vault, {
category: "projects",
name: "Open Second Brain",
aliases: ["OSB", "the vault project"],
agent: "claude-dev-agent",
now: NOW,
});
}
function seedPerson(name = "Robert Smith"): string {
const { entity } = upsertEntity(tmp.vault, {
category: "people",
name,
agent: "claude-dev-agent",
now: NOW,
});
return entity.id;
}
/** Write the operator nickname map the config reader resolves. */
function writeNicknames(entries: Record<string, string[]>): void {
mkdirSync(join(tmp.vault, "Brain", "entities"), { recursive: true });
writeFileSync(join(tmp.vault, PERSON_NICKNAMES_ARTIFACT_REL), JSON.stringify(entries));
}
/** One note the keyword lane can match, so the pipeline reaches ranking. */
function writeMatchableNote(): void {
mkdirSync(join(tmp.vault, "notes"), { recursive: true });
writeFileSync(
join(tmp.vault, "notes", "a.md"),
"---\ntitle: A\n---\n\nR Smith planned the payment flow for the vault project this week.\n",
);
}
describe("expandQueryEntities", () => {
test("query naming an alias gains the canonical name forms", () => {
seedRegistry();
const out = expandQueryEntities(tmp.vault, ["osb"]);
expect(out.expanded).toContain("osb");
expect(out.expanded).toContain("open second brain");
expect(out.added).toContain("open second brain");
expect(out.sourceIds).toEqual(["ent-projects-open-second-brain"]);
});
test("query naming the canonical name gains the alias forms", () => {
seedRegistry();
const out = expandQueryEntities(tmp.vault, ["open second brain"]);
expect(out.added).toContain("osb");
});
test("no registry means identity expansion", () => {
const out = expandQueryEntities(tmp.vault, ["osb"]);
expect(out.expanded).toEqual(["osb"]);
expect(out.added).toEqual([]);
expect(out.sourceIds).toEqual([]);
});
test("archived entities do not expand", () => {
seedRegistry();
archiveEntity(tmp.vault, { category: "projects", query: "Open Second Brain" }, { now: NOW });
const out = expandQueryEntities(tmp.vault, ["osb"]);
expect(out.added).toEqual([]);
});
});
describe("person-variant expansion", () => {
test("query 'Bob' resolves against a Robert-only registry through operator nickname data", () => {
const id = seedPerson();
writeNicknames({ bob: ["Robert Smith"] });
const out = expandQueryEntities(tmp.vault, ["bob"]);
// The declared canonical name joins `added`; the derived structural
// forms join `derived` ("bob" itself is already a query entity).
expect(out.expanded).toEqual(["bob", "robert smith", "r smith", "smith robert"]);
expect(out.added).toEqual(["robert smith"]);
expect(out.derived).toEqual(["r smith", "smith robert"]);
expect(out.sourceIds).toEqual([id]);
});
test("structural variants participate without any nickname data", () => {
seedPerson();
const out = expandQueryEntities(tmp.vault, ["smith robert"]);
expect(out.added).toEqual(["robert smith"]);
// The reversed form the query already carried is skipped; the
// initial form is the one derived addition.
expect(out.derived).toEqual(["r smith"]);
expect(out.expanded).toEqual(["smith robert", "robert smith", "r smith"]);
});
test("declared forms always win attribution: a derived form another entity declared stays in added", () => {
seedPerson();
upsertEntity(tmp.vault, {
category: "people",
name: "Smith Robert",
agent: "claude-dev-agent",
now: NOW,
});
const out = expandQueryEntities(tmp.vault, ["smith robert"]);
// "smith robert" is entity B's DECLARED name: it must never also
// appear as a derived form.
expect(out.added).toContain("robert smith");
expect(out.derived).not.toContain("smith robert");
expect(out.sourceIds).toContain("ent-people-smith-robert");
});
test("a malformed nickname file drops only the nickname lane: declared expansion keeps working", () => {
// Identity expansion here would turn off the declared name/alias
// expansion that never needed the file - one bad operator file must
// not silence the whole registry.
seedRegistry();
mkdirSync(join(tmp.vault, "Brain", "entities"), { recursive: true });
writeFileSync(join(tmp.vault, PERSON_NICKNAMES_ARTIFACT_REL), "{ not json");
const out = expandQueryEntities(tmp.vault, ["osb"]);
expect(out.added).toEqual(["open second brain", "the vault project"]);
expect(out.expanded).toEqual(["osb", "open second brain", "the vault project"]);
});
test("a form two entities share is attributed to the declaration, never to both lanes", () => {
// Entity A's derivation reaches "smith robert"; entity B DECLARES it
// as an alias. Whichever entity the walk visits first, the form must
// land in exactly one lane - the declared one - or candidate signals
// count it twice and attribute it wrong.
seedPerson("Robert Smith");
upsertEntity(tmp.vault, {
category: "people",
name: "R Smith",
aliases: ["Smith Robert"],
agent: "claude-dev-agent",
now: NOW,
});
const out = expandQueryEntities(tmp.vault, ["r smith"]);
// The declared claim wins: the shared form is added, not derived.
expect(out.added).toContain("smith robert");
expect(out.derived).not.toContain("smith robert");
// And the lanes are disjoint over the whole expansion.
expect(new Set(out.expanded).size).toBe(out.expanded.length);
});
test("a vault with no person entities returns the identity expansion byte-identically", () => {
seedRegistry();
writeNicknames({ bob: ["ada lovelace"] });
const out = expandQueryEntities(tmp.vault, ["osb"]);
// Exactly the pre-variant expansion: every declared non-query form
// in `added`, nothing derived.
expect(out.expanded).toEqual(["osb", "open second brain", "the vault project"]);
expect(out.added).toEqual(["open second brain", "the vault project"]);
expect(out.derived).toEqual([]);
expect(out.sourceIds).toEqual(["ent-projects-open-second-brain"]);
});
test("org-category entities never derive person variants", () => {
upsertEntity(tmp.vault, {
category: "org",
name: "Acme Corp",
agent: "claude-dev-agent",
now: NOW,
});
const out = expandQueryEntities(tmp.vault, ["corp acme"]);
expect(out.derived).toEqual([]);
expect(out.added).toEqual([]);
});
test("a quarantined person does not derive", () => {
upsertEntity(tmp.vault, {
category: "people",
name: "Robert Smith",
agent: "claude-dev-agent",
now: NOW,
untrustedOrigin: true,
});
writeNicknames({ bob: ["Robert Smith"] });
const out = expandQueryEntities(tmp.vault, ["bob"]);
expect(out.expanded).toEqual(["bob"]);
expect(out.added).toEqual([]);
expect(out.derived).toEqual([]);
});
test("an unreadable or malformed nickname file degrades to the identity expansion", () => {
seedPerson();
mkdirSync(join(tmp.vault, "Brain", "entities"), { recursive: true });
writeFileSync(join(tmp.vault, PERSON_NICKNAMES_ARTIFACT_REL), "{ not json");
const out = expandQueryEntities(tmp.vault, ["bob"]);
expect(out.expanded).toEqual(["bob"]);
expect(out.added).toEqual([]);
expect(out.derived).toEqual([]);
});
test("a form two people share only through derivation expands nothing and is reported", () => {
// The design's rule for derived ambiguity: reported, never guessed.
// Neither Robert joins the expansion - adding both people's declared
// names would be a guess that the query means all of them.
const smith = seedPerson("Robert Smith");
const jones = seedPerson("Robert Jones");
writeNicknames({ bob: ["Robert Smith", "Robert Jones"] });
const out = expandQueryEntities(tmp.vault, ["bob"]);
expect(out.expanded).toEqual(["bob"]);
expect(out.added).toEqual([]);
expect(out.derived).toEqual([]);
expect(out.sourceIds).toEqual([]);
expect(out.derivedAmbiguities).toEqual([{ form: "bob", ids: [smith, jones].toSorted() }]);
});
test("an initial form two people share is not a guess either", () => {
// "r smith" is derived by BOTH persons (initial-plus-surname), with
// no declared claimant anywhere: ambiguity, not expansion.
seedPerson("Robert Smith");
seedPerson("Richard Smith");
const out = expandQueryEntities(tmp.vault, ["r smith"]);
expect(out.added).toEqual([]);
expect(out.derived).toEqual([]);
expect(out.derivedAmbiguities.map((a) => a.form)).toEqual(["r smith"]);
expect(out.derivedAmbiguities[0]!.ids).toHaveLength(2);
});
test("a unique form expands beside a reported ambiguity", () => {
// Robert and Richard share "r smith" only through derivation - that
// form is reported and expands nothing - while "bob" is uniquely
// Robert Smith's: the unique form still expands Robert's declared
// name, and Richard (reachable only through the ambiguous form)
// contributes nothing.
const smith = seedPerson("Robert Smith");
seedPerson("Richard Smith");
writeNicknames({ bob: ["Robert Smith"] });
const out = expandQueryEntities(tmp.vault, ["bob", "r smith"]);
expect(out.derivedAmbiguities.map((a) => a.form)).toEqual(["r smith"]);
expect(out.derivedAmbiguities[0]!.ids).toHaveLength(2);
expect(out.added).toEqual(["robert smith"]);
expect(out.sourceIds).toEqual([smith]);
});
test("the dotted-initial spelling expands the plain-named person", () => {
const id = seedPerson("Ada Lovelace");
const out = expandQueryEntities(tmp.vault, ["A. Lovelace"]);
expect(out.added).toEqual(["ada lovelace"]);
// The query's dot survives in its own raw form, so the plain
// initial spelling is a derived addition here, not a query form.
expect(out.derived).toEqual(["a lovelace", "lovelace ada"]);
expect(out.sourceIds).toEqual([id]);
});
test("the comma spelling expands through the declared word order", () => {
const id = seedPerson("Ada Lovelace");
const out = expandQueryEntities(tmp.vault, ["Lovelace, Ada"]);
// The canonical word order is new query content (the raw query only
// carried the comma spelling), so it joins `added`; the derivation's
// structural forms follow in `derived`.
expect(out.added).toEqual(["ada lovelace"]);
expect(out.derived).toEqual(["a lovelace", "lovelace ada"]);
expect(out.sourceIds).toEqual([id]);
});
test("a two-letter operator nickname expands the person it stands for", () => {
seedPerson("Alan Lovelace");
writeNicknames({ al: ["Alan Lovelace"] });
const out = expandQueryEntities(tmp.vault, ["al"]);
expect(out.added).toEqual(["alan lovelace"]);
expect(out.derived).toEqual(["a lovelace", "lovelace alan"]);
expect(out.derivedAmbiguities).toEqual([]);
});
});
describe("alias-aware search boost", () => {
test("query naming an alias boosts the doc naming the canonical entity", async () => {
seedRegistry();
mkdirSync(join(tmp.vault, "notes"), { recursive: true });
// Both notes carry identical query-term frequencies and identical
// word counts so their BM25 scores tie exactly (min-max then maps
// both to 1.0); entity boost is re-ranking only, never retrieval.
// Only canonical.md names the CANONICAL entity - without registry
// expansion both docs would get the same one-entity boost from the
// literal alias and stay tied.
writeFileSync(
join(tmp.vault, "notes", "canonical.md"),
"---\ntitle: Canonical\n---\n\nThe payment flow OSB runs through Open Second Brain to pay memory costs.\n",
);
writeFileSync(
join(tmp.vault, "notes", "plain.md"),
"---\ntitle: Plain\n---\n\nThe payment flow OSB runs through other second things to pay memory costs.\n",
);
const config = makeConfig({ vault: tmp.vault, dbPath: tmp.dbPath, maxHops: 0 });
await indexVault(config, {});
const out = await search(config, { query: "payment pay memory OSB", limit: 10 });
const canonical = out.results.findIndex((r) => r.path === "notes/canonical.md");
const plain = out.results.findIndex((r) => r.path === "notes/plain.md");
expect(canonical).toBeGreaterThanOrEqual(0);
expect(plain).toBeGreaterThanOrEqual(0);
expect(canonical).toBeLessThan(plain);
const top = out.results[canonical]!;
expect(top.reasons.some((x) => x.startsWith("entity_match"))).toBe(true);
expect(top.reasons.some((x) => x.includes("ent-projects-open-second-brain"))).toBe(true);
});
test("search without a registry behaves exactly as before", async () => {
mkdirSync(join(tmp.vault, "notes"), { recursive: true });
writeFileSync(
join(tmp.vault, "notes", "a.md"),
"---\ntitle: A\n---\n\nThe vector flow runs through Vector Store to store vector data.\n",
);
const config = makeConfig({ vault: tmp.vault, dbPath: tmp.dbPath, maxHops: 0 });
await indexVault(config, {});
const out = await search(config, { query: "vector Vector Store", limit: 5 });
expect(out.results.length).toBeGreaterThan(0);
expect(out.results[0]!.reasons.some((x) => x.includes("ent-"))).toBe(false);
});
});
describe("derived-ambiguity trail reporting", () => {
test("an ambiguous derived query names the form and the competing ids on the trail", async () => {
const richard = seedPerson("Richard Smith");
const robert = seedPerson("Robert Smith");
writeMatchableNote();
const config = makeConfig({ vault: tmp.vault, dbPath: tmp.dbPath, maxHops: 0 });
await indexVault(config, {});
// "R Smith" is derived by BOTH persons and declared by neither, so
// the expansion adds nothing - and the trail says so instead of the
// answer reading as a quiet miss.
const out = await search(config, { query: "R Smith payment", limit: 10 });
const entries = (out.retrievalTrail?.degraded ?? []).filter(
(d) => d.code === DERIVED_PERSON_AMBIGUITY_CODE,
);
expect(entries).toHaveLength(1);
const ids = [richard, robert].toSorted().join(".");
expect(entries[0]!.detail).toEqual({ "r smith": ids });
// The detail values stay identifiers, under the trail's own rule.
for (const value of Object.values(entries[0]!.detail ?? {})) {
expect(value).toMatch(RETRIEVAL_DETAIL_IDENTIFIER);
}
});
test("an unambiguous query leaves no derived-ambiguity entry on the trail", async () => {
seedPerson("Richard Smith");
seedPerson("Robert Smith");
writeMatchableNote();
const config = makeConfig({ vault: tmp.vault, dbPath: tmp.dbPath, maxHops: 0 });
await indexVault(config, {});
// "Robert Smith" is a declared form of exactly one person: it expands,
// and no ambiguity is reported.
const out = await search(config, { query: "Robert Smith payment", limit: 10 });
const entries = (out.retrievalTrail?.degraded ?? []).filter(
(d) => d.code === DERIVED_PERSON_AMBIGUITY_CODE,
);
expect(entries).toEqual([]);
});
});