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
import { afterEach, beforeEach, describe, expect, setDefaultTimeout, test } from "bun:test";
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { STOP_GUARDRAIL_TEXT } from "../../hooks/lib/messages.ts";
import { CLI_SPAWN_BUDGET_MS } from "../helpers/cli-timeout.ts";
// Tests here spawn processes; see tests/helpers/cli-timeout.ts.
setDefaultTimeout(CLI_SPAWN_BUDGET_MS);
const HOOK = resolve(
dirname(fileURLToPath(import.meta.url)),
"..",
"..",
"hooks",
"stop-log-guardrail.ts",
);
let tmp: string;
beforeEach(() => {
tmp = mkdtempSync(join(tmpdir(), "o2b-hook-stop-"));
});
afterEach(() => {
rmSync(tmp, { recursive: true, force: true });
});
function ccUser(text: string): string {
return JSON.stringify({
type: "user",
message: { role: "user", content: [{ type: "text", text }] },
});
}
function ccAssistantToolUse(name: string, input: Record<string, unknown> = {}): string {
return JSON.stringify({
type: "assistant",
message: {
role: "assistant",
content: [{ type: "tool_use", id: "toolu_" + name, name, input }],
},
});
}
function writeTranscript(lines: readonly string[]): string {
const path = join(tmp, "transcript.jsonl");
writeFileSync(path, lines.join("\n") + "\n");
return path;
}
interface RunResult {
readonly stdout: string;
readonly exit: number;
}
async function runHook(payload: unknown): Promise<RunResult> {
const proc = Bun.spawn(["bun", "run", HOOK], {
stdin: "pipe",
stdout: "pipe",
stderr: "pipe",
// Bun hands a child without `env` the environment this process STARTED
// with, not the live `process.env`: pass it so the child sees the
// throwaway config tests/setup.ts installs, not the operator's real one.
env: { ...process.env },
});
proc.stdin.write(JSON.stringify(payload));
await proc.stdin.end();
const stdout = await new Response(proc.stdout).text();
const exit = await proc.exited;
return { stdout, exit };
}
describe("stop-log-guardrail hook", () => {
test("blocks once when artifact was produced and no brain event was recorded", async () => {
const transcript_path = writeTranscript([
ccUser("please add a file"),
ccAssistantToolUse("Write", { file_path: "/tmp/x.md" }),
]);
const r = await runHook({
hook_event_name: "Stop",
transcript_path,
stop_hook_active: false,
});
expect(r.exit).toBe(0);
expect(r.stdout.endsWith("\n")).toBe(true);
const out = JSON.parse(r.stdout);
// An unrecognised runtime gets the portable one-line block.
expect(out).toEqual({ decision: "block", reason: STOP_GUARDRAIL_TEXT });
// §32 (v0.10.8): event_log_append must not appear in the guardrail
// body — the tool is retired across every runtime.
expect(out.reason).not.toContain("event_log_append");
});
test("passes through when brain_feedback was called this turn", async () => {
const transcript_path = writeTranscript([
ccUser("please add a file"),
ccAssistantToolUse("Write", { file_path: "/tmp/x.md" }),
ccAssistantToolUse("brain_feedback", {
topic: "x",
signal: "positive",
principle: "p",
}),
]);
const r = await runHook({
hook_event_name: "Stop",
transcript_path,
stop_hook_active: false,
});
expect(r.exit).toBe(0);
expect(r.stdout).toBe("");
});
test("passes through when brain_note was called this turn (§32B)", async () => {
const transcript_path = writeTranscript([
ccUser("please add a file"),
ccAssistantToolUse("Write", { file_path: "/tmp/x.md" }),
ccAssistantToolUse("brain_note", { text: "added /tmp/x.md" }),
]);
const r = await runHook({
hook_event_name: "Stop",
transcript_path,
stop_hook_active: false,
});
expect(r.exit).toBe(0);
expect(r.stdout).toBe("");
});
test("passes through when no artifact was produced", async () => {
const transcript_path = writeTranscript([
ccUser("what's in the README?"),
ccAssistantToolUse("Read", { file_path: "/tmp/README.md" }),
]);
const r = await runHook({
hook_event_name: "Stop",
transcript_path,
stop_hook_active: false,
});
expect(r.exit).toBe(0);
expect(r.stdout).toBe("");
});
test("never blocks twice in a row (stop_hook_active === true)", async () => {
const transcript_path = writeTranscript([
ccUser("please add a file"),
ccAssistantToolUse("Write", { file_path: "/tmp/x.md" }),
]);
const r = await runHook({
hook_event_name: "Stop",
transcript_path,
stop_hook_active: true,
});
expect(r.exit).toBe(0);
expect(r.stdout).toBe("");
});
test("stays silent when transcript_path is missing", async () => {
const r = await runHook({
hook_event_name: "Stop",
stop_hook_active: false,
});
expect(r.exit).toBe(0);
expect(r.stdout).toBe("");
});
test("stays silent when transcript_path does not exist on disk", async () => {
const r = await runHook({
hook_event_name: "Stop",
transcript_path: join(tmp, "missing.jsonl"),
stop_hook_active: false,
});
expect(r.exit).toBe(0);
expect(r.stdout).toBe("");
});
test("passes through when the agent logged via Bash (`o2b brain feedback`)", async () => {
const transcript_path = writeTranscript([
ccUser("add a file and record a signal via bash"),
ccAssistantToolUse("Write", { file_path: "/tmp/x.md" }),
JSON.stringify({
type: "assistant",
message: {
role: "assistant",
content: [
{
type: "tool_use",
id: "toolu_b",
name: "Bash",
input: {
command: "o2b brain feedback --topic x --signal positive --principle p",
},
},
],
},
}),
]);
const r = await runHook({
hook_event_name: "Stop",
transcript_path,
stop_hook_active: false,
});
expect(r.exit).toBe(0);
expect(r.stdout).toBe("");
});
test("blocks even when the deprecated `o2b append-event` bash needle is used (§32)", async () => {
// §32 (v0.10.8) drops `o2b append-event` from the brain-event
// detector. The CLI still works for humans / cron, but it no
// longer suppresses the stop guardrail.
const transcript_path = writeTranscript([
ccUser("add a file and write the legacy log line"),
ccAssistantToolUse("Write", { file_path: "/tmp/x.md" }),
JSON.stringify({
type: "assistant",
message: {
role: "assistant",
content: [
{
type: "tool_use",
id: "toolu_b",
name: "Bash",
input: { command: "o2b append-event 'added /tmp/x.md'" },
},
],
},
}),
]);
const r = await runHook({
hook_event_name: "Stop",
transcript_path,
stop_hook_active: false,
});
const out = JSON.parse(r.stdout);
expect(out.decision).toBe("block");
});
test("blocks even when the deprecated MCP-prefixed event_log_append is called (§32)", async () => {
const transcript_path = writeTranscript([
ccUser("add a file"),
ccAssistantToolUse("Write", { file_path: "/tmp/x.md" }),
ccAssistantToolUse("mcp__plugin_open-second-brain_open-second-brain__event_log_append", {
message: "added /tmp/x.md",
}),
]);
const r = await runHook({
hook_event_name: "Stop",
transcript_path,
stop_hook_active: false,
});
const out = JSON.parse(r.stdout);
expect(out.decision).toBe("block");
});
test("blocks for Codex apply_patch with no logging", async () => {
const transcript_path = writeTranscript([
JSON.stringify({
type: "response_item",
payload: {
type: "message",
role: "user",
content: [{ type: "input_text", text: "patch the file" }],
},
}),
JSON.stringify({
type: "response_item",
payload: { type: "custom_tool_call", name: "apply_patch", call_id: "c1", input: "" },
}),
]);
const r = await runHook({
hook_event_name: "Stop",
transcript_path,
stop_hook_active: false,
});
const out = JSON.parse(r.stdout);
expect(out.decision).toBe("block");
});
test("Claude Code gets non-error additionalContext feedback, not a block", async () => {
// Reuse the per-test `tmp` so afterEach cleans this up too.
const transcript_path = join(tmp, ".claude", "projects", "session.jsonl");
mkdirSync(dirname(transcript_path), { recursive: true });
writeFileSync(
transcript_path,
[ccUser("write something"), ccAssistantToolUse("Write", { file_path: "/tmp/x.md" })].join(
"\n",
) + "\n",
);
const r = await runHook({
hook_event_name: "Stop",
transcript_path,
stop_hook_active: false,
});
const out = JSON.parse(r.stdout);
// `decision: "block"` renders as a red "Stop hook error" with the whole
// reason in the user's transcript; additionalContext continues the turn
// as "Stop hook feedback".
expect(out.decision).toBeUndefined();
expect(out.reason).toBeUndefined();
expect(out.hookSpecificOutput).toEqual({
hookEventName: "Stop",
additionalContext: STOP_GUARDRAIL_TEXT,
});
});
test("Codex transcript path gets the one-line block reason", async () => {
// Reuse the per-test `tmp` so afterEach cleans this up too.
const transcript_path = join(tmp, ".codex", "sessions", "session.jsonl");
mkdirSync(dirname(transcript_path), { recursive: true });
writeFileSync(
transcript_path,
[
JSON.stringify({
type: "response_item",
payload: {
type: "message",
role: "user",
content: [{ type: "input_text", text: "patch the file" }],
},
}),
JSON.stringify({
type: "response_item",
payload: {
type: "custom_tool_call",
name: "apply_patch",
call_id: "c1",
input: "",
},
}),
].join("\n") + "\n",
);
const r = await runHook({
hook_event_name: "Stop",
transcript_path,
stop_hook_active: false,
});
const out = JSON.parse(r.stdout);
// Codex documents only decision/reason for Stop; the reason becomes the
// continuation prompt, so it stays one line.
expect(out).toEqual({ decision: "block", reason: STOP_GUARDRAIL_TEXT });
});
test("Grok Build payload gets the one-line block reason", async () => {
const transcript_path = writeTranscript([
ccUser("please add a file"),
ccAssistantToolUse("Write", { file_path: "/tmp/x.md" }),
]);
const r = await runHook({
hookEventName: "Stop",
workspaceRoot: tmp,
transcript_path,
stop_hook_active: false,
});
expect(JSON.parse(r.stdout)).toEqual({ decision: "block", reason: STOP_GUARDRAIL_TEXT });
});
});
describe("STOP_GUARDRAIL_TEXT", () => {
test("is one short line that names the three brain-event tools", () => {
expect(STOP_GUARDRAIL_TEXT).not.toContain("\n");
expect(STOP_GUARDRAIL_TEXT.length).toBeLessThanOrEqual(200);
expect(STOP_GUARDRAIL_TEXT).toStartWith("Open Second Brain:");
expect(STOP_GUARDRAIL_TEXT).not.toContain("!");
for (const tool of ["brain_feedback", "brain_apply_evidence", "brain_note", "brain-memory"]) {
expect(STOP_GUARDRAIL_TEXT).toContain(tool);
}
});
});