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
3.5 KB
Raw Blame
/**
 * The marginal-value stop, as a pure leaf (recall-quality wave, lane A).
 *
 * A page (or a retrieval round) is worth taking only while its value is
 * at least a floor fraction of the best sample's value; the floor rises
 * with observed latency, so a slow route demands denser pages. The
 * formula is the advisor's, extracted verbatim (t_3ffb021c) so the
 * consumers reusing it - the advisor's own allocation and the search-side
 * iterative loop, which feeds per-round candidate yields and elapsed time
 * instead of a pack curve - share one tuning rather than re-deriving
 * their own.
 *
 * This module is a LEAF by construction: it imports nothing, so a
 * consumer in the search pipeline can read the exact advisor formula
 * without dragging the advisor's dependency graph (plan, pack, doctor)
 * behind it - a graph whose load order a pipeline import once flipped
 * into a module-init cycle, which is why the extraction sits here rather
 * than beside its original.
 */

/**
 * Marginal-value stop: a page is worth including only while its density is at
 * least this fraction of the top page's density. The fraction is the base
 * plus a p95-scaled surcharge, so a slow route demands denser pages.
 */
export const STOP_BASE_FRACTION = 0.25;
/** p95 latency (ms) that adds the full {@link STOP_MAX_EXTRA_FRACTION} surcharge. */
export const STOP_P95_SCALE_MS = 4000;
/** Cap on the p95-driven surcharge added to {@link STOP_BASE_FRACTION}. */
export const STOP_MAX_EXTRA_FRACTION = 0.5;

/** The stop verdict over one density curve. */
export interface RetrievalPlanMarginalStop {
  /** Include this many leading pages; beyond it marginal value < cost. */
  readonly stopRank: number;
  /** Cumulative tokens of the leading pages up to the stop. */
  readonly stopTokens: number;
  readonly reason: string;
}

/**
 * Where to stop allocating along a density curve given observed latency.
 * Samples are read in order; the walk keeps pages whose density meets the
 * latency-scaled floor (always at least the first), and the token counts
 * ride along so the caller knows what the kept pages cost.
 *
 * Extracted verbatim from the advisor's private stop so other lanes can
 * reuse the exact formula rather than re-tuning their own: the advisor feeds
 * it the context-pack density curve and the route's p95, and its
 * `buildRetrievalPlan` output stays byte-identical to the pre-extraction
 * fixtures by construction. The search-side iterative loop feeds it
 * per-round candidate yields and elapsed time instead — samples, not pages.
 */
export function marginalValueStop(
  densityCurve: ReadonlyArray<number>,
  tokens: ReadonlyArray<number>,
  p95LatencyMs: number | null,
): RetrievalPlanMarginalStop {
  if (densityCurve.length === 0) {
    return Object.freeze({ stopRank: 0, stopTokens: 0, reason: "no candidates to allocate" });
  }
  const top = densityCurve[0]!;
  const surcharge = Math.min(
    STOP_MAX_EXTRA_FRACTION,
    (Math.max(0, p95LatencyMs ?? 0) / STOP_P95_SCALE_MS) * STOP_MAX_EXTRA_FRACTION,
  );
  const fraction = STOP_BASE_FRACTION + surcharge;
  const floor = top * fraction;
  let stopRank = 0;
  let stopTokens = 0;
  for (let i = 0; i < densityCurve.length; i++) {
    if (densityCurve[i]! < floor && stopRank >= 1) break;
    stopRank += 1;
    stopTokens += tokens[i] ?? 0;
  }
  return Object.freeze({
    stopRank,
    stopTokens,
    reason:
      `stop after ${stopRank} page(s): density floor ${floor.toFixed(4)} ` +
      `(${(fraction * 100).toFixed(0)}% of top) given p95 ${p95LatencyMs ?? 0}ms`,
  });
}