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
/**
* Hygiene kernel: scan over pure detectors
* (continuity-hygiene-freshness suite, Task 8; kanban t_698db8f7 /
* t_db375a60 detection side).
*
* `runHygieneScan` is read-only composition: each detector returns
* typed findings, the scan folds them into one frozen digest, and a
* broken detector lands in `errors` instead of failing the run.
* Detectors here: `conflicts` (truth-layer value conflicts),
* `usefulness` (preferences with no recall evidence), `freshness`
* (stale -> recompile, orphaned -> review).
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { join } from "node:path";
import { tmpdir } from "node:os";
import { appendClaimEvent } from "../../../src/core/brain/truth/store.ts";
import { emitRecallTelemetry, RECALL_CHANNEL } from "../../../src/core/brain/recall-telemetry.ts";
import {
computeSourceStamp,
formatSourceStampFrontmatter,
} from "../../../src/core/brain/freshness.ts";
import { runHygieneScan } from "../../../src/core/brain/hygiene/scan.ts";
let vault: string;
const NOW = new Date("2026-06-10T12:00:00Z");
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "o2b-hygiene-"));
mkdirSync(join(vault, "Brain", "preferences"), { recursive: true });
mkdirSync(join(vault, "Brain", "log"), { recursive: true });
});
afterEach(() => {
rmSync(vault, { recursive: true, force: true });
});
function writePref(slug: string, createdAt: string): void {
writeFileSync(
join(vault, "Brain", "preferences", `pref-${slug}.md`),
[
"---",
"kind: brain-preference",
`id: pref-${slug}`,
"tags: [brain, brain/preference]",
`topic: ${slug}`,
"_status: confirmed",
`principle: principle for ${slug}`,
`created_at: ${createdAt}`,
`unconfirmed_until: ${createdAt}`,
"---",
"",
].join("\n"),
"utf8",
);
}
describe("conflicts detector", () => {
test("surfaces a contested truth slot as a review finding", () => {
appendClaimEvent(vault, {
ts: "2026-06-01T10:00:00Z",
agent: "agent-a",
entity: "ACME Corp",
aspect: "headquarters",
value: "Berlin",
source: "[[note-a]]",
});
appendClaimEvent(vault, {
ts: "2026-06-05T10:00:00Z",
agent: "agent-b",
entity: "ACME Corp",
aspect: "headquarters",
value: "Lisbon",
source: "[[note-b]]",
});
const report = runHygieneScan(vault, { detectors: ["conflicts"], now: NOW });
expect(report.findings).toHaveLength(1);
const finding = report.findings[0]!;
expect(finding.detector).toBe("conflicts");
expect(finding.proposed_action).toBe("review");
expect(finding.targets[0]).toBe("acme corp#headquarters");
expect(report.counts.conflicts).toBe(1);
});
test("no conflicts means no findings", () => {
const report = runHygieneScan(vault, { detectors: ["conflicts"], now: NOW });
expect(report.findings).toHaveLength(0);
});
});
describe("usefulness detector", () => {
test("flags old preferences with zero recall evidence, skips recalled ones", () => {
writePref("never-recalled", "2026-01-01T00:00:00Z");
writePref("recalled", "2026-01-01T00:00:00Z");
writePref("too-young", "2026-06-01T00:00:00Z");
emitRecallTelemetry(vault, {
host: "test",
channel: RECALL_CHANNEL.cli,
mode: "context_pack",
status: "ok",
durationMs: 5,
resultCount: 1,
topArtifacts: [{ id: "pref-recalled" }],
});
const report = runHygieneScan(vault, { detectors: ["usefulness"], now: NOW });
expect(report.findings).toHaveLength(1);
const finding = report.findings[0]!;
expect(finding.detector).toBe("usefulness");
expect(finding.targets).toEqual(["pref-never-recalled"]);
expect(finding.proposed_action).toBe("review");
});
});
describe("freshness detector", () => {
test("maps stale pages to recompile and orphaned pages to review", () => {
writeFileSync(join(vault, "notes-src.md"), "alpha", "utf8");
const staleStamp = computeSourceStamp(vault, ["notes-src.md"]);
mkdirSync(join(vault, "Brain", "derived"), { recursive: true });
writeFileSync(
join(vault, "Brain", "derived", "stale.md"),
`---\n${formatSourceStampFrontmatter(staleStamp)}\n---\nbody`,
"utf8",
);
const orphanStamp = computeSourceStamp(vault, ["gone-src.md"]);
writeFileSync(
join(vault, "Brain", "derived", "orphan.md"),
`---\n${formatSourceStampFrontmatter(orphanStamp)}\n---\nbody`,
"utf8",
);
writeFileSync(join(vault, "notes-src.md"), "alpha CHANGED", "utf8");
const report = runHygieneScan(vault, { detectors: ["freshness"], now: NOW });
const byAction = new Map(report.findings.map((f) => [f.proposed_action, f]));
expect(byAction.get("recompile")?.targets[0]?.endsWith("stale.md")).toBe(true);
expect(byAction.get("review")?.targets[0]?.endsWith("orphan.md")).toBe(true);
});
});
describe("scan composition", () => {
test("runs every requested detector, freezes the digest, reports counts", () => {
const report = runHygieneScan(vault, { now: NOW });
expect(report.detectors_run).toEqual([
"conflicts",
"dedup",
"freshness",
"usefulness",
"slug-collisions",
"capture-scope",
]);
expect(Object.isFrozen(report)).toBe(true);
expect(Object.isFrozen(report.findings)).toBe(true);
expect(report.errors).toHaveLength(0);
expect(report.generated_at).toBe(NOW.toISOString());
});
test("an explicit subset composes the two opt-in tag detectors (t_11ee559f)", () => {
writePref("never-recalled", "2026-01-01T00:00:00Z");
writeFileSync(
join(vault, "Brain", "preferences", "pref-fm.md"),
"---\nid: pref-fm\ntags: [bad tag]\n---\n\nbody\n",
"utf8",
);
const report = runHygieneScan(vault, { detectors: ["tags", "frontmatter-tags"], now: NOW });
expect(report.detectors_run).toEqual(["tags", "frontmatter-tags"]);
expect(report.counts["frontmatter-tags"]).toBe(1);
expect(report.counts.tags).toBe(0);
expect(report.findings.filter((f) => f.detector === "frontmatter-tags")).toHaveLength(1);
expect(report.errors).toHaveLength(0);
});
test("finding ids are deterministic across runs", () => {
writePref("never-recalled", "2026-01-01T00:00:00Z");
const first = runHygieneScan(vault, { detectors: ["usefulness"], now: NOW });
const second = runHygieneScan(vault, { detectors: ["usefulness"], now: NOW });
expect(first.findings[0]?.id).toBe(second.findings[0]?.id);
});
});