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
9.2 KB
Raw Blame
/**
 * The `active:` block — what `Brain/active.md` renders and how much of it
 * is injected at SessionStart.
 *
 * One reason to change: the size of the agent's always-on preamble -
 * which is why the cap on the operator's standing-rules block lives here
 * too, even though that block is exempt from the injection budget and
 * charged against its own number.
 * Out-of-range values are hard errors: an operator-tunable knob that
 * silently reverted to its default would be indistinguishable from never
 * having been set.
 */

import type { BrainActiveConfig, BrainConfig, BrainMostAppliedConfig } from "../../types.ts";
import {
  STANDING_RULES_MAX_CHARS_DEFAULT,
  STANDING_RULES_MAX_CHARS_MAX,
  STANDING_RULES_MAX_CHARS_MIN,
} from "../../standing-rules.ts";
import {
  SCOPED_RULES_MAX_CHARS_DEFAULT,
  SCOPED_RULES_MAX_CHARS_MAX,
  SCOPED_RULES_MAX_CHARS_MIN,
} from "../../scoped-rules.ts";
import { requireIntegerInRange } from "../field-checks.ts";
import { openBlock, warnUnknownKeys, type BlockParseContext } from "../key-index.ts";

const BLOCK = "active";

/**
 * Bounds applied to `active.most_applied.{window_days, limit}` at load
 * time. Values outside these ranges are hard errors — clamping silently
 * would mask the operator's intent.
 */
export const MOST_APPLIED_WINDOW_DAYS_MIN = 1;
export const MOST_APPLIED_WINDOW_DAYS_MAX = 365;
export const MOST_APPLIED_LIMIT_MIN = 1;
export const MOST_APPLIED_LIMIT_MAX = 50;
/** Default window when `_brain.yaml` lacks `active.most_applied.window_days`. */
export const MOST_APPLIED_WINDOW_DAYS_DEFAULT = 30;
/** Default top-N limit when `_brain.yaml` lacks `active.most_applied.limit`. */
export const MOST_APPLIED_LIMIT_DEFAULT = 10;

/**
 * The window every most-applied consumer uses when `_brain.yaml` does not
 * configure one. One struct rather than two loose constants, because both
 * readers of this block (`active.md` and the digest) need the pair
 * together and a half-taken default would report a window the operator
 * never chose.
 */
export const BRAIN_MOST_APPLIED_DEFAULTS: BrainMostAppliedConfig = Object.freeze({
  window_days: MOST_APPLIED_WINDOW_DAYS_DEFAULT,
  limit: MOST_APPLIED_LIMIT_DEFAULT,
});

/**
 * Character budget for the active.md body injected at SessionStart
 * (token-diet, t_40eb1de7). ~2K tokens - enough for every confirmed
 * rule on a typical vault, small enough that a runaway preference set
 * cannot flood the session preamble. Override via
 * `active.inject_budget_chars`.
 */
export const INJECT_BUDGET_CHARS_DEFAULT = 8000;
export const INJECT_BUDGET_CHARS_MIN = 500;
export const INJECT_BUDGET_CHARS_MAX = 200_000;

/**
 * Per-lane caps for the opt-in cross-agent log catch-up SessionStart
 * lane (t_3b44cd9a). The lane is a standalone process - it pays no
 * `inject_budget_chars` - so it carries its own caps instead: the newest
 * {@link LOG_CATCHUP_MAX_LINES} other-agent log lines are shown and the
 * count of older ones is stated rather than rendered, and the fenced
 * block is trimmed to {@link LOG_CATCHUP_MAX_CHARS} by dropping the
 * oldest lines first. Deliberately constants, not config keys: a runaway
 * catch-up must be bounded by the same review that bounds every other
 * injected lane, not by a knob an agent could turn up.
 */
export const LOG_CATCHUP_MAX_LINES = 50;
export const LOG_CATCHUP_MAX_CHARS = 6000;

const KNOWN_KEYS = [
  "most_applied_window_days",
  "most_applied_limit",
  "inject_budget_chars",
  "standing_rules_max_chars",
  "scoped_rules_max_chars",
  "topic_heads_max",
  "topic_heads_max_chars",
  "pinned_max_chars",
] as const;

/**
 * The YAML keys are flat at level 2 to fit the existing two-level
 * parser; the in-memory shape `BrainActiveConfig.most_applied` still
 * groups them so downstream consumers (`active.md`, `brain_digest`)
 * can pass one struct around.
 */
export function parseActiveBlock(ctx: BlockParseContext): BrainActiveConfig | undefined {
  const activeMap = openBlock(ctx, BLOCK);
  if (activeMap === undefined) return undefined;

  const mostApplied = parseMostApplied(activeMap, ctx.source);

  const injectBudgetChars = optionalCharCount(
    activeMap,
    "inject_budget_chars",
    INJECT_BUDGET_CHARS_MIN,
    INJECT_BUDGET_CHARS_MAX,
    ctx.source,
  );
  const standingRulesMaxChars = optionalCharCount(
    activeMap,
    "standing_rules_max_chars",
    STANDING_RULES_MAX_CHARS_MIN,
    STANDING_RULES_MAX_CHARS_MAX,
    ctx.source,
  );
  const scopedRulesMaxChars = optionalCharCount(
    activeMap,
    "scoped_rules_max_chars",
    SCOPED_RULES_MAX_CHARS_MIN,
    SCOPED_RULES_MAX_CHARS_MAX,
    ctx.source,
  );
  const topicHeadsMax = optionalIntCount(activeMap, "topic_heads_max", 1, 1000, ctx.source);
  const topicHeadsMaxChars = optionalCharCount(
    activeMap,
    "topic_heads_max_chars",
    0,
    INJECT_BUDGET_CHARS_MAX,
    ctx.source,
  );
  const pinnedMaxChars = optionalCharCount(
    activeMap,
    "pinned_max_chars",
    0,
    INJECT_BUDGET_CHARS_MAX,
    ctx.source,
  );

  warnUnknownKeys(ctx, activeMap, KNOWN_KEYS, BLOCK);
  return {
    ...(mostApplied !== undefined ? { most_applied: mostApplied } : {}),
    ...(injectBudgetChars !== undefined ? { inject_budget_chars: injectBudgetChars } : {}),
    ...(standingRulesMaxChars !== undefined
      ? { standing_rules_max_chars: standingRulesMaxChars }
      : {}),
    ...(scopedRulesMaxChars !== undefined ? { scoped_rules_max_chars: scopedRulesMaxChars } : {}),
    ...(topicHeadsMax !== undefined ? { topic_heads_max: topicHeadsMax } : {}),
    ...(topicHeadsMaxChars !== undefined ? { topic_heads_max_chars: topicHeadsMaxChars } : {}),
    ...(pinnedMaxChars !== undefined ? { pinned_max_chars: pinnedMaxChars } : {}),
  };
}

/**
 * Read one optional character-count knob: absent stays absent so the
 * consumer's own default applies, present is range-checked as a hard
 * error. Every count knob in this block is the same shape, and writing the
 * `in`-check plus the range call twice is how the second one eventually
 * gets a clamped bound the first does not have.
 */
function optionalCharCount(
  activeMap: Readonly<Record<string, unknown>>,
  key: string,
  min: number,
  max: number,
  source: string | null,
): number | undefined {
  if (!(key in activeMap)) return undefined;
  requireIntegerInRange(`${BLOCK}.${key}`, activeMap[key], min, max, source);
  return activeMap[key] as number;
}

/** {@link optionalCharCount} for a whole-number count knob (`topic_heads_max`). */
function optionalIntCount(
  activeMap: Readonly<Record<string, unknown>>,
  key: string,
  min: number,
  max: number,
  source: string | null,
): number | undefined {
  return optionalCharCount(activeMap, key, min, max, source);
}

/**
 * Read side of `active.most_applied`: the configured window, or
 * {@link BRAIN_MOST_APPLIED_DEFAULTS} when the block (or the whole
 * `active:` section) was omitted. Shared by `active.md` and the digest so
 * the two cannot report different windows for the same vault.
 */
export function resolveMostApplied(cfg: BrainConfig): BrainMostAppliedConfig {
  return cfg.active?.most_applied ?? BRAIN_MOST_APPLIED_DEFAULTS;
}

/**
 * Read side of `active.standing_rules_max_chars`: the configured cap, or
 * the reader's default. Takes a nullable config so the two callers - the
 * SessionStart hook, which absorbs an unreadable `_brain.yaml` into the
 * defaults, and `brain_context`, which does the same - resolve the
 * number through one function instead of each spelling the fallback.
 */
export function resolveStandingRulesMaxChars(cfg: BrainConfig | null): number {
  return cfg?.active?.standing_rules_max_chars ?? STANDING_RULES_MAX_CHARS_DEFAULT;
}

/**
 * Read side of `active.scoped_rules_max_chars`: the configured cap on the
 * scoped operator rules block, or its default. Unlike the constitution's
 * cap this block is CHARGED against `inject_budget_chars`: the SessionStart
 * hook clamps it to what `inject_budget_chars` leaves once the block's
 * header and notice reserve are taken (`scopedSectionCap`), so the whole
 * block fits the budget it is charged against; `brain_context` applies the
 * cap alone.
 */
export function resolveScopedRulesMaxChars(cfg: BrainConfig | null): number {
  return cfg?.active?.scoped_rules_max_chars ?? SCOPED_RULES_MAX_CHARS_DEFAULT;
}

/**
 * Either key alone opts the block in; the other one falls back to its
 * default, so `most_applied` is always a complete struct or absent
 * entirely and consumers never see a half-configured window.
 */
function parseMostApplied(
  activeMap: Readonly<Record<string, unknown>>,
  source: string | null,
): BrainMostAppliedConfig | undefined {
  const hasWindow = "most_applied_window_days" in activeMap;
  const hasLimit = "most_applied_limit" in activeMap;
  if (!hasWindow && !hasLimit) return undefined;

  const windowDays = hasWindow
    ? activeMap["most_applied_window_days"]
    : MOST_APPLIED_WINDOW_DAYS_DEFAULT;
  const limit = hasLimit ? activeMap["most_applied_limit"] : MOST_APPLIED_LIMIT_DEFAULT;
  requireIntegerInRange(
    "active.most_applied_window_days",
    windowDays,
    MOST_APPLIED_WINDOW_DAYS_MIN,
    MOST_APPLIED_WINDOW_DAYS_MAX,
    source,
  );
  requireIntegerInRange(
    "active.most_applied_limit",
    limit,
    MOST_APPLIED_LIMIT_MIN,
    MOST_APPLIED_LIMIT_MAX,
    source,
  );
  return { window_days: windowDays as number, limit: limit as number };
}