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
/**
* MCP integration tests for `brain_intake_entities` (model-based NER intake,
* Knowledge Provenance suite). The calling agent owns the recognition; the
* tool validates the typed payload and commits it through the shared
* extraction-intake primitive. OSB never runs a model here.
*
* The handler is exercised directly with a minimal ServerContext - the arg
* validation and the INVALID_PARAMS translation are the surface under test.
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { chmodSync, mkdirSync, mkdtempSync, 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 { getEntity, listEntities } from "../../src/core/brain/entities/registry.ts";
import {
INTAKE_TRUST,
SOURCE_CONTENT_HASH_FRONTMATTER_KEY,
} from "../../src/core/brain/trust/untrusted-provenance.ts";
import { TRANSPORT_REACH } from "../../src/core/graph/transport-reach.ts";
import { NER_TOOLS } from "../../src/mcp/brain/ner-tools.ts";
import { MCPError } from "../../src/mcp/protocol.ts";
import type { ServerContext } from "../../src/mcp/tool-contract.ts";
import { brainPageTexts } from "../helpers/brain-pages.ts";
import { CHMOD_CANNOT_DENY } from "../helpers/platform.ts";
let vault: string;
let configHome: string;
let ctx: ServerContext;
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "o2b-ner-vault-"));
configHome = mkdtempSync(join(tmpdir(), "o2b-ner-cfg-"));
const configPath = join(configHome, "config.yaml");
atomicWriteFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);
bootstrapBrain(vault, { configPath });
ctx = { vault, configPath, repoRoot: null };
});
afterEach(() => {
// The locked directory first: a 0-mode directory cannot be walked, so the
// vault removal below would fail on the test that creates one.
try {
chmodSync(join(vault, LOCKED_DIR), 0o755);
} catch {
// Only one test creates it.
}
rmSync(vault, { recursive: true, force: true });
rmSync(configHome, { recursive: true, force: true });
});
/** A directory this vault denies itself, so `stat` answers with an errno. */
const LOCKED_DIR = "Locked";
const handler = NER_TOOLS[0]!.handler;
/**
* A cited source is trusted only when the file it names is really there
* (GitHub #160), so every intake below that expects its entities in the
* canonical registry seeds the note it claims to have read.
*/
function seed(rel: string): void {
const abs = join(vault, rel);
mkdirSync(join(abs, ".."), { recursive: true });
writeFileSync(abs, `bytes of ${rel}\n`, "utf8");
}
describe("brain_intake_entities", () => {
test("intakes agent-supplied entities into the registry", async () => {
seed("Notes/scaling.md");
const res = await handler(ctx, {
source: "[[Notes/scaling.md]]",
entities: [
{ category: "concept", name: "Layer 2s" },
{ category: "people", name: "Vitalik", aliases: ["V."] },
],
});
expect(res).toEqual({
entities_created: [expect.any(String), expect.any(String)],
entities_updated: [],
relations_applied: 0,
trust: "trusted",
});
expect(listEntities(vault)).toHaveLength(2);
expect(getEntity(vault, { category: "concept", query: "Layer 2s" })?.name).toBe("Layer 2s");
});
test("applies typed relations between extracted entities", async () => {
seed("Notes/restaking.md");
const res = await handler(ctx, {
source: "[[Notes/restaking.md]]",
entities: [
{ category: "concept", name: "Restaking" },
{ category: "concept", name: "Validators" },
],
relations: [{ from: "Restaking", relation: "related", to: "Validators" }],
});
expect(res).toMatchObject({ relations_applied: 1 });
const restaking = getEntity(vault, { category: "concept", query: "Restaking" });
expect(restaking?.relations.some((r) => r.relation === "related")).toBe(true);
});
test("cites the source wikilink in a newly created entity body", async () => {
seed("Articles/eth-roadmap.md");
await handler(ctx, {
entities: [{ category: "concept", name: "Sharding" }],
source: "[[Articles/eth-roadmap.md]]",
});
const sharding = getEntity(vault, { category: "concept", query: "Sharding" });
expect(sharding?.body).toContain("## Sources");
expect(sharding?.body).toContain("[[Articles/eth-roadmap.md]]");
});
test("rejects an empty entities array with INVALID_PARAMS and writes nothing", async () => {
await expect(handler(ctx, { entities: [] })).rejects.toThrow(MCPError);
expect(listEntities(vault)).toHaveLength(0);
});
/**
* The classifier refuses an unreadable source rather than calling it
* untrusted, and that refusal reaches the caller as an MCP error. Rethrown
* verbatim, the Node errno spells out `/home/<user>/<vault>/Locked/note.md`
* - an existence-and-permission oracle over the operator's filesystem,
* queried with a string the caller chose. The refusal is right; the
* operator's path in the answer is not.
*/
// chmod cannot deny access on Windows or as root (tests/helpers/platform.ts).
test.skipIf(CHMOD_CANNOT_DENY)("an unreadable source fails without naming a path", async () => {
const locked = join(vault, LOCKED_DIR);
mkdirSync(locked, { recursive: true });
writeFileSync(join(locked, "note.md"), "bytes\n", "utf8");
chmodSync(locked, 0o000);
let thrown: unknown;
try {
// At local reach: a caller that may not read the page is answered as
// for an absent one before the stat is made (source-reach-first.test.ts).
await handler(
{ ...ctx, reach: TRANSPORT_REACH.local },
{
source: `[[${LOCKED_DIR}/note.md]]`,
entities: [{ category: "concept", name: "Restaking" }],
},
);
} catch (err) {
thrown = err;
}
expect(thrown).toBeInstanceOf(MCPError);
const message = (thrown as Error).message;
expect(message).toContain(`${LOCKED_DIR}/note.md`);
expect(message).toContain("EACCES");
expect(message).not.toContain(vault);
expect(message).not.toContain("permission denied");
expect(listEntities(vault)).toHaveLength(0);
});
test("translates an unknown relation into INVALID_PARAMS with no partial write", async () => {
// A real source, so the refusal under test is the relation vocabulary and
// not the source contract checked before it.
seed("Notes/scaling.md");
await expect(
handler(ctx, {
source: "[[Notes/scaling.md]]",
entities: [
{ category: "concept", name: "A" },
{ category: "concept", name: "B" },
],
relations: [{ from: "A", relation: "causes", to: "B" }],
}),
).rejects.toThrow(MCPError);
expect(listEntities(vault)).toHaveLength(0);
});
});
/**
* A page the caller cannot read at its reach is cited exactly like an absent
* one: the intake commits in the untrusted lane and records no digest of it.
*/
describe("brain_intake_entities - a page withheld at the caller's reach", () => {
const PRIVATE_PATH = "Notes/secret.md";
const ABSENT = "Notes/absent.md";
beforeEach(() => {
mkdirSync(join(vault, "Notes"), { recursive: true });
writeFileSync(
join(vault, PRIVATE_PATH),
"---\nvisibility: private\n---\nThe code is ZX8.\n",
"utf8",
);
});
const intake = (source: string, reachCtx: ServerContext = ctx) =>
handler(reachCtx, { source, entities: [{ category: "concept", name: "Codes" }] }) as Promise<{
trust: string;
}>;
test("answers like an absent source and writes no digest", async () => {
const hidden = await intake(PRIVATE_PATH);
const absent = await intake(ABSENT);
expect(hidden.trust).toBe(INTAKE_TRUST.untrusted);
expect(hidden.trust).toBe(absent.trust);
for (const page of brainPageTexts(vault))
expect(page).not.toContain(SOURCE_CONTENT_HASH_FRONTMATTER_KEY);
});
test("at local reach the same page is trusted, and no digest of it is recorded", async () => {
// The entity pages do not inherit the page's reservation, so its digest
// would be readable where the page is not.
const res = await intake(PRIVATE_PATH, { ...ctx, reach: TRANSPORT_REACH.local });
expect(res.trust).toBe(INTAKE_TRUST.trusted);
for (const page of brainPageTexts(vault))
expect(page).not.toContain(SOURCE_CONTENT_HASH_FRONTMATTER_KEY);
});
});