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
20.9 KB
Raw Blame
/**
 * `brain_context_pack` (task 3.19): the composed context the agent
 * session opens with, assembled at the caller's reach from the rules,
 * digests, pinned context and session evidence the caller may read.
 * Split from `pack-tools.ts`; registration happens through that
 * module's registry, which preserves the public PACK_TOOLS surface.
 */

import {
  resolveDensityRankingContextPack,
  resolveEntityFactsContextPack,
  resolveRecallAdequacyThresholds,
  resolveRecallGateTelemetry,
  resolveSearchFocusContextPack,
  resolveTailTrimContextPack,
} from "../../core/config.ts";
import { resolveSearchConfig } from "../../core/search/index.ts";
import {
  loadBeliefSemanticRelevance,
  spentQueryDisclosure,
} from "../../core/brain/belief-semantic.ts";
import { readActiveSessionFocus } from "../../core/search/session-focus.ts";
import {
  CONTEXT_PACK_QUERY_MODES,
  ContextPackPackingLaneEmptyError,
  isContextPackQueryMode,
  packContext,
} from "../../core/brain/context-pack.ts";
import {
  isPackingPolicy,
  PACKING_POLICIES,
  type PackingPolicy,
} from "../../core/brain/recall-budget.ts";
import { assessRecallAdequacy } from "../../core/brain/recall-adequacy.ts";
import { recordRecallAdequacyDemand } from "../../core/brain/query-demand.ts";
import { emitGatedTelemetry } from "../../core/brain/continuity/emit.ts";
import {
  presetForResolvedWindow,
  unrecognisedModelBudgetRefusal,
} from "../../core/brain/context-presets.ts";
import { type ModelWindowSource, type ResolvedModelWindow } from "../../core/brain/model-window.ts";
import { ownerScopeView } from "../../core/brain/owner-scope-view.ts";
import { resolveOwnerScopeDelivery } from "../../core/brain/preferences-collect.ts";
import { INVALID_PARAMS, MCPError } from "../protocol.ts";
import type { ServerContext } from "../tool-contract.ts";
import { contextReach } from "../tool-contract.ts";
import { reachView } from "../../core/brain/reach-view.ts";
import { TRANSPORT_REACH } from "../../core/graph/transport-reach.ts";
import { vaultPathField } from "../vault-path-field.ts";
import { exceedsMcpQueryCap, MCP_QUERY_CAP_MESSAGE } from "../search-tools.ts";
import {
  coerceAgentScope,
  coerceDecisionAnswerable,
  coerceRecallAdequacyInput,
  DECISION_ANSWERABLE_ARG_NAME,
  coerceStr,
  coerceStrList,
  coerceBool,
} from "../coerce.ts";
import { decisionAnswerableFor } from "../decision-answerable.ts";
import { coercePositiveInteger, telemetryOptionsFromArgs } from "./shared.ts";
import {
  RECALL_SCORES_ARG_NAME,
  configuredDegradation,
  discloseSpentPackQuery,
  optionalModelArg,
  receiptOptionsFromArgs,
  resolveSurfaceModelWindow,
  semanticReportField,
  vaultRelative,
  withSearchErrorsOnWire,
} from "./pack-shared.ts";

export async function toolBrainContextPack(
  ctx: ServerContext,
  args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
  const model = optionalModelArg("brain_context_pack", args);
  const maxTokensArg = coercePositiveInteger(
    "brain_context_pack",
    "max_tokens",
    args["max_tokens"],
  );
  // The adequacy pairing is an input-SHAPE contract, declared in the
  // schema's `dependentRequired`, so it refuses an incomplete pair by
  // name before any semantic refusal can preempt it: `max_tokens` is now
  // optional behind the derivation below (t_a567cc12), and a payload
  // carrying one half of the pair must learn about the pairing, not about
  // a budget it never sent.
  const recallAttempt = coerceRecallAdequacyInput(
    "brain_context_pack",
    args,
    RECALL_SCORES_ARG_NAME,
  );
  const answerableArg = coerceDecisionAnswerable(
    "brain_context_pack",
    args,
    RECALL_SCORES_ARG_NAME,
    recallAttempt !== undefined,
  );
  // Derived budget (t_a567cc12): an explicit `max_tokens` is first-class
  // and untouched. When it is omitted, the budget derives from the model
  // context window the resolver resolves, through the matching preset's
  // `context_pack.max_tokens` - the curated mapping. A `default`-sourced
  // window defers to the model's hint preset, the same mapping
  // `brain_context_presets` suggest answers, so one model gets one budget
  // and one suggestion on every surface - and an id NOTHING places (no
  // table row, no suffix, no hint) refuses: the conservative posture this
  // tool held before derivation existed, never the default window's
  // long-context budget an 8k local model cannot hold. With nothing
  // resolvable the call refuses exactly as before: the pinned decision is
  // never a silent default budget.
  let maxTokens: number;
  let maxTokensSource: ModelWindowSource | undefined;
  if (maxTokensArg !== undefined) {
    maxTokens = maxTokensArg;
  } else {
    let resolved: ResolvedModelWindow | null;
    try {
      resolved = resolveSurfaceModelWindow(ctx.vault, model ?? undefined);
    } catch (e) {
      throw new MCPError(INVALID_PARAMS, `brain_context_pack: ${(e as Error).message}`);
    }
    if (resolved === null) {
      throw new MCPError(
        INVALID_PARAMS,
        "brain_context_pack: max_tokens must be a positive integer",
      );
    }
    const refusal = unrecognisedModelBudgetRefusal(model, resolved);
    if (refusal !== null) {
      throw new MCPError(INVALID_PARAMS, `brain_context_pack: ${refusal}`);
    }
    // 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
    // disclosed on the wire stays the window's.
    maxTokens = presetForResolvedWindow(model, resolved).context_pack.max_tokens;
    maxTokensSource = resolved.source;
  }
  const query = typeof args["query"] === "string" ? (args["query"] as string) : undefined;
  // Ranked query mode (v1.53.0). Enforced beside the `dependentRequired`
  // that declares it: a mode with no query would otherwise be accepted and
  // do nothing, which is the silent no-op this project refuses.
  const queryMode = coerceStr(args, "query_mode", false);
  if (queryMode !== null) {
    if (!isContextPackQueryMode(queryMode)) {
      throw new MCPError(
        INVALID_PARAMS,
        `brain_context_pack: query_mode must be one of ${CONTEXT_PACK_QUERY_MODES.join(", ")}`,
      );
    }
    if (query === undefined) {
      throw new MCPError(
        INVALID_PARAMS,
        "brain_context_pack: query_mode requires query; a mode with nothing to read is inert",
      );
    }
    // The semantic query is embedded once, ungated: a blank one buys nothing.
    if (queryMode === "semantic" && query.trim() === "") {
      throw new MCPError(
        INVALID_PARAMS,
        "brain_context_pack: query_mode requires a non-empty query",
      );
    }
  }
  // Opt-in packing policy (recall-lane-latency wave). Refused beside the
  // `dependentRequired` that declares it, exactly as query_mode is: a
  // policy with no query has no turn to pack for and would be the silent
  // no-op this project refuses. A blank or whitespace-only query is the
  // same refusal, not a pass: the empty string is dropped before the core
  // and the null query filter-passes every candidate, so the policy would
  // silently reorder an unordered pack - the exact evasion the raw read
  // above would otherwise allow.
  const packingPolicy = coerceStr(args, "packing_policy", false);
  if (packingPolicy !== null) {
    if (!isPackingPolicy(packingPolicy)) {
      throw new MCPError(
        INVALID_PARAMS,
        `brain_context_pack: packing_policy must be one of ${PACKING_POLICIES.join(", ")}`,
      );
    }
    if (query === undefined || query.trim() === "") {
      throw new MCPError(
        INVALID_PARAMS,
        "brain_context_pack: packing_policy requires query; a policy with nothing to order is inert",
      );
    }
  }
  if (query !== undefined && exceedsMcpQueryCap(query)) {
    throw new MCPError(INVALID_PARAMS, `brain_context_pack: ${MCP_QUERY_CAP_MESSAGE}`);
  }
  const includeLanes = coerceBool(args, "lanes");
  const cacheStable = coerceBool(args, "cache_stable");
  const dedupRepeated = coerceBool(args, "dedup_repeated");
  const attentionFlowIds = coerceStrList(args, "attention_flow_ids");
  const maxCharsPerMemory = coercePositiveInteger(
    "brain_context_pack",
    "max_chars_per_memory",
    args["max_chars_per_memory"],
  );
  const maxTotalChars = coercePositiveInteger(
    "brain_context_pack",
    "max_total_chars",
    args["max_total_chars"],
  );
  const receipt = receiptOptionsFromArgs("brain_context_pack", args, "context_pack", "mcp");
  const telemetry = telemetryOptionsFromArgs("brain_context_pack", args, "mcp");
  // The pairing coercions themselves ran above the budget derivation, so
  // an incomplete pair is refused by name; only the ASSESSMENT waits for
  // this point, beside the receipt and telemetry options it rides with.
  const adequacy =
    recallAttempt !== undefined
      ? assessRecallAdequacy(
          recallAttempt,
          resolveRecallAdequacyThresholds(ctx.configPath ?? undefined),
        )
      : undefined;
  // Advisory decision-model signal (issue #213, Part 8): annotates the
  // verdict and its receipt, never the level, the action or the pack.
  const answerable =
    adequacy !== undefined && answerableArg !== undefined
      ? decisionAnswerableFor(ctx, adequacy.level, answerableArg)
      : undefined;
  const answerableVerdict = answerable?.kind === "annotated" ? answerable.verdict : undefined;
  // signals-that-survive, unit 6: an unmet verdict is stamped onto the
  // cross-query demand log under the bucket key normalizeQueryTerms already
  // computes, so the knowledge-gap loop can aggregate recurrence without a
  // second identity concept.
  //
  // ONE opt-in for that log, on every surface that writes it: the
  // `recall_gate_telemetry` config key, exactly as `brain_recall_gate`
  // uses. It is a vault-level durable log feeding a vault-level loop, so
  // whether it is written is an operator decision, not a per-call one -
  // gating it here on this tool's `telemetry` ARGUMENT instead made one
  // feature answer to two different opt-ins and left the log's contents
  // depending on which surface a caller happened to use. That argument
  // keeps its own meaning: it selects whether THIS call emits its own
  // continuity records. Fail-open as ever - a log write never breaks the
  // pack.
  if (adequacy !== undefined && query !== undefined) {
    emitGatedTelemetry(resolveRecallGateTelemetry(ctx.configPath ?? undefined), () =>
      recordRecallAdequacyDemand(ctx.vault, { query, verdict: adequacy }),
    );
  }
  // Focus wiring (Agent Surface Suite, t_5b478e47): gated on the
  // search_focus_context_pack config key (default off) so the default
  // pack stays byte-identical. Fail-soft - a broken search config
  // never breaks the pack.
  let sessionFocus: ReturnType<typeof readActiveSessionFocus> = null;
  if (resolveSearchFocusContextPack(ctx.configPath ?? undefined)) {
    // Argument validation stays OUTSIDE the fail-soft block: an invalid
    // focus_session is a caller error (INVALID_PARAMS), not a config
    // read to swallow.
    const focusSession = coerceStr(args, "focus_session", false) ?? undefined;
    try {
      const searchConfig = resolveSearchConfig({
        vault: ctx.vault,
        configPath: ctx.configPath ?? undefined,
      });
      sessionFocus = readActiveSessionFocus(searchConfig, focusSession);
    } catch {
      sessionFocus = null;
    }
  }
  // Density-ranking wiring (impact-per-token allocation, t_affa3bd9):
  // gated on the density_ranking_context_pack config key (default off)
  // so the default pack stays byte-identical to the tier → recency order.
  const densityRanking = resolveDensityRankingContextPack(ctx.configPath ?? undefined);
  // Entity-facts wiring (dated commitments, t_43b0a379): gated on the
  // entity_facts_context_pack config key (default off) so the default
  // tool output carries no entity_facts key.
  const entityFacts = resolveEntityFactsContextPack(ctx.configPath ?? undefined);
  // Tail-trim wiring (t_cb6a5558): gated on the tail_trim_context_pack
  // config key (default off) so the default tool output carries no
  // tail_trim key and no trim ever runs.
  const tailTrim = resolveTailTrimContextPack(ctx.configPath ?? undefined);
  const agentScope = coerceAgentScope(ctx, args, true);
  // Root closure (t_sec_pack_reach): the pack reads page bodies by path,
  // outside the three read roots, so the reserved-token rule is asked per
  // candidate - the same shape `brain_clusters`/`brain_bridges` apply. It
  // is asked INSIDE the core, before ranking and budgeting, because every
  // other member of the report (`lanes`, `skipped`, tension `warnings`,
  // `deduped_from`, the receipt) is derived from the candidate set: a
  // filter over `items` alone left a reserved page's path and body in
  // `lanes` and its id in `skipped`. At local reach the view is the shared
  // no-op, so an operator's own transports see a byte-identical pack. The
  // core holds absolute paths; the view answers over vault-relative ones.
  const view = reachView(ctx.vault, contextReach(ctx));
  const remote = view.reach !== TRANSPORT_REACH.local;
  // Semantic mode (Honest Embedding Spend): the one async step - the query
  // embed and the stored-vector read - happens here, so `packContext`
  // stays synchronous for every other caller. Every refusal is a named
  // SearchError: a blocked tier and a missing sqlite-vec from the loader,
  // before any embed, and `BELIEF_VECTORS_MISSING` from the pack, after
  // the reach filter and before a receipt is written. The loader reads
  // only the beliefs this caller's pack can keep - the same reach and
  // owner views the pack applies - so its own pre-embed refusal never
  // answers for a withheld belief differently than for an absent one.
  const semantic =
    queryMode === "semantic" && query !== undefined
      ? await withSearchErrorsOnWire(() => {
          const owners = ownerScopeView(
            ctx.vault,
            resolveOwnerScopeDelivery(ctx.vault, agentScope).enforcedScope,
          );
          return loadBeliefSemanticRelevance(
            resolveSearchConfig({ vault: ctx.vault, configPath: ctx.configPath ?? undefined }),
            query,
            { reach: view.reach, inView: (rel) => view.visible(rel) && owners.visible(rel) },
          );
        })
      : null;
  let report: Awaited<ReturnType<typeof packContext>>;
  try {
    report = await withSearchErrorsOnWire(
      async () =>
        packContext(ctx.vault, {
          ...(remote
            ? { visible: (abs: string) => view.visible(vaultRelative(ctx.vault, abs)) }
            : {}),
          maxTokens,
          ...(agentScope !== undefined ? { agentScope } : {}),
          ...(densityRanking ? { densityRanking: true } : {}),
          ...(entityFacts ? { entityFacts: true } : {}),
          ...(tailTrim ? { tailTrim: true } : {}),
          ...(sessionFocus !== null ? { sessionFocus } : {}),
          ...(query ? { query } : {}),
          ...(queryMode !== null ? { queryMode } : {}),
          ...(packingPolicy !== null ? { packingPolicy: packingPolicy as PackingPolicy } : {}),
          ...(includeLanes ? { includeLanes: true } : {}),
          ...(receipt !== undefined ? { receipt } : {}),
          ...(adequacy !== undefined ? { recallAdequacy: adequacy } : {}),
          ...(answerableVerdict !== undefined ? { decisionAnswerable: answerableVerdict } : {}),
          ...(cacheStable || dedupRepeated
            ? {
                transforms: {
                  ...(cacheStable ? { cacheStableOrdering: true } : {}),
                  ...(dedupRepeated ? { deduplicateRepeatedContext: true } : {}),
                },
              }
            : {}),
          ...(maxCharsPerMemory !== undefined ? { maxCharsPerMemory } : {}),
          ...(maxTotalChars !== undefined ? { maxTotalChars } : {}),
          ...(configuredDegradation(ctx.vault) !== undefined
            ? { degradation: configuredDegradation(ctx.vault)! }
            : {}),
          ...(telemetry !== undefined ? { telemetry } : {}),
          // The synthesized attention-flow block has no page of its own to ask
          // the reach view about, so a remote caller does not get it (fail
          // closed, as the per-item filter this replaced did).
          ...(attentionFlowIds.length > 0 && !remote ? { attentionFlowIds } : {}),
          ...(semantic !== null ? { semanticRelevance: semantic.relevanceByPath } : {}),
        }),
      discloseSpentPackQuery(semantic),
    );
  } catch (e) {
    // A policy against a one-lane vault is a caller error the core
    // refuses by name; on the wire it is INVALID_PARAMS carrying that
    // same named message, never an internal error and never a no-op.
    if (e instanceof ContextPackPackingLaneEmptyError) {
      // The spend disclosure rides the refusal too: in semantic mode the
      // query embed was paid before the lanes were judged, and a refusal
      // that hides that spend under-discloses exactly when the caller
      // gets nothing back for it.
      throw new MCPError(
        INVALID_PARAMS,
        semantic !== null ? `${e.message} ${spentQueryDisclosure(semantic.report)}` : e.message,
      );
    }
    throw e;
  }
  const warnings = [
    ...(report.warnings ?? []),
    ...(semantic?.warnings ?? []),
    ...(answerable?.kind === "ignored" ? [answerable.warning] : []),
  ];
  return {
    vault_path: vaultPathField(ctx),
    max_tokens: report.maxTokens,
    // Present only when the budget was derived (t_a567cc12): the channel
    // that decided, so a caller can see a resolution was assumed rather
    // than paid for. An explicit `max_tokens` answers without it.
    ...(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,
      body: i.body,
      trimmed: i.trimmed,
      epistemic: i.epistemic,
      ...(i.evidenceRefs.length > 0 ? { evidence_refs: i.evidenceRefs } : {}),
      ...(i.density !== undefined ? { density: i.density } : {}),
      ...(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 } : {}),
      ...(i.safety ? { safety: i.safety } : {}),
    })),
    skipped: report.skipped.map((s) => ({
      id: s.id,
      tokens: s.tokens,
      reason: s.reason,
    })),
    ...(report.receiptId ? { receipt_id: report.receiptId } : {}),
    ...(report.telemetryId ? { telemetry_id: report.telemetryId } : {}),
    ...(report.lanes ? { lanes: report.lanes } : {}),
    // The core computes injection-time tension warnings and the
    // owner-scope observation and this projection dropped both, so the one
    // surface that puts vault text in front of a model every turn was the
    // one surface that could not say a memory it injected is contested.
    // `brain_pre_compress_pack` has forwarded them all along; absent when
    // empty, so a warning-free pack stays byte-identical.
    ...(warnings.length > 0 ? { warnings } : {}),
    ...(semantic !== null && report.semantic !== undefined
      ? { semantic: semanticReportField(semantic, report.semantic) }
      : {}),
    // The packing accounting appears only when the caller named a
    // policy - the same conditional shape as `semantic` above.
    ...(report.packing ? { packing: report.packing } : {}),
    // The entity-facts rollup appears only when the config key resolved
    // on - the same conditional shape as `packing` above. Fields project
    // to the tool's wire casing.
    ...(report.entityFacts
      ? {
          entity_facts: {
            entities: report.entityFacts.entities.map((e) => ({
              entity_id: e.entityId,
              name: e.name,
              item_ids: e.itemIds,
            })),
          },
        }
      : {}),
    // The trim block appears only when the config key resolved on AND
    // the pack actually trimmed - the same conditional shape as
    // `entity_facts` above. Fields project to the tool's wire casing.
    ...(report.tailTrim
      ? {
          tail_trim: {
            dropped: report.tailTrim.dropped,
            kept_by_query_terms: report.tailTrim.keptByQueryTerms,
            rescued: report.tailTrim.rescued,
            tokens_saved: report.tailTrim.tokensSaved,
          },
        }
      : {}),
    ...(adequacy !== undefined
      ? {
          adequacy: {
            level: adequacy.level,
            action: adequacy.action,
            escalate: adequacy.escalate,
            result_count: adequacy.resultCount,
            top_score: adequacy.topScore,
            mean_score: adequacy.meanScore,
            reason: adequacy.reason,
            ...(answerableVerdict !== undefined
              ? {
                  [DECISION_ANSWERABLE_ARG_NAME]: {
                    probability: answerableVerdict.probability,
                    disagrees: answerableVerdict.disagrees,
                  },
                }
              : {}),
          },
        }
      : {}),
  };
}