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.9 KB
Raw Blame
/**
 * Self-tuning reinforce ledger (Search & Recall Quality Suite).
 *
 * Reinforcement is an EXPLICIT signal: a caller (operator or downstream
 * agent) naming a memory that proved useful. It is never inferred from a
 * memory merely being surfaced - surfaced-only frequency carries no
 * positive signal, by design, so popularity can never snowball.
 *
 * Each reinforce event is one small JSON file under
 * `Brain/search/reinforce/` - the same conflict-free one-file-per-signal
 * pattern `Brain/inbox/` and the feedback ledger use, so multi-device
 * vaults never produce sync conflicts on a shared append-only file. The
 * per-path strength is a PURE FOLD over the event set (count of distinct
 * events naming the path, normalized and bounded), so it is replayable
 * and resettable: deleting the derived view loses nothing.
 *
 * The boost is bounded ({@link REINFORCE_BOOST_CAP}) and applied before
 * the top_k cut, so a reinforced memory is lifted into the window without
 * ever floating an irrelevant chunk.
 *
 * A store-only machine (design D14 item 1) appends each event as a
 * `search-reinforce` ledger row instead of a file; the store is
 * append-only, so a reset there is a row too, and the fold counts only
 * the events after the newest reset.
 */

import { legacyVaultOf } from "../brain/no-vault.ts";
import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync, existsSync } from "node:fs";
import { join } from "node:path";

import { canonicalJson } from "../integrity/digest.ts";
import { ledgerRowRecord } from "../store/dual-write-records.ts";
import { readLedgerRows } from "../store/read/ledger-rows.ts";
import { rowNamesPrivatePage } from "../store/reference-privacy.ts";
import { isStoreOnly } from "../store/store-only.ts";
import { storeWrite } from "../store/store-write.ts";
import { dedupeIdentical, fnv1aHex } from "./feedback.ts";
import type { BrainSearchResult } from "./types.ts";

/** Maximum additive boost a fully-reinforced path receives. */
export const REINFORCE_BOOST_CAP = 0.05;
/** Event count at which a path reaches full reinforcement strength. */
export const REINFORCE_SATURATION = 5;

export interface ReinforceEvent {
  /** Unix-ms timestamp the reinforcement was recorded. */
  readonly ts: number;
  /** Vault-relative paths reinforced in this event. */
  readonly paths: ReadonlyArray<string>;
}

export interface RecordReinforceOptions {
  /** Injected clock for deterministic tests. Defaults to Date.now(). */
  readonly nowMs?: number;
}

export function reinforceDir(vault: string | null): string {
  return join(legacyVaultOf(vault, "reinforceDir"), "Brain", "search", "reinforce");
}

/**
 * Record one reinforce event as its own file. The filename derives from
 * the timestamp plus a content hash, so recording the identical event
 * (same timestamp and paths) twice is idempotent. Empty path lists are a
 * no-op.
 */
export function recordReinforce(
  vault: string | null,
  paths: ReadonlyArray<string>,
  opts: RecordReinforceOptions = {},
): string | null {
  const cleaned = [...new Set(paths.filter((p) => p.length > 0))].toSorted();
  if (cleaned.length === 0) return null;
  const event: ReinforceEvent = Object.freeze({ ts: opts.nowMs ?? Date.now(), paths: cleaned });
  // One `search-reinforce` ledger row on a store-only machine (design D14
  // item 1); an unswitched machine keeps its event file, with no dual write
  // (format version 1 has none for this ledger; the migration imports the
  // files).
  if (isStoreOnly({ vault })) {
    return storeWrite(() => reinforceRowRecord(vault, event), { vault })[0]?.path ?? "";
  }
  const dir = reinforceDir(vault);
  mkdirSync(dir, { recursive: true });
  const body = JSON.stringify(event, null, 2) + "\n";
  const file = join(dir, `${event.ts}-${fnv1aHex(body)}.json`);
  writeFileSync(file, body);
  return file;
}

/** The store ledger of reinforce events (FORMAT.md, the migration's ledgers). */
export const SEARCH_REINFORCE_LEDGER = "search-reinforce";

/**
 * A store row that resets the ledger: the store is append-only, so a
 * reset on a store-only machine is a row, and every event before the
 * newest reset row (in fold order) no longer counts.
 */
interface ReinforceResetRow {
  readonly ts: number;
  readonly reset: true;
}

function isResetRow(row: unknown): row is ReinforceResetRow {
  return (
    row !== null &&
    typeof row === "object" &&
    (row as { reset?: unknown }).reset === true &&
    typeof (row as { ts?: unknown }).ts === "number"
  );
}

/**
 * The store row of one event: `private` when a reinforced path names a
 * private page or one that cannot be judged, else `private` when this
 * machine holds it (what proved useful says what the user worked on).
 */
function reinforceRowRecord(vault: string | null, row: ReinforceEvent | ReinforceResetRow) {
  return ledgerRowRecord(
    SEARCH_REINFORCE_LEDGER,
    row,
    rowNamesPrivatePage(vault, row) ? "private" : "private-when-held",
  );
}

function isReinforceEvent(parsed: unknown): parsed is ReinforceEvent {
  if (parsed === null || typeof parsed !== "object") return false;
  const e = parsed as Partial<ReinforceEvent>;
  return (
    typeof e.ts === "number" &&
    Array.isArray(e.paths) &&
    e.paths.every((p) => typeof p === "string")
  );
}

/** The store rows after the newest reset row, in fold order. */
function storeRowsSinceReset(vault: string | null): unknown[] {
  const rows = readLedgerRows<unknown>(SEARCH_REINFORCE_LEDGER, () => [], { vault });
  const lastReset = rows.findLastIndex(isResetRow);
  return rows.slice(lastReset + 1);
}

/** Load all reinforce events, sorted by timestamp (stable). */
export function loadReinforceEvents(vault: string | null): ReinforceEvent[] {
  // A store-only machine reads the `search-reinforce` rows after the
  // newest reset; an identical row is counted once, as the event's file
  // name made it one file.
  if (isStoreOnly({ vault })) {
    return dedupeIdentical(storeRowsSinceReset(vault).filter(isReinforceEvent)).toSorted(
      (a, b) => a.ts - b.ts,
    );
  }
  let files: string[];
  try {
    files = readdirSync(reinforceDir(vault)).filter((f) => f.endsWith(".json"));
  } catch {
    return [];
  }
  const out: ReinforceEvent[] = [];
  for (const f of files.toSorted()) {
    try {
      const parsed: unknown = JSON.parse(readFileSync(join(reinforceDir(vault), f), "utf8"));
      if (isReinforceEvent(parsed)) out.push(parsed);
    } catch {
      // One malformed file never breaks the fold.
    }
  }
  out.sort((a, b) => a.ts - b.ts);
  return out;
}

/**
 * Pure fold: per-path strength in [0, 1], the count of distinct events
 * naming the path normalized by {@link REINFORCE_SATURATION} and capped
 * at 1. Order-insensitive by construction.
 */
export function loadReinforceStrengths(vault: string | null): Map<string, number> {
  const counts = new Map<string, number>();
  for (const event of loadReinforceEvents(vault)) {
    for (const path of new Set(event.paths)) {
      counts.set(path, (counts.get(path) ?? 0) + 1);
    }
  }
  const strengths = new Map<string, number>();
  for (const [path, count] of counts) {
    strengths.set(path, Math.min(1, count / REINFORCE_SATURATION));
  }
  return strengths;
}

/** Delete the reinforce ledger. The fold replays as empty afterwards. */
export function resetReinforce(vault: string | null, opts: RecordReinforceOptions = {}): void {
  // The store is append-only: a store-only machine records the reset as a
  // row (design D14 item 1) and removes nothing.
  if (isStoreOnly({ vault })) {
    // The reset names no page and carries no user text: it goes to
    // `shared`, so every device, one without the private partition
    // included, applies the same cutoff to the events before it.
    const reset: ReinforceResetRow = { ts: opts.nowMs ?? Date.now(), reset: true };
    storeWrite(() => ledgerRowRecord(SEARCH_REINFORCE_LEDGER, reset, "shared"), { vault });
    return;
  }
  rmSync(reinforceDir(vault), { recursive: true, force: true });
}

/**
 * Stable fingerprint of the ledger state for the query-cache key: "off"
 * when no ledger exists, else a hash of the sorted event filenames (the
 * filenames already encode ts + content hash, so they change iff the
 * ledger does).
 */
export function reinforceFingerprint(vault: string | null): string {
  if (isStoreOnly({ vault })) {
    const rows = storeRowsSinceReset(vault).filter(isReinforceEvent);
    return rows.length === 0 ? "off" : fnv1aHex(rows.map((row) => canonicalJson(row)).join("|"));
  }
  const dir = reinforceDir(vault);
  if (!existsSync(dir)) return "off";
  try {
    const files = readdirSync(dir)
      .filter((f) => f.endsWith(".json"))
      .toSorted();
    if (files.length === 0) return "off";
    return fnv1aHex(files.join("|"));
  } catch {
    return "off";
  }
}

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

/**
 * Apply the bounded reinforcement boost to a ranked pool and re-sort.
 * A result whose path carries ledger strength gets `CAP * strength` added
 * to its score (clamped to 1) and a `reinforce:` reason; everything else
 * is untouched. Pure: returns a new array, never mutates the input. The
 * tie-break matches the ranker family (score desc, keywordScore desc,
 * chunkId asc) so the ordering stays deterministic.
 */
export function applyReinforceBoost(
  results: ReadonlyArray<BrainSearchResult>,
  strengthByPath: ReadonlyMap<string, number>,
): BrainSearchResult[] {
  if (strengthByPath.size === 0) return results.slice();
  const boosted = results.map((r) => {
    const strength = strengthByPath.get(r.path);
    if (strength === undefined || strength <= 0) return r;
    const boost = REINFORCE_BOOST_CAP * Math.min(1, strength);
    return Object.freeze({
      ...r,
      score: Math.min(1, r.score + boost),
      reasons: Object.freeze([...r.reasons, `reinforce: +${fmt(boost)}`]),
    });
  });
  return boosted.toSorted((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;
  });
}