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.3 KB
Raw Blame
/**
 * Relation-aware recall polarity (recall-trust-suite, Feature A).
 *
 * Typed relation edges (src/core/graph/relation-vocab.ts) participate in
 * ranking with explicit polarity instead of being decorative metadata:
 *
 * - `superseded_by` marks the declaring page as a stale predecessor. When
 *   the predecessor matches a query, its score is demoted and the successor
 *   is boosted — pulled into the pool when it was not already retrieved —
 *   so a stale memory cannot outrank the memory that replaced it.
 * - `contradicts` is relevant-but-not-endorsing: both endpoints gain a
 *   warning-style `why_retrieved` reason and neither score moves.
 * - `related` / `extends` / `depends_on` / `refines` grant a small bounded
 *   directional boost to a co-retrieved target — always weaker than a
 *   direct text match.
 *
 * The pass is pure (no I/O): callers (search.ts) fetch the candidate
 * documents' typed edges and a successor-chunk lookup, then hand both in.
 * A pool with zero typed edges passes through bit-identically, so vaults
 * without typed relations are unaffected.
 */

import { clamp01 } from "../math.ts";
import type { BrainSearchResult } from "./types.ts";

/** Multiplier applied to a matched predecessor's score. */
export const SUPERSEDED_DEMOTION = 0.6;
/** The successor inherits this share of the predecessor's original score. */
export const SUCCESSOR_CARRY = 0.9;
/** Additive boost per positive relation edge between co-retrieved candidates. */
export const RELATION_BOOST_PER_EDGE = 0.02;
/** Cap on the total positive relation boost one result can accumulate. */
export const RELATION_BOOST_CAP = 0.04;

const POSITIVE_RELATIONS = new Set(["related", "extends", "depends_on", "refines"]);

/** One typed relation edge declared by a candidate document. */
export interface RelationEdge {
  readonly sourceDocumentId: number;
  readonly relation: string;
  /** Relation target as written in frontmatter (normalised wikilink id). */
  readonly target: string;
  /** Resolved target document id, or null when the target page is unknown. */
  readonly targetDocumentId: number | null;
}

/** Representative document head used when pulling in an absent successor. */
export interface SuccessorDoc {
  readonly documentId: number;
  readonly chunkId: number;
  readonly path: string;
  readonly title: string | null;
  readonly content: string;
  readonly startLine: number;
  readonly endLine: number;
}

export interface RelationPolarityInputs {
  readonly ranked: ReadonlyArray<BrainSearchResult>;
  /** Typed edges declared by the ranked candidates' documents. */
  readonly edges: ReadonlyArray<RelationEdge>;
  /** Lookup for a successor document absent from the pool; null = unknown. */
  readonly successorDoc: (documentId: number) => SuccessorDoc | null;
}

export interface RelationPolarityOptions {
  /**
   * History mode: keep matched predecessors undemoted and skip successor
   * pull-in. Informational reasons still land so callers can see the edge.
   */
  readonly includeSuperseded?: boolean;
}

/**
 * Per-result effect accumulators. Each is order-insensitive on its own
 * (min, max, capped sum), and the final score composes them exactly
 * once — so edge application order cannot change the outcome even for
 * a node that is simultaneously a demoted predecessor, a carried
 * successor, and a positive-relation target.
 */
interface Mutable {
  result: BrainSearchResult;
  reasons: string[];
  /** Multiplier on the original score; min over demotion edges. */
  demotionFactor: number;
  /** Successor carry floor; max over carried predecessor scores. */
  carriedScore: number;
  /** Additive positive-relation boost; capped sum. */
  positiveBoost: number;
}

function fmt(x: number): string {
  return x.toFixed(3);
}

/**
 * Apply relation polarity over the assembled candidate pool. Returns a new
 * re-sorted array; the inputs are never mutated. With zero edges the pool
 * is returned as-is (same array contents, same order).
 */
export function applyRelationPolarity(
  inputs: RelationPolarityInputs,
  opts: RelationPolarityOptions,
): BrainSearchResult[] {
  if (inputs.edges.length === 0) return [...inputs.ranked];
  const includeSuperseded = opts.includeSuperseded === true;

  const byDoc = new Map<number, Mutable[]>();
  const pool: Mutable[] = inputs.ranked.map((result) => {
    const m: Mutable = {
      result,
      reasons: [...result.reasons],
      demotionFactor: 1,
      carriedScore: 0,
      positiveBoost: 0,
    };
    const list = byDoc.get(result.documentId);
    if (list) list.push(m);
    else byDoc.set(result.documentId, [m]);
    return m;
  });

  const pulledIn = new Map<number, Mutable>();

  const successorEntries = (edge: RelationEdge): Mutable[] => {
    if (edge.targetDocumentId === null) return [];
    const present = byDoc.get(edge.targetDocumentId);
    if (present) return present;
    const already = pulledIn.get(edge.targetDocumentId);
    if (already) return [already];
    const doc = inputs.successorDoc(edge.targetDocumentId);
    if (!doc) return [];
    const m: Mutable = {
      result: Object.freeze({
        documentId: doc.documentId,
        chunkId: doc.chunkId,
        path: doc.path,
        title: doc.title,
        content: doc.content,
        startLine: doc.startLine,
        endLine: doc.endLine,
        score: 0,
        keywordScore: 0,
        semanticScore: 0,
        linkBoost: 0,
        recencyBoost: 0,
        searchType: "link" as const,
        reasons: Object.freeze([] as string[]),
      }),
      reasons: [],
      demotionFactor: 1,
      carriedScore: 0,
      positiveBoost: 0,
    };
    pulledIn.set(doc.documentId, m);
    return [m];
  };

  // Each branch only ACCUMULATES (min demotion factor, max carry, capped
  // additive boost); the score composes from the accumulators exactly
  // once below. Every accumulator is order-insensitive on its own, so
  // edge application order cannot change the final score — even for a
  // node that is simultaneously a demoted predecessor, a carried
  // successor, and a positive-relation target.
  for (const edge of inputs.edges) {
    if (edge.targetDocumentId !== null && edge.targetDocumentId === edge.sourceDocumentId) {
      continue; // self-edge: inert
    }
    const sources = byDoc.get(edge.sourceDocumentId) ?? [];
    if (sources.length === 0) continue;

    if (edge.relation === "superseded_by") {
      for (const src of sources) {
        pushUnique(src.reasons, `superseded_by: ${edge.target}`);
      }
      if (includeSuperseded || edge.targetDocumentId === null) continue;
      const successors = successorEntries(edge);
      if (successors.length === 0) continue; // unresolved successor: inert
      for (const src of sources) {
        const original = src.result.score;
        src.demotionFactor = Math.min(src.demotionFactor, SUPERSEDED_DEMOTION);
        const carried = clamp01(original * SUCCESSOR_CARRY);
        for (const succ of successors) {
          succ.carriedScore = Math.max(succ.carriedScore, carried);
          pushUnique(succ.reasons, `supersedes_matched: ${src.result.path}`);
        }
      }
      continue;
    }

    if (edge.relation === "contradicts") {
      for (const src of sources) {
        pushUnique(src.reasons, `contradicts: ${edge.target}`);
      }
      if (edge.targetDocumentId === null) continue;
      const targets = byDoc.get(edge.targetDocumentId) ?? [];
      for (const tgt of targets) {
        for (const src of sources) {
          pushUnique(tgt.reasons, `contradicted_by: ${src.result.path}`);
        }
      }
      continue;
    }

    if (POSITIVE_RELATIONS.has(edge.relation)) {
      if (edge.targetDocumentId === null) continue;
      const targets = byDoc.get(edge.targetDocumentId) ?? [];
      for (const tgt of targets) {
        const head = Math.min(RELATION_BOOST_PER_EDGE, RELATION_BOOST_CAP - tgt.positiveBoost);
        if (head <= 0) continue;
        tgt.positiveBoost += head;
        for (const src of sources) {
          pushUnique(tgt.reasons, `relation_boost: ${edge.relation} ${src.result.path}`);
          break; // one reason per edge, not per source chunk
        }
      }
    }
    // Unknown relation tokens (open vocabulary) carry no polarity: inert.
  }

  const out = [...pool, ...pulledIn.values()].map((m) => {
    // Single composition point: demote the original score, let a
    // successor carry floor it, then add the capped positive boost.
    const score = clamp01(
      Math.max(m.result.score * m.demotionFactor, m.carriedScore) + m.positiveBoost,
    );
    if (
      score === m.result.score &&
      m.reasons.length === m.result.reasons.length &&
      m.positiveBoost === 0
    ) {
      return m.result;
    }
    const extras: string[] = [];
    if (m.positiveBoost > 0) extras.push(`relation_polarity: +${fmt(m.positiveBoost)}`);
    return Object.freeze({
      ...m.result,
      score,
      reasons: Object.freeze([...m.reasons, ...extras]),
    });
  });

  // Same tie-break family as the ranker: score desc, keywordScore desc,
  // chunkId asc — deterministic for equal scores.
  out.sort((a, b) => {
    if (b.score !== a.score) return b.score - a.score;
    if (b.keywordScore !== a.keywordScore) return b.keywordScore - a.keywordScore;
    return a.chunkId - b.chunkId;
  });
  return out;
}

function pushUnique(list: string[], entry: string): void {
  if (!list.includes(entry)) list.push(entry);
}