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
9.8 KB
Raw Blame
/**
 * Skill auto-attach (Agent Surface Suite, t_10b86707).
 *
 * Deterministic per-turn skill relevance: score discovered skills
 * against the current turn text with the shared lexical scorer and
 * render a small Markdown block of the top matches. No LLM in the
 * loop; the same query, skill set and usage input always produce the
 * same block. The char budget drops whole trailing entries - a
 * half-rendered skill line would read as a different skill.
 *
 * Ranking is the scorer's by default. When the caller supplies a usage
 * weight map (t_5d1ec8a8), candidates near the top are reordered by a
 * bounded composite of lexical score and observed invocation weight
 * (see {@link SKILL_USAGE_ORDERING_MAX_BOOST}); with the input absent
 * the output is byte-identical to the scorer's order, so existing
 * callers are untouched.
 *
 * Two properties were added in t_ccb05134:
 *
 *   - A discriminating-term floor. BM25 already down-weights a term the
 *     whole corpus carries, but down-weighted is not dropped: a candidate
 *     whose ENTIRE match is such terms still outscores nothing and still
 *     gets offered. It should not be. See
 *     {@link DISCRIMINATING_TERM_CORPUS_SHARE}.
 *   - An offer identity. The block cites the id of the offer it renders, so
 *     an agent invoking one of these skills can quote it back and the
 *     invocation becomes joinable to the offer. See `./skill-offer.ts`.
 */

import { isRareTerm } from "../search/coverage.ts";
import { skillDescriptors } from "./descriptor.ts";
import { scoreDescriptors, type ScoredDescriptor } from "./lexical-score.ts";
import { computeSkillOfferId, SKILL_OFFER_ID_KEY, SKILL_OFFER_ID_LENGTH } from "./skill-offer.ts";
import type { SkillEntry } from "./skills.ts";

export interface SkillAttachItem {
  readonly name: string;
  readonly description: string;
  readonly path: string;
  readonly score: number;
}

export interface SkillAttachment {
  /** Markdown block ("## Relevant skills" + bullets), "" when empty. */
  readonly block: string;
  readonly items: ReadonlyArray<SkillAttachItem>;
  /**
   * Content-addressed id of this offer, or null when nothing was offered.
   * Null is not a failure: an offer that was never made has no identity,
   * and inventing one would put an unbacked id into the join.
   */
  readonly offerId: string | null;
}

export interface BuildSkillAttachmentOptions {
  /** Current turn text to score against. */
  readonly query: string;
  readonly skills: ReadonlyArray<SkillEntry>;
  /** Maximum skills to attach. Default 3. */
  readonly maxSkills?: number;
  /** Char budget for the rendered block. Default 1200. */
  readonly maxChars?: number;
  /**
   * When set, the `triggers` field from each skill's frontmatter is
   * included in the lexical scorer as a 2x-BM25 tag signal. Default
   * false (name 3x + description 1x only).
   */
  readonly includeTriggers?: boolean;
  /**
   * Observed usage weight per discovered skill name, from
   * `skillUsageRankingWeights` (`../brain/skill-usage.ts`) - the ranking
   * weight, which normalises frequency against the largest joined count
   * and so does not saturate the way the decay weight `deriveSkillUsage`
   * reports does. When set and
   * non-empty, candidates near the top are reordered by
   * {@link SKILL_USAGE_ORDERING_MAX_BOOST}-bounded composite instead of
   * raw lexical score. Absent or empty keeps the scorer's order
   * (default off); the `score` field of every item stays the lexical
   * score either way, and the floor is never crossable by weight.
   */
  readonly usageWeight?: ReadonlyMap<string, number>;
}

export const DEFAULT_MAX_SKILLS = 3;
export const DEFAULT_MAX_CHARS = 1200;
const BLOCK_HEADER = "## Relevant skills";
const OFFER_LINE_PREFIX = "Offer ";
const OFFER_LINE_SUFFIX = ` - cite it as ${SKILL_OFFER_ID_KEY} when calling get_skill.`;
/**
 * Chars the offer line costs: a fixed-width id between two literals, plus
 * the blank line separating it from the bullets. Fixed width is why the
 * budget can reserve it before the id exists, without a second pass.
 */
const OFFER_LINE_BUDGET =
  OFFER_LINE_PREFIX.length + SKILL_OFFER_ID_LENGTH + OFFER_LINE_SUFFIX.length + 2;

/**
 * Share of the descriptor corpus a query term may appear in and still
 * discriminate between its members.
 *
 * A term more than half the descriptors carry cannot separate them: nearly
 * every candidate matches it, so it is evidence for none of them in
 * particular. A candidate whose entire match rests on such terms has not
 * been shown to be relevant to this turn and is dropped rather than offered.
 *
 * The only input is corpus document frequency, so the rule holds in any
 * language and there is no vocabulary list anywhere in its derivation - the
 * standing project position, and the reason the vault-side coverage engine
 * this shares {@link isRareTerm} with carries no stopword list either.
 *
 * The one-document floor inside `isRareTerm` matters here: a single-skill
 * corpus has df = the whole corpus for every term, so the floor makes the
 * rule abstain rather than drop the only candidate on no evidence.
 */
export const DISCRIMINATING_TERM_CORPUS_SHARE = 0.5;

/**
 * Largest multiplicative gain a usage weight may add to a candidate's
 * lexical score when the attach ordering runs with a usage map
 * (t_5d1ec8a8): the composite is
 * `score * (1 + SKILL_USAGE_ORDERING_MAX_BOOST * weight)` with weights in
 * (0, 1], so a candidate rises by at most half again its own lexical
 * score. Relevance stays primary - a wide lexical gap is never closed by
 * usage, only the near-ties the scorer cannot see break toward the skill
 * an agent actually invokes. The floor applies before the composite, so
 * no weight resurrects a non-discriminating candidate; the reported
 * `score` stays the untouched lexical score.
 */
export const SKILL_USAGE_ORDERING_MAX_BOOST = 0.5;

/**
 * Whether at least one term this candidate matched separates it from the
 * rest of the corpus.
 */
function hasDiscriminatingMatch(scored: ScoredDescriptor, corpusSize: number): boolean {
  return scored.matched.some((m) => isRareTerm(m.df, corpusSize, DISCRIMINATING_TERM_CORPUS_SHARE));
}

function renderLine(item: SkillAttachItem): string {
  return `- ${item.name} - ${item.description} (load with get_skill: ${item.name})`;
}

function emptyAttachment(): SkillAttachment {
  return Object.freeze({ block: "", items: Object.freeze([]), offerId: null });
}

/**
 * The BM25 ranking with the discriminating-term floor, cut at `limit`.
 * `buildSkillAttachment` offers the first `maxSkills` of it; the optional
 * decision-model selection (`./skill-attach-decision.ts`) reads a longer
 * shortlist from the same ranking and never adds anything outside it.
 */
export function rankSkillCandidates(
  opts: Pick<BuildSkillAttachmentOptions, "query" | "skills" | "includeTriggers" | "usageWeight">,
  limit: number,
): SkillAttachItem[] {
  const byName = new Map(opts.skills.map((s) => [s.name, s]));
  const descriptors = skillDescriptors(opts.skills, opts.includeTriggers);
  const surviving = scoreDescriptors(opts.query, descriptors)
    // The floor filters, it never reorders, and no usage weight crosses it:
    // a candidate dropped here stays dropped. Without a usage map ranking
    // stays the scorer's; with one, the bounded composite below reorders
    // the survivors.
    .filter((scored) => hasDiscriminatingMatch(scored, descriptors.length));
  const usageWeight = opts.usageWeight;
  const ranked =
    usageWeight === undefined
      ? surviving.slice(0, limit)
      : surviving
          .map((scored) => ({
            scored,
            // Missing name means no observed invocation: weight 0, which
            // leaves the composite at the lexical score.
            composite:
              scored.score *
              (1 + SKILL_USAGE_ORDERING_MAX_BOOST * (usageWeight.get(scored.descriptor.name) ?? 0)),
          }))
          .toSorted(
            (a, b) =>
              b.composite - a.composite ||
              (a.scored.descriptor.name < b.scored.descriptor.name
                ? -1
                : a.scored.descriptor.name > b.scored.descriptor.name
                  ? 1
                  : 0),
          )
          .slice(0, limit)
          .map((entry) => entry.scored);
  const items: SkillAttachItem[] = [];
  for (const { descriptor, score } of ranked) {
    const skill = byName.get(descriptor.name);
    if (skill === undefined) continue;
    items.push(
      Object.freeze({
        name: skill.name,
        description: skill.description,
        path: skill.path,
        score,
      }),
    );
  }
  return items;
}

/**
 * Render ranked items into the attach block within the char budget, and
 * compute the offer id over exactly the items that fit.
 */
export function renderSkillAttachment(
  query: string,
  ranked: ReadonlyArray<SkillAttachItem>,
  maxChars: number = DEFAULT_MAX_CHARS,
): SkillAttachment {
  const items: SkillAttachItem[] = [];
  const lines: string[] = [];
  let used = BLOCK_HEADER.length + 2 + OFFER_LINE_BUDGET; // header + blank line + offer line
  for (const item of ranked) {
    const line = renderLine(item);
    if (used + line.length + 1 > maxChars) break;
    used += line.length + 1;
    items.push(item);
    lines.push(line);
  }

  if (items.length === 0) return emptyAttachment();
  const offerId = computeSkillOfferId(
    query,
    items.map((item) => ({ name: item.name, path: item.path })),
  );
  return Object.freeze({
    block: `${BLOCK_HEADER}\n\n${lines.join("\n")}\n\n${OFFER_LINE_PREFIX}${offerId}${OFFER_LINE_SUFFIX}`,
    items: Object.freeze(items),
    offerId,
  });
}

export function buildSkillAttachment(opts: BuildSkillAttachmentOptions): SkillAttachment {
  const maxSkills = opts.maxSkills ?? DEFAULT_MAX_SKILLS;
  const maxChars = opts.maxChars ?? DEFAULT_MAX_CHARS;
  return renderSkillAttachment(opts.query, rankSkillCandidates(opts, maxSkills), maxChars);
}