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.2 KB
Raw Blame
/**
 * Targeted recompile of stale derived pages
 * (continuity-hygiene-freshness suite, Task 12; kanban t_fe490119).
 *
 * The planner walks freshness findings and produces a typed plan:
 * stale handoff notes re-derive from their recorded transcript onto
 * the SAME page path, orphaned pages stage an archive cleanup,
 * anything without a known derivation pipeline is `manual`. Dry-run
 * previews the full plan with zero writes. Unrelated pages are never
 * touched.
 */

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

import { checkPageFreshness } from "../../../src/core/brain/freshness.ts";
import { freezeVault } from "../../../src/core/brain/freeze.ts";
import { writeHandoffNote } from "../../../src/core/brain/handoff.ts";
import { executeRecompile, planRecompile } from "../../../src/core/brain/recompile.ts";

let vault: string;

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

/** A minimal Claude-format transcript the session adapters can read. */
function writeTranscript(path: string, text: string): void {
  writeFileSync(
    path,
    [
      '{"type":"queue-operation","timestamp":"2026-06-10T10:00:00.000Z","sessionId":"recompile-sess"}',
      `{"parentUuid":null,"sessionId":"recompile-sess","entrypoint":"sdk-cli","type":"user","message":{"role":"user","content":${JSON.stringify(text)}},"uuid":"u1","timestamp":"2026-06-10T10:00:01.000Z"}`,
      "",
    ].join("\n"),
    "utf8",
  );
}

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-recompile-"));
  mkdirSync(join(vault, "Brain", "handoffs"), { recursive: true });
});

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

function seedStaleHandoff(): { page: string; transcript: string } {
  const transcript = join(vault, "session.jsonl");
  writeTranscript(transcript, "implemented the original feature");
  const note = writeHandoffNote(vault, {
    sessionId: "recompile-sess",
    agent: "tester",
    now: new Date("2026-06-09T12:00:00Z"),
    turns: [
      {
        turnId: "t1",
        role: "user",
        text: "implemented the original feature",
        timestamp: "2026-06-10T10:00:01Z",
      },
    ],
    sourcePaths: [transcript],
  });
  // The transcript changes after derivation -> the note goes stale.
  writeTranscript(transcript, "implemented the UPDATED feature with new scope");
  return { page: note.path, transcript };
}

describe("planRecompile", () => {
  test("maps stale handoff notes to rederive and orphans to cleanup", () => {
    const { page } = seedStaleHandoff();
    const orphan = join(vault, "Brain", "orphan.md");
    writeFileSync(
      orphan,
      '---\nsource_paths: ["gone.md"]\nsource_hashes: ["deadbeef"]\n---\nbody',
      "utf8",
    );
    const plan = planRecompile(vault);
    const byKind = new Map(plan.entries.map((entry) => [entry.kind, entry]));
    expect(byKind.get("rederive-handoff")?.page).toBe(page);
    expect(byKind.get("cleanup")?.page).toBe(orphan);
    expect(plan.entries).toHaveLength(2);
  });

  test("a stale page without a known pipeline plans as manual", () => {
    const source = join(vault, "data.txt");
    writeFileSync(source, "v1", "utf8");
    const page = join(vault, "Brain", "derived.md");
    const { computeSourceStamp, formatSourceStampFrontmatter } =
      require("../../../src/core/brain/freshness.ts") as typeof import("../../../src/core/brain/freshness.ts");
    writeFileSync(
      page,
      `---\n${formatSourceStampFrontmatter(computeSourceStamp(vault, ["data.txt"]))}\n---\nbody`,
      "utf8",
    );
    writeFileSync(source, "v2", "utf8");
    const plan = planRecompile(vault);
    expect(plan.entries[0]?.kind).toBe("manual");
  });
});

describe("executeRecompile", () => {
  test("dry-run previews and writes nothing", async () => {
    const { page } = seedStaleHandoff();
    const before = readFileSync(page, "utf8");
    const plan = planRecompile(vault);
    const result = await executeRecompile(vault, plan, { dryRun: true, agent: "tester", now: NOW });
    expect(result.dry_run).toBe(true);
    expect(result.rederived).toHaveLength(0);
    expect(readFileSync(page, "utf8")).toBe(before);
  });

  test("previews and refreshes stale active preferences without rewriting a fresh digest", async () => {
    const digest = join(vault, "Brain", "active.md");
    const stale =
      "---\ngenerated_at: 2026-06-09T12:00:00Z\n---\n## Confirmed (1)\n- retired marker\n";
    writeFileSync(digest, stale, "utf8");
    expect(planRecompile(vault).entries).toEqual([]);
    const plan = planRecompile(vault, { now: NOW, includeActiveDigest: true });
    expect(plan.entries).toContainEqual({
      kind: "rederive-active",
      page: digest,
      reason: "the active preference digest differs from current memory state",
    });
    await executeRecompile(vault, plan, { dryRun: true, agent: "tester", now: NOW });
    expect(readFileSync(digest, "utf8")).toBe(stale);

    const result = await executeRecompile(vault, plan, { agent: "tester", now: NOW });
    expect(result.rederived).toEqual([digest]);
    expect(result.errors).toEqual([]);
    const fresh = readFileSync(digest, "utf8");
    expect(fresh).toContain("## Confirmed (0)");
    expect(fresh).not.toContain("retired marker");
    expect(planRecompile(vault, { now: NOW, includeActiveDigest: true }).entries).toEqual([]);
    expect(readFileSync(digest, "utf8")).toBe(fresh);
  });

  test("a frozen vault can preview a stale active digest but refuses a refresh write", async () => {
    const digest = join(vault, "Brain", "active.md");
    const stale = "---\nkind: brain-active\n---\n\n## Confirmed (1)\n";
    writeFileSync(digest, stale, "utf8");
    freezeVault(vault, { now: NOW, agent: "tester", reason: "migration" });
    const plan = planRecompile(vault, { now: NOW, includeActiveDigest: true });
    expect(plan.entries.map((entry) => entry.kind)).toEqual(["rederive-active"]);
    await executeRecompile(vault, plan, { dryRun: true, now: NOW, agent: "tester" });
    await expect(executeRecompile(vault, plan, { now: NOW, agent: "tester" })).rejects.toThrow(
      "frozen",
    );
    expect(readFileSync(digest, "utf8")).toBe(stale);
  });

  test("re-derives a stale handoff note in place and makes it fresh again", async () => {
    const { page } = seedStaleHandoff();
    const plan = planRecompile(vault);
    const result = await executeRecompile(vault, plan, { agent: "tester", now: NOW });
    expect(result.rederived).toEqual([page]);
    expect(readFileSync(page, "utf8")).toContain("UPDATED feature");
    expect(checkPageFreshness(vault, page)?.status).toBe("fresh");
  });

  test("cleanup archives the orphaned page out of its live location", async () => {
    const orphan = join(vault, "Brain", "orphan.md");
    writeFileSync(
      orphan,
      '---\nsource_paths: ["gone.md"]\nsource_hashes: ["deadbeef"]\n---\nbody',
      "utf8",
    );
    const plan = planRecompile(vault);
    const result = await executeRecompile(vault, plan, { agent: "tester", now: NOW });
    expect(result.archived).toHaveLength(1);
    expect(existsSync(orphan)).toBe(false);
    expect(existsSync(result.archived[0]!)).toBe(true);
    expect(result.archived[0]).toContain(".snapshots");
  });
});