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
8.8 KB
Raw Blame
/**
 * `o2b brain context-pack` - return the highest-tier, most recent
 * vault slice that fits under a caller-specified token budget.
 * Intended for agents priming a context window without manual page
 * curation. `--query <q>` adds a case/Unicode-insensitive substring
 * filter on topic + principle.
 *
 * `--max-tokens` is optional (t_a567cc12): when it is omitted, the
 * budget derives from the model context window the shared resolver
 * resolves - the vault's `context:` block, the environment override, or
 * `--model`, in that precedence - through the matching preset. A
 * hint-matching id budgets from its preset hint, the same mapping
 * `brain context-presets suggest` answers. An id nothing published
 * places - no table row, no `1m` suffix, no hint - is refused: pass
 * `--max-tokens` or set `context.window_tokens`. With nothing resolvable
 * the verb refuses exactly as it always has: never a silent default
 * budget.
 */

import {
  presetForResolvedWindow,
  unrecognisedModelBudgetRefusal,
} from "../../../core/brain/context-presets.ts";
import {
  resolveModelContextWindowTokens,
  type ModelWindowSource,
} from "../../../core/brain/model-window.ts";
import { resolveModelContextWindowEnvTokens } from "../../../core/config.ts";
import { packContext } from "../../../core/brain/context-pack.ts";
import { loadBrainConfig } from "../../../core/brain/policy.ts";
import { RECALL_CHANNEL } from "../../../core/brain/recall-telemetry.ts";
import { brainVerbContext, fail, okJson, parse } from "../helpers.ts";

export async function cmdBrainContextPack(argv: string[]): Promise<number> {
  const { flags } = parse(argv, {
    vault: { type: "string" },
    json: { type: "boolean" },
    "max-tokens": { type: "string" },
    model: { type: "string" },
    query: { type: "string" },
    lanes: { type: "boolean" },
    receipt: { type: "boolean" },
    "receipt-host": { type: "string" },
    telemetry: { type: "boolean" },
    "telemetry-host": { type: "string" },
    "session-id": { type: "string" },
    "turn-id": { type: "string" },
    "cache-stable": { type: "boolean" },
    "dedup-repeated": { type: "boolean" },
  });
  const { vault } = brainVerbContext(flags);

  const model = trimOrUndefined(flags["model"]);
  const maxTokensRaw = trimOrUndefined(flags["max-tokens"]);
  let maxTokens: number;
  let maxTokensSource: ModelWindowSource | undefined;
  if (maxTokensRaw !== undefined) {
    // Strict integer parsing - `Number()` rejects partial numeric
    // strings like "12abc" that `parseInt` would silently accept.
    maxTokens = Number(maxTokensRaw);
    if (!Number.isInteger(maxTokens) || maxTokens <= 0) {
      return fail(
        `brain context-pack: --max-tokens must be a positive integer; got ${maxTokensRaw}`,
      );
    }
  } else {
    // Derivation path (t_a567cc12). The vault channel is fail-soft: a
    // broken `_brain.yaml` raises later, inside `packContext`, exactly as
    // it always has. A malformed env value refuses here under its own
    // name - an operator typo must not silently shrink the budget to the
    // default.
    const operatorWindow = contextWindowConfigValue(vault);
    let envWindow: number | undefined;
    try {
      envWindow = resolveModelContextWindowEnvTokens();
    } catch (exc) {
      return fail(`brain context-pack: ${(exc as Error).message}`);
    }
    if (model === undefined && operatorWindow === undefined && envWindow === undefined) {
      return fail("brain context-pack: --max-tokens <n> is required");
    }
    const resolved = resolveModelContextWindowTokens({
      ...(model !== undefined ? { model } : {}),
      ...(operatorWindow !== undefined ? { operatorWindowTokens: operatorWindow } : {}),
      ...(envWindow !== undefined ? { envWindowTokens: envWindow } : {}),
    });
    // The hint fallback rides along exactly when the resolver's answer is
    // the default-sourced assumption, so a hint-only model budgets the
    // preset `brain context-presets suggest` names for it; the source
    // printed below stays the window's. An id NOTHING places - no table
    // row, no suffix, no hint - refuses instead: the conservative posture
    // this verb held before derivation existed, never the default
    // window's long-context budget an 8k local model cannot hold.
    const refusal = unrecognisedModelBudgetRefusal(model, resolved);
    if (refusal !== null) return fail(`brain context-pack: ${refusal}`);
    maxTokens = presetForResolvedWindow(model, resolved).context_pack.max_tokens;
    maxTokensSource = resolved.source;
  }

  // `packContext` reads the guardrail block and raises on a `_brain.yaml`
  // the operator wrote and broke. Without this boundary that raise left
  // the verb as a stack trace naming this repo's files instead of theirs;
  // every sibling verb on the same path already reports
  // `<verb> failed: <cause>`.
  let report;
  try {
    report = packContext(vault, {
      maxTokens,
      ...(flags["query"] ? { query: flags["query"] as string } : {}),
      ...(flags["lanes"] === true ? { includeLanes: true } : {}),
      ...(flags["receipt"] === true
        ? {
            receipt: {
              host: trimOrDefault(flags["receipt-host"], "cli"),
              trigger: "context_pack" as const,
              ...(trimOrUndefined(flags["session-id"]) !== undefined
                ? { sessionId: trimOrUndefined(flags["session-id"]) }
                : {}),
              ...(trimOrUndefined(flags["turn-id"]) !== undefined
                ? { turnId: trimOrUndefined(flags["turn-id"]) }
                : {}),
            },
          }
        : {}),
      ...(flags["cache-stable"] === true || flags["dedup-repeated"] === true
        ? {
            transforms: {
              ...(flags["cache-stable"] === true ? { cacheStableOrdering: true } : {}),
              ...(flags["dedup-repeated"] === true ? { deduplicateRepeatedContext: true } : {}),
            },
          }
        : {}),
      ...(flags["telemetry"] === true
        ? {
            telemetry: {
              host: trimOrDefault(flags["telemetry-host"], RECALL_CHANNEL.cli),
              channel: RECALL_CHANNEL.cli,
              ...(trimOrUndefined(flags["session-id"]) !== undefined
                ? { sessionId: trimOrUndefined(flags["session-id"]) }
                : {}),
              ...(trimOrUndefined(flags["turn-id"]) !== undefined
                ? { turnId: trimOrUndefined(flags["turn-id"]) }
                : {}),
            },
          }
        : {}),
    });
  } catch (exc) {
    return fail(`context-pack failed: ${(exc as Error).message ?? exc}`);
  }

  if (flags["json"]) {
    okJson({
      max_tokens: report.maxTokens,
      ...(maxTokensSource !== undefined ? { max_tokens_source: maxTokensSource } : {}),
      tokens_used: report.tokensUsed,
      items: report.items.map((i) => ({
        id: i.id,
        path: i.path,
        tier: i.tier,
        tokens: i.tokens,
        epistemic: i.epistemic,
        ...(i.evidenceRefs.length > 0 ? { evidence_refs: i.evidenceRefs } : {}),
        ...(i.originalRank !== undefined ? { original_rank: i.originalRank } : {}),
        ...(i.stableRank !== undefined ? { stable_rank: i.stableRank } : {}),
        ...(i.dedupedFrom !== undefined ? { deduped_from: i.dedupedFrom } : {}),
        ...(i.referenceHint !== undefined ? { reference_hint: i.referenceHint } : {}),
      })),
      skipped: report.skipped,
      ...(report.receiptId ? { receipt_id: report.receiptId } : {}),
      ...(report.telemetryId ? { telemetry_id: report.telemetryId } : {}),
      ...(report.lanes ? { lanes: report.lanes } : {}),
    });
    return 0;
  }

  process.stdout.write(`tokens used: ${report.tokensUsed} / ${report.maxTokens}\n`);
  if (maxTokensSource !== undefined) {
    process.stdout.write(`budget source: ${maxTokensSource}\n`);
  }
  process.stdout.write(`pages included: ${report.items.length}\n`);
  process.stdout.write(`pages skipped: ${report.skipped.length}\n\n`);
  if (report.receiptId) process.stdout.write(`receipt: ${report.receiptId}\n`);
  for (const i of report.items) {
    process.stdout.write(`[${i.tier}] ${i.epistemic} ${i.id} (${i.tokens} tokens)\n`);
  }
  return 0;
}

/**
 * The vault's declared `context.window_tokens`; `undefined` when the
 * block is absent or the file cannot be read. Fail-soft on purpose: a
 * broken `_brain.yaml` raises later, inside `packContext`, exactly as it
 * always has.
 */
function contextWindowConfigValue(vault: string): number | undefined {
  try {
    return loadBrainConfig(vault).context?.window_tokens;
  } catch {
    return undefined;
  }
}

function trimOrDefault(value: string | boolean | string[] | undefined, fallback: string): string {
  return trimOrUndefined(value) ?? fallback;
}

function trimOrUndefined(value: string | boolean | string[] | undefined): string | undefined {
  if (typeof value !== "string") return undefined;
  const trimmed = value.trim();
  return trimmed.length > 0 ? trimmed : undefined;
}