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
13.2 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, setDefaultTimeout, test } from "bun:test";
import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";

import { hookAuditDir } from "../../src/core/brain/paths.ts";
import {
  isRecallInjectFault,
  RECALL_INJECT_FAULT,
  RECALL_INJECT_FAULTS,
  recallInjectAuditDetails,
  recallInjectTelemetryMetadata,
  type RecallInjectDecision,
} from "../../src/core/brain/recall-inject.ts";
import { listRecallTelemetry, RECALL_CHANNEL } from "../../src/core/brain/recall-telemetry.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 HOOK = resolve(
  dirname(fileURLToPath(import.meta.url)),
  "..",
  "..",
  "hooks",
  "recall-inject.ts",
);

let vault: string;
let configHome: string;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-hook-recall-vault-"));
  configHome = mkdtempSync(join(tmpdir(), "o2b-hook-recall-cfg-"));
  mkdirSync(join(vault, "Brain"), { recursive: true });
});

afterEach(() => {
  rmSync(vault, { recursive: true, force: true });
  rmSync(configHome, { 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", HOOK], {
    stdin: "pipe",
    stdout: "pipe",
    stderr: "pipe",
    env: { ...inherited, ...env },
  });
  proc.stdin.write(JSON.stringify(payload));
  await proc.stdin.end();
  const [stdout, stderr] = await Promise.all([
    new Response(proc.stdout).text(),
    new Response(proc.stderr).text(),
  ]);
  const exit = await proc.exited;
  return { stdout, stderr, exit };
}

/**
 * The retrieval budget the tests that assert a decision ran give the hook:
 * the highest value the setting accepts. The default (2.5 s) is a product
 * bound for an interactive prompt; on a loaded Windows runner the cold
 * retrieval of a fresh vault outlived it and the hook rightly audited a
 * `timeout` error, which failed tests that are about the cap settings, not
 * about the clock. A valid value, so it never shows up in `config_invalid`.
 */
const ROOMY_TIME_BUDGET = { OPEN_SECOND_BRAIN_RECALL_INJECT_TIME_BUDGET_MS: "6000" } as const;

function auditRecords(): Array<Record<string, unknown>> {
  const dir = hookAuditDir(vault);
  if (!existsSync(dir)) return [];
  return readdirSync(dir)
    .filter((name) => name.endsWith(".jsonl"))
    .flatMap((name) =>
      readFileSync(join(dir, name), "utf8")
        .split("\n")
        .filter((line) => line.trim().length > 0)
        .map((line) => JSON.parse(line) as Record<string, unknown>),
    );
}

describe("recall-inject hook", () => {
  test("flag off (default) is a silent no-op: no stdout, no audit, no hook state", async () => {
    const r = await runHook(
      {
        hook_event_name: "UserPromptSubmit",
        prompt: "how do receipts work",
        session_id: "sess-flag-off",
      },
      { VAULT_DIR: vault },
    );
    expect(r.exit).toBe(0);
    expect(r.stdout).toBe("");
    expect(auditRecords()).toHaveLength(0);
    expect(existsSync(join(vault, ".open-second-brain", "hook-state"))).toBe(false);
  });

  test("an invalid cap is named in config_invalid and the decision still runs", async () => {
    const r = await runHook(
      { hook_event_name: "UserPromptSubmit", prompt: "how do receipts work" },
      {
        VAULT_DIR: vault,
        OPEN_SECOND_BRAIN_RECALL_INJECT_ENABLED: "true",
        OPEN_SECOND_BRAIN_RECALL_INJECT_MAX_NOTES: "99",
        ...ROOMY_TIME_BUDGET,
      },
    );
    expect(r.exit).toBe(0);
    const record = auditRecords().find((rec) => rec["actor"] === "recall-inject");
    const details = (record?.["details"] ?? {}) as Record<string, unknown>;
    expect(["inject", "abstain"]).toContain(details["decision"] as string);
    expect(details["config_invalid"]).toEqual(["OPEN_SECOND_BRAIN_RECALL_INJECT_MAX_NOTES"]);
  });

  test("valid caps leave config_invalid off the audit line", async () => {
    await runHook(
      { hook_event_name: "UserPromptSubmit", prompt: "how do receipts work" },
      { VAULT_DIR: vault, OPEN_SECOND_BRAIN_RECALL_INJECT_ENABLED: "true", ...ROOMY_TIME_BUDGET },
    );
    const record = auditRecords().find((rec) => rec["actor"] === "recall-inject");
    expect(record).toBeDefined();
    const details = record!["details"] as Record<string, unknown>;
    expect(["inject", "abstain"]).toContain(details["decision"] as string);
    expect(Object.keys(details)).not.toContain("config_invalid");
  });

  test("flag on stays fail-open and audits a decision on an empty vault", async () => {
    const r = await runHook(
      { hook_event_name: "UserPromptSubmit", prompt: "how do receipts work" },
      { VAULT_DIR: vault, OPEN_SECOND_BRAIN_RECALL_INJECT_ENABLED: "true" },
    );
    expect(r.exit).toBe(0);
    // Nothing to recall in a bare vault, so the hook abstains and injects nothing.
    expect(r.stdout).toBe("");
    const records = auditRecords();
    expect(records.length).toBeGreaterThanOrEqual(1);
    const record = records.find((rec) => rec["actor"] === "recall-inject");
    expect(record).toBeDefined();
    const details = (record?.["details"] ?? {}) as Record<string, unknown>;
    expect(["inject", "abstain", "error"]).toContain(details["decision"] as string);
  });

  test("flag on stays silent when the vault cannot be resolved", async () => {
    const r = await runHook(
      { hook_event_name: "UserPromptSubmit", prompt: "receipts" },
      {
        OPEN_SECOND_BRAIN_RECALL_INJECT_ENABLED: "true",
      },
    );
    expect(r.exit).toBe(0);
    expect(r.stdout).toBe("");
  });

  test("flag on abstains without stdout on an empty prompt", async () => {
    const r = await runHook(
      { hook_event_name: "UserPromptSubmit", prompt: "   " },
      { VAULT_DIR: vault, OPEN_SECOND_BRAIN_RECALL_INJECT_ENABLED: "true" },
    );
    expect(r.exit).toBe(0);
    expect(r.stdout).toBe("");
    const record = auditRecords().find((rec) => rec["actor"] === "recall-inject");
    const details = (record?.["details"] ?? {}) as Record<string, unknown>;
    expect(details["decision"]).toBe("abstain");
    expect(details["reason"]).toBe("empty_prompt");
  });
});

describe("recall-inject telemetry", () => {
  test("the flag-off no-op writes no telemetry, exactly as it writes no audit", async () => {
    await runHook(
      { hook_event_name: "UserPromptSubmit", prompt: "how do receipts work" },
      { VAULT_DIR: vault },
    );
    expect(listRecallTelemetry(vault, { channel: RECALL_CHANNEL.hook })).toHaveLength(0);
  });

  test("an abstain is recorded as an empty delivery, not as no delivery", async () => {
    // The whole point of the channel dimension: a hook that ran and
    // decided not to inject must be distinguishable from a hook that was
    // never installed. Emitting nothing here would destroy that.
    const r = await runHook(
      { hook_event_name: "UserPromptSubmit", prompt: "   " },
      { VAULT_DIR: vault, OPEN_SECOND_BRAIN_RECALL_INJECT_ENABLED: "true" },
    );
    expect(r.exit).toBe(0);
    expect(r.stdout).toBe("");

    const records = listRecallTelemetry(vault, { channel: RECALL_CHANNEL.hook });
    expect(records).toHaveLength(1);
    expect(records[0]!.payload).toMatchObject({
      channel: RECALL_CHANNEL.hook,
      status: "empty",
      result_count: 0,
      metadata: { decision: "abstain", reason: "empty_prompt" },
    });
  });

  test("an error's telemetry metadata carries a classification, never the retriever's message", () => {
    // `errorReason()` used to hand the raw `Error.message` straight to the
    // telemetry metadata, and `brain_recall_telemetry` returns those
    // records verbatim to a model. A SQLite, store or config failure names
    // the index file or the config path, and the shared redactor removes
    // secret-shaped tokens, not paths.
    const decision: RecallInjectDecision = {
      kind: "error",
      fault: RECALL_INJECT_FAULT.retrieverFailed,
      detail:
        "cannot read schema_version from /home/operator/vault/.open-second-brain/brain.sqlite: " +
        "disk I/O error",
    };
    const metadata = recallInjectTelemetryMetadata(decision);
    expect(metadata).toEqual({ decision: "error", fault: RECALL_INJECT_FAULT.retrieverFailed });
    expect(JSON.stringify(metadata)).not.toContain("brain.sqlite");
    expect(JSON.stringify(metadata)).not.toContain("/home/operator");
  });

  test("the local audit line keeps the message, because that file never leaves the machine", () => {
    const decision: RecallInjectDecision = {
      kind: "error",
      fault: RECALL_INJECT_FAULT.retrieverFailed,
      detail:
        "cannot read schema_version from /home/operator/vault/.open-second-brain/brain.sqlite",
    };
    const details = recallInjectAuditDetails(decision);
    expect(details["fault"]).toBe(RECALL_INJECT_FAULT.retrieverFailed);
    expect(String(details["detail"])).toContain("brain.sqlite");
  });

  test("the telemetry projection carries the whole decision, match quality included", () => {
    // Asserted against literals rather than against the other projection.
    // Comparing the two proves nothing: `recallInjectAuditDetails` RETURNS
    // the telemetry object unchanged except on `error` with a `detail`, so
    // over these three fixtures the comparison is an identity, and every
    // field could be deleted from both with the test still green.
    // `match_quality` is the field that reaches the synced continuity log
    // and `brain_recall_telemetry`, so it is the one that needs naming.
    expect(
      recallInjectTelemetryMetadata({
        kind: "inject",
        brief: "a fenced brief",
        noteCount: 2,
        topScore: 0.9,
        matchQuality: 0.8,
        injectedNotes: [{ path: "Brain/a.md", startLine: 1, endLine: 4 }],
      }),
    ).toEqual({ decision: "inject", note_count: 2, top_score: 0.9, match_quality: 0.8 });
    expect(
      recallInjectTelemetryMetadata({
        kind: "abstain",
        reason: "below_floor",
        topScore: 0.65,
        matchQuality: 0.2,
      }),
    ).toEqual({
      decision: "abstain",
      reason: "below_floor",
      top_score: 0.65,
      match_quality: 0.2,
    });
    // An unmeasurable quality travels as null, not as a substituted
    // number: the log must be able to say "there was no measurement".
    expect(
      recallInjectTelemetryMetadata({
        kind: "abstain",
        reason: "unmeasurable_quality",
        topScore: 0.65,
        matchQuality: null,
      }),
    ).toEqual({
      decision: "abstain",
      reason: "unmeasurable_quality",
      top_score: 0.65,
      match_quality: null,
    });
    expect(recallInjectTelemetryMetadata({ kind: "error", fault: RECALL_INJECT_FAULT.timeout }))
      // The error projection carries no quality and no score at all.
      .toEqual({ decision: "error", fault: RECALL_INJECT_FAULT.timeout });
  });

  test("the audit projection adds the message and nothing else", () => {
    // The one place the two projections may differ, stated as a
    // difference rather than as an identity over fixtures that cannot
    // produce one.
    const withDetail: RecallInjectDecision = {
      kind: "error",
      fault: RECALL_INJECT_FAULT.retrieverFailed,
      detail: "disk I/O error",
    };
    expect(recallInjectAuditDetails(withDetail)).toEqual({
      decision: "error",
      fault: RECALL_INJECT_FAULT.retrieverFailed,
      detail: "disk I/O error",
    });
    const noDetail: RecallInjectDecision = { kind: "error", fault: RECALL_INJECT_FAULT.timeout };
    expect(recallInjectAuditDetails(noDetail)).toEqual(
      recallInjectTelemetryMetadata(noDetail) as Record<string, unknown>,
    );
    // And an abstain never grows one, however the retriever failed.
    const abstain: RecallInjectDecision = {
      kind: "abstain",
      reason: "no_matches",
      topScore: 0,
      matchQuality: 0,
    };
    expect(Object.keys(recallInjectAuditDetails(abstain))).not.toContain("detail");
  });

  test("every fault a decision can carry is a member of the closed vocabulary", () => {
    for (const fault of RECALL_INJECT_FAULTS) expect(isRecallInjectFault(fault)).toBe(true);
    expect(isRecallInjectFault("a retriever sentence about /var/lib")).toBe(false);
  });

  test("a decision on a bare vault reaches the hook channel with a mapped status", async () => {
    await runHook(
      { hook_event_name: "UserPromptSubmit", prompt: "how do receipts work" },
      { VAULT_DIR: vault, OPEN_SECOND_BRAIN_RECALL_INJECT_ENABLED: "true" },
    );
    const records = listRecallTelemetry(vault, { channel: RECALL_CHANNEL.hook });
    expect(records).toHaveLength(1);
    const payload = records[0]!.payload;
    expect(payload["mode"]).toBe("search");
    // inject -> ok, abstain -> empty, error -> error. Nothing else.
    expect(["ok", "empty", "error"]).toContain(payload["status"] as string);
  });
});