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.8 KB
Raw Blame
import { resolveModelContextWindowTokens, type ResolvedModelWindow } from "./model-window.ts";

export type ContextPresetId = "tight-context" | "long-context";
export type ContextPresetConfidence = "high" | "medium" | "low";

export interface ContextBudgetPreset {
  readonly id: ContextPresetId;
  readonly label: string;
  readonly model_hints: ReadonlyArray<string>;
  readonly context_window_tokens: {
    readonly min: number;
    readonly max: number | null;
  };
  readonly context_pack: {
    readonly max_tokens: number;
    readonly max_chars_per_memory: number;
    readonly max_total_chars: number;
  };
  readonly pre_compress: {
    readonly top_k: number;
    readonly max_chars_per_memory: number;
    readonly max_total_chars: number;
  };
}

export interface ContextPresetSuggestionInput {
  readonly model?: string;
  readonly contextWindowTokens?: number;
}

export interface ContextPresetSuggestion {
  readonly preset_id: ContextPresetId;
  readonly confidence: ContextPresetConfidence;
  readonly reason: string;
  readonly preset: ContextBudgetPreset;
  /**
   * Present only when the window was RESOLVED from the model id through
   * the shared resolver AND that resolution decided the preset (a
   * declared table hit, a `1m` suffix, or the default when no hint
   * outranks it). An explicit window is the caller's own number, and a
   * hint-only model answers from its hint: neither claims a resolved
   * window.
   */
  readonly resolvedWindow?: ResolvedModelWindow;
}

export interface ContextPresetCurrentConfig {
  readonly context_pack?: Partial<ContextBudgetPreset["context_pack"]>;
  readonly pre_compress?: Partial<ContextBudgetPreset["pre_compress"]>;
  readonly overrides?: ReadonlyArray<string>;
}

export interface ContextPresetChange {
  readonly path: string;
  readonly current: number | null;
  readonly preset: number;
}

export interface ContextPresetDiff {
  readonly preset_id: ContextPresetId;
  readonly changes: ReadonlyArray<ContextPresetChange>;
  readonly preserved_overrides: ReadonlyArray<ContextPresetChange>;
  readonly unchanged: ReadonlyArray<string>;
  readonly invalid_overrides: ReadonlyArray<string>;
}

const PRESETS: ReadonlyArray<ContextBudgetPreset> = Object.freeze([
  Object.freeze({
    id: "tight-context",
    label: "Tight context",
    model_hints: Object.freeze(["mini", "small", "flash", "haiku"]),
    context_window_tokens: Object.freeze({ min: 0, max: 32_000 }),
    context_pack: Object.freeze({
      max_tokens: 4_000,
      max_chars_per_memory: 1_200,
      max_total_chars: 6_000,
    }),
    pre_compress: Object.freeze({
      top_k: 5,
      max_chars_per_memory: 800,
      max_total_chars: 4_000,
    }),
  }),
  Object.freeze({
    id: "long-context",
    label: "Long context",
    model_hints: Object.freeze(["sonnet", "opus", "pro", "large"]),
    context_window_tokens: Object.freeze({ min: 32_001, max: null }),
    context_pack: Object.freeze({
      max_tokens: 24_000,
      max_chars_per_memory: 4_000,
      max_total_chars: 30_000,
    }),
    pre_compress: Object.freeze({
      top_k: 20,
      max_chars_per_memory: 2_000,
      max_total_chars: 16_000,
    }),
  }),
]);

const PRESET_FIELDS = Object.freeze([
  "context_pack.max_tokens",
  "context_pack.max_chars_per_memory",
  "context_pack.max_total_chars",
  "pre_compress.top_k",
  "pre_compress.max_chars_per_memory",
  "pre_compress.max_total_chars",
]);

export function listContextPresets(): ReadonlyArray<ContextBudgetPreset> {
  return PRESETS;
}

export function getContextPreset(id: string): ContextBudgetPreset | null {
  return PRESETS.find((preset) => preset.id === id) ?? null;
}

/**
 * The preset whose window bucket contains `window`. The one definition of
 * the bucket mapping - suggest sizes from it, and so does every surface
 * that derives a budget from a resolved window (t_a567cc12) - so a caller
 * can never size from a different mapping than a suggestion named. A
 * budget derived for a MODEL goes through {@link presetForResolvedWindow},
 * which layers the shared hint fallback on this mapping when the
 * resolver's answer is the default-sourced assumption.
 */
export function presetForWindowTokens(window: number): ContextBudgetPreset {
  const hit = PRESETS.find(
    (preset) =>
      window >= preset.context_window_tokens.min &&
      (preset.context_window_tokens.max === null || window <= preset.context_window_tokens.max),
  );
  // The buckets tile [0, ∞), so the fallback is unreachable; it keeps the
  // compiler honest without inventing a third preset.
  return hit ?? PRESETS[0]!;
}

/**
 * The `model_hints` fallback, defined once: the preset whose hint list
 * contains a whole token of the id - the lowercased id split on
 * `[-_.:/@\s]+`, and the hint must EQUAL one token, so "mini" never
 * matches inside "gemini" while a real `mini` token still does.
 * {@link suggestContextPreset} answers from it when the resolver has
 * nothing published to say, and {@link presetForResolvedWindow} budgets
 * from it on exactly the same condition - so a hint-only model suggests
 * and budgets one mapping.
 */
function hintPresetForModel(model: string | null | undefined): ContextBudgetPreset | null {
  const id = model?.toLowerCase() ?? "";
  if (id === "") return null;
  const tokens = new Set(id.split(/[-_.:/@\s]+/));
  return PRESETS.find((preset) => preset.model_hints.some((hint) => tokens.has(hint))) ?? null;
}

/**
 * The pack-budget refusal for a model id nothing published places: no
 * declared table row, no `1m`/`[1m]` suffix, no matching hint. The
 * derived budget used to answer such an id with the default window's
 * long-context `max_tokens` - about three times an 8k local model's
 * whole window - so the pack surfaces refuse instead, the conservative
 * posture they held before derivation existed. `null` means the id IS
 * placed and budgets from its resolved window (table, suffix) or its
 * hint. A blank or absent model is ABSENT - the same condition the
 * surfaces' nothing-resolvable refusal already answers - so the two
 * refusals agree, and {@link suggestContextPreset} answers its
 * conservative fallback on exactly this predicate.
 */
export function unrecognisedModelBudgetRefusal(
  model: string | null | undefined,
  resolved: ResolvedModelWindow,
): string | null {
  if (resolved.source !== "default") return null;
  const id = model?.trim() ?? "";
  if (id !== "" && hintPresetForModel(id) !== null) return null;
  return id === ""
    ? "model not recognised; pass max_tokens or set context.window_tokens"
    : `model '${id}' not recognised; pass max_tokens or set context.window_tokens`;
}

/**
 * The preset a DERIVED budget sizes from for one model id: the mapping
 * the resolved window names - except when that answer is the resolver's
 * `default`-sourced assumption about the host, where the same
 * `model_hints` fallback {@link suggestContextPreset} answers with
 * applies, so a hint-only id (the reviewed disagreement: `gemini-2.5-flash`
 * suggested tight-context from its hint while the pack budgeted
 * long-context from the default window) budgets and suggests one mapping.
 * An id the table knows resolves from the table on both surfaces and
 * never from its hint; a model-free call (an operator channel resolved
 * the window) has no hint to apply and sizes from the resolved window.
 * An id NOTHING places (default source, no hint) never reaches a pack
 * budget from here - the pack surfaces refuse it first through
 * {@link unrecognisedModelBudgetRefusal} - and the pre-compress caps
 * path, which must always answer, keeps this mapping for it.
 * The window's `source` stays what the surface discloses either way.
 */
export function presetForResolvedWindow(
  model: string | null | undefined,
  resolved: ResolvedModelWindow,
): ContextBudgetPreset {
  if (resolved.source === "default") {
    const byHint = hintPresetForModel(model);
    if (byHint !== null) return byHint;
  }
  return presetForWindowTokens(resolved.windowTokens);
}

/**
 * The conservative fallback, defined once: tight-context, low
 * confidence, the answer for every call nothing published places - a
 * model-free call, or a model id with no window source, no suffix and no
 * hint. Never claims a resolved window.
 */
function conservativeFallbackSuggestion(): ContextPresetSuggestion {
  const fallback = PRESETS[0]!;
  return {
    preset_id: fallback.id,
    confidence: "low",
    reason: "no model or context-window hint matched; using conservative default",
    preset: fallback,
  };
}

export function suggestContextPreset(input: ContextPresetSuggestionInput): ContextPresetSuggestion {
  const model = input.model?.toLowerCase() ?? "";

  // Order (deliberate, changed by this branch from the hint-first order
  // it replaced): an explicit window wins over a matching `model_hints`
  // token. The window is authoritative - it is the caller's own
  // number for the deployment at hand, the same figure a derived budget
  // sizes from, just as the operator-config channel is authoritative in
  // the resolver - while a hint is a heuristic read off the id, and a
  // hint answers only when the resolver has nothing published to say. A
  // caller passing both therefore gets the window's mapping, and nothing
  // is resolved: the number was given, not inferred.
  const window = input.contextWindowTokens;
  if (window !== undefined && Number.isFinite(window)) {
    const byWindow = presetForWindowTokens(window);
    return {
      preset_id: byWindow.id,
      confidence: "high",
      reason: `context window ${window} tokens matched ${byWindow.id}`,
      preset: byWindow,
    };
  }

  // The window resolves FIRST, through the same resolver every derived
  // budget sizes from, so a suggestion can never name a different mapping
  // than the pack uses for the same model: a table-declared id that also
  // matches a hint answers from the table here AND in the pack budget
  // (the reviewed disagreement), and a hint-only id falls to the SAME
  // `model_hints` fallback on both surfaces - the pack derivation applies
  // it through presetForResolvedWindow whenever the resolver's
  // answer is the default-sourced assumption. A hint never masquerades as
  // a resolved window: the hint answer claims no `resolvedWindow`.
  if (model !== "") {
    const resolved = resolveModelContextWindowTokens({ model: input.model });
    if (resolved.source !== "default") {
      const byWindow = presetForWindowTokens(resolved.windowTokens);
      const clampedNote = resolved.clamped ? " (clamped)" : "";
      return {
        preset_id: byWindow.id,
        confidence: "high",
        reason: `context window ${resolved.windowTokens} tokens resolved from ${resolved.source}${clampedNote} matched ${byWindow.id}`,
        preset: byWindow,
        resolvedWindow: resolved,
      };
    }
    const byModel = hintPresetForModel(input.model);
    if (byModel) {
      return {
        preset_id: byModel.id,
        confidence: "high",
        reason: `model hint matched ${byModel.id}`,
        preset: byModel,
      };
    }
    // Nothing published places the id: the resolver's answer is the
    // default-sourced assumption and no hint matched, so the conservative
    // fallback answers - the same tight-context/low answer a model-free
    // call gets, and the exact condition the pack budget surfaces refuse
    // on ({@link unrecognisedModelBudgetRefusal}). An ASSUMED window is
    // never a basis for a suggestion: no `resolvedWindow` is claimed.
    return conservativeFallbackSuggestion();
  }

  return conservativeFallbackSuggestion();
}

export function diffContextPreset(
  id: string,
  current: ContextPresetCurrentConfig,
): ContextPresetDiff {
  const preset = getContextPreset(id);
  if (preset === null) throw new Error(`unknown context preset: ${id}`);

  const overrides = new Set(current.overrides ?? []);
  const validFields = new Set(PRESET_FIELDS);
  const changes: ContextPresetChange[] = [];
  const preserved: ContextPresetChange[] = [];
  const unchanged: string[] = [];

  for (const path of PRESET_FIELDS) {
    const presetValue = valueAt(preset, path)!;
    const currentValue = valueAt(current, path);
    if (currentValue === presetValue) {
      unchanged.push(path);
      continue;
    }
    const change = { path, current: currentValue, preset: presetValue };
    if (overrides.has(path)) preserved.push(change);
    else changes.push(change);
  }

  return Object.freeze({
    preset_id: preset.id,
    changes: Object.freeze(changes),
    preserved_overrides: Object.freeze(preserved),
    unchanged: Object.freeze(unchanged),
    invalid_overrides: Object.freeze([...overrides].filter((path) => !validFields.has(path))),
  });
}

function valueAt(
  obj: ContextBudgetPreset | ContextPresetCurrentConfig,
  path: string,
): number | null {
  const [section, key] = path.split(".") as ["context_pack" | "pre_compress", string];
  const sectionValue = obj[section] as Record<string, number | undefined> | undefined;
  const value = sectionValue?.[key];
  return typeof value === "number" ? value : null;
}