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.2 KB
Raw Blame
/**
 * Deterministic salience gate over the rollup ladder's fold set
 * (salience-lifecycle-enrichment, unit 1, t_de8a0b2d).
 *
 * ## What it governs, and what it does not
 *
 * The dream pass has no per-item model lane. Its entire model delegation
 * is the count-triggered rollup ladder (`rollup-ladder.ts`), which reads
 * one number - how many facts exist - and emits one envelope per fired
 * rung. So there is exactly one place a salience judgement can change
 * anything: WHICH facts are counted into that fold set. This module
 * decides that and nothing else. It never suppresses a preference, never
 * touches a retire, and never changes what the pass writes about a fact
 * it excluded.
 *
 * ## The formula
 *
 * Three signals already exist as pure functions elsewhere and are reused
 * verbatim - there is no second copy of their math here:
 *
 *   - `mass` — the dominant decayed outcome mass from `lessons.ts`,
 *     `max(positiveMass, negativeMass)`. Unbounded and >= 0. Contested
 *     evidence is loud, not cancelled: a fact people keep violating is
 *     as worth folding as one they keep applying.
 *   - `confidence` — the Wilson lower bound times freshness decay from
 *     `confidence.ts`, already in [0, 1].
 *   - `reuse` — the observed-reuse rate from `observed-use.ts`, already
 *     in [0, 1]: `(used - contradicted) / total`, clamped.
 *
 * `mass` is the only unbounded one, so it is mapped into [0, 1) by the
 * hyperbolic saturation `mass / (mass + HALF)`, which is monotone, zero
 * at zero, and exactly 0.5 at {@link SALIENCE_MASS_HALF_SATURATION}. The
 * combined score is then the weighted sum
 *
 *   score = W_mass * (mass / (mass + HALF))
 *         + W_confidence * confidence
 *         + W_reuse * reuse
 *
 * whose weights sum to 1, so the score is bounded to [0, 1] and each
 * weight reads directly as "how much of the score this signal can buy".
 * Mass leads because it is the only signal that grows with repeated
 * evidence; confidence is the corroboration term; reuse is the smallest
 * because it is the sparsest store in a young vault.
 *
 * No model, no cache, no prompt version. Recomputation is free, and a
 * cached verdict would be a second source of truth about a number three
 * pure functions already answer.
 *
 * ## Absent threshold is the documented default, not a fallback
 *
 * With `dream.salience_threshold` unset the gate is OPEN: nothing is
 * scored (so neither the log nor the continuity store is read), every
 * fact is admitted, and the verdict reports `threshold: null` so the
 * summary can say the gate was absent rather than omit the subject. A
 * malformed threshold is refused by name - the same doctrine
 * `dream-gates.ts` states for a malformed gate override, and for the
 * same reason: a knob that silently reverted is indistinguishable from
 * one the operator never set.
 */

import { vaultRelativeOf } from "./no-vault.ts";
import { computeConfidence } from "./confidence.ts";
import { computeLessons } from "./lessons.ts";
import { observedReuseRates } from "./observed-use.ts";
import { describe as describeValue } from "./policy/field-checks.ts";
import type { BrainConfig, BrainPreference } from "./types.ts";

/** Share of the score the decayed outcome mass can buy. */
export const SALIENCE_MASS_WEIGHT = 0.5;
/** Share of the score the Wilson-bound confidence can buy. */
export const SALIENCE_CONFIDENCE_WEIGHT = 0.3;
/** Share of the score the observed-reuse rate can buy. */
export const SALIENCE_REUSE_WEIGHT = 0.2;
/**
 * Decayed mass that maps to exactly half the mass component's range.
 * Two full-weight outcomes is the anchor: one event is an anecdote, two
 * is the smallest pattern the corroboration tier in `lessons.ts` also
 * recognises.
 */
export const SALIENCE_MASS_HALF_SATURATION = 2;
/** Decimal places every reported salience number is rounded to. */
const SALIENCE_PRECISION = 4;
/** The configuration key this gate reads, spelled as an operator writes it. */
export const SALIENCE_THRESHOLD_FIELD = "dream.salience_threshold";

/**
 * Raised when a salience input cannot be honoured exactly as given.
 * Carries the field and the offending value so a caller reading only the
 * error knows which signal to fix.
 */
export class SalienceGateError extends Error {
  /** `mass`, `confidence`, `reuse`, or the config key. */
  readonly field: string;
  /** The value as supplied. */
  readonly value: unknown;

  constructor(field: string, value: unknown, requirement: string) {
    super(`salience gate: ${field} ${requirement}; got ${describeValue(value)}`);
    this.name = "SalienceGateError";
    this.field = field;
    this.value = value;
  }
}

/** The three raw signals for one fact, as their source modules report them. */
export interface SalienceComponents {
  /** Dominant decayed outcome mass; unbounded, >= 0. */
  readonly mass: number;
  /** Wilson lower bound x freshness, in [0, 1]. */
  readonly confidence: number;
  /** Observed-reuse rate, in [0, 1]. */
  readonly reuse: number;
}

/** One fact's components plus the derived numbers the gate compares. */
export interface SalienceScore extends SalienceComponents {
  /** `mass` mapped into [0, 1) by the hyperbolic saturation. */
  readonly mass_component: number;
  /** Weighted sum of the three components, in [0, 1]. */
  readonly score: number;
}

/** A preference offered to the gate, as `scanBrain` already holds it. */
export interface SalienceCandidate {
  /** Absolute path of the preference file. */
  readonly path: string;
  readonly pref: BrainPreference;
}

/** One scored member of the fold set. */
export interface SalienceFoldItem {
  readonly pref_id: string;
  /** Vault-relative path, so the verdict survives a synced vault. */
  readonly path: string;
  readonly score: SalienceScore;
}

/** A fact the gate kept out of the fold set, with the reason in numbers. */
export interface SalienceExclusion extends SalienceComponents {
  readonly pref_id: string;
  readonly path: string;
  readonly score: number;
}

/**
 * What the gate decided for one pass.
 *
 * `threshold: null` is the OPEN gate: nothing was scored, `admitted`
 * equals `considered`, and `excluded` is empty. The field is always
 * present - a summary that omitted it could not tell an absent gate from
 * a gate that excluded nothing.
 */
export interface SalienceGateVerdict {
  readonly threshold: number | null;
  /** Facts offered to the gate. */
  readonly considered: number;
  /** Facts the rollup ladder counts. */
  readonly admitted: number;
  /** Every excluded fact, by name. Never truncated, never summarised. */
  readonly excluded: ReadonlyArray<SalienceExclusion>;
}

export interface SalienceFoldSetInput {
  /** The vault, or `null` with none (design D14). */
  readonly vault: string | null;
  readonly preferences: ReadonlyArray<SalienceCandidate>;
  readonly cfg: BrainConfig;
  readonly now: Date;
}

function round(n: number): number {
  const factor = 10 ** SALIENCE_PRECISION;
  return Math.round(n * factor) / factor;
}

/** Refuse a component outside its domain rather than clamping it. */
function requireUnitComponent(field: string, value: number): void {
  if (!Number.isFinite(value) || value < 0 || value > 1) {
    throw new SalienceGateError(field, value, "must be a number in [0, 1]");
  }
}

/**
 * Combine the three signals into one score. Pure, total, and monotone in
 * every component.
 */
export function scoreSalience(components: SalienceComponents): SalienceScore {
  const { mass, confidence, reuse } = components;
  if (!Number.isFinite(mass) || mass < 0) {
    throw new SalienceGateError("mass", mass, "must be a finite number >= 0");
  }
  requireUnitComponent("confidence", confidence);
  requireUnitComponent("reuse", reuse);
  const massComponent = round(mass / (mass + SALIENCE_MASS_HALF_SATURATION));
  return Object.freeze({
    mass,
    confidence,
    reuse,
    mass_component: massComponent,
    score: round(
      SALIENCE_MASS_WEIGHT * massComponent +
        SALIENCE_CONFIDENCE_WEIGHT * confidence +
        SALIENCE_REUSE_WEIGHT * reuse,
    ),
  });
}

/** Codepoint order, so the reported partition is machine-stable. */
function byPrefId(a: { pref_id: string }, b: { pref_id: string }): number {
  return a.pref_id < b.pref_id ? -1 : a.pref_id > b.pref_id ? 1 : 0;
}

/** The verdict for a vault with no configured threshold. Nothing is scored. */
export function openSalienceGate(considered: number): SalienceGateVerdict {
  return Object.freeze({
    threshold: null,
    considered,
    admitted: considered,
    excluded: Object.freeze([] as ReadonlyArray<SalienceExclusion>),
  });
}

/**
 * Partition a scored fold set at `threshold`. A fact scoring exactly the
 * threshold is admitted: the operator asked for "at least this salient".
 */
export function gateFoldSet(
  items: ReadonlyArray<SalienceFoldItem>,
  threshold: number,
): SalienceGateVerdict {
  requireUnitComponent(SALIENCE_THRESHOLD_FIELD, threshold);
  const excluded: SalienceExclusion[] = [];
  let admitted = 0;
  for (const entry of items) {
    if (entry.score.score >= threshold) {
      admitted++;
      continue;
    }
    excluded.push(
      Object.freeze({
        pref_id: entry.pref_id,
        path: entry.path,
        score: entry.score.score,
        mass: entry.score.mass,
        confidence: entry.score.confidence,
        reuse: entry.score.reuse,
      }),
    );
  }
  return Object.freeze({
    threshold,
    considered: items.length,
    admitted,
    excluded: Object.freeze(excluded.toSorted(byPrefId)),
  });
}

/**
 * Read the configured threshold, or `null` when the operator set none.
 * A present-but-malformed value is refused by name; it is never treated
 * as absent, because that would report an applied setting the pass did
 * not apply.
 */
export function resolveSalienceThreshold(cfg: BrainConfig): number | null {
  const raw: unknown = cfg.dream.salience_threshold;
  if (raw === undefined || raw === null) return null;
  if (typeof raw !== "number" || !Number.isFinite(raw) || raw < 0 || raw > 1) {
    throw new SalienceGateError(SALIENCE_THRESHOLD_FIELD, raw, "must be a number in [0, 1]");
  }
  return raw;
}

/**
 * Score every candidate against the three signal stores. Reads the log
 * (through `computeLessons`) and the continuity store (through
 * `observedReuseRates`) once for the whole set, never once per fact.
 */
export function collectSalienceFoldSet(
  input: SalienceFoldSetInput,
): ReadonlyArray<SalienceFoldItem> {
  const { vault, preferences, cfg, now } = input;
  if (preferences.length === 0) return Object.freeze([]);

  const lessons = computeLessons(
    vault,
    preferences.map((c) => c.pref),
    [],
    // The default limit is a rendering budget for `Brain/lessons.md`; a
    // gate that saw only the top twenty would score the rest as silent.
    { now, limit: preferences.length },
  );
  const massById = new Map<string, number>();
  for (const lesson of lessons) {
    massById.set(lesson.id, Math.max(lesson.positiveMass, lesson.negativeMass));
  }
  const reuseByKey = observedReuseRates(vault);

  return Object.freeze(
    preferences.map((candidate) => {
      const relative = vaultRelativeOf(candidate.path, vault);
      // Observed use is keyed by path when the emitter knew one, else by
      // id; the id is tried first so a record carrying both resolves the
      // same way every run.
      const reuse = reuseByKey.get(candidate.pref.id) ?? reuseByKey.get(relative);
      return Object.freeze({
        pref_id: candidate.pref.id,
        path: relative,
        score: scoreSalience({
          mass: massById.get(candidate.pref.id) ?? 0,
          confidence: computeConfidence(
            candidate.pref.applied_count,
            candidate.pref.violated_count,
            candidate.pref.last_evidence_at,
            cfg,
            now,
          ).value,
          reuse: reuse?.score ?? 0,
        }),
      });
    }),
  );
}

/**
 * Resolve the threshold and partition the fold set. With no threshold
 * configured this reads nothing at all, so a vault that never opted in
 * pays no I/O and behaves exactly as it did before the gate existed.
 */
export function applySalienceGate(input: SalienceFoldSetInput): SalienceGateVerdict {
  const threshold = resolveSalienceThreshold(input.cfg);
  if (threshold === null) return openSalienceGate(input.preferences.length);
  return gateFoldSet(collectSalienceFoldSet(input), threshold);
}