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 the read-only `brain_entity` tool
* (Memory Integrity Suite). Writes stay on the CLI; the MCP surface
* exposes lookup (`view: get`) and listing (`view: list`) only.
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { JSONRPC_VERSION, MCPServer, PROTOCOL_VERSION } from "../../src/mcp/index.ts";
import { buildToolTable } from "../../src/mcp/tools.ts";
import { bootstrapBrain } from "../../src/core/brain/init.ts";
import { upsertEntity } from "../../src/core/brain/entities/registry.ts";
import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";
let tmp: string;
let vault: string;
let configHome: string;
let configPath: string;
const savedEnv: Record<string, string | undefined> = {};
const NOW = new Date("2026-06-02T12:00:00Z");
beforeEach(() => {
tmp = mkdtempSync(join(tmpdir(), "o2b-mcp-entity-"));
vault = join(tmp, "vault");
configHome = mkdtempSync(join(tmpdir(), "o2b-mcp-entity-cfg-"));
configPath = join(configHome, "config.yaml");
for (const k of ["VAULT_AGENT_NAME", "VAULT_TIMEZONE", "VAULT_DIR", "OPEN_SECOND_BRAIN_CONFIG"]) {
savedEnv[k] = process.env[k];
delete process.env[k];
}
process.env["OPEN_SECOND_BRAIN_CONFIG"] = configPath;
atomicWriteFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);
bootstrapBrain(vault, { configPath });
upsertEntity(vault, {
category: "people",
name: "Ada",
aliases: ["the operator"],
agent: "claude",
now: NOW,
});
upsertEntity(vault, {
category: "projects",
name: "Open Second Brain",
agent: "claude",
now: NOW,
});
});
afterEach(() => {
rmSync(tmp, { recursive: true, force: true });
rmSync(configHome, { recursive: true, force: true });
for (const [k, v] of Object.entries(savedEnv)) {
if (v === undefined) delete process.env[k];
else process.env[k] = v;
}
});
async function initialize(server: MCPServer): Promise<void> {
await server.handleRequest({
jsonrpc: JSONRPC_VERSION,
id: 1,
method: "initialize",
params: {
protocolVersion: PROTOCOL_VERSION,
capabilities: {},
clientInfo: { name: "entity-tool-test", version: "0" },
},
});
await server.handleRequest({
jsonrpc: JSONRPC_VERSION,
method: "notifications/initialized",
});
}
async function callEntity(
server: MCPServer,
args: Record<string, unknown>,
): Promise<{ ok: boolean; payload: Record<string, unknown>; error?: string }> {
const r = (await server.handleRequest({
jsonrpc: JSONRPC_VERSION,
id: 7,
method: "tools/call",
params: { name: "brain_entity", arguments: args },
})) as {
result?: { content: ReadonlyArray<{ type: string; text: string }>; isError?: boolean };
error?: { message: string };
};
if (r.error) return { ok: false, payload: {}, error: r.error.message };
const text = r.result!.content[0]!.text;
if (r.result!.isError) return { ok: false, payload: {}, error: text };
return { ok: true, payload: JSON.parse(text) as Record<string, unknown> };
}
describe("brain_entity registration", () => {
test("present in the full scope, absent from the writer scope", () => {
expect(buildToolTable("full").find((t) => t.name === "brain_entity")).toBeDefined();
expect(buildToolTable("writer").find((t) => t.name === "brain_entity")).toBeUndefined();
});
});
describe("brain_entity view: get", () => {
test("resolves an alias to the canonical record", async () => {
const server = new MCPServer({ vault, configPath });
await initialize(server);
const out = await callEntity(server, { view: "get", query: "the operator" });
expect(out.ok).toBe(true);
expect(out.payload["id"]).toBe("ent-people-ada");
expect(out.payload["name"]).toBe("Ada");
});
test("reports found:false for an unknown name", async () => {
const server = new MCPServer({ vault, configPath });
await initialize(server);
const out = await callEntity(server, { view: "get", query: "nobody" });
expect(out.ok).toBe(true);
expect(out.payload["found"]).toBe(false);
});
test("requires query", async () => {
const server = new MCPServer({ vault, configPath });
await initialize(server);
const out = await callEntity(server, { view: "get" });
expect(out.ok).toBe(false);
});
});
describe("brain_entity view: list", () => {
test("lists all entities sorted by id, with category filter", async () => {
const server = new MCPServer({ vault, configPath });
await initialize(server);
const all = await callEntity(server, { view: "list" });
expect(all.ok).toBe(true);
expect((all.payload["entities"] as Array<{ id: string }>).map((e) => e.id)).toEqual([
"ent-people-ada",
"ent-projects-open-second-brain",
]);
const people = await callEntity(server, { view: "list", category: "people" });
expect((people.payload["entities"] as Array<{ id: string }>).map((e) => e.id)).toEqual([
"ent-people-ada",
]);
});
test("rejects an unknown view", async () => {
const server = new MCPServer({ vault, configPath });
await initialize(server);
const out = await callEntity(server, { view: "explode" });
expect(out.ok).toBe(false);
});
});