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
17.9 KB
Raw Blame
/**
 * The storage forecast and the usage sampler (`forecastStorageUsage`,
 * `sampleStorageUsage`).
 *
 * Claims pinned here:
 *
 *   1. Over seeded `storage_usage` metric samples the forecast returns
 *      the linear slope (bytes per day), the days left to the cap and a
 *      tier, and the tier boundaries land EXACTLY on the default
 *      constants: 80 percent / 30 days warns, 95 percent / 7 days is
 *      critical.
 *   2. An absent `cap_bytes` is `unbounded`; an incomplete measurement is
 *      `unmeasurable` - a census that could not read a surface refuses
 *      the forecast by name instead of projecting from partial bytes.
 *   3. Fewer than two stored samples is the named `no_forecast` state:
 *      the stored aggregate is advisory, never tier-eligible on its own.
 *      A FRESH reading (`latestUsage`) is enforcement truth, so the
 *      percent tiers compute from it even with an empty history.
 *   4. `sampleStorageUsage` appends exactly one `storage_usage` metrics
 *      record per call, is idempotent per run id, and an append failure
 *      is reported by name, never thrown.
 */

import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

import { appendMetric, listMetrics, metricsDir } from "../../../src/core/brain/metrics.ts";
import {
  MIN_TREND_DAYS,
  STORAGE_CRITICAL_DAYS_DEFAULT,
  STORAGE_CRITICAL_PERCENT_DEFAULT,
  STORAGE_USAGE_METRIC_SURFACE,
  STORAGE_WARN_DAYS_DEFAULT,
  STORAGE_WARN_PERCENT_DEFAULT,
  TREND_WINDOW_DAYS,
  forecastStorageUsage,
  sampleStorageUsage,
} from "../../../src/core/brain/storage/forecast.ts";
import { evaluateCapacityGate } from "../../../src/core/brain/storage/gate.ts";
import { measureStorageUsage } from "../../../src/core/brain/storage/usage.ts";
import { CHMOD_CANNOT_DENY } from "../../helpers/platform.ts";

let vault: string;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-storage-forecast-"));
  // A legacy Brain/ tree: an unswitched machine (a vault without one is store-only).
  mkdirSync(join(vault, "Brain"), { recursive: true });
});

afterEach(() => {
  rmSync(vault, { recursive: true, force: true });
});

const CAP = 1000;
const NOW = new Date("2026-10-15T12:00:00Z");

/** Seed one `storage_usage` sample `daysAgo` days before the forecast instant. */
function seedSample(daysAgo: number, totalBytes: number): void {
  const t = new Date(Date.parse("2026-10-15T12:00:00Z") - daysAgo * 86_400_000);
  appendMetric(vault, {
    surface: STORAGE_USAGE_METRIC_SURFACE,
    runAt: t.toISOString().replace(".000Z", "Z"),
    payload: { run_id: `seed-${daysAgo}`, total_bytes: totalBytes, measured: true },
  });
}

/** Seed one `storage_usage` sample at an exact instant, sub-day precision. */
function seedSampleAt(t: Date, totalBytes: number, runId: string, measured = true): void {
  appendMetric(vault, {
    surface: STORAGE_USAGE_METRIC_SURFACE,
    runAt: t.toISOString(),
    payload: { run_id: runId, total_bytes: totalBytes, measured },
  });
}

describe("forecastStorageUsage", () => {
  test("returns the linear slope, days to cap and tier over seeded samples", () => {
    seedSample(2, 100);
    seedSample(1, 200);
    seedSample(0, 300);
    // Cap 5000 keeps the reading clear of every boundary: 6 percent
    // used, 47 days to the cap.
    const forecast = forecastStorageUsage(vault, { capBytes: 5000 });
    expect(forecast.tier).toBe("ok");
    expect(forecast.slopeBytesPerDay).toBe(100);
    expect(forecast.measuredBytes).toBe(300);
    expect(forecast.percentUsed).toBe(6);
    expect(forecast.daysToCap).toBe(47);
    expect(forecast.capBytes).toBe(5000);
  });

  test("exactly the warn percent warns and exactly the critical percent is critical", () => {
    expect(STORAGE_WARN_PERCENT_DEFAULT).toBe(80);
    expect(STORAGE_CRITICAL_PERCENT_DEFAULT).toBe(95);
    expect(STORAGE_WARN_DAYS_DEFAULT).toBe(30);
    expect(STORAGE_CRITICAL_DAYS_DEFAULT).toBe(7);

    // Two samples a day apart are under the three-day minimum: no slope,
    // so the percent comparison alone decides - exactly 80 warns.
    seedSample(1, 790);
    seedSample(0, 800);
    expect(forecastStorageUsage(vault, { capBytes: CAP }).tier).toBe("warn");

    seedSample(-1, 950);
    // 95 percent used; the three-day fit (790, 800, 950) gives 40 bytes
    // per day, so 1.25 days to the cap - critical on both counts.
    expect(forecastStorageUsage(vault, { capBytes: CAP }).tier).toBe("critical");
  });

  test("the percent boundaries are inclusive with no trend to decide instead", () => {
    // The tier fixtures below sit inside the days bands too, so a
    // comparison flipped exclusive would still answer warn/critical
    // through the days path and the percent boundary would go unpinned.
    // Two distinct days fit no slope at all (the three-day minimum), so
    // the percent comparison alone decides: exactly 80 warns, exactly 95
    // is critical, and neither carries a daysToCap figure.
    seedSample(1, 800);
    seedSample(0, 800);
    const warn = forecastStorageUsage(vault, { capBytes: CAP });
    expect(warn.slopeBytesPerDay).toBe(null);
    expect(warn.daysToCap).toBe(null);
    expect(warn.percentUsed).toBe(80);
    expect(warn.tier).toBe("warn");

    rmSync(metricsDir(vault), { recursive: true, force: true });
    seedSample(1, 950);
    seedSample(0, 950);
    const critical = forecastStorageUsage(vault, { capBytes: CAP });
    expect(critical.slopeBytesPerDay).toBe(null);
    expect(critical.daysToCap).toBe(null);
    expect(critical.percentUsed).toBe(95);
    expect(critical.tier).toBe("critical");
  });

  test("a history that cannot be listed answers samplesUnreadable, never no-samples", () => {
    // A metrics directory replaced by a plain file makes the ledger
    // listing throw; the forecast must NAME the unreadable history on
    // the result instead of flattening it into "no samples ever
    // recorded" - the two say opposite things about the vault's past.
    seedSample(1, 400);
    seedSample(0, 500);
    rmSync(metricsDir(vault), { recursive: true, force: true });
    writeFileSync(metricsDir(vault), "not a directory\n", "utf8");
    const forecast = forecastStorageUsage(vault, { capBytes: CAP });
    expect(forecast.samplesUnreadable).toBe(true);
    expect(forecast.tier).toBe("no_forecast");
  });

  test("a percent-only warn never outranks a critical days horizon", () => {
    // 280 of 350 bytes is exactly 80 percent (warn by percent), and a
    // three-day slope of 10 bytes per day puts the cap exactly 7 days
    // out (critical by days). The critical comparison runs first, so the
    // days horizon decides the tier.
    seedSample(2, 260);
    seedSample(1, 270);
    seedSample(0, 280);
    const forecast = forecastStorageUsage(vault, { capBytes: 350 });
    expect(forecast.percentUsed).toBe(80);
    expect(forecast.daysToCap).toBe(7);
    expect(forecast.tier).toBe("critical");
  });

  test("exactly the warn days to cap warns", () => {
    // current 300, three-day slope 10 per day: 30 days to 600, at the
    // boundary.
    seedSample(2, 280);
    seedSample(1, 290);
    seedSample(0, 300);
    const warn = forecastStorageUsage(vault, { capBytes: 600 });
    expect(warn.slopeBytesPerDay).toBe(10);
    expect(warn.daysToCap).toBe(30);
    expect(warn.tier).toBe("warn");
  });

  test("exactly the critical days to cap is critical", () => {
    // current 300, three-day slope 50 per day: 7 days to 650, at the
    // boundary.
    seedSample(2, 200);
    seedSample(1, 250);
    seedSample(0, 300);
    const critical = forecastStorageUsage(vault, { capBytes: 650 });
    expect(critical.slopeBytesPerDay).toBe(50);
    expect(critical.daysToCap).toBe(7);
    expect(critical.tier).toBe("critical");
  });

  test("an absent cap is unbounded", () => {
    seedSample(1, 900);
    seedSample(0, 990);
    const forecast = forecastStorageUsage(vault, { capBytes: null });
    expect(forecast.tier).toBe("unbounded");
    expect(forecast.percentUsed).toBe(null);
    expect(forecast.daysToCap).toBe(null);
  });

  test("fewer than two stored samples is the named no-forecast state", () => {
    expect(forecastStorageUsage(vault, { capBytes: CAP }).tier).toBe("no_forecast");
    seedSample(0, 500);
    expect(forecastStorageUsage(vault, { capBytes: CAP }).tier).toBe("no_forecast");
  });

  test("a fresh reading is tier-eligible even with an empty history", () => {
    const usage = measureStorageUsage(vault);
    const forecast = forecastStorageUsage(vault, { capBytes: 100, latestUsage: usage });
    expect(forecast.measuredBytes).toBe(usage.totalBytes);
    expect(forecast.tier).toBe("ok");
    // One fresh reading is no trend.
    expect(forecast.slopeBytesPerDay).toBe(null);
    expect(forecast.daysToCap).toBe(null);
  });

  test("the freshest reading wins over the stored aggregate", () => {
    // Flat history at 90 percent: the stored aggregate alone warns.
    seedSample(1, 900);
    seedSample(0, 900);
    expect(forecastStorageUsage(vault, { capBytes: CAP }).tier).toBe("warn");
    // The fresh census of the same vault counts only the metric records
    // themselves - a fraction of the stored total - and answers ok.
    const usage = measureStorageUsage(vault);
    expect(usage.totalBytes).toBeLessThan(900);
    const forecast = forecastStorageUsage(vault, { capBytes: CAP, latestUsage: usage });
    expect(forecast.measuredBytes).toBe(usage.totalBytes);
    expect(forecast.tier).toBe("ok");
  });

  test("a shrinking vault never forecasts past the cap", () => {
    seedSample(2, 600);
    seedSample(1, 500);
    seedSample(0, 400);
    const forecast = forecastStorageUsage(vault, { capBytes: CAP });
    expect(forecast.slopeBytesPerDay).toBe(-100);
    expect(forecast.daysToCap).toBe(null);
    expect(forecast.tier).toBe("ok");
  });

  test("two samples a minute apart never produce a day-based tier", () => {
    // The H2 burst probe: a vault a third full, one ordinary 20 KB write
    // between two calls of the storage report a minute apart. The burst
    // extrapolates to tens of megabytes per day when fitted raw, which
    // read `critical` and refused ingest on a healthy vault. The trend
    // is day-based: both samples land on one UTC day, so no slope
    // exists, daysToCap stays null and the tier answers from the percent
    // alone - the fresh census the gate hands in measures 31 percent.
    expect(MIN_TREND_DAYS).toBe(3);
    const t0 = new Date(Date.parse("2026-10-15T12:00:00Z"));
    const base = 300 * 1024;
    mkdirSync(join(vault, "Brain", "sources"), { recursive: true });
    writeFileSync(join(vault, "Brain", "sources", "AA-base.md"), "x".repeat(base), "utf8");
    seedSampleAt(t0, base, "burst-1");
    writeFileSync(join(vault, "Brain", "sources", "AA-grow.md"), "x".repeat(20 * 1024), "utf8");
    seedSampleAt(new Date(t0.getTime() + 60_000), base + 20 * 1024, "burst-2");
    // The gate's path: fresh census for the percent, day-based history
    // for the trend.
    const decision = evaluateCapacityGate(vault, {
      capBytes: 1024 * 1024,
      now: new Date(t0.getTime() + 90_000),
    });
    expect(decision.tier).toBe("ok");
    expect(decision.decision).toBe("run");
    expect(decision.reading!.percentUsed).toBeLessThan(35);
    expect(decision.reading!.slopeBytesPerDay).toBe(null);
    expect(decision.reading!.daysToCap).toBe(null);
    // The samples-only path holds to the two-truths rule: one bucketed
    // day is one observation, and samples alone never tier.
    const forecast = forecastStorageUsage(vault, { capBytes: 1024 * 1024 });
    expect(forecast.tier).toBe("no_forecast");
  });

  test("an intraday burst folds into the day's last sample once days exist", () => {
    // Three distinct days fit a slope, and the day bucket keeps only the
    // day's LAST sample: a burst of intra-day readings cannot steer the
    // fit, whatever their spacing.
    seedSampleAt(new Date("2026-10-13T09:00:00Z"), 100, "d1");
    seedSampleAt(new Date("2026-10-14T09:00:00Z"), 200, "d2");
    // A burst on the last day, hours BEFORE the settled reading: three
    // readings minutes apart that the bucket must fold away.
    seedSampleAt(new Date("2026-10-15T08:00:00Z"), 9_900, "d3a");
    seedSampleAt(new Date("2026-10-15T08:01:00Z"), 9_950, "d3b");
    seedSampleAt(new Date("2026-10-15T09:00:00Z"), 300, "d3-final");
    const forecast = forecastStorageUsage(vault, { capBytes: 10_000 });
    expect(forecast.slopeBytesPerDay).toBe(100);
    expect(forecast.measuredBytes).toBe(300);
  });

  test("the fit runs over the trailing window, not the whole history", () => {
    // A reclamation 40 days ago (the vault was emptied) must not drag the
    // slope: the fit sees only the last TREND_WINDOW_DAYS days, where the
    // vault grows at a steady 100 bytes per day.
    expect(TREND_WINDOW_DAYS).toBe(30);
    seedSample(40, 0);
    seedSample(2, 300);
    seedSample(1, 400);
    seedSample(0, 500);
    const forecast = forecastStorageUsage(vault, { capBytes: 100_000 });
    expect(forecast.slopeBytesPerDay).toBe(100);
    expect(forecast.tier).toBe("ok");
  });

  test("a partial census never enters the trend", () => {
    // A sample recorded with measured: false carries a total that
    // understates the vault by exactly the refused surfaces. Fed into the
    // fit, the jump when the surface becomes readable again reads as
    // growth; parseSamples skips it, so the three complete days fit the
    // line and the partial day is evidence for no number at all.
    seedSample(3, 100);
    seedSample(2, 200);
    seedSample(1, 300);
    appendMetric(vault, {
      surface: STORAGE_USAGE_METRIC_SURFACE,
      runAt: "2026-10-15T12:00:00Z",
      payload: { run_id: "partial", total_bytes: 999_999, measured: false },
    });
    const forecast = forecastStorageUsage(vault, { capBytes: 100_000 });
    expect(forecast.slopeBytesPerDay).toBe(100);
    expect(forecast.measuredBytes).toBe(300);
  });

  test("a sample without the measured flag is not trend evidence either", () => {
    // The flag is the census's own claim of completeness, and absence is
    // not a claim: an unflagged sample never completes the three-day
    // minimum the slope needs.
    seedSample(2, 100);
    seedSample(1, 200);
    appendMetric(vault, {
      surface: STORAGE_USAGE_METRIC_SURFACE,
      runAt: "2026-10-15T12:00:00Z",
      payload: { run_id: "unflagged", total_bytes: 42 },
    });
    const forecast = forecastStorageUsage(vault, { capBytes: 100_000 });
    expect(forecast.slopeBytesPerDay).toBe(null);
    expect(forecast.daysToCap).toBe(null);
  });

  test.skipIf(CHMOD_CANNOT_DENY)("an incomplete measurement is unmeasurable", () => {
    seedSample(1, 100);
    seedSample(0, 200);
    mkdirSync(join(vault, "Brain", ".artifacts"), { recursive: true });
    chmodSync(join(vault, "Brain", ".artifacts"), 0o000);
    try {
      const usage = measureStorageUsage(vault);
      expect(usage.complete).toBe(false);
      const forecast = forecastStorageUsage(vault, { capBytes: CAP, latestUsage: usage });
      expect(forecast.tier).toBe("unmeasurable");
      expect(forecast.unmeasured).toHaveLength(1);
    } finally {
      chmodSync(join(vault, "Brain", ".artifacts"), 0o755);
    }
  });

  test("the forecast is deterministic for identical inputs", () => {
    seedSample(1, 100);
    seedSample(0, 200);
    const a = forecastStorageUsage(vault, { capBytes: CAP });
    const b = forecastStorageUsage(vault, { capBytes: CAP });
    expect(b).toEqual(a);
  });
});

describe("sampleStorageUsage", () => {
  test("appends exactly one storage_usage record per call", () => {
    const usage = measureStorageUsage(vault);
    const result = sampleStorageUsage(vault, { runId: "run-1", now: NOW });
    expect(result.appended).toBe(true);
    expect(result.runId).toBe("run-1");
    expect(result.usage.totalBytes).toBe(usage.totalBytes);
    const records = listMetrics(vault, { surface: STORAGE_USAGE_METRIC_SURFACE });
    expect(records).toHaveLength(1);
    expect(records[0]!.surface).toBe(STORAGE_USAGE_METRIC_SURFACE);
    expect(records[0]!.payload["total_bytes"]).toBe(usage.totalBytes);
    expect(records[0]!.payload["measured"]).toBe(true);
  });

  test("is idempotent per run id and appends again for a new one", () => {
    sampleStorageUsage(vault, { runId: "run-1", now: NOW });
    const repeat = sampleStorageUsage(vault, { runId: "run-1", now: NOW });
    expect(repeat.appended).toBe(false);
    expect(listMetrics(vault, { surface: STORAGE_USAGE_METRIC_SURFACE })).toHaveLength(1);
    const next = sampleStorageUsage(vault, { runId: "run-2", now: NOW });
    expect(next.appended).toBe(true);
    expect(listMetrics(vault, { surface: STORAGE_USAGE_METRIC_SURFACE })).toHaveLength(2);
  });

  test("a pre-measured census is recorded instead of walking the vault again", () => {
    // The census a gate already took, before the vault grew: the sampler
    // must record THESE bytes, not take a second census that would
    // measure the growth.
    const usage = measureStorageUsage(vault, { now: NOW });
    mkdirSync(join(vault, "Brain", "sources"), { recursive: true });
    writeFileSync(join(vault, "Brain", "sources", "AA-grown.md"), "x".repeat(50_000), "utf8");
    const result = sampleStorageUsage(vault, { runId: "run-1", now: NOW, usage });
    expect(result.usage).toBe(usage);
    expect(result.appended).toBe(true);
    const records = listMetrics(vault, { surface: STORAGE_USAGE_METRIC_SURFACE });
    expect(records).toHaveLength(1);
    expect(records[0]!.payload["total_bytes"]).toBe(usage.totalBytes);
  });

  test("an append failure is reported by name, never thrown", () => {
    // Brain/metrics exists as a regular file, so creating the metrics
    // directory fails and the append cannot land.
    mkdirSync(join(vault, "Brain"), { recursive: true });
    writeFileSync(join(vault, "Brain", "metrics"), "not a directory", "utf8");
    const result = sampleStorageUsage(vault, { runId: "run-1", now: NOW });
    expect(result.appended).toBe(false);
    expect(result.appendError).toContain("EEXIST");
    expect(result.appendError).toContain("metrics");
  });
});