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
4.7 KB
Raw Blame
/**
 * Pure scoring function over vault-maintenance signals. Replaces the
 * vague "Recommendation:" text that earlier digests carried with a
 * deterministic ranked list of operator-actionable next steps.
 *
 * The scorer takes already-collected inputs (page dedup candidates,
 * stale-lifecycle pages, broken merged-link rewrites, token-footprint
 * excess) and emits a sorted list of {@link ActionItem} ordered by
 * impact descending. The function is pure: every input is a typed
 * shape, no I/O. Use with `findDuplicateCandidates`, `lintConsolidate`,
 * and `computeTokenFootprint` outputs upstream.
 */

export type ActionCategory = "dedup" | "lifecycle" | "merged-link" | "token-footprint";

export interface ActionItem {
  readonly id: string;
  readonly category: ActionCategory;
  readonly title: string;
  readonly impact: number;
  /** Optional target reference (page id, file path, etc). */
  readonly target?: string;
}

export interface ActionInputs {
  readonly dedupCandidates?: ReadonlyArray<{
    readonly canonicalId: string;
    readonly secondaryCount: number;
  }>;
  readonly staleByLifecycle?: ReadonlyArray<{
    readonly id: string;
    readonly ageDays: number;
  }>;
  readonly brokenLinks?: ReadonlyArray<{
    readonly path: string;
    readonly from: string;
  }>;
  readonly tokenFootprint?: {
    readonly total: number;
    readonly warnThreshold: number;
  };
}

const WEIGHT = Object.freeze({
  dedupPerSecondary: 8,
  staleLifecyclePerYear: 4,
  brokenLink: 5,
  tokenFootprintExcessPer10k: 3,
});

function scoreDedup(inputs: NonNullable<ActionInputs["dedupCandidates"]>): ActionItem[] {
  const out: ActionItem[] = [];
  for (const c of inputs) {
    if (c.secondaryCount <= 0) continue;
    out.push({
      id: `dedup:${c.canonicalId}`,
      category: "dedup",
      title: `Merge ${c.secondaryCount} duplicate(s) into ${c.canonicalId}`,
      impact: c.secondaryCount * WEIGHT.dedupPerSecondary,
      target: c.canonicalId,
    });
  }
  return out;
}

function scoreStale(inputs: NonNullable<ActionInputs["staleByLifecycle"]>): ActionItem[] {
  const out: ActionItem[] = [];
  for (const s of inputs) {
    if (s.ageDays <= 0) continue;
    const years = Math.max(0.5, s.ageDays / 365);
    out.push({
      id: `lifecycle:${s.id}`,
      category: "lifecycle",
      title: `Re-verify or demote stale stable: ${s.id}`,
      impact: Math.round(years * WEIGHT.staleLifecyclePerYear),
      target: s.id,
    });
  }
  return out;
}

function scoreBrokenLinks(inputs: NonNullable<ActionInputs["brokenLinks"]>): ActionItem[] {
  // Bucket by source path so the report does not duplicate noisy
  // file-level recommendations when one page has many broken links.
  const byPath = new Map<string, number>();
  for (const l of inputs) {
    byPath.set(l.path, (byPath.get(l.path) ?? 0) + 1);
  }
  const out: ActionItem[] = [];
  for (const [path, count] of byPath) {
    out.push({
      id: `merged-link:${path}`,
      category: "merged-link",
      title: `Rewrite ${count} merged-link reference(s) in ${path}`,
      impact: count * WEIGHT.brokenLink,
      target: path,
    });
  }
  return out;
}

function scoreTokenFootprint(input: NonNullable<ActionInputs["tokenFootprint"]>): ActionItem[] {
  const excess = input.total - input.warnThreshold;
  if (excess <= 0) return [];
  const buckets = Math.ceil(excess / 10_000);
  return [
    {
      id: "token-footprint:vault",
      category: "token-footprint",
      title: `Vault exceeds warn threshold by ${excess} tokens; archive or split`,
      impact: buckets * WEIGHT.tokenFootprintExcessPer10k,
      target: "vault",
    },
  ];
}

export interface ScoreOptions {
  /** Cap on returned items. Default 10. */
  readonly topN?: number;
}

export function scoreActions(
  inputs: ActionInputs,
  opts: ScoreOptions = {},
): ReadonlyArray<ActionItem> {
  const all: ActionItem[] = [];
  if (inputs.dedupCandidates) all.push(...scoreDedup(inputs.dedupCandidates));
  if (inputs.staleByLifecycle) all.push(...scoreStale(inputs.staleByLifecycle));
  if (inputs.brokenLinks) all.push(...scoreBrokenLinks(inputs.brokenLinks));
  if (inputs.tokenFootprint) all.push(...scoreTokenFootprint(inputs.tokenFootprint));

  all.sort((a, b) => {
    if (b.impact !== a.impact) return b.impact - a.impact;
    if (a.category !== b.category) return a.category < b.category ? -1 : 1;
    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
  });

  // Clamp + floor opts.topN so negative or fractional input cannot
  // produce slice(0, -n) (which silently truncates from the tail
  // in JS semantics) or off-by-one truncation.
  const capRaw = opts.topN ?? 10;
  const cap = Number.isFinite(capRaw) ? Math.max(0, Math.floor(capRaw)) : 10;
  return Object.freeze(all.slice(0, cap));
}