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
/**
* Unit H - injection-size meter for the SessionStart eager layer.
*
* The hook is fail-soft by absolute contract, so every assertion here is
* paired with the invariant that matters more than the measurement: the
* emitted context and the exit code are what they were without the meter.
*/
import { afterEach, beforeEach, describe, expect, setDefaultTimeout, test } from "bun:test";
import {
existsSync,
mkdirSync,
mkdtempSync,
readFileSync,
readdirSync,
rmSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { homeEnv } from "../helpers/platform.ts";
import { waitForSelfHealChildren } from "../helpers/self-heal-children.ts";
import { untrustedBindingFramingHeader } from "../../src/core/brain/untrusted-source.ts";
import {
assembleActiveContext,
createInjectionMeter,
SOURCE_ACTIVE_BODY,
SOURCE_LESSONS_BODY,
} from "../../hooks/lib/active-context.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",
"active-inject.ts",
);
let vault: string;
let configHome: string;
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "o2b-inject-meter-vault-"));
configHome = mkdtempSync(join(tmpdir(), "o2b-inject-meter-cfg-"));
mkdirSync(join(vault, "Brain"), { recursive: true });
});
afterEach(async () => {
// A SessionStart on an initialised vault spawns a detached reindex that
// would otherwise recreate the directories removed below.
await waitForSelfHealChildren(vault);
rmSync(vault, { recursive: true, force: true });
rmSync(configHome, { recursive: true, force: true });
});
interface RunResult {
readonly stdout: string;
readonly exit: number;
}
async function runHook(payload: unknown, env: Record<string, string> = {}): Promise<RunResult> {
const inherited: Record<string, string> = {
PATH: process.env["PATH"] ?? "",
...homeEnv(configHome),
OPEN_SECOND_BRAIN_RUNTIME_NOTICES: "false",
VAULT_DIR: vault,
};
const proc = Bun.spawn(["bun", "run", HOOK], {
stdin: "pipe",
stdout: "pipe",
stderr: "pipe",
env: { ...inherited, ...env },
});
proc.stdin.write(JSON.stringify(payload));
await proc.stdin.end();
const [stdout] = await Promise.all([
new Response(proc.stdout).text(),
new Response(proc.stderr).text(),
]);
const exit = await proc.exited;
return { stdout, exit };
}
function writeActive(body: string): void {
writeFileSync(join(vault, "Brain", "active.md"), body, "utf8");
}
function writeLessons(body: string): void {
writeFileSync(join(vault, "Brain", "lessons.md"), body, "utf8");
}
/** Run `fn` with the runtime-notice channel off, restoring the env after. */
function withRuntimeNoticesOff(fn: () => void): void {
const priorNotices = process.env["OPEN_SECOND_BRAIN_RUNTIME_NOTICES"];
process.env["OPEN_SECOND_BRAIN_RUNTIME_NOTICES"] = "false";
try {
fn();
} finally {
if (priorNotices === undefined) delete process.env["OPEN_SECOND_BRAIN_RUNTIME_NOTICES"];
else process.env["OPEN_SECOND_BRAIN_RUNTIME_NOTICES"] = priorNotices;
}
}
interface ReceiptRecord {
readonly kind: string;
readonly payload: Record<string, unknown>;
}
function readReceipts(): ReceiptRecord[] {
const dir = join(vault, "Brain", "log", "continuity");
if (!existsSync(dir)) return [];
const out: ReceiptRecord[] = [];
for (const name of readdirSync(dir)) {
if (!name.endsWith(".jsonl")) continue;
for (const line of readFileSync(join(dir, name), "utf8").split("\n")) {
if (!line.trim()) continue;
out.push(JSON.parse(line) as ReceiptRecord);
}
}
return out;
}
function injectionReceipts(): ReceiptRecord[] {
return readReceipts().filter(
(r) => r.kind === "context_receipt" && r.payload["trigger"] === "session_inject",
);
}
const ACTIVE_BODY =
"---\nkind: brain-active\ngenerated_at: 2026-05-15T10:00:00Z\n---\n\n# Active Brain Preferences\n\n## Confirmed (1)\n\n- `pref-foo` — Rule body\n";
const LESSONS_BODY =
"---\nkind: brain-lessons\ngenerated_at: 2026-05-15T10:00:00Z\n---\n\n# Lessons\n\n## Avoid (1)\n\n- `de-2026-05-18-x` (score: -0.95) — the flaky retry loop\n";
/** The frontmatter-stripped bodies, as the assembly budgets and meters them. */
const ACTIVE_TRIMMED = ACTIVE_BODY.slice(ACTIVE_BODY.indexOf("# Active")).trimEnd();
const LESSONS_TRIMMED = LESSONS_BODY.slice(LESSONS_BODY.indexOf("# Lessons")).trimEnd();
/** An active body far too wide for a small budget, and a lessons body that is not. */
const WIDE_ACTIVE_BODY =
"---\nkind: brain-active\ngenerated_at: 2026-05-15T10:00:00Z\n---\n\n" +
"# Active Brain Preferences — a preamble line long enough that no small inner budget survives it\n\n" +
"## Confirmed (1)\n\n- `pref-foo` — Rule body\n";
const TINY_LESSONS_BODY =
"---\nkind: brain-lessons\ngenerated_at: 2026-05-15T10:00:00Z\n---\n\n# Lessons\n\n## Avoid (1)\n\n- `de-1` — short lesson\n";
describe("active-inject injection meter", () => {
test("records one session_inject receipt per injection with per-source bytes and tokens", async () => {
writeActive(ACTIVE_BODY);
writeLessons(LESSONS_BODY);
const r = await runHook({ hook_event_name: "SessionStart" });
expect(r.exit).toBe(0);
const injected: string = JSON.parse(r.stdout).hookSpecificOutput.additionalContext;
const receipts = injectionReceipts();
expect(receipts.length).toBe(1);
const payload = receipts[0]!.payload;
const injection = payload["injection"] as Record<string, unknown>;
expect(injection["hook_event"]).toBe("SessionStart");
expect(injection["loader_source"]).toBe("fresh");
expect(injection["sources_measured"]).toBe(true);
expect(injection["total_bytes"]).toBe(Buffer.byteLength(injected, "utf8"));
expect(injection["total_tokens"]).toBe(Math.ceil(Buffer.byteLength(injected, "utf8") / 4));
const items = payload["items"] as ReadonlyArray<Record<string, unknown>>;
const byId = new Map(items.map((i) => [i["id"], i]));
expect([...byId.keys()].toSorted()).toEqual(["active-body", "lessons-body"]);
for (const item of items) {
const bytes = item["bytes"] as number;
expect(bytes).toBeGreaterThan(0);
expect(item["tokens"]).toBe(Math.ceil(bytes / 4));
}
});
test("scopes the meter to this hook and names the runtime-notice source", async () => {
writeActive(ACTIVE_BODY);
const r = await runHook(
{ hook_event_name: "SessionStart" },
{ OPEN_SECOND_BRAIN_RUNTIME_NOTICES: "true" },
);
expect(r.exit).toBe(0);
const items = injectionReceipts()[0]!.payload["items"] as ReadonlyArray<
Record<string, unknown>
>;
expect(items.map((i) => i["id"]).toSorted()).toEqual(["active-body", "runtime-notices"]);
});
test("records the hook event name so a non-SessionStart injection is distinguishable", async () => {
writeActive(ACTIVE_BODY);
const r = await runHook({ hook_event_name: "UserPromptSubmit" });
expect(r.exit).toBe(0);
const injection = injectionReceipts()[0]!.payload["injection"] as Record<string, unknown>;
expect(injection["hook_event"]).toBe("UserPromptSubmit");
});
test("attributes the GUARDED bytes: the framing header is part of the metered source", async () => {
// The guard runs BEFORE the meter push, so the receipt names exactly
// the bytes that reached the payload - framed, neutralized body
// included. Guarding after the push would break this exact-match
// attribution silently.
writeActive(ACTIVE_BODY);
writeLessons(LESSONS_BODY);
const r = await runHook({ hook_event_name: "SessionStart" });
expect(r.exit).toBe(0);
const injected: string = JSON.parse(r.stdout).hookSpecificOutput.additionalContext;
const items = injectionReceipts()[0]!.payload["items"] as ReadonlyArray<
Record<string, unknown>
>;
const byId = new Map(items.map((i) => [i["id"], i]));
const activeItem = byId.get(SOURCE_ACTIVE_BODY)!;
const lessonsItem = byId.get(SOURCE_LESSONS_BODY)!;
// Each metered source is the framing header line plus the neutralized
// body block, exactly as the join in the emitted context carries them.
expect(activeItem["bytes"]).toBe(
Buffer.byteLength(
`${untrustedBindingFramingHeader(SOURCE_ACTIVE_BODY)}\n${ACTIVE_TRIMMED}`,
"utf8",
),
);
expect(lessonsItem["bytes"]).toBe(
Buffer.byteLength(
`${untrustedBindingFramingHeader(SOURCE_LESSONS_BODY)}\n${LESSONS_TRIMMED}`,
"utf8",
),
);
expect(injected).toContain(
`${untrustedBindingFramingHeader(SOURCE_ACTIVE_BODY)}\n${ACTIVE_TRIMMED}`,
);
expect(injected).toContain(untrustedBindingFramingHeader(SOURCE_LESSONS_BODY));
});
test("records the budget the sources were measured against", async () => {
writeFileSync(
join(vault, "Brain", "_brain.yaml"),
"schema_version: 1\nactive:\n inject_budget_chars: 500\n",
"utf8",
);
writeActive(ACTIVE_BODY);
writeLessons(LESSONS_BODY);
const r = await runHook({ hook_event_name: "SessionStart" });
expect(r.exit).toBe(0);
const budget = injectionReceipts()[0]!.payload["budget"] as Record<string, unknown>;
// Both budgeted sub-bodies are charged against the SAME configured
// ceiling, so the effective ceiling is a multiple of it. The record
// states both numbers rather than implying one.
expect(budget["inject_budget_chars"]).toBe(500);
expect(budget["budgeted_source_count"]).toBe(2);
});
test("a degraded-to-cache injection is distinguishable from a genuinely small one", async () => {
writeActive(ACTIVE_BODY);
const first = await runHook({ hook_event_name: "SessionStart" });
expect(first.exit).toBe(0);
const fresh: string = JSON.parse(first.stdout).hookSpecificOutput.additionalContext;
// A directory where active.md was makes the assembly throw, so the
// fail-open loader degrades to the last-good cache.
rmSync(join(vault, "Brain", "active.md"));
mkdirSync(join(vault, "Brain", "active.md"));
const second = await runHook({ hook_event_name: "SessionStart" });
expect(second.exit).toBe(0);
const cached: string = JSON.parse(second.stdout).hookSpecificOutput.additionalContext;
expect(cached).toBe(fresh);
const receipts = injectionReceipts();
expect(receipts.length).toBe(2);
const injection = receipts[1]!.payload["injection"] as Record<string, unknown>;
expect(injection["loader_source"]).toBe("cached");
// Nothing was assembled, so there is no per-source attribution to
// report - and reporting zeros would be a finding that never happened.
expect(injection["sources_measured"]).toBe(false);
expect(receipts[1]!.payload["items"]).toEqual([]);
expect(injection["total_bytes"]).toBe(Buffer.byteLength(cached, "utf8"));
});
test("a throwing receipt sink changes neither the emitted context nor the exit code", async () => {
writeActive(ACTIVE_BODY);
writeLessons(LESSONS_BODY);
const healthy = await runHook({ hook_event_name: "SessionStart" });
expect(healthy.exit).toBe(0);
expect(injectionReceipts().length).toBe(1);
// A regular file where the continuity store expects its directory
// makes every append throw (mkdirSync recursive raises EEXIST).
rmSync(join(vault, "Brain", "log", "continuity"), { recursive: true, force: true });
writeFileSync(join(vault, "Brain", "log", "continuity"), "not a directory", "utf8");
const broken = await runHook({ hook_event_name: "SessionStart" });
expect(broken.exit).toBe(0);
expect(broken.stdout).toBe(healthy.stdout);
});
test("a budget that cannot hold the framing header skips the memory sources unmetered", () => {
// Unit-level on the exported assembly: the e2e hook cannot reach a
// sub-header budget (the config validator floors inject_budget_chars
// at 500), but the scoped-rules charge can leave the assembly less
// room than the header costs. A source whose header cannot fit is
// skipped whole - emitting it would push the framed remainder over
// the very budget it is charged against, and metering it would name
// bytes that never reached the payload.
writeActive(ACTIVE_BODY);
writeLessons(LESSONS_BODY);
withRuntimeNoticesOff(() => {
const meter = createInjectionMeter(8000);
const assembled = assembleActiveContext(vault, 0, meter);
expect(assembled).toBe("");
expect(meter.sources.map((s) => s.name)).toEqual([]);
expect(meter.budgetChars).toBeNull();
});
});
test("a budget exactly equal to the framing overhead emits nothing", () => {
// The floor is `<=`, not `<`: at exactly the header's overhead the
// inner budget is 0, where the budgeter answers with the truncation
// notice alone - and header + notice framed lands far over the very
// budget the source is charged against. The source skips instead.
writeActive(ACTIVE_BODY);
writeLessons(LESSONS_BODY);
withRuntimeNoticesOff(() => {
const overhead = untrustedBindingFramingHeader(SOURCE_ACTIVE_BODY).length + 1;
const meter = createInjectionMeter(8000);
const assembled = assembleActiveContext(vault, overhead, meter);
expect(assembled).toBe("");
expect(meter.sources.map((s) => s.name)).toEqual([]);
expect(meter.budgetChars).toBeNull();
});
});
test("a budget barely above the framing overhead does not emit a framed truncation notice", () => {
// With the header paid, a few spare characters cannot hold any
// content, so the budgeter's answer is the truncation notice alone.
// Framing it would emit header + multi-hundred-character notice over
// budget, so a source whose budgeted inner body is nothing but the
// notice skips whole - "never emitted over budget" holds with room
// to spare, not only below the header.
writeActive(ACTIVE_BODY);
writeLessons(LESSONS_BODY);
withRuntimeNoticesOff(() => {
const budget = untrustedBindingFramingHeader(SOURCE_ACTIVE_BODY).length + 1 + 8;
const meter = createInjectionMeter(8000);
const assembled = assembleActiveContext(vault, budget, meter);
expect(assembled).toBe("");
// Nothing was emitted, so nothing was measured under the ceiling:
// the receipt's budget block stays out, like the siblings above.
expect(meter.budgetChars).toBeNull();
expect(meter.sources.map((s) => s.name)).toEqual([]);
});
});
test("an active body truncated to its notice does not sink a lessons body that fits", () => {
// The notice-only skip is the ACTIVE source's alone. It used to
// return "" for the whole assembly, discarding a lessons body that
// had already passed its own budget and its own floor under the
// same ceiling - the lessons reader answers to its header, not to
// the active body's, so what it produced still emits and meters.
// "" is for a run where no block was produced at all.
writeActive(WIDE_ACTIVE_BODY);
writeLessons(TINY_LESSONS_BODY);
withRuntimeNoticesOff(() => {
const activeOverhead = untrustedBindingFramingHeader(SOURCE_ACTIVE_BODY).length + 1;
const lessonsOverhead = untrustedBindingFramingHeader(SOURCE_LESSONS_BODY).length + 1;
const activeTrimmed = WIDE_ACTIVE_BODY.slice(WIDE_ACTIVE_BODY.indexOf("# Active")).trimEnd();
const lessonsTrimmed = TINY_LESSONS_BODY.slice(
TINY_LESSONS_BODY.indexOf("# Lessons"),
).trimEnd();
// The lessons body fits its own inner budget with room to spare,
// while the active body's preamble line alone outlasts anything
// the same budget leaves it - so the budgeter's answer for the
// active body is the notice, and the notice alone.
const budget = lessonsOverhead + lessonsTrimmed.length + 16;
expect(lessonsTrimmed.length + 16).toBeLessThan(activeTrimmed.length);
const meter = createInjectionMeter(8000);
const assembled = assembleActiveContext(vault, budget, meter);
expect(meter.sources.map((s) => s.name)).toEqual([SOURCE_LESSONS_BODY]);
expect(assembled).toBe(
`${untrustedBindingFramingHeader(SOURCE_LESSONS_BODY)}\n${lessonsTrimmed}`,
);
// The lessons source was measured under the configured ceiling,
// so the receipt names that ceiling even without an active body.
expect(meter.budgetChars).toBe(8000);
});
});
});