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
/**
* The two write lanes of the entity registry (provenance-at-the-boundary).
*
* `quarantine` was introduced as a lane for records an untrusted source
* introduced, but the write seam resolved a quarantined holder for EVERY
* upsert. That gave an untrusted source permanent capture of a name: the
* first scraped page that mentioned `Acme Corp` created the quarantined
* record, and every later TRUSTED write of that name landed inside it -
* `created: false`, status copied from the quarantined target, the
* `untrusted_source` marker carried forward as an extra, and the result
* invisible to `getEntity`, to the default listing, to alias resolution and
* to the retrieval gate. The writer was told the write succeeded.
*
* What is pinned here is the lane rule that replaced it: a write resolves
* only inside its OWN identity space. A trusted write never lands on a
* quarantined record (so an untrusted source cannot capture a name), and an
* untrusted write never lands on a canonical one (so untrusted material
* cannot ride into a trusted record's aliases, agent stamp or edges). The
* two spaces are joined again only by the operator's explicit release, which
* is why the collision that release can now produce is refused with its
* remedy rather than silently forked into two active records.
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { mkdtempSync, readFileSync, rmSync } 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 {
archiveEntity,
getEntity,
listEntities,
relateEntities,
upsertEntity,
} from "../../../../src/core/brain/entities/registry.ts";
import { BRAIN_ENTITY_STATUS } from "../../../../src/core/brain/entities/types.ts";
import { UNTRUSTED_SOURCE_FRONTMATTER_KEY } from "../../../../src/core/brain/trust/untrusted-provenance.ts";
let vault: string;
let configHome: string;
const NOW = new Date("2026-06-13T12:00:00Z");
const CATEGORY = "org";
const NAME = "Acme Corp";
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "o2b-lane-vault-"));
configHome = mkdtempSync(join(tmpdir(), "o2b-lane-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 untrustedUpsert(name: string, aliases?: readonly string[]): string {
return upsertEntity(vault, {
category: CATEGORY,
name,
...(aliases !== undefined ? { aliases } : {}),
agent: "scraper",
now: NOW,
untrustedOrigin: true,
}).entity.id;
}
function trustedUpsert(name: string, aliases?: readonly string[]) {
return upsertEntity(vault, {
category: CATEGORY,
name,
...(aliases !== undefined ? { aliases } : {}),
agent: "operator",
now: NOW,
});
}
describe("a trusted write does not disappear into an untrusted-seeded record", () => {
test("the trusted write creates a readable record of its own", () => {
untrustedUpsert(NAME);
const res = trustedUpsert(NAME);
expect(res.created).toBe(true);
expect(res.entity.status).toBe(BRAIN_ENTITY_STATUS.active);
const found = getEntity(vault, { category: CATEGORY, query: NAME });
expect(found).not.toBeNull();
expect(found!.id).toBe(res.entity.id);
expect(listEntities(vault, { category: CATEGORY })).toHaveLength(1);
});
test("the trusted record carries no untrusted-source marker", () => {
untrustedUpsert(NAME);
const res = trustedUpsert(NAME);
expect(readFileSync(res.entity.path, "utf8")).not.toContain(UNTRUSTED_SOURCE_FRONTMATTER_KEY);
});
test("the quarantined record is neither promoted nor rewritten by it", () => {
const quarantinedId = untrustedUpsert(NAME);
const before = readFileSync(
listEntities(vault, { status: BRAIN_ENTITY_STATUS.quarantine })[0]!.path,
"utf8",
);
trustedUpsert(NAME);
const quarantined = listEntities(vault, { status: BRAIN_ENTITY_STATUS.quarantine });
expect(quarantined).toHaveLength(1);
expect(quarantined[0]!.id).toBe(quarantinedId);
expect(quarantined[0]!.source_agent).toBe("scraper");
expect(readFileSync(quarantined[0]!.path, "utf8")).toBe(before);
});
});
describe("an untrusted write does not launder itself into a trusted record", () => {
test("it lands in the quarantine lane even when a trusted namesake exists", () => {
const trusted = trustedUpsert(NAME);
untrustedUpsert(NAME, ["Acme Holdings"]);
const found = getEntity(vault, { category: CATEGORY, query: NAME })!;
expect(found.id).toBe(trusted.entity.id);
expect(found.status).toBe(BRAIN_ENTITY_STATUS.active);
expect(found.aliases).toHaveLength(0);
expect(found.source_agent).toBe("operator");
expect(readFileSync(found.path, "utf8")).not.toContain(UNTRUSTED_SOURCE_FRONTMATTER_KEY);
expect(listEntities(vault, { status: BRAIN_ENTITY_STATUS.quarantine })).toHaveLength(1);
});
test("an alias claimed only by an untrusted record never resolves a trusted lookup", () => {
untrustedUpsert(NAME, ["Acme Holdings"]);
expect(getEntity(vault, { category: CATEGORY, query: "Acme Holdings" })).toBeNull();
});
test("re-ingesting the same untrusted source updates its record rather than forking one", () => {
const first = untrustedUpsert(NAME);
const second = untrustedUpsert(NAME);
expect(second).toBe(first);
expect(listEntities(vault, { status: BRAIN_ENTITY_STATUS.quarantine })).toHaveLength(1);
});
test("a quarantined record keeps its marker across an untrusted update", () => {
untrustedUpsert(NAME);
untrustedUpsert(NAME);
const path = listEntities(vault, { status: BRAIN_ENTITY_STATUS.quarantine })[0]!.path;
expect(readFileSync(path, "utf8")).toContain(UNTRUSTED_SOURCE_FRONTMATTER_KEY);
});
});
describe("edges stay inside the lane that wrote them", () => {
test("an untrusted intake can link the records it quarantined", () => {
untrustedUpsert("Acme Corp");
untrustedUpsert("Acme Labs");
const from = relateEntities(vault, {
from: { category: CATEGORY, query: "Acme Corp" },
relation: "related",
to: { category: CATEGORY, query: "Acme Labs" },
now: NOW,
untrustedOrigin: true,
});
expect(from.status).toBe(BRAIN_ENTITY_STATUS.quarantine);
expect(from.relations.some((r) => r.relation === "related")).toBe(true);
});
test("an untrusted edge cannot attach itself to a trusted record", () => {
const trusted = trustedUpsert("Acme Corp");
untrustedUpsert("Acme Corp");
untrustedUpsert("Acme Labs");
relateEntities(vault, {
from: { category: CATEGORY, query: "Acme Corp" },
relation: "related",
to: { category: CATEGORY, query: "Acme Labs" },
now: NOW,
untrustedOrigin: true,
});
const stillClean = getEntity(vault, { category: CATEGORY, query: "Acme Corp" })!;
expect(stillClean.id).toBe(trusted.entity.id);
expect(stillClean.relations).toHaveLength(0);
});
test("a trusted relate that finds only a quarantined holder names the exit", () => {
trustedUpsert("Acme Labs");
untrustedUpsert("Acme Corp");
expect(() =>
relateEntities(vault, {
from: { category: CATEGORY, query: "Acme Corp" },
relation: "related",
to: { category: CATEGORY, query: "Acme Labs" },
now: NOW,
}),
).toThrow(/quarantine/);
});
});
describe("release is refused when it would collide, not silently duplicated", () => {
test("restoring a quarantined record whose name a trusted record holds throws with the ids", () => {
untrustedUpsert(NAME);
const trusted = trustedUpsert(NAME);
expect(() =>
archiveEntity(vault, { category: CATEGORY, query: NAME }, { now: NOW, restore: true }),
).toThrow(new RegExp(trusted.entity.id));
expect(listEntities(vault, { status: BRAIN_ENTITY_STATUS.quarantine })).toHaveLength(1);
});
test("restore still releases a quarantined record when no trusted record holds the name", () => {
untrustedUpsert(NAME);
const released = archiveEntity(
vault,
{ category: CATEGORY, query: NAME },
{ now: NOW, restore: true },
);
expect(released.status).toBe(BRAIN_ENTITY_STATUS.active);
expect(getEntity(vault, { category: CATEGORY, query: NAME })).not.toBeNull();
});
});