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
/**
* The SessionStart backlog nudge hook (session-mining-economy,
* t_0358af42).
*
* The hook answers one question at session start - how much of the
* imported session backlog has never been distilled - and only when the
* answer has CHANGED since the last time it was injected. The census is
* the vault-side mining census, so no source log is ever hashed inside
* the hook's budget; under the deadline the hook degrades to silence,
* never to a fabricated number.
*
* Flag off is an immediate no-op with zero output: the session preamble
* stays byte-identical. Every path exits 0.
*/
import { afterEach, beforeEach, describe, expect, setDefaultTimeout, test } from "bun:test";
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { bootstrapBrain } from "../../src/core/brain/init.ts";
import { importSession } from "../../src/core/brain/sessions/import.ts";
import { recordSessionImports, sessionLedgerPath } from "../../src/core/brain/sessions/discover.ts";
import { sessionMiningLedgerPath } from "../../src/core/brain/session-mining-ledger.ts";
import { DERIVED_STORE_DIR } from "../../src/core/brain/path-constants.ts";
import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";
import { SESSION_RUNTIME_ID } from "../../src/core/runtime/host-facts.ts";
import { homeEnv } from "../helpers/platform.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 HOOKS_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "hooks");
const NOW = new Date("2026-09-18T10:00:00Z");
let vault: string;
let configHome: string;
let sessionsDir: string;
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "o2b-nudge-vault-"));
configHome = mkdtempSync(join(tmpdir(), "o2b-nudge-cfg-"));
sessionsDir = mkdtempSync(join(tmpdir(), "o2b-nudge-sessions-"));
bootstrapBrain(vault);
});
afterEach(() => {
rmSync(vault, { recursive: true, force: true });
rmSync(configHome, { recursive: true, force: true });
rmSync(sessionsDir, { recursive: true, force: true });
});
interface RunResult {
readonly stdout: string;
readonly stderr: 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),
};
const proc = Bun.spawn(["bun", "run", join(HOOKS_DIR, "backlog-nudge.ts")], {
stdin: "pipe",
stdout: "pipe",
stderr: "pipe",
env: { ...inherited, ...env },
});
proc.stdin.write(JSON.stringify(payload));
await proc.stdin.end();
const stdout = await new Response(proc.stdout).text();
const stderr = await new Response(proc.stderr).text();
const exit = await proc.exited;
return { stdout, stderr, exit };
}
/** The flag-on environment, built per call: `vault` moves with every test. */
function flagOn(): Record<string, string> {
return { OPEN_SECOND_BRAIN_BACKLOG_NUDGE_ENABLED: "true", VAULT_DIR: vault };
}
const SESSION_START = { hook_event_name: "SessionStart" };
/** The state file: one overwrite-only count beside the hygiene digest. */
function statePath(): string {
return join(vault, DERIVED_STORE_DIR, "backlog-nudge.count");
}
/** Session filenames stay unique across calls: the basename IS the identity. */
let seeded = 0;
/** Seed `n` imported, never-mined sessions, the way the import verb does. */
async function seedBacklog(n: number): Promise<void> {
for (let i = 0; i < n; i++) {
const path = join(sessionsDir, `backlog-${seeded}.jsonl`);
seeded += 1;
writeFileSync(
path,
JSON.stringify({
type: "user",
parentUuid: null,
entrypoint: "cli",
sessionId: `s-${seeded}`,
uuid: `u-${seeded}`,
timestamp: "2026-09-18T09:00:00.000Z",
message: { role: "user", content: [{ type: "text", text: `backlog item ${seeded}` }] },
}) + "\n",
"utf8",
);
// Sequential on purpose: each importSession builds and consults its
// own dedup index, and two concurrent imports would race the vault.
// oxlint-disable-next-line no-await-in-loop
await importSession(vault, path, { agent: "tester", now: NOW, recall: true });
recordSessionImports(vault, [{ path, runtime: SESSION_RUNTIME_ID.claudeCode }]);
}
}
interface InjectedPayload {
readonly hookSpecificOutput?: {
readonly hookEventName?: string;
readonly additionalContext?: string;
};
}
describe("backlog-nudge hook (SessionStart)", () => {
test("flag off is an immediate no-op with zero output and no state", async () => {
await seedBacklog(2);
const r = await runHook(SESSION_START, { VAULT_DIR: vault });
expect(r.exit).toBe(0);
expect(r.stdout).toBe("");
expect(existsSync(statePath())).toBe(false);
});
test("flag on with a changed count injects one line naming the count", async () => {
await seedBacklog(1);
const r = await runHook(SESSION_START, flagOn());
expect(r.exit).toBe(0);
const payload = JSON.parse(r.stdout) as InjectedPayload;
expect(payload.hookSpecificOutput?.hookEventName).toBe("SessionStart");
expect(payload.hookSpecificOutput?.additionalContext).toMatch(/1 imported session\b/);
expect(payload.hookSpecificOutput?.additionalContext).not.toMatch(/2 imported sessions/);
// The nudge points at the JSON form, the one that hands out the
// mining envelopes.
expect(payload.hookSpecificOutput?.additionalContext).toContain(
"o2b brain import-session --propose-backlog --json",
);
// The state lands only after the emit, overwrite-only, size one.
expect(readFileSync(statePath(), "utf8")).toBe("1\n");
});
test("an unchanged count stays silent", async () => {
await seedBacklog(1);
expect((await runHook(SESSION_START, flagOn())).stdout).not.toBe("");
const again = await runHook(SESSION_START, flagOn());
expect(again.exit).toBe(0);
expect(again.stdout).toBe("");
});
test("a grown backlog re-arms the nudge", async () => {
await seedBacklog(1);
await runHook(SESSION_START, flagOn());
await seedBacklog(1);
const r = await runHook(SESSION_START, flagOn());
const payload = JSON.parse(r.stdout) as InjectedPayload;
expect(payload.hookSpecificOutput?.additionalContext).toMatch(/2 imported sessions/);
expect(readFileSync(statePath(), "utf8")).toBe("2\n");
});
test("a drained backlog is recorded, not announced, and re-arms when it returns", async () => {
await seedBacklog(1);
expect((await runHook(SESSION_START, flagOn())).stdout).not.toBe("");
// The backlog empties (the sessions were mined, or the import records
// went away). A line announcing zero work is noise; the state still
// moves, so the NEXT change is measured against zero.
rmSync(sessionLedgerPath(vault));
const drained = await runHook(SESSION_START, flagOn());
expect(drained.exit).toBe(0);
expect(drained.stdout).toBe("");
expect(readFileSync(statePath(), "utf8")).toBe("0\n");
await seedBacklog(1);
const returned = await runHook(SESSION_START, flagOn());
const payload = JSON.parse(returned.stdout) as InjectedPayload;
expect(payload.hookSpecificOutput?.additionalContext).toMatch(/1 imported session\b/);
}, 20000);
test("a count of zero with no recorded state is silent too", async () => {
const r = await runHook(SESSION_START, flagOn());
expect(r.exit).toBe(0);
expect(r.stdout).toBe("");
expect(readFileSync(statePath(), "utf8")).toBe("0\n");
});
test("an event that cannot carry additionalContext gets nothing", async () => {
await seedBacklog(1);
const r = await runHook({ hook_event_name: "PostToolUse" }, flagOn());
expect(r.exit).toBe(0);
expect(r.stdout).toBe("");
expect(existsSync(statePath())).toBe(false);
});
test("no vault resolves to silence", async () => {
const r = await runHook(SESSION_START, { OPEN_SECOND_BRAIN_BACKLOG_NUDGE_ENABLED: "true" });
expect(r.exit).toBe(0);
expect(r.stdout).toBe("");
});
test("a corrupt census source degrades to silence, naming itself on stderr", async () => {
await seedBacklog(1);
mkdirSync(dirname(sessionMiningLedgerPath(vault)), { recursive: true });
writeFileSync(sessionMiningLedgerPath(vault), "{ this is not json", "utf8");
const r = await runHook(SESSION_START, flagOn());
expect(r.exit).toBe(0);
expect(r.stdout).toBe("");
expect(r.stderr).toContain("backlog-nudge");
expect(r.stderr).toContain("session mining ledger is corrupted JSON");
});
test("a corrupt state file reads as changed, so the next eligible session emits", async () => {
await seedBacklog(1);
mkdirSync(dirname(statePath()), { recursive: true });
atomicWriteFileSync(statePath(), "not a count\n");
const r = await runHook(SESSION_START, flagOn());
expect(r.exit).toBe(0);
expect(JSON.parse(r.stdout as string)).toBeDefined();
expect(readFileSync(statePath(), "utf8")).toBe("1\n");
});
});