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
15.0 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync } 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 {
  autoCloseRecalledGaps,
  detectRecurringGaps,
  gapTaskKey,
  GAP_SOURCE_ADEQUACY,
  GAP_SOURCE_TELEMETRY,
  GAP_SOURCES,
  GAP_TASK_CLOSED_RETENTION_MS,
  GAP_TASK_KIND,
  GAP_TASK_STATUS_CLOSED,
  GAP_TASK_STATUS_OPEN,
  GAP_TASKS_MAX_NOTES,
  listGapTasks,
  promoteGapsToTasks,
  renderGapAgenda,
  GapRecallScopeError,
  type GapRecallRetriever,
} from "../../../src/core/brain/gaps/gap-loop.ts";
import { brainGapTasksDir } from "../../../src/core/brain/paths.ts";
import type { RecallResultSet } from "../../../src/core/brain/recall-inject.ts";
import { UNTRUSTED_SOURCE_TAG } from "../../../src/core/brain/untrusted-source.ts";
import { parseFrontmatterText, writeFrontmatterAtomic } from "../../../src/core/vault.ts";

let vault: string;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-gap-loop-"));
  // 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 });
});

function seedGap(topic: string, times: number): void {
  for (let i = 0; i < times; i++) {
    emitRecallTelemetry(vault, {
      host: "test",
      channel: RECALL_CHANNEL.cli,
      mode: "search",
      status: "empty",
      durationMs: 0,
      resultCount: 0,
      gaps: [topic],
      createdAt: `2026-05-2${i}T09:00:00.000Z`,
    });
  }
}

const NOW = new Date("2026-06-01T12:00:00.000Z");

/** Path of the one ordinary note the fixtures below recall. */
const ORDINARY_NOTE = "Brain/x.md";

/** Path of a gap-task note - the row the membership rule excludes. */
const GAP_TASK_NOTE = "Brain/gap-tasks/gap-abc.md";

/**
 * A retrieval that covers `matchQuality` of the topic with a candidate
 * scoring `score`.
 *
 * Both are parameters, and callers are required to pass them on OPPOSITE
 * sides of the floor. A fixture where the two agree cannot tell the gate
 * apart from the substitution this release removed: with `score` and
 * coverage both at 0.92, reverting the gate to `topScore >= floor` leaves
 * the test green, so it asserts the outcome without asserting the reason.
 */
function retrieverWithCoverage(matchQuality: number | null, score: number): GapRecallRetriever {
  return async () =>
    ({
      candidates: [
        {
          path: ORDINARY_NOTE,
          title: "X",
          score,
          searchType: "hybrid",
          startLine: 1,
          endLine: 2,
        },
      ],
      total: 1,
      idfWeightedCoverage: matchQuality,
    }) satisfies RecallResultSet;
}

/** One row of the fixture corpus {@link retrieverOverRows} recalls. */
interface FixtureRow {
  readonly path: string;
  readonly score: number;
  /** Share of the topic this row alone covers. */
  readonly coverage: number;
}

/**
 * A retrieval that honours its membership rule the way a real one must:
 * the predicate selects the rows BEFORE the quality is measured, so the
 * number describes the rows the gate is about to judge.
 *
 * Coverage over the admitted rows is modelled as the best admitted row's
 * share, and zero when none survived - a measured zero, since the topic
 * has terms and nothing covered them.
 */
function retrieverOverRows(rows: ReadonlyArray<FixtureRow>): GapRecallRetriever {
  return async (_topic, admits) => {
    const admitted = rows.filter((row) => admits(row.path));
    return {
      candidates: admitted.map((row) => ({
        path: row.path,
        title: "X",
        score: row.score,
        searchType: "hybrid" as const,
        startLine: 1,
        endLine: 2,
      })),
      total: admitted.length,
      idfWeightedCoverage:
        admitted.length === 0 ? 0 : Math.max(...admitted.map((row) => row.coverage)),
    } satisfies RecallResultSet;
  };
}

describe("gap loop (A3 / t_67d38036)", () => {
  test("detects only gaps at or above the recurrence threshold, most-frequent first", () => {
    seedGap("alpha topic", 3);
    seedGap("beta topic", 2);
    seedGap("gamma topic", 1);
    const recurring = detectRecurringGaps(vault, { threshold: 2 });
    expect(recurring.map((g) => g.topic)).toEqual(["alpha topic", "beta topic"]);
    expect(recurring[0]?.occurrences).toBe(3);
  });

  test("promotes each recurring gap to one durable gap-task note under the Brain area", () => {
    seedGap("alpha topic", 3);
    const result = promoteGapsToTasks(vault, { threshold: 2, now: NOW });
    expect(result.created).toHaveLength(1);
    const key = gapTaskKey("alpha topic");
    const path = join(vault, "Brain", "gap-tasks", `${key}.md`);
    expect(existsSync(path)).toBe(true);
    const [fm] = parseFrontmatterText(readFileSync(path, "utf8"));
    expect(fm["kind"]).toBe(GAP_TASK_KIND);
    expect(fm["status"]).toBe(GAP_TASK_STATUS_OPEN);
    expect(fm["gap_topic"]).toBe("alpha topic");
    // Plain note file: no kanban board fields whatsoever.
    expect(fm["board"]).toBeUndefined();
    expect(fm["column"]).toBeUndefined();
  });

  test("re-promotion dedupes on the stable gap key and never collides", () => {
    seedGap("alpha topic", 3);
    const first = promoteGapsToTasks(vault, { threshold: 2, now: NOW });
    const second = promoteGapsToTasks(vault, { threshold: 2, now: NOW });
    expect(first.created).toHaveLength(1);
    expect(second.created).toHaveLength(0);
    expect(second.skipped).toEqual([gapTaskKey("alpha topic")]);
  });

  test("renders open gap tasks as a compact agenda through the shared helper", () => {
    seedGap("alpha topic", 3);
    promoteGapsToTasks(vault, { threshold: 2, now: NOW });
    const agenda = renderGapAgenda(vault, NOW);
    expect(agenda).toContain("alpha topic");
    // The shared activity helper stamps the fixed "open" marker for questions.
    expect(agenda).toContain("[open]");
  });

  test("the agenda is fenced as untrusted content and gap topics are single-line neutralized", () => {
    // Gap topics come from recall telemetry buckets, and telemetry text
    // originates outside this module: the agenda block rides the shared
    // fence, and each topic rides the single-line neutralizer.
    const zwsp = String.fromCodePoint(0x200b);
    seedGap(`al${zwsp}pha topic`, 3);
    promoteGapsToTasks(vault, { threshold: 2, now: NOW });
    const agenda = renderGapAgenda(vault, NOW);
    expect(agenda).toContain(`<${UNTRUSTED_SOURCE_TAG} origin="recall-gap-agenda">`);
    expect(agenda.trimEnd().endsWith(`</${UNTRUSTED_SOURCE_TAG}>`)).toBe(true);
    const closes = agenda.split(`</${UNTRUSTED_SOURCE_TAG}>`).length - 1;
    expect(closes).toBe(1);
    expect(agenda).not.toContain(zwsp);
    expect(agenda).toContain("alpha topic");
  });

  test("agenda is empty when there are no open gap tasks", () => {
    expect(renderGapAgenda(vault, NOW)).toBe("");
  });

  test("auto-closes a gap task once its topic is recalled with sufficient confidence", async () => {
    seedGap("alpha topic", 3);
    promoteGapsToTasks(vault, { threshold: 2, now: NOW });
    // Coverage above the floor, score far below it: only the gate that
    // reads coverage can close this task.
    const result = await autoCloseRecalledGaps(vault, retrieverWithCoverage(0.92, 0.05), {
      confidenceFloor: 0.5,
      now: NOW,
    });
    expect(result.closed).toEqual([gapTaskKey("alpha topic")]);
    const open = listGapTasks(vault, { status: GAP_TASK_STATUS_OPEN });
    expect(open).toHaveLength(0);
    const closed = listGapTasks(vault, { status: GAP_TASK_STATUS_CLOSED });
    expect(closed).toHaveLength(1);
    const [fm] = parseFrontmatterText(readFileSync(closed[0]!.path, "utf8"));
    expect(fm["status"]).toBe(GAP_TASK_STATUS_CLOSED);
    expect(typeof fm["closed_at"]).toBe("string");
  });

  test("never self-closes: the gap-task note cannot supply the coverage the floor reads", async () => {
    seedGap("alpha topic", 3);
    promoteGapsToTasks(vault, { threshold: 2, now: NOW });
    // The gap-task note covers its own topic completely - it carries the
    // topic verbatim - and one ordinary note mentions it in passing. The
    // membership rule excludes the first, so the quality the floor reads
    // must be the second's 0.1, not the pair's 1.0.
    //
    // This is the case the previous shape got wrong. It filtered the task
    // note out of `coveredElsewhere` but read a coverage number measured
    // over BOTH rows, so the note it was excluding still cleared the floor
    // for it and the task closed on its own text.
    const result = await autoCloseRecalledGaps(
      vault,
      retrieverOverRows([
        { path: GAP_TASK_NOTE, score: 0.99, coverage: 1 },
        { path: ORDINARY_NOTE, score: 0.4, coverage: 0.1 },
      ]),
      { confidenceFloor: 0.5, now: NOW },
    );
    expect(result.closed).toHaveLength(0);
    expect(listGapTasks(vault, { status: GAP_TASK_STATUS_OPEN })).toHaveLength(1);
  });

  test("a retriever that answers outside the membership rule is refused by name", async () => {
    seedGap("alpha topic", 3);
    promoteGapsToTasks(vault, { threshold: 2, now: NOW });
    // Ignores `admits` and returns the excluded row anyway. Its quality
    // number therefore describes rows the gate rejects, and reading it
    // would be reading a measurement of something else.
    const ignoresTheRule: GapRecallRetriever = async () =>
      ({
        candidates: [
          {
            path: GAP_TASK_NOTE,
            title: "gap",
            score: 0.99,
            searchType: "hybrid",
            startLine: 1,
            endLine: 2,
          },
        ],
        total: 1,
        idfWeightedCoverage: 1,
      }) satisfies RecallResultSet;
    await expect(
      autoCloseRecalledGaps(vault, ignoresTheRule, { confidenceFloor: 0.5, now: NOW }),
    ).rejects.toThrow(GapRecallScopeError);
    expect(listGapTasks(vault, { status: GAP_TASK_STATUS_OPEN })).toHaveLength(1);
  });

  test("keeps a gap task open when recall stays below the confidence floor", async () => {
    seedGap("alpha topic", 3);
    promoteGapsToTasks(vault, { threshold: 2, now: NOW });
    // Coverage below the floor, score far above it: only the gate that
    // reads coverage can keep this task open.
    const result = await autoCloseRecalledGaps(vault, retrieverWithCoverage(0.2, 0.99), {
      confidenceFloor: 0.5,
      now: NOW,
    });
    expect(result.closed).toHaveLength(0);
    expect(listGapTasks(vault, { status: GAP_TASK_STATUS_OPEN })).toHaveLength(1);
  });

  test("an unmeasurable recall never closes a task", async () => {
    seedGap("alpha topic", 3);
    promoteGapsToTasks(vault, { threshold: 2, now: NOW });
    // A confident-looking row with no measurable quality behind it: the
    // exact pair the old `totalIdf === 0 ? 1` produced, which cleared
    // every floor.
    const result = await autoCloseRecalledGaps(vault, retrieverWithCoverage(null, 0.99), {
      confidenceFloor: 0.5,
      now: NOW,
    });
    expect(result.closed).toHaveLength(0);
    expect(listGapTasks(vault, { status: GAP_TASK_STATUS_OPEN })).toHaveLength(1);
  });
});

// ----- the directory the loop writes into is bounded ------------------------

describe("gap-task retention", () => {
  /** Write one gap-task note directly, bypassing the mint budget. */
  function writeTask(key: string, status: string, closedAt?: string): void {
    writeFrontmatterAtomic(
      join(brainGapTasksDir(vault), `${key}.md`),
      {
        kind: GAP_TASK_KIND,
        gap_key: key,
        gap_topic: key,
        gap_source: GAP_SOURCE_TELEMETRY,
        status,
        occurrences: "3",
        created_at: "2026-01-01T00:00:00.000Z",
        ...(closedAt !== undefined ? { closed_at: closedAt, closed_reason: "recalled" } : {}),
      },
      "body",
      { vaultForRelativePath: vault, overwrite: true },
    );
  }

  test("a closed task past the retention window is removed, and the removal is reported", () => {
    const stale = new Date(NOW.getTime() - GAP_TASK_CLOSED_RETENTION_MS - 1).toISOString();
    writeTask("gap-stale", GAP_TASK_STATUS_CLOSED, stale);
    writeTask("gap-recent", GAP_TASK_STATUS_CLOSED, NOW.toISOString());
    writeTask("gap-open", GAP_TASK_STATUS_OPEN);

    const result = promoteGapsToTasks(vault, { threshold: 2, now: NOW });
    expect(result.pruned).toEqual(["gap-stale"]);
    expect(
      listGapTasks(vault)
        .map((t) => t.key)
        .toSorted(),
    ).toEqual(["gap-open", "gap-recent"]);
  });

  test("an open task is never pruned, however old it is", () => {
    writeTask("gap-open", GAP_TASK_STATUS_OPEN);
    const result = promoteGapsToTasks(vault, {
      threshold: 2,
      now: new Date(NOW.getTime() + GAP_TASK_CLOSED_RETENTION_MS * 10),
    });
    expect(result.pruned).toEqual([]);
    expect(listGapTasks(vault)).toHaveLength(1);
  });

  test("at the cap, minting is REFUSED and named - never silently skipped", () => {
    for (let i = 0; i < GAP_TASKS_MAX_NOTES; i++)
      writeTask(`gap-filler-${i}`, GAP_TASK_STATUS_OPEN);
    seedGap("alpha topic", 3);
    const result = promoteGapsToTasks(vault, { threshold: 2, now: NOW });
    expect(result.created).toEqual([]);
    expect(result.capped).toBe(1);
    expect(listGapTasks(vault)).toHaveLength(GAP_TASKS_MAX_NOTES);
  });

  test("at the cap, a topic that already has a note is skipped, not counted as refused", () => {
    writeTask(gapTaskKey("alpha topic"), GAP_TASK_STATUS_OPEN);
    for (let i = 0; i < GAP_TASKS_MAX_NOTES - 1; i++) {
      writeTask(`gap-filler-${i}`, GAP_TASK_STATUS_OPEN);
    }
    seedGap("alpha topic", 3);
    const result = promoteGapsToTasks(vault, { threshold: 2, now: NOW });
    expect(result.capped).toBe(0);
    expect(result.skipped).toEqual([gapTaskKey("alpha topic")]);
  });

  test("room freed by pruning is usable in the same run", () => {
    const stale = new Date(NOW.getTime() - GAP_TASK_CLOSED_RETENTION_MS - 1).toISOString();
    for (let i = 0; i < GAP_TASKS_MAX_NOTES - 1; i++) {
      writeTask(`gap-filler-${i}`, GAP_TASK_STATUS_OPEN);
    }
    writeTask("gap-stale", GAP_TASK_STATUS_CLOSED, stale);
    seedGap("alpha topic", 3);
    const result = promoteGapsToTasks(vault, { threshold: 2, now: NOW });
    expect(result.pruned).toEqual(["gap-stale"]);
    expect(result.created).toEqual([gapTaskKey("alpha topic")]);
    expect(result.capped).toBe(0);
  });
});

// ----- keys are collision-free across the two recurrence sources ------------

describe("gapTaskKey", () => {
  test("a telemetry topic spelled like the adequacy namespace does not collide", () => {
    expect(gapTaskKey(`${GAP_SOURCE_ADEQUACY}:alpha`, GAP_SOURCE_TELEMETRY)).not.toBe(
      gapTaskKey("alpha", GAP_SOURCE_ADEQUACY),
    );
  });

  test("both sources are namespaced, so no pair of (source, topic) can share a key", () => {
    const seen = new Set<string>();
    for (const source of GAP_SOURCES) {
      for (const topic of ["alpha", "recall_adequacy:alpha", "recall_telemetry:alpha", "2:alpha"]) {
        seen.add(gapTaskKey(topic, source));
      }
    }
    expect(seen.size).toBe(8);
  });
});