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
12.9 KB
Raw Blame
/**
 * Shared, pure recall-budget primitive (v0.20.0).
 *
 * A single place to enforce character budgets on an ordered list of
 * recall entries, reused by `context-pack.ts` and
 * `brain_pre_compress_pack` so neither reimplements trimming. Two
 * independent dimensions:
 *
 *   - `maxCharsPerEntry` trims any single oversized entry's text (so one
 *     huge memory cannot crowd out the rest);
 *   - `maxTotalChars` caps the cumulative characters across the kept
 *     entries, discarding the lowest-priority overflow.
 *
 * Entries MUST arrive pre-sorted by priority (highest first); the
 * primitive preserves that order and trims/drops from the tail. Lengths
 * are measured in Unicode code points, so multi-byte scripts and astral
 * characters are counted and truncated without splitting a surrogate
 * pair. Pure and deterministic: no I/O, clock, or randomness.
 *
 * Per-entry trimming supports two strategies
 * (continuity-hygiene-freshness suite): the historical hard cut
 * (default, byte-identical) and an opt-in staged degradation ladder
 * that prefers structural boundaries - sentence terminators, then
 * whole leading lines - over cutting mid-sentence.
 */

export type CharBudgetDegradationMode = "hard-cut" | "staged";
export type CharBudgetDegradationStage = "sentence" | "lines" | "hard";

export interface CharBudgetOptions {
  /** Max code points per entry; <= 0 or undefined disables per-entry trimming. */
  readonly maxCharsPerEntry?: number;
  /** Max cumulative code points across kept entries; <= 0 or undefined disables. */
  readonly maxTotalChars?: number;
  /**
   * Per-entry trim strategy. `hard-cut` (default) keeps the historical
   * mid-sentence cut byte-identical; `staged` walks the deterministic
   * degradation ladder: sentence-boundary trim, then whole leading
   * lines, then hard cut.
   */
  readonly degradation?: CharBudgetDegradationMode;
}

export interface BudgetedEntry<T> {
  readonly item: T;
  /** Entry text after any per-entry trim. */
  readonly text: string;
  /** True when `text` was truncated by `maxCharsPerEntry`. */
  readonly trimmed: boolean;
  /** Ladder stage that produced the trim (staged mode only). */
  readonly degradation?: CharBudgetDegradationStage;
}

export interface CharBudgetResult<T> {
  readonly kept: ReadonlyArray<BudgetedEntry<T>>;
  /** Items dropped because the total-character cap was reached. */
  readonly dropped: ReadonlyArray<T>;
  /** Total code points across kept entries. */
  readonly totalChars: number;
}

function codePoints(s: string): string[] {
  return [...s];
}

/**
 * Sentence-terminator code points across scripts. Structural
 * punctuation only - Latin/Cyrillic terminators, ellipsis, CJK full
 * stops, Arabic question mark and full stop, Devanagari danda - never
 * language-specific wordlists.
 */
const SENTENCE_TERMINATORS = new Set([
  ".",
  "!",
  "?",
  "…", // horizontal ellipsis
  "。", // CJK full stop
  "!", // fullwidth exclamation
  "?", // fullwidth question
  "؟", // Arabic question mark
  "۔", // Arabic full stop
  "।", // Devanagari danda
  "॥", // Devanagari double danda
]);

interface DegradedText {
  readonly text: string;
  readonly stage: CharBudgetDegradationStage;
}

/**
 * Walk the degradation ladder for one over-budget entry: cut after the
 * last sentence terminator inside the window, else keep whole leading
 * lines that fit, else hard-cut. Pure and deterministic.
 */
function degradeEntry(cps: ReadonlyArray<string>, budget: number): DegradedText {
  const window = cps.slice(0, budget);

  // Stage 1: last sentence terminator inside the window.
  for (let i = window.length - 1; i >= 0; i--) {
    if (!SENTENCE_TERMINATORS.has(window[i]!)) continue;
    const candidate = window
      .slice(0, i + 1)
      .join("")
      .trimEnd();
    if (candidate.length > 0) return { text: candidate, stage: "sentence" };
    break;
  }

  // Stage 2: whole leading lines that fit the window.
  const windowText = window.join("");
  const lastBreak = windowText.lastIndexOf("\n");
  if (lastBreak > 0) {
    const candidate = windowText.slice(0, lastBreak).trimEnd();
    if (candidate.length > 0) return { text: candidate, stage: "lines" };
  }

  // Stage 3: the historical hard cut.
  return { text: windowText, stage: "hard" };
}

/**
 * Apply per-entry and total character caps to an ordered entry list.
 * With no caps set this is an identity pass (every entry kept, untrimmed,
 * nothing dropped).
 */
export function applyCharBudget<T>(
  entries: ReadonlyArray<{ readonly item: T; readonly text: string }>,
  opts: CharBudgetOptions,
): CharBudgetResult<T> {
  const perEntry = opts.maxCharsPerEntry && opts.maxCharsPerEntry > 0 ? opts.maxCharsPerEntry : 0;
  const total = opts.maxTotalChars && opts.maxTotalChars > 0 ? opts.maxTotalChars : 0;

  const kept: BudgetedEntry<T>[] = [];
  const dropped: T[] = [];
  let used = 0;

  for (const { item, text } of entries) {
    let outText = text;
    let trimmed = false;
    let stage: CharBudgetDegradationStage | undefined;
    if (perEntry > 0) {
      const cps = codePoints(text);
      if (cps.length > perEntry) {
        if (opts.degradation === "staged") {
          const degraded = degradeEntry(cps, perEntry);
          outText = degraded.text;
          stage = degraded.stage;
        } else {
          outText = cps.slice(0, perEntry).join("");
        }
        trimmed = true;
      }
    }
    const len = codePoints(outText).length;
    if (total > 0 && used + len > total) {
      // Lowest-priority overflow: drop and keep trying smaller tail
      // entries (matches the existing context-pack token-budget policy).
      dropped.push(item);
      continue;
    }
    used += len;
    kept.push({
      item,
      text: outText,
      trimmed,
      ...(stage !== undefined ? { degradation: stage } : {}),
    });
  }

  return Object.freeze({
    kept: Object.freeze(kept),
    dropped: Object.freeze(dropped),
    totalChars: used,
  });
}

/**
 * How a caller wants the correlated recall budget claimed, one claim
 * order per member (recall-lane-latency wave).
 *
 * The premise of one reading budget over which a packing order reorders
 * is false ACROSS surfaces - pages and the facts-side brief are
 * budgeted by two separate surfaces with separate caps - so this
 * vocabulary names the claim order over the populations that DO share
 * one budget. Neither member is the omitted default: the omitted pack
 * interleaves both populations by tier, while a named policy orders whole
 * lanes, reserves the attention charge up front instead of drawing it
 * last, and - through the pack-level application of the policy - refuses
 * a vault where one lane holds no candidate in reach, a call the omitted
 * pack succeeds on. `facts_first` claims for the distilled facts lane
 * first and the retired pages fill the exact remainder. `retired_first`
 * hands the first claim to the retired pages lane, so a retired page
 * keeps its budget share even when facts-side demand would have
 * exhausted the remainder.
 */
export const PACKING_POLICIES = Object.freeze(["facts_first", "retired_first"] as const);

export type PackingPolicy = (typeof PACKING_POLICIES)[number];

/** Narrow an untrusted string to a {@link PACKING_POLICIES} member. */
export function isPackingPolicy(value: unknown): value is PackingPolicy {
  return typeof value === "string" && (PACKING_POLICIES as ReadonlyArray<string>).includes(value);
}

/** One candidate in a budget lane, priced in the shared token currency. */
export interface RecallBudgetEntry<T> {
  readonly item: T;
  /** Estimated token cost of the entry AS THE LANE WOULD EMIT IT. */
  readonly tokens: number;
}

export type RecallBudgetLaneName = "pages" | "facts";

export interface RecallBudgetLaneResult<T> {
  /** Which lane this result describes. */
  readonly name: RecallBudgetLaneName;
  /**
   * The share of the total this lane ends up holding: the first
   * claimer's allocation is exactly what it claimed; the second lane's
   * is the exact remainder handed to it (which the lane may under-use).
   * The two allocations plus the reserved charge always sum to the
   * total.
   */
  readonly allocation: number;
  /** Entries whose cost fits the lane's window, in input order. */
  readonly kept: ReadonlyArray<T>;
  /** Entries that did not fit, in input order. */
  readonly dropped: ReadonlyArray<T>;
  /** Sum of kept entries' token costs. */
  readonly spent: number;
}

export interface RecallBudgetAllocation<TPage, TFacts> {
  /** The policy that decided the claim order. */
  readonly policy: PackingPolicy;
  /** The shared total the lanes claimed against. */
  readonly totalTokens: number;
  /** Tokens charged before either lane claimed (see the argument). */
  readonly reservedTokens: number;
  readonly pages: RecallBudgetLaneResult<TPage>;
  readonly facts: RecallBudgetLaneResult<TFacts>;
}

/**
 * Walk one lane's claim over a budget window: entries are kept whole,
 * in input order, while the running spend stays inside the window; the
 * first entry that would overflow is dropped and the walk CONTINUES, so
 * a smaller later entry still fits (the same policy the context-pack
 * token loop applies to `over-budget` candidates). An entry with a
 * non-finite or negative cost is dropped rather than charged. The
 * primitive never splits or trims an entry: per-lane native caps
 * (chars, note counts) stay lane-internal fit rules, exactly as today.
 * The returned `spent` never exceeds the window.
 */
function claimLane<T>(
  name: RecallBudgetLaneName,
  entries: ReadonlyArray<RecallBudgetEntry<T>>,
  window: number,
): RecallBudgetLaneResult<T> {
  const kept: T[] = [];
  const dropped: T[] = [];
  let spent = 0;
  for (const { item, tokens } of entries) {
    if (!Number.isFinite(tokens) || tokens < 0) {
      dropped.push(item);
      continue;
    }
    if (spent + tokens > window) {
      dropped.push(item);
      continue;
    }
    spent += tokens;
    kept.push(item);
  }
  return Object.freeze({
    name,
    allocation: spent,
    kept: Object.freeze(kept),
    dropped: Object.freeze(dropped),
    spent,
  });
}

/** A lane result with its allocation restated to the window it holds. */
function withHeldWindow<T>(
  walk: RecallBudgetLaneResult<T>,
  heldWindow: number,
): RecallBudgetLaneResult<T> {
  return walk.allocation === heldWindow ? walk : Object.freeze({ ...walk, allocation: heldWindow });
}

/**
 * Correlate two recall populations over ONE shared token budget
 * (recall-lane-latency wave), beside the shared trimming primitive
 * above: both lanes already denominate content with the same
 * `estimateTokens` currency, so tokens are the correlation currency and
 * each lane's native caps stay its own business.
 *
 * Pure and deterministic. Claiming is strictly sequential with no
 * minimum-page floor: the policy names the first claimer, that lane
 * claims greedily against everything left after the reserved charge,
 * and the second lane fills the exact remainder - so conservation holds
 * by construction: `pages.allocation + facts.allocation + reservedTokens`
 * equals `totalTokens` whenever the total is usable. The total never
 * grows. A non-finite or non-positive total is a fail-closed empty
 * allocation: no lane claims anything, and the reserved charge is
 * dropped with it. A reserved charge over the total is clamped to it,
 * leaving both lanes nothing.
 *
 * The reserved charge (default 0) is a fixed cost paid before either
 * lane claims - the pack's synthesized attention block, for instance -
 * reported back on the allocation so every consumer accounts it inside
 * the same total instead of letting a lane draw over it.
 */
export function allocateRecallBudget<TPage, TFacts>(
  totalTokens: number,
  pagesLane: ReadonlyArray<RecallBudgetEntry<TPage>>,
  factsLane: ReadonlyArray<RecallBudgetEntry<TFacts>>,
  policy: PackingPolicy,
  reservedTokens = 0,
): RecallBudgetAllocation<TPage, TFacts> {
  const usable = Number.isFinite(totalTokens) && totalTokens > 0;
  const reserved = usable ? Math.min(Math.max(reservedTokens, 0), totalTokens) : 0;
  const claimable = usable ? totalTokens - reserved : 0;
  // The first claimer's allocation is exactly what it claimed, so the
  // second lane is handed the precise remainder and the books always
  // balance against the total. The second lane holds its whole window
  // even when it under-uses it.
  if (policy === "retired_first") {
    const pages = claimLane("pages", pagesLane, claimable);
    const facts = withHeldWindow(
      claimLane("facts", factsLane, claimable - pages.spent),
      claimable - pages.spent,
    );
    return Object.freeze({
      policy,
      totalTokens: usable ? totalTokens : 0,
      reservedTokens: reserved,
      pages,
      facts,
    });
  }
  const facts = claimLane("facts", factsLane, claimable);
  const pages = withHeldWindow(
    claimLane("pages", pagesLane, claimable - facts.spent),
    claimable - facts.spent,
  );
  return Object.freeze({
    policy,
    totalTokens: usable ? totalTokens : 0,
    reservedTokens: reserved,
    pages,
    facts,
  });
}