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
13.9 KB
Raw Blame
/**
 * Per-MOC topic-coverage audit.
 *
 * Given a hub note id, classify each member of the hub's outbound
 * cluster into:
 *   - `wellCovered`     - many inbound backlinks + body above floor
 *   - `fragile`         - one inbound backlink OR short body
 *   - `candidateMissing` - target referenced via `[[…]]` but no
 *                          on-disk artifact exists
 *   - `suggestedNext`   - the highest-leverage candidate-missing,
 *                          measured by reference count across hub +
 *                          cluster members
 *
 * MOC detection is purely structural: outbound link count + ratio
 * of link characters to non-whitespace body characters must cross
 * the thresholds in `link_graph` config. No vocabulary detection
 * of "this looks like a MOC because the title says so".
 *
 * That structural predicate lives in ONE exported place,
 * {@link isHubBody} / {@link evaluateHubBody}: the audit and the
 * inbox-drain hub selection (t_23bd347d) decide through the same
 * function, so there is exactly one definition of "hub".
 */

import { existsSync, readFileSync } from "node:fs";
import { join } from "node:path";

import { memoryFromStore, storePageInPreferenceFolders } from "../memory-pages.ts";
import { FRONTMATTER_RE } from "../../vault.ts";
import { buildBacklinkIndex } from "../backlinks.ts";
import { ownerScopeView } from "../owner-scope-view.ts";
import { brainDirs, vaultRelative } from "../paths.ts";
import { BRAIN_LINK_GRAPH_DEFAULTS, loadBrainConfig, resolveLinkGraph } from "../policy.ts";
import { normaliseWikilinkTarget } from "../wikilink.ts";
import { extractWikilinkRichBodies, parseWikilinkRich } from "./parse-wikilink.ts";
import { requireVaultAdapter, WIKILINK_AUDIT } from "../../vault-adapter/index.ts";

/** Inclusive minimum backlink count for the `wellCovered` bucket. */
const WELL_COVERED_MIN_BACKLINKS = 2;
/** Inclusive minimum body-character count for the `wellCovered` bucket. */
const WELL_COVERED_MIN_BODY_CHARS = 200;
/** Maximum backlink count that still qualifies for the `fragile` bucket. */
const FRAGILE_MAX_BACKLINKS = 1;

export class MocAuditError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "MocAuditError";
  }
}

export interface MocClusterMember {
  readonly id: string;
  readonly backlinkCount: number;
  readonly bodyChars: number;
}

export interface MocAuditReport {
  readonly hubId: string;
  readonly outboundCount: number;
  readonly wellCovered: ReadonlyArray<MocClusterMember>;
  readonly fragile: ReadonlyArray<MocClusterMember>;
  readonly candidateMissing: ReadonlyArray<{
    readonly id: string;
    readonly referenceCount: number;
  }>;
  readonly suggestedNext?: {
    readonly id: string;
    readonly referenceCount: number;
  };
}

export interface AuditMocOptions {
  /** When set, skip the `link_graph` config lookup and use this. */
  readonly minOutboundLinks?: number;
  /** When set, skip the `link_graph` config lookup and use this. */
  readonly minLinkRatio?: number;
  /**
   * Owner scope the cluster is filtered against
   * (a-label-is-not-a-boundary, U3). Absent / `null` filters nothing.
   *
   * A hidden member is dropped from EVERY bucket, not moved into
   * `candidateMissing`: reporting it as missing would answer the
   * exists-vs-absent question this audit exists to answer, in the
   * direction that says "no such artifact" about one that exists. It
   * simply does not appear, which is what "identical to absent" means
   * everywhere else in this vault. `bodyChars` sizes a private body and
   * `backlinkCount` counts references from artifacts the caller may not
   * see, so both follow the member out.
   */
  readonly ownerScope?: string | null;
  /**
   * May the caller read the page at this vault-relative path? Absent
   * reads every page. A hub it refuses answers as an absent hub, and a
   * member it refuses is dropped exactly as an owner-hidden member is:
   * not bucketed, not sized, and its links not counted toward a missing
   * target's `referenceCount`.
   */
  readonly readable?: (rel: string) => boolean;
  /**
   * The caller is below local reach: log events of the store's `private`
   * partition count toward no member's `backlinkCount` (passed to the
   * backlink index).
   */
  readonly withholdsPrivate?: boolean;
}

/** The structural hub thresholds (from `link_graph` config unless overridden). */
export interface HubBodyThresholds {
  /** Inclusive minimum of unique non-self outbound wikilink targets. */
  readonly minOutbound: number;
  /** Inclusive minimum of link characters over non-whitespace body characters. */
  readonly minRatio: number;
}

/** Options of the shared hub-body predicate. */
export interface HubBodyOptions {
  /**
   * Normalized wikilink id of the page the body belongs to; links to it are
   * not counted toward its own hubness, exactly as {@link auditMoc} never
   * counted a hub's link to itself. Absent / null excludes nothing.
   */
  readonly selfTarget?: string | null;
}

/** The outcome of the shared structural check over one page body. */
export interface HubBodyVerdict {
  /** True when the body crosses both thresholds. */
  readonly isHub: boolean;
  /** Unique non-self outbound wikilink targets, first-occurrence order. */
  readonly outboundTargets: ReadonlyArray<string>;
  /** Link characters over non-whitespace body characters. */
  readonly linkRatio: number;
}

/**
 * Evaluate the structural hub predicate over one page body: unique non-self
 * outbound wikilink targets >= `minOutbound` AND link ratio >= `minRatio`.
 *
 * This is THE definition of "hub" - `auditMoc` and the inbox-drain hub
 * selection (t_23bd347d) both decide through it, so the two can never drift
 * into two spellings of the same question.
 */
export function evaluateHubBody(
  body: string,
  thresholds: HubBodyThresholds,
  opts: HubBodyOptions = {},
): HubBodyVerdict {
  const selfTarget = opts.selfTarget ?? null;
  const outboundBodies = extractWikilinkRichBodies(body);
  const outboundTargets = uniq(
    outboundBodies
      .map((b) => parseWikilinkRich(b).target)
      .filter((t) => t.length > 0 && t !== selfTarget),
  );

  // Link-ratio: total characters inside `[[…]]` over non-whitespace
  // body characters. Whitespace is excluded from the denominator so
  // a heavily-indented link list isn't penalised against a compact
  // one. Numerator includes the four bracket characters (`[[]]`)
  // per link so a bracket-heavy body counts proportionally.
  const linkChars = outboundBodies.reduce((sum, b) => sum + b.length + 4, 0);
  const bodyChars = body.replace(/\s+/g, "").length;
  const ratio = bodyChars > 0 ? linkChars / bodyChars : 0;

  return {
    isHub: outboundTargets.length >= thresholds.minOutbound && ratio >= thresholds.minRatio,
    outboundTargets,
    linkRatio: ratio,
  };
}

/** Boolean form of {@link evaluateHubBody} for callers that need only the verdict. */
export function isHubBody(
  body: string,
  thresholds: HubBodyThresholds,
  opts: HubBodyOptions = {},
): boolean {
  return evaluateHubBody(body, thresholds, opts).isHub;
}

/**
 * The hub thresholds this vault's `link_graph` config resolves to, falling
 * back to the shipped defaults when the config cannot be read - the same
 * resolution `auditMoc` performs for its own audit.
 */
export function resolveHubThresholds(vault: string): HubBodyThresholds {
  let cfg;
  try {
    cfg = loadBrainConfig(vault);
  } catch {
    cfg = null;
  }
  const lg = cfg ? resolveLinkGraph(cfg) : null;
  return {
    minOutbound: lg ? lg.moc_min_outbound_links : BRAIN_LINK_GRAPH_DEFAULTS.moc_min_outbound_links,
    minRatio: lg ? lg.moc_min_link_ratio : BRAIN_LINK_GRAPH_DEFAULTS.moc_min_link_ratio,
  };
}

/** The {@link AuditMocOptions.readable} answer when none is given. */
const READ_EVERY_PAGE = (): boolean => true;

export function auditMoc(
  vaultOrNull: string | null,
  hubId: string,
  opts: AuditMocOptions = {},
): MocAuditReport {
  const vault = requireVaultAdapter(vaultOrNull, WIKILINK_AUDIT.mocAudit);
  const hubCanonical = normaliseWikilinkTarget(hubId);
  const view = ownerScopeView(vault, opts.ownerScope ?? null);
  const hub = locateArtifact(vault, hubCanonical);
  const hubPath = hub?.path ?? null;
  const readable = opts.readable ?? READ_EVERY_PAGE;
  // A hub the caller may not see reads as a hub that is not there: the
  // same sentence an absent hub produces, so the two are indistinguishable.
  if (!hubPath || !view.visible(hubCanonical) || !readable(vaultRelative(hubPath, vault))) {
    throw new MocAuditError(`hub note not found: ${hubCanonical}`);
  }

  const hubBody = stripFrontmatter(hub!.text());

  const thresholds = resolveThresholds(vault, opts);
  const verdict = evaluateHubBody(hubBody, thresholds, { selfTarget: hubCanonical });
  if (!verdict.isHub) {
    // The count is named first, exactly as the two checks were ordered when
    // they lived inline: a body below both thresholds reports the count.
    if (verdict.outboundTargets.length < thresholds.minOutbound) {
      throw new MocAuditError(
        `not a MOC: outbound link count ${verdict.outboundTargets.length} < threshold ${thresholds.minOutbound}`,
      );
    }
    throw new MocAuditError(
      `not a MOC: link ratio ${verdict.linkRatio.toFixed(2)} < threshold ${thresholds.minRatio}`,
    );
  }
  const outboundTargets = verdict.outboundTargets;

  // Backlink index + cluster member metadata.
  const index = buildBacklinkIndex(vault, view.scope, {
    withholdsPrivate: opts.withholdsPrivate === true,
  });
  const wellCovered: MocClusterMember[] = [];
  const fragile: MocClusterMember[] = [];
  const candidateMissing: { id: string; referenceCount: number }[] = [];
  const missingCounts = new Map<string, number>();

  for (const target of outboundTargets) {
    const located = locateArtifact(vault, target);
    const memberPath = located?.path ?? null;
    // A member this caller may not see leaves no trace in any bucket -
    // not even the missing one, which would decide exists-vs-absent for it.
    if (memberPath && (!view.visible(target) || !readable(vaultRelative(memberPath, vault)))) {
      continue;
    }
    if (!memberPath) {
      missingCounts.set(target, (missingCounts.get(target) ?? 0) + 1);
      continue;
    }
    const memberBody = stripFrontmatter(located!.text());
    const backlinks = index.get(target) ?? [];
    // Don't count the hub's own outbound reference toward the
    // bucket assignment; the bucket measures coverage by OTHER
    // notes, not by the hub itself.
    const inboundFromOthers = backlinks.filter((r) => r.source !== hubCanonical).length;
    const member: MocClusterMember = Object.freeze({
      id: target,
      backlinkCount: inboundFromOthers,
      bodyChars: memberBody.length,
    });
    if (
      inboundFromOthers >= WELL_COVERED_MIN_BACKLINKS &&
      memberBody.length >= WELL_COVERED_MIN_BODY_CHARS
    ) {
      wellCovered.push(member);
    } else if (inboundFromOthers <= FRAGILE_MAX_BACKLINKS) {
      fragile.push(member);
    }
    // Members between the two buckets (e.g. high backlinks but short
    // body) fall through; future releases can expose them under a
    // "developing" bucket if profile shows it pays.
  }

  // Walk cluster member bodies to find additional references to
  // missing targets (for the `referenceCount` field).
  for (const target of outboundTargets) {
    if (!missingCounts.has(target)) continue;
    for (const member of outboundTargets) {
      const found = locateArtifact(vault, member);
      if (!found || !view.visible(member) || !readable(vaultRelative(found.path, vault))) continue;
      const body = stripFrontmatter(found.text());
      for (const bracketBody of extractWikilinkRichBodies(body)) {
        const t = parseWikilinkRich(bracketBody).target;
        if (t === target) {
          missingCounts.set(target, (missingCounts.get(target) ?? 0) + 1);
        }
      }
    }
  }

  for (const [id, count] of missingCounts) {
    candidateMissing.push(Object.freeze({ id, referenceCount: count }));
  }
  candidateMissing.sort((a, b) => b.referenceCount - a.referenceCount);

  const suggestedNext = candidateMissing[0];

  return Object.freeze({
    hubId: hubCanonical,
    outboundCount: outboundTargets.length,
    wellCovered: Object.freeze(wellCovered) as ReadonlyArray<MocClusterMember>,
    fragile: Object.freeze(fragile) as ReadonlyArray<MocClusterMember>,
    candidateMissing: Object.freeze(candidateMissing) as ReadonlyArray<{
      id: string;
      referenceCount: number;
    }>,
    ...(suggestedNext ? { suggestedNext } : {}),
  });
}

/**
 * The preference or retired page `id` names: its path and its text. On a
 * store-only machine (task 2.10) the fold's record, as the page it would be.
 */
function locateArtifact(
  vault: string,
  id: string,
): { readonly path: string; readonly text: () => string } | null {
  if (memoryFromStore(vault)) {
    // The same two folders the legacy lookup reads.
    const page = storePageInPreferenceFolders(vault, id);
    if (page === null) return null;
    return { path: page.path, text: () => page.text };
  }
  const dirs = brainDirs(vault);
  const candidates = [join(dirs.preferences, `${id}.md`), join(dirs.retired, `${id}.md`)];
  for (const c of candidates)
    if (existsSync(c)) return { path: c, text: () => readFileSync(c, "utf8") };
  return null;
}

function stripFrontmatter(text: string): string {
  const m = FRONTMATTER_RE.exec(text);
  if (!m) return text;
  return text.slice(m[0].length);
}

function uniq<T>(values: ReadonlyArray<T>): T[] {
  const seen = new Set<T>();
  const out: T[] = [];
  for (const v of values) {
    if (seen.has(v)) continue;
    seen.add(v);
    out.push(v);
  }
  return out;
}

function resolveThresholds(vault: string, opts: AuditMocOptions): HubBodyThresholds {
  if (opts.minOutboundLinks !== undefined && opts.minLinkRatio !== undefined) {
    return {
      minOutbound: opts.minOutboundLinks,
      minRatio: opts.minLinkRatio,
    };
  }
  const resolved = resolveHubThresholds(vault);
  return {
    minOutbound: opts.minOutboundLinks ?? resolved.minOutbound,
    minRatio: opts.minLinkRatio ?? resolved.minRatio,
  };
}