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
6.3 KB
Raw Blame
/**
 * Structural prompt-prefix stability (Hindsight brain-loop ops,
 * t_d8c1f7d9): the kernel never calls an LLM, so it cannot attach a
 * provider cache hint to an outbound request. What it CAN guarantee is
 * the byte-stable prompt prefix a provider cache rewards. These tests
 * cover the pure helpers and the gated, fail-soft metric emit.
 */

import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

import {
  PROMPT_PREFIX_SURFACE,
  canonicalSegment,
  deterministicPrefix,
  emitPromptPrefixMetric,
  isStable,
  summarizePrefixPass,
} from "../../../src/core/brain/prompt-prefix.ts";
import { METRICS_SCHEMA_VERSION, listMetrics } from "../../../src/core/brain/metrics.ts";
import { useUnshardedLegacyLog } from "../../helpers/device-id.ts";

// The legacy day log and ledgers are read under their un-sharded names.
useUnshardedLegacyLog();

let vault: string;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-prompt-prefix-"));
  // A legacy Brain/ tree: an unswitched machine (a vault without one is store-only).
  mkdirSync(join(vault, "Brain"), { recursive: true });
});

afterEach(() => {
  rmSync(vault, { recursive: true, force: true });
});

describe("deterministicPrefix", () => {
  test("byte-identical prefix and hash for identical inputs", () => {
    const a = deterministicPrefix({
      kind: "write_session",
      segments: ["Decision topic: X", "\n\n"],
    });
    const b = deterministicPrefix({
      kind: "write_session",
      segments: ["Decision topic: X", "\n\n"],
    });
    expect(a.prefix).toBe("Decision topic: X\n\n");
    expect(a.hash).toBe(b.hash);
    expect(a.prefix).toBe(b.prefix);
    expect(a.chars).toBe(b.chars);
    // 64 hex chars = full sha-256.
    expect(a.hash).toMatch(/^[0-9a-f]{64}$/);
  });

  test("differs predictably when inputs change", () => {
    const a = deterministicPrefix({ kind: "write_session", segments: ["topic A"] });
    const b = deterministicPrefix({ kind: "write_session", segments: ["topic B"] });
    expect(a.hash).not.toBe(b.hash);
  });

  test("chars counts code points, not UTF-16 units", () => {
    const p = deterministicPrefix({ kind: "context_pack", segments: ["💡"] });
    expect(p.chars).toBe(1);
  });
});

describe("canonicalSegment", () => {
  test("key order does not perturb the bytes", () => {
    const a = canonicalSegment({ b: "2", a: "1", c: "3" });
    const b = canonicalSegment({ c: "3", a: "1", b: "2" });
    expect(a).toBe(b);
    expect(a).toBe("a=1\nb=2\nc=3");
  });
});

describe("isStable", () => {
  test("true only when kind and hash both match", () => {
    const base = deterministicPrefix({ kind: "write_session", segments: ["X"] });
    const same = deterministicPrefix({ kind: "write_session", segments: ["X"] });
    const otherText = deterministicPrefix({ kind: "write_session", segments: ["Y"] });
    const otherKind = deterministicPrefix({ kind: "context_pack", segments: ["X"] });
    expect(isStable(base, same)).toBe(true);
    expect(isStable(base, otherText)).toBe(false);
    expect(isStable(base, otherKind)).toBe(false);
  });
});

describe("summarizePrefixPass", () => {
  test("all calls share the head prefix => full stability", () => {
    const p = deterministicPrefix({ kind: "write_session", segments: ["Decision topic: X\n\n"] });
    const summary = summarizePrefixPass({ kind: "write_session", prefixes: [p, p, p, p, p] });
    expect(summary).toEqual({
      kind: "write_session",
      prefix_hash: p.hash,
      prefix_chars: p.chars,
      call_count: 5,
      stable_count: 5,
    });
  });

  test("counts only the calls reusing the head prefix", () => {
    const head = deterministicPrefix({ kind: "write_session", segments: ["A"] });
    const drift = deterministicPrefix({ kind: "write_session", segments: ["B"] });
    const summary = summarizePrefixPass({
      kind: "write_session",
      prefixes: [head, head, drift, head],
    });
    expect(summary.call_count).toBe(4);
    expect(summary.stable_count).toBe(3);
    expect(summary.prefix_hash).toBe(head.hash);
  });

  test("empty pass reports zeros and an empty hash", () => {
    const summary = summarizePrefixPass({ kind: "context_pack", prefixes: [] });
    expect(summary).toEqual({
      kind: "context_pack",
      prefix_hash: "",
      prefix_chars: 0,
      call_count: 0,
      stable_count: 0,
    });
  });
});

describe("emitPromptPrefixMetric", () => {
  const summary = {
    kind: "write_session" as const,
    prefix_hash: "abc",
    prefix_chars: 7,
    call_count: 5,
    stable_count: 5,
  };
  const runAt = "2026-06-05T10:00:00Z";

  test("gate on writes one run-level prompt_prefix record", () => {
    emitPromptPrefixMetric(vault, { runAt, summary }, true);
    const path = join(vault, "Brain", "metrics", `${PROMPT_PREFIX_SURFACE}.jsonl`);
    expect(existsSync(path)).toBe(true);
    const lines = readFileSync(path, "utf8")
      .split("\n")
      .filter((l) => l.trim().length > 0);
    expect(lines).toHaveLength(1);
    expect(JSON.parse(lines[0]!)).toEqual({
      schema: METRICS_SCHEMA_VERSION,
      surface: PROMPT_PREFIX_SURFACE,
      run_at: runAt,
      payload: {
        kind: "write_session",
        prefix_hash: "abc",
        prefix_chars: 7,
        call_count: 5,
        stable_count: 5,
      },
    });
  });

  test("listMetrics discovers the surface with no metrics.ts change", () => {
    emitPromptPrefixMetric(vault, { runAt, summary }, true);
    const records = listMetrics(vault, { surface: PROMPT_PREFIX_SURFACE });
    expect(records).toHaveLength(1);
    expect(records[0]!.surface).toBe(PROMPT_PREFIX_SURFACE);
    expect(records[0]!.payload.call_count).toBe(5);
  });

  test("gate off writes nothing", () => {
    emitPromptPrefixMetric(vault, { runAt, summary }, false);
    emitPromptPrefixMetric(vault, { runAt, summary }, undefined);
    emitPromptPrefixMetric(vault, { runAt, summary }, null);
    expect(existsSync(join(vault, "Brain", "metrics"))).toBe(false);
  });

  test("a bad runAt is swallowed (fail-soft), never throwing", () => {
    expect(() =>
      emitPromptPrefixMetric(vault, { runAt: "not-a-timestamp", summary }, true),
    ).not.toThrow();
    expect(existsSync(join(vault, "Brain", "metrics", `${PROMPT_PREFIX_SURFACE}.jsonl`))).toBe(
      false,
    );
  });
});