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
13.1 KB
Raw Blame
/**
 * Dead-weight utilization fold (recall-quality, t_1ee67e5b / task D3).
 *
 * The complement of retrieval: full set = the vault walk's included
 * `.md` pages (the population recall can currently return), retrieved
 * set = the union of `recall_telemetry` top-artifact paths and
 * `recall_observed_use` source-ref paths, and everything in the full set
 * that no record ever surfaced is dead weight. Three honesty rules are
 * pinned here:
 *
 *   - a vanished page (deleted on disk, still in some stale index) is
 *     never reported: the denominator is the LIVE walk, so a deletion
 *     cannot masquerade as dead weight, and a vanished path inside a
 *     record neither counts as retrieved nor leaks;
 *   - the observation window is stated from the records themselves (the
 *     earliest and latest matching `createdAt`), never from the clock;
 *   - the fold is read-only and deterministic: no emit, no mutation, and
 *     two runs over the same inputs agree exactly.
 *
 * "Dead" therefore means "never surfaced in recorded telemetry history
 * within the window" - telemetry is opt-in and records only the surfaced
 * top rows, so the report carries the caveat verbatim rather than a
 * stronger claim it cannot prove.
 */

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

import { emitRecallTelemetry, RECALL_CHANNEL } from "../../../src/core/brain/recall-telemetry.ts";
import { emitObservedUse } from "../../../src/core/brain/observed-use.ts";
import { computeDeadWeight } from "../../../src/core/brain/dead-weight.ts";

let vault: string;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-dead-weight-"));
  mkdirSync(join(vault, "Brain"), { recursive: true });
  writeMd("a.md", "# A\n\nalpha beta gamma.\n");
  writeMd("b.md", "# B\n\nalpha beta delta.\n");
  writeMd("c.md", "# C\n\nalpha epsilon zeta.\n");
  writeMd("sub/d.md", "# D\n\neta theta iota.\n");
  // Not a page: the walk counts it, the fold must not.
  writeFileSync(join(vault, "notes.txt"), "plain text attachment\n");
});

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

function writeMd(relPath: string, content: string): void {
  const abs = join(vault, relPath);
  mkdirSync(join(abs, ".."), { recursive: true });
  writeFileSync(abs, content);
}

describe("computeDeadWeight", () => {
  test("reports the complement of recorded retrieval", () => {
    emitRecallTelemetry(vault, {
      createdAt: "2026-05-20T16:00:00.000Z",
      host: "fold-test",
      channel: RECALL_CHANNEL.cli,
      mode: "search",
      status: "ok",
      durationMs: 5,
      resultCount: 2,
      topArtifacts: [
        { id: "doc-a:0", path: "a.md" },
        { id: "doc-b:0", path: "b.md" },
      ],
    });
    emitObservedUse(vault, {
      createdAt: "2026-05-21T09:00:00.000Z",
      host: "fold-test",
      entries: [{ id: "doc-c:0", path: "c.md", verdict: "USED" }],
    });

    const report = computeDeadWeight(vault);
    expect(report.pages_total).toBe(4);
    expect(report.pages_retrieved).toBe(3);
    expect(report.dead_count).toBe(1);
    expect(report.dead).toEqual([{ path: "sub/d.md" }]);
    // The window is the records' own span, not the wall clock.
    expect(report.window.since).toBe("2026-05-20T16:00:00.000Z");
    expect(report.window.until).toBe("2026-05-21T09:00:00.000Z");
  });

  test("a vanished page is never reported, from either side of the fold", () => {
    emitRecallTelemetry(vault, {
      createdAt: "2026-05-20T16:00:00.000Z",
      host: "fold-test",
      channel: RECALL_CHANNEL.cli,
      mode: "search",
      status: "ok",
      durationMs: 5,
      resultCount: 1,
      topArtifacts: [
        { id: "gone:0", path: "gone.md" },
        { id: "doc-a:0", path: "a.md" },
      ],
    });

    const report = computeDeadWeight(vault);
    expect(report.pages_total).toBe(4);
    // The vanished path was surfaced once, but it is not a page the vault
    // can return any more: it neither counts as retrieved nor appears as
    // dead weight (deleting a page is not what dead weight measures).
    expect(report.pages_retrieved).toBe(1);
    expect(report.dead.map((d) => d.path)).toEqual(["b.md", "c.md", "sub/d.md"]);
    expect(report.dead_count).toBe(3);
  });

  test("since and until bound the records folded, and the window follows", () => {
    emitRecallTelemetry(vault, {
      createdAt: "2026-05-20T16:00:00.000Z",
      host: "fold-test",
      channel: RECALL_CHANNEL.cli,
      mode: "search",
      status: "ok",
      durationMs: 5,
      resultCount: 1,
      topArtifacts: [{ id: "doc-a:0", path: "a.md" }],
    });
    emitObservedUse(vault, {
      createdAt: "2026-05-21T09:00:00.000Z",
      host: "fold-test",
      entries: [{ id: "doc-c:0", path: "c.md", verdict: "USED" }],
    });

    const onlyLate = computeDeadWeight(vault, { since: "2026-05-21T00:00:00.000Z" });
    expect(onlyLate.pages_retrieved).toBe(1);
    expect(onlyLate.dead.map((d) => d.path)).toEqual(["a.md", "b.md", "sub/d.md"]);
    expect(onlyLate.window.since).toBe("2026-05-21T09:00:00.000Z");

    const onlyEarly = computeDeadWeight(vault, { until: "2026-05-21T00:00:00.000Z" });
    expect(onlyEarly.pages_retrieved).toBe(1);
    expect(onlyEarly.window.until).toBe("2026-05-20T16:00:00.000Z");
  });

  test("hidden-page-only telemetry never widens or shifts the window at remote reach", () => {
    // The caller's reach: everything under sub/ is hidden to this view,
    // exactly the predicate the surfaces compose from requestRefView and
    // the gated owner scope.
    const view = (rel: string) => !rel.startsWith("sub/");
    // A hidden-only record BEFORE the visible one, the visible one, and a
    // hidden-only record AFTER it: only the visible record may shape the
    // remote window, from either side.
    emitRecallTelemetry(vault, {
      createdAt: "2026-05-01T00:00:00.000Z",
      host: "fold-test",
      channel: RECALL_CHANNEL.cli,
      mode: "search",
      status: "ok",
      durationMs: 5,
      resultCount: 1,
      topArtifacts: [{ id: "doc-d:0", path: "sub/d.md" }],
    });
    emitRecallTelemetry(vault, {
      createdAt: "2026-05-20T16:00:00.000Z",
      host: "fold-test",
      channel: RECALL_CHANNEL.cli,
      mode: "search",
      status: "ok",
      durationMs: 5,
      resultCount: 1,
      topArtifacts: [{ id: "doc-a:0", path: "a.md" }],
    });
    emitObservedUse(vault, {
      createdAt: "2026-05-25T23:59:00.000Z",
      host: "fold-test",
      entries: [{ id: "doc-d:1", path: "sub/d.md", verdict: "USED" }],
    });

    const remote = computeDeadWeight(vault, { includePath: view });
    // Counts were already clean: the hidden page drops before totals.
    expect(remote.pages_total).toBe(3);
    expect(remote.pages_retrieved).toBe(1);
    expect(remote.dead.map((d) => d.path)).toEqual(["b.md", "c.md"]);
    // The window rides the same view: the hidden-page records' earlier and
    // later timestamps must not widen or shift it.
    expect(remote.window.since).toBe("2026-05-20T16:00:00.000Z");
    expect(remote.window.until).toBe("2026-05-20T16:00:00.000Z");

    // Owner reach filters nothing, so the owner still sees the full span.
    const owner = computeDeadWeight(vault);
    expect(owner.pages_total).toBe(4);
    expect(owner.window.since).toBe("2026-05-01T00:00:00.000Z");
    expect(owner.window.until).toBe("2026-05-25T23:59:00.000Z");
  });

  test("a vault with no records reports an empty window and everything dead", () => {
    const report = computeDeadWeight(vault);
    expect(report.pages_total).toBe(4);
    expect(report.pages_retrieved).toBe(0);
    expect(report.dead_count).toBe(4);
    expect(report.window.since).toBeNull();
    expect(report.window.until).toBeNull();
    expect(report.gate_caveat.length).toBeGreaterThan(0);
  });

  test("the dead preview is capped while dead_count stays exact", () => {
    emitRecallTelemetry(vault, {
      createdAt: "2026-05-20T16:00:00.000Z",
      host: "fold-test",
      channel: RECALL_CHANNEL.cli,
      mode: "search",
      status: "ok",
      durationMs: 5,
      resultCount: 1,
      topArtifacts: [{ id: "doc-a:0", path: "a.md" }],
    });
    const report = computeDeadWeight(vault, { deadLimit: 2 });
    expect(report.dead_count).toBe(3);
    expect(report.dead).toEqual([{ path: "b.md" }, { path: "c.md" }]);
  });

  test("the fold is deterministic and emits nothing", () => {
    emitRecallTelemetry(vault, {
      createdAt: "2026-05-20T16:00:00.000Z",
      host: "fold-test",
      channel: RECALL_CHANNEL.cli,
      mode: "search",
      status: "ok",
      durationMs: 5,
      resultCount: 1,
      topArtifacts: [{ id: "doc-b:0", path: "b.md" }],
    });
    const logBefore = readdirSync(join(vault, "Brain", "log"), {
      recursive: true,
    }).toSorted();
    const first = computeDeadWeight(vault);
    const second = computeDeadWeight(vault);
    expect(second).toEqual(first);
    expect(readdirSync(join(vault, "Brain", "log"), { recursive: true }).toSorted()).toEqual(
      logBefore,
    );
  });
});

/**
 * The emitters spell surfaced pages in more than the vault-relative way
 * the fold originally compared (PR #248 review M10): context packs record
 * `join(dir, name)` - absolute - and a Windows writer leaves backslashes
 * in the spelling; pre-compress records the active page as an absolute
 * path and its preference items as ids only. Every spelling names a page
 * the walk holds, so every one must count as retrieved; an id that names
 * no walked page counts as neither retrieved nor dead and lands in the
 * `unresolved_ids` bucket instead of vanishing.
 */
describe("surfaced spellings beyond the relative one", () => {
  test("a page a context pack surfaces by absolute path is not dead weight", () => {
    emitRecallTelemetry(vault, {
      createdAt: "2026-05-20T16:00:00.000Z",
      host: "fold-test",
      channel: RECALL_CHANNEL.cli,
      mode: "context_pack",
      status: "ok",
      durationMs: 5,
      resultCount: 1,
      // The shape context-pack.ts emits: `path` is the absolute file path.
      topArtifacts: [{ id: "pref-a:0", path: join(vault, "a.md") }],
    });
    const report = computeDeadWeight(vault);
    expect(report.pages_retrieved).toBe(1);
    expect(report.dead.map((d) => d.path)).toEqual(["b.md", "c.md", "sub/d.md"]);
    expect(report.unresolved_ids).toBe(0);
  });

  test("a backslash-spelled relative path matches the walked page", () => {
    emitRecallTelemetry(vault, {
      createdAt: "2026-05-20T16:00:00.000Z",
      host: "fold-test",
      channel: RECALL_CHANNEL.cli,
      mode: "search",
      status: "ok",
      durationMs: 5,
      resultCount: 1,
      topArtifacts: [{ id: "doc-d:0", path: "sub\\d.md" }],
    });
    const report = computeDeadWeight(vault);
    expect(report.pages_retrieved).toBe(1);
    expect(report.dead.map((d) => d.path)).toEqual(["a.md", "b.md", "c.md"]);
  });

  test("pre-compress records: the active page by absolute path, items by id", () => {
    writeMd("Brain/active.md", "# Active\n\nthe digest page\n");
    writeMd("Brain/preferences/pref-keep-short.md", "# Keep it short\n\nstatus: confirmed\n");
    emitRecallTelemetry(vault, {
      createdAt: "2026-05-20T16:00:00.000Z",
      host: "fold-test",
      channel: RECALL_CHANNEL.hook,
      mode: "pre_compress",
      status: "ok",
      durationMs: 5,
      resultCount: 2,
      // The shape pre-compress-pack.ts emits: the active head as an
      // absolute path, each ranked preference item as its id only.
      topArtifacts: [
        { id: "__active__", path: join(vault, "Brain", "active.md") },
        { id: "pref-keep-short" },
      ],
    });
    const report = computeDeadWeight(vault);
    // The walk now holds six pages; the two the pack surfaced count as
    // retrieved, resolved from the absolute path and from the id.
    expect(report.pages_total).toBe(6);
    expect(report.pages_retrieved).toBe(2);
    expect(report.dead.map((d) => d.path)).toEqual(["a.md", "b.md", "c.md", "sub/d.md"]);
    expect(report.unresolved_ids).toBe(0);
  });

  test("an id that names no walked page counts in the unresolved bucket", () => {
    emitRecallTelemetry(vault, {
      createdAt: "2026-05-20T16:00:00.000Z",
      host: "fold-test",
      channel: RECALL_CHANNEL.hook,
      mode: "pre_compress",
      status: "ok",
      durationMs: 5,
      resultCount: 1,
      topArtifacts: [{ id: "pref-gone" }],
    });
    const report = computeDeadWeight(vault);
    expect(report.pages_retrieved).toBe(0);
    expect(report.dead_count).toBe(4);
    expect(report.unresolved_ids).toBe(1);
  });

  test("an ambiguous stem is unresolved, never a guess between two pages", () => {
    writeMd("sub/a.md", "# A again\n");
    emitRecallTelemetry(vault, {
      createdAt: "2026-05-20T16:00:00.000Z",
      host: "fold-test",
      channel: RECALL_CHANNEL.hook,
      mode: "pre_compress",
      status: "ok",
      durationMs: 5,
      resultCount: 1,
      topArtifacts: [{ id: "a" }],
    });
    const report = computeDeadWeight(vault);
    // Both `a.md` and `sub/a.md` stay dead: the fold does not pick one.
    expect(report.pages_retrieved).toBe(0);
    expect(report.dead_count).toBe(5);
    expect(report.unresolved_ids).toBe(1);
  });
});