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
16.6 KB
Raw Blame
/**
 * Section-aware character budget (token-diet, plan Task 1): pure
 * deterministic truncation shared by the active.md injection budget
 * and any future hook-side body budgeting. Sections drop whole
 * (lowest priority first); the most important remaining section is
 * trimmed at line boundaries, never mid-line.
 */

import { describe, expect, test } from "bun:test";

import {
  applySectionBudget,
  type BudgetSection,
  compareItemLines,
  firstTagGroup,
  joinedSectionsLength,
  type SectionBudgetOptions,
  type SectionTruncationReport,
  splitSectionBullets,
  topItemLines,
} from "../../../src/core/brain/text/text-budget.ts";

const NOTICE = "_Truncated to fit the injection budget. Call `brain_context` for the full view._";

function sections(): BudgetSection[] {
  return [
    { key: "confirmed", priority: 0, text: "## Confirmed\n\n- a one\n- a two\n- a three" },
    { key: "most-applied", priority: 1, text: "## Most-applied\n\n- m one\n- m two" },
    { key: "quarantine", priority: 2, text: "## Quarantine\n\n- q one" },
    { key: "retired", priority: 3, text: "## Retired\n\n- r one" },
  ];
}

describe("applySectionBudget", () => {
  test("everything fits: identity join, no truncation", () => {
    const out = applySectionBudget(sections(), 10_000, { notice: NOTICE });
    expect(out.truncated).toBe(false);
    expect(out.droppedKeys).toEqual([]);
    expect(out.body).toBe(
      [
        "## Confirmed\n\n- a one\n- a two\n- a three",
        "## Most-applied\n\n- m one\n- m two",
        "## Quarantine\n\n- q one",
        "## Retired\n\n- r one",
      ].join("\n\n"),
    );
  });

  test("over budget: drops the lowest-priority sections first, keeps render order", () => {
    const full = applySectionBudget(sections(), 10_000, { notice: NOTICE }).body.length;
    // Budget one section short of the full body: only `retired` drops.
    const out = applySectionBudget(sections(), full - 20, { notice: NOTICE });
    expect(out.truncated).toBe(true);
    expect(out.droppedKeys).toEqual(["retired"]);
    expect(out.body).toContain("## Confirmed");
    expect(out.body).not.toContain("## Retired");
    expect(out.body.endsWith(NOTICE)).toBe(true);
  });

  test("still over budget after drops: trims the least important kept section at line boundaries", () => {
    const out = applySectionBudget(sections(), 30, { notice: NOTICE });
    expect(out.truncated).toBe(true);
    expect(out.droppedKeys).toEqual(["retired", "quarantine", "most-applied"]);
    // The confirmed section is line-trimmed from the tail: every kept
    // line must be a complete line from the original text.
    const kept = out.body.slice(0, out.body.length - NOTICE.length).trimEnd();
    for (const line of kept.split("\n")) {
      expect("## Confirmed\n\n- a one\n- a two\n- a three".split("\n")).toContain(line);
    }
    expect(kept).toContain("## Confirmed");
    expect(kept).not.toContain("- a three");
  });

  test("zero budget returns the notice only", () => {
    const out = applySectionBudget(sections(), 0, { notice: NOTICE });
    expect(out.truncated).toBe(true);
    expect(out.body).toBe(NOTICE);
    expect(out.droppedKeys).toEqual(["retired", "quarantine", "most-applied", "confirmed"]);
  });

  test("deterministic: identical inputs produce identical outputs", () => {
    const a = applySectionBudget(sections(), 90, { notice: NOTICE });
    const b = applySectionBudget(sections(), 90, { notice: NOTICE });
    expect(a).toEqual(b);
  });

  test("priority ties drop the later section first", () => {
    const tied: BudgetSection[] = [
      { key: "first", priority: 1, text: "first body" },
      { key: "second", priority: 1, text: "second body" },
    ];
    const out = applySectionBudget(tied, "first body".length + 2, { notice: NOTICE });
    expect(out.droppedKeys).toEqual(["second"]);
    expect(out.body.startsWith("first body")).toBe(true);
  });

  test("budget respected across a fixture sweep (content within budget, notice rides on top)", () => {
    const secs = sections();
    const overhead = NOTICE.length + 2; // separator + notice when truncated
    for (let budget = 0; budget <= 400; budget += 7) {
      const out = applySectionBudget(secs, budget, { notice: NOTICE });
      expect(out.body.length).toBeLessThanOrEqual(budget + overhead);
    }
  });

  test("no notice configured: truncation still works, body stays within budget", () => {
    const out = applySectionBudget(sections(), 50, {});
    expect(out.truncated).toBe(true);
    expect(out.body.length).toBeLessThanOrEqual(50);
    expect(out.body).toContain("## Confirmed");
  });
});

/**
 * The notice may be a function of the truncation report, which is what
 * lets a caller say WHICH sections went and by how much rather than
 * emitting a fixed sentence that names nothing. The report carries
 * integers and section keys only - no text of the sections themselves -
 * so a notice built from it is safe to show whatever the sections hold.
 */
describe("applySectionBudget: the notice as a function of the truncation report", () => {
  function reportFor(budget: number): SectionTruncationReport {
    let seen: SectionTruncationReport | null = null;
    applySectionBudget(sections(), budget, {
      notice: (report) => {
        seen = report;
        return "";
      },
    });
    if (seen === null) throw new Error("the notice function was never called");
    return seen;
  }

  test("the function receives droppedKeys in drop order", () => {
    const full = applySectionBudget(sections(), 10_000).body.length;
    expect(reportFor(full - 20).droppedKeys).toEqual(["retired"]);
    expect(reportFor(30).droppedKeys).toEqual(["retired", "quarantine", "most-applied"]);
  });

  test("the function receives kept and total characters and the trimmed flag", () => {
    const full = applySectionBudget(sections(), 10_000).body.length;
    // A whole-section drop with no tail trim.
    const dropped = reportFor(full - 20);
    expect(dropped.totalChars).toBe(full);
    expect(dropped.keptChars).toBeLessThan(full);
    expect(dropped.trimmed).toBe(false);
    // A budget tight enough that the last kept section is tail-trimmed.
    expect(reportFor(30).trimmed).toBe(true);
  });

  test("the returned string is appended verbatim", () => {
    const out = applySectionBudget(sections(), 30, {
      notice: (report) => `dropped ${report.droppedKeys.length}`,
    });
    expect(out.body.endsWith("\n\ndropped 3")).toBe(true);
  });

  test("a function returning the empty string appends nothing", () => {
    const out = applySectionBudget(sections(), 30, { notice: () => "" });
    expect(out.truncated).toBe(true);
    expect(out.body.length).toBeLessThanOrEqual(30);
  });

  test("the function is not called when nothing was truncated", () => {
    let calls = 0;
    const out = applySectionBudget(sections(), 10_000, {
      notice: () => {
        calls++;
        return NOTICE;
      },
    });
    expect(calls).toBe(0);
    expect(out.body).not.toContain(NOTICE);
  });

  test("the string form still behaves identically to a function returning it", () => {
    for (const budget of [0, 30, 90, 200, 10_000]) {
      const asString = applySectionBudget(sections(), budget, { notice: NOTICE });
      const asFunction = applySectionBudget(sections(), budget, { notice: () => NOTICE });
      expect(asFunction).toEqual(asString);
    }
  });
});

// ----- The reported total (original-size notice) -----------------------------

/**
 * `totalChars` on the options lets a caller that shrinks the sections
 * BEFORE this pass (the active-body budgeter tiers them first) report
 * the notice total against the body it started from, not the pre-shrunk
 * slices it hands in. Without the override such a caller has no way to
 * keep "kept X of Y" honest across its own pre-pass. The default - the
 * join of the sections as handed in - is what the standing-rules and
 * scoped-rules callers must keep receiving.
 */
describe("applySectionBudget: the reported total", () => {
  function reportFor(opts: SectionBudgetOptions, budget: number): SectionTruncationReport {
    let seen: SectionTruncationReport | null = null;
    applySectionBudget(sections(), budget, {
      ...opts,
      notice: (report) => {
        seen = report;
        return "";
      },
    });
    if (seen === null) throw new Error("the notice function was never called");
    return seen;
  }

  test("default: the total is the join of the sections as handed in", () => {
    const full = applySectionBudget(sections(), 10_000).body.length;
    expect(reportFor({}, full - 20).totalChars).toBe(full);
  });

  test("an explicit totalChars is reported instead of the join of the given sections", () => {
    const full = applySectionBudget(sections(), 10_000).body.length;
    const report = reportFor({ totalChars: 50_000 }, full - 20);
    expect(report.totalChars).toBe(50_000);
    // The override changes only what the notice is told: the body the
    // pass renders and the kept-chars figure are unaffected.
    expect(report.keptChars).toBeLessThan(full);
  });

  test("the override never surfaces when nothing was truncated", () => {
    const out = applySectionBudget(sections(), 10_000, { totalChars: 50_000, notice: NOTICE });
    expect(out.truncated).toBe(false);
    expect(out.body).not.toContain(NOTICE);
  });
});

// ----- Section bullet primitives (headline tier, context-injection-pipeline) --

/**
 * The bullet primitives parse the DISPLAY grammar the active.md and
 * lessons.md renderers emit at shrink time, when no structured metadata
 * is available: heading, non-bullet lead-in lines, then `- ` item lines
 * whose inline `(tag, tag)` group carries the ranking keys. The
 * renderer functions and these primitives point at each other in their
 * docblocks.
 */
describe("splitSectionBullets", () => {
  const SECTION_TEXT = [
    "## Quarantine (2)",
    "",
    "_Probationary rules β€” still active._",
    "",
    "- `q1` (applied: 0 / violated: 2) β€” one",
    "- `q2` (applied: 1 / violated: 0) β€” two",
  ].join("\n");

  test("isolates the heading, the lead-in lines and the item lines", () => {
    const split = splitSectionBullets(SECTION_TEXT);
    expect(split.heading).toBe("## Quarantine (2)");
    expect(split.leadInLines).toEqual(["", "_Probationary rules β€” still active._", ""]);
    expect(split.itemLines).toEqual([
      "- `q1` (applied: 0 / violated: 2) β€” one",
      "- `q2` (applied: 1 / violated: 0) β€” two",
    ]);
    expect(split.headLines).toEqual(["## Quarantine (2)", ...split.leadInLines]);
  });

  test("a slice without a heading: heading null, every non-bullet line is a head line", () => {
    const split = splitSectionBullets("plain lead-in prose\n- one");
    expect(split.heading).toBeNull();
    expect(split.leadInLines).toEqual([]);
    expect(split.headLines).toEqual(["plain lead-in prose"]);
    expect(split.itemLines).toEqual(["- one"]);
  });

  test("a slice without items: everything is head, items empty", () => {
    const split = splitSectionBullets("## Confirmed (0)\n\n_Nothing yet._");
    expect(split.itemLines).toEqual([]);
    expect(split.headLines).toEqual(["## Confirmed (0)", "", "_Nothing yet._"]);
  });

  test("pure and deterministic: identical inputs, untouched input text", () => {
    const before = SECTION_TEXT;
    expect(splitSectionBullets(SECTION_TEXT)).toEqual(splitSectionBullets(SECTION_TEXT));
    expect(SECTION_TEXT).toBe(before);
  });
});

describe("firstTagGroup", () => {
  test("reads the first parenthesized group after the id prefix", () => {
    expect(firstTagGroup("- `pref-a` (scope: web, pinned) β€” Rule A")).toBe("scope: web, pinned");
  });

  test("survives nested parentheses inside the group", () => {
    expect(firstTagGroup("- `pref-a` (confidence: high (0.95)) β€” Rule A")).toBe(
      "confidence: high (0.95)",
    );
  });

  test("the principle text after the group is never read", () => {
    expect(firstTagGroup("- `pref-a` (applied: 1 / violated: 0) β€” use (parens) here")).toBe(
      "applied: 1 / violated: 0",
    );
  });

  test("a line with an id but no tag group is null", () => {
    expect(firstTagGroup("- `pref-r` β€” low_confidence on 2026-05-01")).toBeNull();
  });

  test("a line without the id-backtick prefix is null", () => {
    expect(firstTagGroup("- plain bullet without an id")).toBeNull();
    expect(firstTagGroup("not a bullet at all")).toBeNull();
  });

  test("an unbalanced group is null (fail-open, never a misparse)", () => {
    expect(firstTagGroup("- `p` (unclosed group of text")).toBeNull();
  });
});

describe("item line ranking", () => {
  test("applied_in_window ranks descending", () => {
    const m1 = "- `m1` (applied_in_window: 2)";
    const m2 = "- `m2` (applied_in_window: 5)";
    const m3 = "- `m3` (applied_in_window: 9)";
    expect(compareItemLines(m3, m1)).toBeLessThan(0);
    expect(compareItemLines(m1, m3)).toBeGreaterThan(0);
    expect(compareItemLines(m2, m1)).toBeLessThan(0);
    expect(topItemLines([m1, m3, m2], 2)).toEqual([m3, m2]);
  });

  test("confidence values rank descending, the nested value parsed", () => {
    const c1 = "- `c1` (confidence: high (0.95)) β€” A";
    const c2 = "- `c2` (confidence: medium (0.50)) β€” B";
    const c3 = "- `c3` (confidence: high (0.80)) β€” C";
    expect(compareItemLines(c1, c2)).toBeLessThan(0);
    expect(compareItemLines(c3, c2)).toBeLessThan(0);
    expect(compareItemLines(c1, c3)).toBeLessThan(0);
    expect(topItemLines([c2, c1, c3], 2)).toEqual([c1, c3]);
  });

  test("applied ranks descending, then violated ascending", () => {
    const q1 = "- `q1` (applied: 2 / violated: 5) β€” one";
    const q2 = "- `q2` (applied: 2 / violated: 1) β€” two";
    const q3 = "- `q3` (applied: 4 / violated: 9) β€” three";
    expect(compareItemLines(q3, q1)).toBeLessThan(0);
    expect(compareItemLines(q2, q1)).toBeLessThan(0);
    // Same applied count: fewer violations first.
    expect(compareItemLines(q2, q3)).toBeGreaterThan(0);
    // Same applied count: fewer violations first. Top two are q3, q2;
    // survivors come back in render order.
    expect(topItemLines([q1, q2, q3], 2)).toEqual([q2, q3]);
  });

  test("lines without a recognizable id-tag group rank last, in original order", () => {
    const lines = [
      "- trailing plain note",
      "- `m1` (applied_in_window: 1)",
      "- `r1` β€” retired prose without tags",
      "- `m2` (applied_in_window: 2)",
    ];
    // Both recognized lines survive the cut; the unrecognizable band keeps
    // its original order and loses its tail (`r1`). Survivors come back in
    // render order, so the leading unrankable note rides along.
    expect(topItemLines(lines, 3)).toEqual([
      "- trailing plain note",
      "- `m1` (applied_in_window: 1)",
      "- `m2` (applied_in_window: 2)",
    ]);
  });

  test("a group with none of the known keys ranks in the recognized band, original order", () => {
    const lines = ["- `d2` (score: -0.50) β€” later", "- `d1` (score: -0.95) β€” earlier"];
    expect(topItemLines(lines, 2)).toEqual(lines);
  });

  test("ties keep original render order", () => {
    const lines = [
      "- `m1` (applied_in_window: 4)",
      "- `m2` (applied_in_window: 4)",
      "- `m3` (applied_in_window: 4)",
    ];
    expect(topItemLines(lines, 2)).toEqual(lines.slice(0, 2));
  });

  test("top-N selection keeps the survivors in render order", () => {
    const lines = [
      "- `m1` (applied_in_window: 3)",
      "- `m2` (applied_in_window: 9)",
      "- `m3` (applied_in_window: 6)",
      "- `m4` (applied_in_window: 1)",
    ];
    // Top three by count are m2, m3, m1; rendered in their original order.
    expect(topItemLines(lines, 3)).toEqual([
      "- `m1` (applied_in_window: 3)",
      "- `m2` (applied_in_window: 9)",
      "- `m3` (applied_in_window: 6)",
    ]);
  });

  test("a limit at or below zero keeps nothing; a limit past the end keeps everything", () => {
    const lines = ["- `m1` (applied_in_window: 3)", "- `m2` (applied_in_window: 9)"];
    expect(topItemLines(lines, 0)).toEqual([]);
    expect(topItemLines(lines, 10)).toEqual(lines);
  });

  test("deterministic and pure: identical calls agree, inputs untouched", () => {
    const lines = [
      "- `m1` (applied_in_window: 3)",
      "- `q1` (applied: 1 / violated: 1) β€” x",
      "- `c1` (confidence: high (0.95)) β€” y",
      "stray tail",
    ];
    const snapshot = [...lines];
    expect(topItemLines(lines, 4)).toEqual(topItemLines(lines, 4));
    expect(compareItemLines(lines[0]!, lines[1]!)).toBe(compareItemLines(lines[0]!, lines[1]!));
    expect(lines).toEqual(snapshot);
  });
});

describe("joinedSectionsLength", () => {
  test("is the character length of the separator-joined sections", () => {
    expect(joinedSectionsLength([{ text: "aaa" }, { text: "bb" }])).toBe("aaa\n\nbb".length);
    expect(joinedSectionsLength([{ text: "only" }])).toBe(4);
    expect(joinedSectionsLength([])).toBe(0);
  });
});