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
7.0 KB
Raw Blame
/**
 * Agent quality summary for the brain digest.
 *
 * Groups Brain/log events by agent within the given window and returns
 * per-agent counts: total events, breakdown by type (feedback /
 * apply-evidence / note), and attribution to confirmed/retired rules.
 */

import {
  memoryPageNamed,
  storeMemoryPages,
  type MemoryFolder,
  type MemoryPage,
} from "./memory-pages.ts";

import type { BrainLogEntry } from "./log.ts";
import { logDayReader } from "./log-days.ts";
import { BRAIN_LOG_EVENT_KIND } from "./types.ts";

export interface AgentSummaryEntry {
  readonly agent: string;
  readonly total_events: number;
  readonly feedback_count: number;
  readonly apply_evidence_count: number;
  readonly note_count: number;
  readonly confirmed_attributed: number;
  readonly retired_attributed: number;
}

interface AgentAccumulator {
  agent: string;
  total_events: number;
  feedback_count: number;
  apply_evidence_count: number;
  note_count: number;
  confirmed_attributed: number;
  retired_attributed: number;
}

/**
 * `keep` answers whether the caller may count an event; an event it
 * refuses moves no count and attributes no rule. Without it every event
 * in the window is counted.
 */
export function computeAgentSummary(
  vault: string,
  since: Date,
  until: Date,
  keep?: (entry: BrainLogEntry) => boolean,
): ReadonlyArray<AgentSummaryEntry> {
  const windowed = readLogsInWindow(vault, since, until);
  const logs = keep === undefined ? windowed : windowed.filter(keep);
  const byAgent = new Map<string, AgentAccumulator>();
  const field = memoryFieldReader(vault);

  for (const entry of logs) {
    const agent = getEntryAgent(entry);
    let acc = byAgent.get(agent);
    if (!acc) {
      acc = {
        agent,
        total_events: 0,
        feedback_count: 0,
        apply_evidence_count: 0,
        note_count: 0,
        confirmed_attributed: 0,
        retired_attributed: 0,
      };
      byAgent.set(agent, acc);
    }
    acc.total_events++;
    switch (entry.eventType) {
      case BRAIN_LOG_EVENT_KIND.feedback:
        acc.feedback_count++;
        break;
      case BRAIN_LOG_EVENT_KIND.applyEvidence:
        acc.apply_evidence_count++;
        break;
      case BRAIN_LOG_EVENT_KIND.note:
        acc.note_count++;
        break;
    }
  }

  const seenPrefs = new Set<string>();
  const prefFirstAgent = new Map<string, string>();

  for (const entry of logs) {
    const agent = getEntryAgent(entry);
    const pref = entry.body["preference"];
    if (typeof pref !== "string") continue;
    const prefId = extractPrefId(pref);
    if (!prefId) continue;

    if (!prefFirstAgent.has(prefId)) {
      prefFirstAgent.set(prefId, agent);
    }
  }

  for (const entry of logs) {
    const agent = getEntryAgent(entry);
    const acc = byAgent.get(agent);
    if (!acc) continue;

    const pref = entry.body["preference"];
    if (typeof pref !== "string") continue;
    const prefId = extractPrefId(pref);
    if (!prefId) continue;

    const key = `${agent}:${prefId}`;
    if (seenPrefs.has(key)) continue;

    const firstAgent = prefFirstAgent.get(prefId);
    if (firstAgent !== agent) continue;

    seenPrefs.add(key);

    const confirmedAt = field("preferences", `${prefId}.md`, "confirmed_at");
    const retiredAt = field("retired", `${prefId.replace("pref-", "ret-")}.md`, "retired_at");

    if (confirmedAt && isInWindow(confirmedAt, since, until)) {
      acc.confirmed_attributed++;
    }
    if (retiredAt && isInWindow(retiredAt, since, until)) {
      acc.retired_attributed++;
    }
  }

  return [...byAgent.values()].toSorted((a, b) => {
    const diff = b.total_events - a.total_events;
    return diff !== 0 ? diff : a.agent.localeCompare(b.agent);
  });
}

function readLogsInWindow(vault: string, since: Date, until: Date): BrainLogEntry[] {
  const sinceIso = since.toISOString();
  const untilIso = until.toISOString();
  const sinceDay = sinceIso.slice(0, 10);
  const untilDay = untilIso.slice(0, 10);
  const out: BrainLogEntry[] = [];
  // Shard-aware (Memory Integrity Suite): one discovery helper, merged reads.
  const log = logDayReader(vault);
  for (const date of log.dates) {
    if (date < addDays(sinceDay, -1)) continue;
    if (date > addDays(untilDay, 1)) continue;
    const { entries } = log.day(date);
    for (const e of entries) {
      if (e.timestamp >= sinceIso && e.timestamp < untilIso) {
        out.push(e);
      }
    }
  }
  out.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
  return out;
}

function addDays(day: string, delta: number): string {
  const t = Date.parse(`${day}T00:00:00Z`);
  if (!Number.isFinite(t)) return day;
  return new Date(t + delta * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
}

function extractPrefId(raw: string): string | null {
  const m = /\[\[([^\]|#]+)/.exec(raw);
  if (m) return m[1]!.trim();
  if (raw.startsWith("pref-")) return raw;
  return null;
}

function getEntryAgent(entry: BrainLogEntry): string {
  const runtimeAgent = entry.agent;
  if (typeof runtimeAgent === "string" && runtimeAgent.trim() !== "") {
    return runtimeAgent;
  }
  const bodyAgent = entry.body["agent"];
  if (typeof bodyAgent === "string" && bodyAgent.trim() !== "") {
    return bodyAgent;
  }
  return "unknown";
}

/**
 * A reader of one frontmatter field of memory page `name` of `folder`:
 * the file on an unswitched machine (read when asked), the page the
 * store's fold rebuilds once switched (no file exists there). The field
 * is read from the parsed frontmatter in either `field` or the writer's
 * `_field` spelling, so a page the preference writer wrote counts as a
 * hand-written one does. The store's pages of a folder are loaded once
 * per reader and indexed by name, so a summary costs one fold read per
 * folder, not one per preference. `null` when there is no such page, no
 * such field, or it cannot be read.
 */
function memoryFieldReader(
  vault: string,
): (folder: "preferences" | "retired", name: string, field: string) => string | null {
  const folders = new Map<MemoryFolder, Map<string, MemoryPage> | null>();
  const storedPages = (folder: MemoryFolder): Map<string, MemoryPage> | null => {
    if (!folders.has(folder)) {
      let pages: ReadonlyArray<MemoryPage> | null;
      try {
        pages = storeMemoryPages(vault, folder);
      } catch {
        pages = [];
      }
      folders.set(folder, pages === null ? null : new Map(pages.map((p) => [p.name, p])));
    }
    return folders.get(folder)!;
  };
  return (folder, name, field) => {
    try {
      const stored = storedPages(folder);
      const page = stored === null ? memoryPageNamed(vault, folder, name) : stored.get(name);
      if (page === undefined || page === null) return null;
      const [meta] = page.read();
      const value = meta[field] ?? meta[`_${field}`];
      if (typeof value === "string") return value.trim() || null;
      return value instanceof Date ? value.toISOString() : null;
    } catch {
      return null;
    }
  };
}

function isInWindow(iso: string, since: Date, until: Date): boolean {
  const t = Date.parse(iso);
  if (!Number.isFinite(t)) return false;
  return t >= since.getTime() && t < until.getTime();
}