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
6.6 KB
Raw Blame
/**
 * Vault vitals β€” aggregate governance health scorecard.
 *
 * The existing hygiene surfaces (`doctor`, `health`, `moc-audit`) are
 * all per-item: one warning per duplicate pair, one finding per
 * contradiction, one bucket per MOC hub. None of them answer "is the
 * preference set as a whole spreading thin, well-evidenced, and
 * keeping up with its own gap backlog?" β€” a single scorecard over the
 * full `Brain/preferences/` set, four numbers:
 *
 *   - `domain_diversity`   β€” normalised Shannon entropy of the `scope`
 *                            distribution (0 = every preference shares
 *                            one scope, 1 = evenly spread).
 *   - `connectivity_index` β€” mean `evidenced_by.length` per confirmed
 *                            preference (how well individual rules are
 *                            backed by originating signals).
 *   - `orphan_preferences` β€” confirmed preferences below the evidence
 *                            threshold (thin backing, candidates for
 *                            re-confirmation or retirement).
 *   - `gap_pressure`       β€” open `concept-gap` findings (reused from
 *                            {@link computeSemanticHealth}'s pass, not
 *                            recomputed here) divided by preference
 *                            count: are gaps piling up faster than
 *                            they're being distilled into preferences?
 *
 * Pure aggregation, no new detector logic and no filesystem writes.
 * Read-only; scope limited to `confirmed` preferences so trial
 * (`unconfirmed`) and `quarantine` records don't skew the averages β€”
 * same convention `checkLowEvidenceConfirmed` uses.
 */

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

import { brainDirs } from "./paths.ts";
import { memoryFromStore } from "./memory-pages.ts";
import { storePreferenceRecords } from "./memory-page-records.ts";
import { parsePreference } from "./preference.ts";
import { computeSemanticHealth } from "./doctor.ts";
import { BRAIN_PREFERENCE_STATUS, type BrainPreference } from "./types.ts";

export interface VaultVitalsOptions {
  /** `evidenced_by.length` strictly below this counts as an orphan. Default 2. */
  readonly orphanThreshold?: number;
}

export interface VaultVitalsOrphan {
  readonly id: string;
  readonly scope: string | undefined;
  readonly evidence_count: number;
}

export interface VaultVitalsScopeCount {
  readonly scope: string;
  readonly count: number;
}

export interface VaultVitalsReport {
  readonly preferences_scanned: number;
  readonly domain_diversity: number;
  readonly connectivity_index: number;
  readonly orphan_preferences: ReadonlyArray<VaultVitalsOrphan>;
  readonly gap_pressure: number;
  readonly scope_distribution: ReadonlyArray<VaultVitalsScopeCount>;
}

function round2(n: number): number {
  return Math.round(n * 100) / 100;
}

/** Confirmed preferences only β€” mirrors `checkLowEvidenceConfirmed`'s scope. */
function readConfirmedPreferences(vault: string): BrainPreference[] {
  if (memoryFromStore(vault)) {
    // Store-only (task 2.10): the preference fold, by the page's rules.
    return storePreferenceRecords(vault)
      .records.map((r) => r.pref)
      .filter((pref) => pref.status === BRAIN_PREFERENCE_STATUS.confirmed);
  }
  const dir = brainDirs(vault).preferences;
  if (!existsSync(dir)) return [];
  const out: BrainPreference[] = [];
  for (const name of readdirSync(dir)) {
    if (!name.endsWith(".md") || !name.startsWith("pref-")) continue;
    let pref: BrainPreference;
    try {
      pref = parsePreference(join(dir, name));
    } catch {
      continue; // schema errors are already surfaced by `o2b brain doctor`
    }
    if (pref.status === BRAIN_PREFERENCE_STATUS.confirmed) out.push(pref);
  }
  return out;
}

/** Normalised Shannon entropy of `scope` (missing scope groups as `"unscoped"`). */
function scopeDiversity(prefs: ReadonlyArray<BrainPreference>): {
  diversity: number;
  distribution: VaultVitalsScopeCount[];
} {
  const counts = new Map<string, number>();
  for (const p of prefs) {
    const scope = p.scope ?? "unscoped";
    counts.set(scope, (counts.get(scope) ?? 0) + 1);
  }
  const distribution = [...counts.entries()]
    .map(([scope, count]) => ({ scope, count }))
    .toSorted((a, b) => b.count - a.count || a.scope.localeCompare(b.scope));

  if (prefs.length === 0 || counts.size <= 1) return { diversity: 0, distribution };
  let entropy = 0;
  for (const count of counts.values()) {
    const p = count / prefs.length;
    entropy -= p * Math.log2(p);
  }
  const entropyMax = Math.log2(counts.size);
  return { diversity: entropyMax > 0 ? round2(entropy / entropyMax) : 0, distribution };
}

/**
 * Compute the vault vitals scorecard. `gap_pressure`'s numerator reuses
 * {@link computeSemanticHealth}'s `conceptGaps` count rather than
 * re-running the detector β€” one source of truth for "how many gaps are
 * open" β€” and takes the semantic-only path so vitals does not pay for
 * the full structural doctor sweep just to read one number. A pass
 * failure degrades `gap_pressure` to `0` rather than failing the whole
 * report: vitals is observability, not correctness.
 */
export function computeVaultVitals(
  vault: string,
  opts: VaultVitalsOptions = {},
): VaultVitalsReport {
  const orphanThreshold = opts.orphanThreshold ?? 2;
  const prefs = readConfirmedPreferences(vault);
  const { diversity, distribution } = scopeDiversity(prefs);

  const connectivity =
    prefs.length > 0
      ? round2(prefs.reduce((sum, p) => sum + p.evidenced_by.length, 0) / prefs.length)
      : 0;

  const orphans: VaultVitalsOrphan[] = prefs
    .filter((p) => p.evidenced_by.length < orphanThreshold)
    .map((p) => ({ id: p.id, scope: p.scope, evidence_count: p.evidenced_by.length }))
    .toSorted((a, b) => a.evidence_count - b.evidence_count || a.id.localeCompare(b.id));

  // Semantic-only path: same detector `runDoctor` runs, without the
  // structural sweep vitals never reads. `computeSemanticHealth` already
  // swallows its own failures (returns undefined); the guard is belt and
  // suspenders so gap_pressure degrades to 0 rather than failing.
  let gapCount = 0;
  try {
    gapCount = computeSemanticHealth(vault)?.conceptGaps.length ?? 0;
  } catch {
    // Vitals is observability, not correctness β€” a probe failure
    // should not block the rest of the report.
  }
  const gapPressure = prefs.length > 0 ? round2(gapCount / prefs.length) : 0;

  return {
    preferences_scanned: prefs.length,
    domain_diversity: diversity,
    connectivity_index: connectivity,
    orphan_preferences: orphans,
    gap_pressure: gapPressure,
    scope_distribution: distribution,
  };
}