Skip to content

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
8.8 KB
Raw Blame
/**
 * 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([]);
});