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
8.3 KB
Raw Blame
/**
 * Serve-with-correction coupling across the Brain serving surfaces
 * (truth-correctable-time-aware, Task 19).
 *
 * Every surface that serves a retired-but-serveable record decides
 * through `couplingVerdict`: the record appears only beside its
 * resolved, readable chain-tip correction and is dropped fail-closed
 * otherwise - a withheld correction takes its predecessor with it. The
 * surfaces covered here are recall by topic (`queryByRuleTopic`), the
 * context pack, the active.md digest and the dream scan.
 *
 * Today's exclusion wiring is pinned too: a tombstoned retired record
 * stays hidden everywhere (the status filter's job, before any coupling
 * question arises), a retired record with no successor pointer is not in
 * the predicate's regime and keeps today's behavior, and every surface's
 * non-retired output is unchanged.
 */

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

import { bootstrapBrain } from "../../../src/core/brain/init.ts";
import { brainDirs } from "../../../src/core/brain/paths.ts";
import { queryByRuleTopic } from "../../../src/core/brain/query.ts";
import { packContext } from "../../../src/core/brain/context-pack.ts";
import { renderActive } from "../../../src/core/brain/active.ts";
import { scanBrain } from "../../../src/core/brain/dream-scan.ts";
import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";

let vault: string;
let configHome: string;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-coupling-surfaces-"));
  configHome = mkdtempSync(join(tmpdir(), "o2b-coupling-surfaces-cfg-"));
  const configPath = join(configHome, "config.yaml");
  atomicWriteFileSync(configPath, `vault: ${vault}\n`);
  bootstrapBrain(vault, { configPath });
});

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

/** Frontmatter lines plus body of a retired record, written vault-relative. */
function writeRetired(
  id: string,
  fields: { topic: string; supersededBy?: string; tombstoned?: boolean },
): void {
  const lines = [
    "---",
    "kind: brain-retired",
    `id: ${id}`,
    // Group C fields use the `_`-prefixed shape on disk; a tombstoned
    // record carries the tombstone status in the same field, which is
    // what the shared exclusion predicate reads.
    fields.tombstoned === true ? "_status: tombstoned" : "_status: retired",
    "retired_at: 2026-06-01T00:00:00Z",
    "retired_reason: stale-no-evidence",
    "retired_by: '[[Brain/log/2026-06-01]]'",
    "created_at: 2026-05-01T00:00:00Z",
    "tags: [brain, brain/retired]",
    `topic: ${fields.topic}`,
    `principle: Retired rule for ${fields.topic}.`,
    "pinned: false",
    ...(fields.tombstoned ? ["tombstoned_at: 2026-06-02T00:00:00Z"] : []),
    ...(fields.supersededBy !== undefined ? [`superseded_by: "[[${fields.supersededBy}]]"`] : []),
    "---",
    "",
    "The retired body text.",
    "",
  ].join("\n");
  writeFileSync(join(brainDirs(vault).retired, `${id}.md`), lines);
}

/** A preference page, the usual shape of a correction. */
function writePreferencePage(id: string, topic: string, supersededBy?: string): void {
  const lines = [
    "---",
    "kind: brain-preference",
    `id: ${id}`,
    "_status: confirmed",
    "created_at: 2026-06-02T00:00:00Z",
    "unconfirmed_until: 2026-06-02T00:00:00Z",
    "_confirmed_at: 2026-06-02T00:00:00Z",
    "_evidenced_by: []",
    "tags: [brain, brain/preference]",
    `topic: ${topic}`,
    `principle: Live rule for ${topic}.`,
    "pinned: false",
    ...(supersededBy !== undefined ? [`superseded_by: "[[${supersededBy}]]"`] : []),
    "---",
    "",
    `The live body for ${topic}.`,
    "",
  ].join("\n");
  mkdirSync(brainDirs(vault).preferences, { recursive: true });
  writeFileSync(join(brainDirs(vault).preferences, `${id}.md`), lines);
}

describe("recall by topic", () => {
  test("a retired record with a resolved, readable correction stays recallable", () => {
    writePreferencePage("pref-new", "alpha-v2");
    writeRetired("ret-old", { topic: "alpha", supersededBy: "pref-new" });

    const out = queryByRuleTopic(vault, "alpha");
    expect(out.preference?.id).toBe("ret-old");
  });

  test("a retired record whose correction is unresolved is dropped fail-closed", () => {
    writeRetired("ret-dangling", { topic: "beta", supersededBy: "pref-ghost" });

    const out = queryByRuleTopic(vault, "beta");
    expect(out.preference).toBeNull();
  });

  test("a retired record with no successor pointer keeps today's behavior", () => {
    writeRetired("ret-plain", { topic: "gamma" });

    const out = queryByRuleTopic(vault, "gamma");
    expect(out.preference?.id).toBe("ret-plain");
  });

  test("a tombstoned retired record stays hidden even with a resolved correction", () => {
    writePreferencePage("pref-new", "delta-v2");
    writeRetired("ret-dead", { topic: "delta", supersededBy: "pref-new", tombstoned: true });

    const out = queryByRuleTopic(vault, "delta");
    expect(out.preference).toBeNull();
  });

  test("non-retired output is unchanged: the correction itself still resolves", () => {
    writePreferencePage("pref-new", "alpha-v2");
    writeRetired("ret-old", { topic: "alpha", supersededBy: "pref-new" });

    const out = queryByRuleTopic(vault, "alpha-v2");
    expect(out.preference?.id).toBe("pref-new");
  });
});

describe("context pack", () => {
  test("historical injection keeps a superseded ancestor beside its resolved correction", () => {
    writePreferencePage("pref-tip", "tip topic");
    writePreferencePage("pref-anc", "ancestor topic", "pref-tip");

    const historical = packContext(vault, { maxTokens: 4000, includeHistorical: true });
    const ids = historical.items.map((i) => i.id).toSorted();
    expect(ids).toEqual(["pref-anc", "pref-tip"]);
  });

  test("historical injection drops an ancestor whose correction is unresolved", () => {
    writePreferencePage("pref-anc-dangling", "dangling topic", "pref-ghost");

    const historical = packContext(vault, { maxTokens: 4000, includeHistorical: true });
    expect(historical.items.map((i) => i.id)).not.toContain("pref-anc-dangling");
  });

  test("default injection still serves only chain tips, unchanged", () => {
    writePreferencePage("pref-tip", "tip topic");
    writePreferencePage("pref-anc", "ancestor topic", "pref-tip");
    writePreferencePage("pref-plain", "plain topic");

    const out = packContext(vault, { maxTokens: 4000 });
    const ids = out.items.map((i) => i.id).toSorted();
    expect(ids).toEqual(["pref-plain", "pref-tip"]);
  });
});

describe("active.md digest", () => {
  test("the digest keeps a retired record whose correction resolves", () => {
    writePreferencePage("pref-new", "epsilon-v2");
    writeRetired("ret-old", { topic: "epsilon", supersededBy: "pref-new" });

    const body = renderActive(vault).body;
    expect(body).toContain("ret-old");
  });

  test("the digest drops a retired record whose correction is unresolved", () => {
    writeRetired("ret-dangling", { topic: "zeta", supersededBy: "pref-ghost" });

    const body = renderActive(vault).body;
    expect(body).not.toContain("ret-dangling");
  });

  test("a retired record with no successor pointer keeps today's rendering", () => {
    writeRetired("ret-plain", { topic: "eta" });

    const body = renderActive(vault).body;
    expect(body).toContain("ret-plain");
  });
});

describe("dream scan", () => {
  test("the scan keeps a retired record whose correction resolves", () => {
    writePreferencePage("pref-new", "theta-v2");
    writeRetired("ret-old", { topic: "theta", supersededBy: "pref-new" });

    const scan = scanBrain(vault);
    expect(scan.retired.map((r) => r.id)).toContain("ret-old");
  });

  test("the scan drops a retired record whose correction is unresolved", () => {
    writeRetired("ret-dangling", { topic: "iota", supersededBy: "pref-ghost" });

    const scan = scanBrain(vault);
    expect(scan.retired.map((r) => r.id)).not.toContain("ret-dangling");
  });

  test("a retired record with no successor pointer is scanned as before", () => {
    writeRetired("ret-plain", { topic: "kappa" });

    const scan = scanBrain(vault);
    expect(scan.retired.map((r) => r.id)).toContain("ret-plain");
  });
});