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
/**
 * Sliding 30-day applied-evidence ranker that backs the
 * `## Most-applied (30d)` section of `Brain/active.md`.
 *
 * Pure read. Caller passes the candidate preferences (already
 * filtered to `confirmed | quarantine` in `regenerateActive`); this
 * module never re-walks the preferences directory.
 */

import { logDayReader } from "./log-days.ts";
import { withoutPrivateEntries } from "./log-events-at-reach.ts";
import { MOST_APPLIED_LIMIT_DEFAULT, MOST_APPLIED_WINDOW_DAYS_DEFAULT } from "./policy.ts";
import { isoDate } from "./time.ts";
import { normaliseWikilinkTarget } from "./wikilink.ts";
import {
  BRAIN_APPLY_RESULT,
  BRAIN_LOG_EVENT_KIND,
  BRAIN_PREFERENCE_STATUS,
  type BrainPreference,
} from "./types.ts";

const DAY_MS = 24 * 3600 * 1000;
export interface MostAppliedEntry {
  readonly preference: BrainPreference;
  readonly applied_30d: number;
}

export interface ComputeMostAppliedOptions {
  /** Window anchor. Defaults to `new Date()`. */
  readonly now?: Date;
  /** Window length in days. Defaults to 30. */
  readonly windowDays?: number;
  /** Max entries returned. Defaults to 10. */
  readonly limit?: number;
  /**
   * The caller is below local reach: events of the store's `private`
   * partition are not counted, so the counts and the order read as if
   * they did not exist. Default false (local callers and the CLI).
   */
  readonly withholdsPrivate?: boolean;
}

/**
 * Compute the Most-applied list for the `active.md` section.
 *
 * @param vault       Vault root.
 * @param preferences Candidate preferences (confirmed | quarantine).
 *                    Events referencing preferences outside this list
 *                    are silently ignored by design — retired rules
 *                    do not appear in `active.md`.
 */
export function computeMostApplied(
  vault: string | null,
  preferences: ReadonlyArray<BrainPreference>,
  opts: ComputeMostAppliedOptions = {},
): ReadonlyArray<MostAppliedEntry> {
  const now = opts.now ?? new Date();
  const windowDays = opts.windowDays ?? MOST_APPLIED_WINDOW_DAYS_DEFAULT;
  const limit = opts.limit ?? MOST_APPLIED_LIMIT_DEFAULT;
  // The caller is supposed to filter to confirmed | quarantine upstream,
  // but the status guard here keeps the contract honest if a future
  // caller passes a wider list — retired rules must never surface in
  // the active digest.
  const prefByKey = new Map<string, BrainPreference>();
  for (const p of preferences) {
    if (
      p.status !== BRAIN_PREFERENCE_STATUS.confirmed &&
      p.status !== BRAIN_PREFERENCE_STATUS.quarantine
    ) {
      continue;
    }
    prefByKey.set(normaliseWikilinkTarget(p.id), p);
  }
  if (prefByKey.size === 0) return [];

  const windowEndMs = now.getTime();
  const windowStartMs = windowEndMs - windowDays * DAY_MS;
  // Day-level fence: include the day before window start to absorb
  // UTC drift between the event timestamp and the file's date prefix.
  const earliestDayPrefix = isoDate(new Date(windowStartMs - DAY_MS));
  // Only the window's days are read (on a store-only machine, only the
  // shards that can hold them); a missing `Brain/log/` lists no date.
  const log = logDayReader(vault, { from: earliestDayPrefix });

  const counts = new Map<string, number>();
  // Shard-aware (Memory Integrity Suite): one discovery pass over every
  // log filename shape; readLogDay merges the day's shards.
  for (const datePrefix of log.dates) {
    if (datePrefix < earliestDayPrefix) continue;

    let parsed;
    try {
      parsed = log.day(datePrefix);
    } catch (err) {
      process.stderr.write(
        `warning: most-applied: failed to read ${datePrefix}: ${(err as Error).message}\n`,
      );
      continue;
    }
    for (const e of withoutPrivateEntries(parsed.entries, opts.withholdsPrivate === true)) {
      if (e.eventType !== BRAIN_LOG_EVENT_KIND.applyEvidence) continue;
      if (e.body["result"] !== BRAIN_APPLY_RESULT.applied) continue;
      const eventMs = Date.parse(e.timestamp);
      if (Number.isNaN(eventMs)) continue;
      if (eventMs < windowStartMs || eventMs > windowEndMs) continue;
      const prefField = e.body["preference"];
      if (typeof prefField !== "string") continue;
      const key = normaliseWikilinkTarget(prefField);
      if (!prefByKey.has(key)) continue;
      counts.set(key, (counts.get(key) ?? 0) + 1);
    }
  }

  const entries: MostAppliedEntry[] = [];
  for (const [key, count] of counts) {
    const pref = prefByKey.get(key)!;
    entries.push({ preference: pref, applied_30d: count });
  }
  entries.sort((a, b) => {
    if (b.applied_30d !== a.applied_30d) return b.applied_30d - a.applied_30d;
    return a.preference.id.localeCompare(b.preference.id);
  });
  return entries.slice(0, limit);
}