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
/**
* Cross-agent shared memory namespace (Agent Write Contract Suite,
* t_936a1a61): opt-in mirror of explicit remember-writes into a shared
* vault, per-agent + origin attribution, fail-soft mirroring.
*/
import { afterEach, beforeEach, expect, test } from "bun:test";
import { mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import {
MIRROR_OUTCOME,
MIRROR_OUTCOMES,
isMirrorOutcome,
mirrorNote,
mirrorSignal,
resolveSharedNamespace,
} from "../../../src/core/brain/shared-namespace.ts";
import { appendBrainNote } from "../../../src/core/brain/note.ts";
import { parseSignal } from "../../../src/core/brain/signal.ts";
import { parseLogDay } from "../../../src/core/brain/log.ts";
import { buildToolTable, findTool } from "../../../src/mcp/tools.ts";
import type { ServerContext } from "../../../src/mcp/tool-contract.ts";
import { useUnshardedLegacyLog } from "../../helpers/device-id.ts";
// The legacy day log and ledgers are read under their un-sharded names.
useUnshardedLegacyLog();
let tmp: string;
let vault: string;
let shared: string;
let configPath: string;
const SIGNAL_INPUT = {
topic: "mirror-topic",
signal: "positive" as const,
agent: "coding-agent",
principle: "Mirrored facts stay attributed.",
created_at: "2026-06-04T10:00:00Z",
date: "2026-06-04",
slug: "mirror-topic",
};
beforeEach(() => {
tmp = mkdtempSync(join(tmpdir(), "o2b-shared-ns-"));
vault = join(tmp, "vault");
shared = join(tmp, "shared");
mkdirSync(join(vault, "Brain"), { recursive: true });
mkdirSync(join(shared, "Brain"), { recursive: true });
configPath = join(tmp, "config.yaml");
writeFileSync(configPath, `vault: "${vault}"\nshared_namespace: "${shared}"\n`);
});
afterEach(() => {
rmSync(tmp, { recursive: true, force: true });
});
test("resolveSharedNamespace reads the config key; absent means off", () => {
expect(resolveSharedNamespace(configPath)).toBe(shared);
writeFileSync(configPath, `vault: "${vault}"\n`);
expect(resolveSharedNamespace(configPath)).toBeNull();
expect(resolveSharedNamespace(join(tmp, "missing.yaml"))).toBeNull();
});
test("mirrorSignal lands the signal in the shared vault with origin attribution", () => {
expect(mirrorSignal(shared, vault, SIGNAL_INPUT)).toEqual({ outcome: MIRROR_OUTCOME.ok });
const inbox = join(shared, "Brain", "inbox");
const files = readdirSync(inbox).filter((f) => f.endsWith(".md"));
expect(files).toHaveLength(1);
const signal = parseSignal(join(inbox, files[0]!));
expect(signal.agent).toBe("coding-agent");
const text = readFileSync(join(inbox, files[0]!), "utf8");
expect(text).toContain("origin_vault: vault");
});
/**
* Fail-soft is not the same as mute. Both writes used to sit behind a bare
* `catch { return "failed" }`, so a permissions problem, a missing shared
* vault, a full disk and a schema violation reached the operator as one
* indistinguishable bit - on the one path they cannot observe any other way,
* because nothing read the shared vault back.
*/
test("a broken shared namespace degrades to failed and says why", () => {
rmSync(shared, { recursive: true, force: true });
writeFileSync(shared, "not a directory");
const signal = mirrorSignal(shared, vault, SIGNAL_INPUT);
expect(signal.outcome).toBe(MIRROR_OUTCOME.failed);
expect(signal.reason).toBeDefined();
expect(signal.reason).not.toBe("");
const note = mirrorNote(shared, vault, { text: "hello", agent: "coding-agent" });
expect(note.outcome).toBe(MIRROR_OUTCOME.failed);
expect(note.reason).toBeDefined();
});
/**
* A self-mirror is decided before any I/O and is repaired by editing one
* config key; a failed write is repaired on the filesystem. Reporting both
* as `failed` sent the operator after the wrong fault.
*/
test("a shared namespace pointing at the origin vault is misconfigured, not failed", () => {
const signal = mirrorSignal(vault, vault, SIGNAL_INPUT);
expect(signal.outcome).toBe(MIRROR_OUTCOME.misconfigured);
expect(signal.outcome).not.toBe(MIRROR_OUTCOME.failed);
expect(signal.reason).toContain("shared_namespace");
expect(mirrorNote(vault, vault, { text: "self", agent: "a" }).outcome).toBe(
MIRROR_OUTCOME.misconfigured,
);
expect(readdirSync(join(vault, "Brain")).some((f) => f === "inbox")).toBe(false);
});
test("the mirror outcome vocabulary is closed, and carries no member nothing produces", () => {
expect([...MIRROR_OUTCOMES]).toEqual([
MIRROR_OUTCOME.ok,
MIRROR_OUTCOME.failed,
MIRROR_OUTCOME.misconfigured,
]);
for (const member of MIRROR_OUTCOMES) expect(isMirrorOutcome(member)).toBe(true);
// `off` was retracted: the key being absent is reported by omitting the
// field, so no producer could ever return the token.
expect(isMirrorOutcome("off")).toBe(false);
expect(isMirrorOutcome(null)).toBe(false);
});
test("mirrorNote lands a note event with origin attribution", () => {
expect(
mirrorNote(shared, vault, {
text: "released v1",
agent: "coding-agent",
now: new Date("2026-06-04T10:00:00Z"),
}),
).toEqual({ outcome: MIRROR_OUTCOME.ok });
const { entries } = parseLogDay(shared, "2026-06-04");
expect(entries).toHaveLength(1);
expect(entries[0]!.eventType).toBe("note");
expect(entries[0]!.body["origin_vault"]).toBe("vault");
expect(entries[0]!.body["agent"]).toBe("coding-agent");
});
test("appendBrainNote mirrors when configured and reports the outcome", () => {
const res = appendBrainNote({
vault,
text: "fact discovered",
agent: "coding-agent",
configPath,
now: new Date("2026-06-04T10:00:00Z"),
});
expect(res.mirror).toBe(MIRROR_OUTCOME.ok);
expect(res.mirror_reason).toBeUndefined();
expect(parseLogDay(shared, "2026-06-04").entries).toHaveLength(1);
// Primary log always lands regardless of mirror state.
expect(parseLogDay(vault, "2026-06-04").entries).toHaveLength(1);
});
test("appendBrainNote without the key stays silent about mirroring", () => {
writeFileSync(configPath, `vault: "${vault}"\n`);
const res = appendBrainNote({ vault, text: "no mirror", agent: "a", configPath });
expect(res.mirror).toBeUndefined();
});
test("MCP brain_feedback mirrors the signal and reports mirror: ok", async () => {
const ctx: ServerContext = { vault, configPath, repoRoot: null };
const tool = findTool(buildToolTable("writer"), "brain_feedback");
const res = (await tool.handler(ctx, {
topic: "mirror-topic",
signal: "positive",
principle: "Mirrored facts stay attributed.",
agent: "coding-agent",
})) as Record<string, unknown>;
expect(res["mirror"]).toBe(MIRROR_OUTCOME.ok);
const files = readdirSync(join(shared, "Brain", "inbox")).filter((f) => f.endsWith(".md"));
expect(files).toHaveLength(1);
});
test("MCP brain_feedback mirror failure never breaks the primary write", async () => {
rmSync(shared, { recursive: true, force: true });
writeFileSync(shared, "not a directory");
const ctx: ServerContext = { vault, configPath, repoRoot: null };
const tool = findTool(buildToolTable("writer"), "brain_feedback");
const res = (await tool.handler(ctx, {
topic: "mirror-topic",
signal: "positive",
principle: "Primary write survives.",
agent: "coding-agent",
})) as Record<string, unknown>;
expect(res["mirror"]).toBe(MIRROR_OUTCOME.failed);
// The diagnosis reaches the caller on the MCP surface too, not only the
// bit that something went wrong.
expect(typeof res["mirror_reason"]).toBe("string");
const files = readdirSync(join(vault, "Brain", "inbox")).filter((f) => f.endsWith(".md"));
expect(files).toHaveLength(1);
});
test("unconfigured setups keep the previous result shape (no mirror key)", async () => {
writeFileSync(configPath, `vault: "${vault}"\n`);
const ctx: ServerContext = { vault, configPath, repoRoot: null };
const tool = findTool(buildToolTable("writer"), "brain_feedback");
const res = (await tool.handler(ctx, {
topic: "plain",
signal: "positive",
principle: "No mirror configured.",
agent: "coding-agent",
})) as Record<string, unknown>;
expect("mirror" in res).toBe(false);
expect("mirror_reason" in res).toBe(false);
});
/**
* Once the shared namespace is store-only on this machine, a store write
* lands in this machine's own store, never in the shared vault: the
* mirror refuses up front instead of duplicating the origin record there
* and reporting `ok`.
*/
test("a shared vault with no legacy tree is a misconfigured mirror, and nothing is written", () => {
rmSync(join(shared, "Brain"), { recursive: true, force: true });
const signal = mirrorSignal(shared, vault, SIGNAL_INPUT);
expect(signal.outcome).toBe(MIRROR_OUTCOME.misconfigured);
expect(signal.reason).toContain("store-only");
expect(mirrorNote(shared, vault, { text: "hello", agent: "a" }).outcome).toBe(
MIRROR_OUTCOME.misconfigured,
);
expect(readdirSync(shared)).toEqual([]);
});