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
10.2 KB
Raw Blame
/**
 * The `capture-scope` hygiene detector. A retrievable page of active
 * knowledge whose every cited source is CURRENTLY `url-only` rests on a
 * locator that may rot; the detector names it (`warning`, `review`). The
 * scope is re-derived from each cited identity on every sweep, so a
 * full-local page whose file vanished reports, and a stamped
 * `bounded-local` counts as backing only while its excerpt block is present
 * and matches its digest. Quarantined pages are skipped: their untrusted
 * marker already names the condition.
 */

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

import { bootstrapBrain } from "../../../src/core/brain/init.ts";
import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";
import { formatFrontmatter, parseFrontmatter } from "../../../src/core/vault.ts";
import type { FrontmatterMap } from "../../../src/core/types.ts";
import { ingestSource } from "../../../src/core/brain/ingest/ingest.ts";
import {
  BRAIN_REPORT_KIND,
  writeResearchReport,
} from "../../../src/core/brain/research/research.ts";
import { distillSource } from "../../../src/core/brain/distill/distill-source.ts";
import {
  CAPTURE_SCOPE,
  excerptDigest,
  renderExcerptSection,
} from "../../../src/core/brain/provenance/capture-scope.ts";
import {
  CAPTURE_SCOPE_DETECTOR_ID,
  detectCaptureScope,
} from "../../../src/core/brain/hygiene/detectors/capture-scope.ts";
import { runHygieneScan } from "../../../src/core/brain/hygiene/scan.ts";
import {
  UNTRUSTED_SOURCE_FRONTMATTER_KEY,
  hasUntrustedSourceMarker,
} from "../../../src/core/brain/trust/untrusted-provenance.ts";
import { CHMOD_CANNOT_DENY } from "../../helpers/platform.ts";
import { DEFAULT_SCAN_IDS, HYGIENE_DETECTOR_IDS } from "../../../src/core/brain/hygiene/types.ts";

let vault: string;
let configHome: string;

const NOW = new Date("2026-06-13T12:00:00Z");
const LOCAL_SOURCE = "Articles/a.md";
const URL_A = "https://example.test/a";
const URL_B = "https://example.test/b";
const ENTITY_PAGE = "Brain/entities/concept/ent-concept-alpha.md";
const BOUNDED_PAGE = "Brain/distillations/dist-bounded.md";
const EXCERPT = "The protocol settles in two rounds.\n";

function seed(rel: string): void {
  mkdirSync(join(vault, dirname(rel)), { recursive: true });
  writeFileSync(join(vault, rel), "bytes\n", "utf8");
}

function writePage(rel: string, meta: FrontmatterMap, body: string): void {
  mkdirSync(join(vault, dirname(rel)), { recursive: true });
  writeFileSync(join(vault, rel), formatFrontmatter(meta, body), "utf8");
}

function writeEntity(status: string, source: string): void {
  writePage(
    ENTITY_PAGE,
    {
      kind: "brain-entity",
      entity_id: "ent-concept-alpha",
      category: "concept",
      name: "Alpha",
      status,
      tags: ["brain", "brain/entity"],
    },
    `# Alpha\n\n## Sources\n\n- [[${source}]]`,
  );
}

function writeBounded(excerpt: string, stampedHashOf: string): void {
  writePage(
    BOUNDED_PAGE,
    {
      kind: "brain-distillation",
      source_path: URL_A,
      capture_scope: CAPTURE_SCOPE.boundedLocal,
      excerpt_hash: excerptDigest(stampedHashOf),
      provenance: "stated",
    },
    [
      "## Claims",
      "",
      "- A claim.",
      "",
      "## Sources",
      "",
      `- [[${URL_A}]]`,
      "",
      renderExcerptSection(excerpt),
    ].join("\n"),
  );
}

function findingsFor(page: string) {
  return detectCaptureScope(vault).filter((f) => f.targets.includes(page));
}

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

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

describe("detectCaptureScope", () => {
  test("a finding that opens a fence and never closes it does not hide the report", () => {
    const report = writeResearchReport(
      vault,
      { title: "T", sources: [URL_B], findings: [{ statement: "x\n```", sources: [URL_B] }] },
      { agent: "claude", now: NOW },
    );

    expect(findingsFor(report.reportPath)).toHaveLength(1);
  });

  test("a research report citing only URLs is one review warning naming the URLs", () => {
    const report = writeResearchReport(
      vault,
      { title: "T", sources: [URL_A, URL_B], findings: [{ statement: "S", sources: [URL_A] }] },
      { agent: "claude", now: NOW },
    );

    const findings = findingsFor(report.reportPath);
    expect(findings).toHaveLength(1);
    const finding = findings[0]!;
    expect(finding.detector).toBe(CAPTURE_SCOPE_DETECTOR_ID);
    expect(finding.severity).toBe("warning");
    expect(finding.proposed_action).toBe("review");
    expect(finding.title).toBe("Active knowledge rests on url-only sources");
    expect(finding.targets).toEqual([report.reportPath]);
    expect(finding.evidence).toEqual({ sources: [URL_A, URL_B], stamped: null });
  });

  test("a report citing one URL and one vault file is not reported", () => {
    seed(LOCAL_SOURCE);
    const report = writeResearchReport(
      vault,
      {
        title: "T",
        sources: [URL_A, LOCAL_SOURCE],
        findings: [{ statement: "S", sources: [URL_A] }],
      },
      { agent: "claude", now: NOW },
    );

    expect(findingsFor(report.reportPath)).toEqual([]);
  });

  test("an active entity citing a URL is reported; the same entity in quarantine is not", () => {
    writeEntity("active", URL_A);
    expect(findingsFor(ENTITY_PAGE)).toHaveLength(1);

    writeEntity("quarantine", URL_A);
    expect(findingsFor(ENTITY_PAGE)).toEqual([]);
  });

  test("an archived entity is outside the canonical scope and is not reported", () => {
    writeEntity("archived", URL_A);
    expect(findingsFor(ENTITY_PAGE)).toEqual([]);
  });

  test("an untrusted ingest page is already gated out and is not reported", () => {
    const ingest = ingestSource(
      vault,
      { sourcePath: URL_A, summary: "S.", extraction: { entities: [], relations: [] } },
      { agent: "claude", now: NOW },
    );

    expect(findingsFor(ingest.summaryPath)).toEqual([]);

    // The cause is the marker, not a page the detector cannot read: the
    // same page without it is reported.
    const [meta, body] = parseFrontmatter(join(vault, ingest.summaryPath));
    expect(hasUntrustedSourceMarker(meta)).toBe(true);
    const { [UNTRUSTED_SOURCE_FRONTMATTER_KEY]: _marker, ...released } = meta;
    writePage(ingest.summaryPath, released, body);
    expect(findingsFor(ingest.summaryPath)).toHaveLength(1);
  });

  test("a distillation whose vault source was deleted is re-derived as url-only", () => {
    seed(LOCAL_SOURCE);
    const distilled = distillSource(
      vault,
      { sourcePath: LOCAL_SOURCE, claims: [{ text: "A claim." }] },
      { agent: "claude", now: NOW },
    );
    expect(findingsFor(distilled.distillationPath)).toEqual([]);

    unlinkSync(join(vault, LOCAL_SOURCE));

    const findings = findingsFor(distilled.distillationPath);
    expect(findings).toHaveLength(1);
    expect(findings[0]!.evidence).toEqual({ sources: [LOCAL_SOURCE], stamped: null });
  });

  test("a bounded-local page backs itself only while its excerpt matches the digest", () => {
    writeBounded(EXCERPT, EXCERPT);
    expect(findingsFor(BOUNDED_PAGE)).toEqual([]);

    writeBounded("The protocol settles in three rounds.\n", EXCERPT);
    const edited = findingsFor(BOUNDED_PAGE);
    expect(edited).toHaveLength(1);
    expect(edited[0]!.evidence).toEqual({ sources: [URL_A], stamped: CAPTURE_SCOPE.boundedLocal });

    writePage(
      BOUNDED_PAGE,
      {
        kind: "brain-distillation",
        source_path: URL_A,
        capture_scope: CAPTURE_SCOPE.boundedLocal,
        excerpt_hash: excerptDigest(EXCERPT),
      },
      `## Claims\n\n- A claim.\n\n## Sources\n\n- [[${URL_A}]]`,
    );
    expect(findingsFor(BOUNDED_PAGE)).toHaveLength(1);
  });

  test("a page of another kind is never inspected", () => {
    // Inside an inspected directory, so only the kind filter can exclude it.
    writePage("Brain/distillations/n.md", { kind: "note" }, `## Sources\n\n- [[${URL_A}]]`);
    expect(detectCaptureScope(vault)).toEqual([]);
  });
});

describe("capture-scope when the filesystem refuses a source", () => {
  test.skipIf(CHMOD_CANNOT_DENY)(
    "an unreadable cited source is treated as backing and does not abort the sweep",
    () => {
      const locked = join(vault, "locked");
      seed("locked/inner/a.md");
      writePage("Brain/reports/a.md", { kind: BRAIN_REPORT_KIND }, `## Sources\n\n- [[${URL_A}]]`);
      writePage(
        "Brain/reports/b.md",
        { kind: BRAIN_REPORT_KIND },
        "## Sources\n\n- [[locked/inner/a.md]]",
      );
      chmodSync(locked, 0o000);
      try {
        const report = runHygieneScan(vault, { now: NOW, detectors: [CAPTURE_SCOPE_DETECTOR_ID] });
        expect(report.errors).toEqual([]);
        expect(report.counts[CAPTURE_SCOPE_DETECTOR_ID]).toBe(1);
        expect(findingsFor("Brain/reports/a.md")).toHaveLength(1);
        expect(findingsFor("Brain/reports/b.md")).toEqual([]);
      } finally {
        chmodSync(locked, 0o755);
      }
    },
  );
});

describe("capture-scope in the hygiene sweep", () => {
  test("the detector is registered and runs in the default sweep", () => {
    expect(HYGIENE_DETECTOR_IDS).toContain(CAPTURE_SCOPE_DETECTOR_ID);
    expect(DEFAULT_SCAN_IDS).toContain(CAPTURE_SCOPE_DETECTOR_ID);
    writeEntity("active", URL_A);

    const report = runHygieneScan(vault, { now: NOW });

    expect(report.detectors_run).toContain(CAPTURE_SCOPE_DETECTOR_ID);
    expect(report.counts[CAPTURE_SCOPE_DETECTOR_ID]).toBe(1);
  });

  test("finding ids are deterministic across sweeps", () => {
    writeEntity("active", URL_A);
    const first = detectCaptureScope(vault).map((f) => f.id);
    const second = detectCaptureScope(vault).map((f) => f.id);
    expect(first).toHaveLength(1);
    expect(second).toEqual(first);
    expect(first[0]!.startsWith(`${CAPTURE_SCOPE_DETECTOR_ID}:`)).toBe(true);
  });
});