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
/**
* Topic-key folding in the dream pass's consolidation path (D2).
*
* The defect: the READ path canonicalises entity references
* (`search/entity-alias.ts` folds through `normalizeEntityName`) and the
* CONSOLIDATION path did not. `dream-plan-topics.ts` grouped active signals
* with `Map.get(rec.signal.topic)` and indexed existing preferences with
* `Map.set(p.pref.topic, …)` — byte equality, no NFC, no case fold, no
* whitespace collapse, no quote fold. Two signals whose topics differ only by
* Unicode normal form, letter case, an internal whitespace run, or a
* curly-versus-straight quote were consolidated as unrelated subjects, and a
* preference already covering one of them was never found for the other.
*
* Every variant spelling is a named constant carrying the code points it is
* built from, because the differences these tests turn on - a combining mark
* versus a precomposed character, an ideographic space versus an ASCII one -
* are invisible in an editor and unreadable at the call site.
*
* These tests exercise the fold through the public `dream()` entry point, so
* they cover the whole consolidation path — grouping, the existing-preference
* lookup, retired-suppressor matching, and the contradiction hand-off to
* `reconcile-outcomes.ts` — rather than one internal map.
*
* Deliberately NOT covered here:
* - the exact footprint of the quote-variant class (owned and proved
* exhaustively by `tests/core/brain/entities/quote-variant-fold.test.ts`);
* - `intent-review.ts`, which clusters signals for the PRE-dream review with
* its own map and does not consume the plan's topics — a separate surface,
* outside this unit;
* - retire timing, confidence refresh, snapshots, and every other dream
* phase that keys on a preference id rather than on a topic.
*/
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { mkdtempSync, readFileSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { dream } from "../../../src/core/brain/dream.ts";
import { bootstrapBrain } from "../../../src/core/brain/init.ts";
import { brainConfigPath, logPath, preferencePath } from "../../../src/core/brain/paths.ts";
import { moveToRetired, writePreference } from "../../../src/core/brain/preference.ts";
import { writeSignal } from "../../../src/core/brain/signal.ts";
import { BRAIN_RETIRED_REASON } from "../../../src/core/brain/types.ts";
import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";
import { useUnshardedLegacyLog } from "../../helpers/device-id.ts";
// The legacy day log and ledgers are read under their un-sharded names.
useUnshardedLegacyLog();
const NOW = new Date("2026-06-05T12:00:00Z");
const SIGNAL_DAY = "2026-06-01";
const SIGNAL_STAMP = `${SIGNAL_DAY}T10:00:00Z`;
/** "cafe" + U+0301 COMBINING ACUTE ACCENT — the NFD spelling. */
const CAFE_NFD = "café rules";
/** U+00E9 LATIN SMALL LETTER E WITH ACUTE — the NFC spelling. */
const CAFE_NFC = "café rules";
/** NFC plus an internal whitespace run. */
const CAFE_NFC_WIDE = "café rules";
/** U+30AC KATAKANA LETTER GA — precomposed. */
const GUIDE_NFC = "ガイド ライン";
/** U+30AB + U+3099 COMBINING KATAKANA-HIRAGANA VOICED SOUND MARK — the same. */
const GUIDE_NFD = "ガイド ライン";
/** Precomposed, with a run of U+3000 IDEOGRAPHIC SPACE for the separator. */
const GUIDE_WIDE_SPACE = "ガイド ライン";
/** A genuinely different caseless topic. */
const RULES_JA = "テスト規則";
/** U+2019 RIGHT SINGLE QUOTATION MARK. */
const CONSENT_CURLY = "operator’s consent";
/** U+0027 APOSTROPHE. */
const CONSENT_STRAIGHT = "operator's consent";
const CONSENT_CURLY_TITLED = "Operator’s Consent";
let tmp: string;
beforeEach(() => {
tmp = mkdtempSync(join(tmpdir(), "o2b-topic-fold-"));
});
afterEach(() => {
rmSync(tmp, { recursive: true, force: true });
});
function newVault(name: string): string {
const vault = join(tmp, name);
const configPath = join(tmp, `${name}.yaml`);
atomicWriteFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);
bootstrapBrain(vault, { configPath });
return vault;
}
interface SeedSignal {
readonly topic: string;
readonly slug: string;
readonly sign?: "positive" | "negative";
}
function seed(vault: string, sig: SeedSignal): void {
writeSignal(vault, {
topic: sig.topic,
signal: sig.sign ?? "positive",
agent: "claude",
principle: "Ship the fold with the rule it folds.",
created_at: SIGNAL_STAMP,
date: SIGNAL_DAY,
slug: sig.slug,
});
}
function seedPreference(vault: string, slug: string, topic: string): void {
writePreference(vault, {
slug,
topic,
principle: `Rule of record for ${slug}.`,
created_at: "2026-05-01T00:00:00Z",
unconfirmed_until: "2026-05-15T00:00:00Z",
confirmed_at: "2026-05-08T00:00:00Z",
status: "confirmed",
evidenced_by: [],
applied_count: 2,
violated_count: 0,
last_evidence_at: "2026-06-01T00:00:00Z",
confidence: "medium",
});
}
function setCandidateThreshold(vault: string, value: number): void {
const path = brainConfigPath(vault);
const yaml = readFileSync(path, "utf8").replace(
/^ {2}candidate_threshold: \d+$/m,
` candidate_threshold: ${value}`,
);
atomicWriteFileSync(path, yaml);
}
function planOf(vault: string) {
return dream(vault, { now: NOW, dryRun: true, agentName: "claude" });
}
function contentionsOf(vault: string) {
return planOf(vault).warnings.filter((w) => w.code === "topic-key-contention");
}
describe("folding variants cluster as one topic", () => {
test("case-only variants promote a single preference", () => {
const vault = newVault("case");
seed(vault, { topic: "Deploy Cadence", slug: "a" });
seed(vault, { topic: "deploy cadence", slug: "b" });
seed(vault, { topic: "DEPLOY CADENCE", slug: "c" });
expect(planOf(vault).new_unconfirmed).toEqual(["pref-DEPLOY CADENCE"]);
});
test("normal-form and whitespace variants promote a single preference", () => {
const vault = newVault("shape");
seed(vault, { topic: CAFE_NFD, slug: "a" });
seed(vault, { topic: CAFE_NFC, slug: "b" });
seed(vault, { topic: CAFE_NFC_WIDE, slug: "c" });
// The raw NFD spelling is the smallest in code-unit order, so it stands
// for the group — and it is emphatically not the folded key, which is NFC.
expect(planOf(vault).new_unconfirmed).toEqual([`pref-${CAFE_NFD}`]);
});
test("a curly apostrophe and a straight one are one topic", () => {
const vault = newVault("quote");
seed(vault, { topic: CONSENT_CURLY, slug: "a" });
seed(vault, { topic: CONSENT_STRAIGHT, slug: "b" });
seed(vault, { topic: CONSENT_CURLY_TITLED, slug: "c" });
expect(planOf(vault).new_unconfirmed).toEqual([`pref-${CONSENT_CURLY_TITLED}`]);
});
});
describe("the fold is structural, not language-specific", () => {
test("a caseless script folds on normal form and whitespace alone", () => {
const vault = newVault("caseless");
seed(vault, { topic: GUIDE_NFC, slug: "a" });
seed(vault, { topic: GUIDE_NFD, slug: "b" });
seed(vault, { topic: GUIDE_WIDE_SPACE, slug: "c" });
// U+30AB sorts below U+30AC, so the decomposed spelling represents the
// group. A script with no case distinction reaches exactly one cluster by
// the same rule that folds a cased one — nothing in the fold asks what
// language a topic is written in.
expect(planOf(vault).new_unconfirmed).toEqual([`pref-${GUIDE_NFD}`]);
});
test("two distinct caseless topics stay distinct", () => {
const vault = newVault("caseless-distinct");
for (const i of ["a", "b", "c"]) {
seed(vault, { topic: GUIDE_NFC, slug: `g-${i}` });
seed(vault, { topic: RULES_JA, slug: `t-${i}` });
}
expect(planOf(vault).new_unconfirmed.toSorted()).toEqual([
`pref-${GUIDE_NFC}`,
`pref-${RULES_JA}`,
]);
});
test("a cased non-Latin script folds on case", () => {
const vault = newVault("cyrillic");
seed(vault, { topic: "Правила релиза", slug: "a" });
seed(vault, { topic: "правила релиза", slug: "b" });
seed(vault, { topic: "ПРАВИЛА РЕЛИЗА", slug: "c" });
expect(planOf(vault).new_unconfirmed).toEqual(["pref-ПРАВИЛА РЕЛИЗА"]);
});
});
describe("the display form", () => {
test("is a raw spelling from the corpus, never the folded key", () => {
const vault = newVault("display");
seed(vault, { topic: "Deploy Cadence", slug: "a" });
seed(vault, { topic: "deploy cadence", slug: "b" });
seed(vault, { topic: "Deploy Cadence", slug: "c" });
const summary = planOf(vault);
// Code-unit order: U+0020 sorts below "C", so the double-spaced raw
// spelling wins. The folded key ("deploy cadence") is never the answer.
expect(summary.new_unconfirmed).toEqual(["pref-Deploy Cadence"]);
});
test("does not depend on the order the corpus was written in", () => {
const forward = newVault("order-forward");
seed(forward, { topic: "Deploy Cadence", slug: "a" });
seed(forward, { topic: "deploy cadence", slug: "b" });
seed(forward, { topic: "DEPLOY CADENCE", slug: "c" });
const reverse = newVault("order-reverse");
seed(reverse, { topic: "DEPLOY CADENCE", slug: "c" });
seed(reverse, { topic: "deploy cadence", slug: "b" });
seed(reverse, { topic: "Deploy Cadence", slug: "a" });
expect(planOf(forward).new_unconfirmed).toEqual(["pref-DEPLOY CADENCE"]);
expect(planOf(reverse).new_unconfirmed).toEqual(planOf(forward).new_unconfirmed);
});
});
describe("the existing-preference lookup folds too", () => {
test("a signal finds the preference of record across a case variant", () => {
const vault = newVault("pref-lookup");
seedPreference(vault, "deploy-cadence", "Deploy Cadence");
for (const i of ["a", "b", "c"]) seed(vault, { topic: "deploy cadence", slug: `s-${i}` });
const summary = planOf(vault);
// The cluster is answered AGAINST the existing rule instead of promoting
// a second rule beside it. (The preference has no resolvable
// `evidenced_by`, so `deriveActiveSign` takes its documented conservative
// branch and reads a unanimous cluster as a rebuttal - which is only
// reachable at all once the lookup finds the preference.)
expect(summary.retired).toEqual([{ id: "ret-deploy-cadence", reason: "rebutted" }]);
expect(summary.new_unconfirmed).toEqual(["pref-deploy-cadence-rebut"]);
});
test("a retired suppressor matches across a quote variant", () => {
const vault = newVault("suppressor");
seedPreference(vault, "operators-consent", CONSENT_CURLY);
moveToRetired(
vault,
preferencePath(vault, "operators-consent"),
BRAIN_RETIRED_REASON.userRejected,
{
now: new Date("2026-05-20T00:00:00Z"),
retired_by: "test",
evidenceApplied: [],
evidenceViolated: [],
user_rejected_reason: "the operator rejected this rule",
},
);
for (const i of ["a", "b", "c"]) seed(vault, { topic: CONSENT_STRAIGHT, slug: `s-${i}` });
const summary = planOf(vault);
expect(summary.suppressed.length).toBe(3);
expect(summary.new_unconfirmed).toEqual([]);
});
test("a contradiction across variants reaches reconcile with both sides", () => {
const vault = newVault("reconcile");
seed(vault, { topic: "Deploy Cadence", slug: "p1", sign: "positive" });
seed(vault, { topic: "Deploy Cadence", slug: "p2", sign: "positive" });
seed(vault, { topic: "deploy cadence", slug: "n1", sign: "negative" });
seed(vault, { topic: "deploy cadence", slug: "n2", sign: "negative" });
const summary = planOf(vault);
expect(summary.contradictions).toEqual(["Deploy Cadence"]);
expect(summary.open_questions.length).toBe(1);
expect(summary.open_questions[0]?.positive_count).toBe(2);
expect(summary.open_questions[0]?.negative_count).toBe(2);
});
});
describe("two preferences contending for one folded key", () => {
test("are named in a warning and neither one is used", () => {
const vault = newVault("contend");
seedPreference(vault, "deploy-cadence-upper", "Deploy Cadence");
seedPreference(vault, "deploy-cadence-lower", "deploy cadence");
for (const i of ["a", "b", "c"]) seed(vault, { topic: "deploy cadence", slug: `s-${i}` });
const summary = planOf(vault);
const contention = summary.warnings.filter((w) => w.code === "topic-key-contention");
expect(contention.length).toBe(1);
expect(contention[0]?.message).toContain("pref-deploy-cadence-lower");
expect(contention[0]?.message).toContain("pref-deploy-cadence-upper");
expect(contention[0]?.message).toContain("Deploy Cadence");
// Nothing is decided for a key the pass cannot attribute: no new rule, no
// retire, and the signals stay in inbox/ for the next pass.
expect(summary.new_unconfirmed).toEqual([]);
expect(summary.retired).toEqual([]);
expect(summary.moved_to_processed).toEqual([]);
});
test("report the same message whichever preference was written first", () => {
const forward = newVault("contend-forward");
seedPreference(forward, "deploy-cadence-upper", "Deploy Cadence");
seedPreference(forward, "deploy-cadence-lower", "deploy cadence");
const reverse = newVault("contend-reverse");
seedPreference(reverse, "deploy-cadence-lower", "deploy cadence");
seedPreference(reverse, "deploy-cadence-upper", "Deploy Cadence");
const a = contentionsOf(forward);
expect(a.length).toBe(1);
expect(a).toEqual(contentionsOf(reverse));
});
test("two preferences on a byte-identical topic are the old duplicate, not a contention", () => {
const vault = newVault("duplicate");
seedPreference(vault, "deploy-cadence-one", "deploy cadence");
seedPreference(vault, "deploy-cadence-two", "deploy cadence");
for (const i of ["a", "b", "c"]) seed(vault, { topic: "deploy cadence", slug: `s-${i}` });
const summary = planOf(vault);
expect(summary.warnings.filter((w) => w.code === "topic-key-contention")).toEqual([]);
// Unchanged pre-fold behaviour: the first preference scanned wins and the
// cluster is answered against it. WHICH of the two wins is directory-
// enumeration order and always was, so the assertion is on the count.
expect(summary.retired.length).toBe(1);
expect(summary.moved_to_processed.length).toBe(3);
});
});
describe("a corpus with no folding variants", () => {
// The two goldens below were captured from the pre-fold build. They are the
// byte-identity proof this unit owes: the fold may not move one byte of the
// dream report for a corpus that carries no variant. Each corpus is shaped
// so its log cannot depend on directory-enumeration order — exactly one
// signal, so no multi-entry list can be permuted. `scanBrain` walks
// `readdirSync`, which yields entries in whatever order the filesystem
// stores them, and a golden over a larger corpus would be a flake, not a
// proof.
//
// They moved once since, and not by the fold: every log event now
// carries an `origin_channel` bullet, the server-derived channel of the
// writing process (Unit C of the nothing-writes-silently wave). It
// reads `unset` because a test harness is not one of the entry points
// that claims a channel. What these goldens still prove is unchanged —
// the fold authors no byte of a variant-free report — because the new
// bullet is on every event of both goldens and of every other log in
// the tree.
test("promotion writes a byte-identical dream report", () => {
const vault = newVault("golden-promote");
setCandidateThreshold(vault, 1);
seed(vault, { topic: "deploy-cadence", slug: "only" });
dream(vault, { now: NOW, agentName: "claude" });
expect(readReport(vault)).toBe(GOLDEN_PROMOTE);
});
test("a rebuttal writes a byte-identical dream report", () => {
const vault = newVault("golden-rebut");
setCandidateThreshold(vault, 1);
seedPreference(vault, "deploy-cadence", "deploy-cadence");
seed(vault, { topic: "deploy-cadence", slug: "only" });
dream(vault, { now: NOW, agentName: "claude" });
expect(readReport(vault)).toBe(GOLDEN_REBUT);
});
});
/**
* The day's log with the snapshot archive's size masked. That one number
* measures a zip this pass did not author — it moves with the compressor's
* version, not with anything the dream decided — so pinning it would make the
* golden a test of the environment. Every other byte is compared as written.
*/
function readReport(vault: string): string {
return readFileSync(logPath(vault, "2026-06-05"), "utf8").replace(
/^- size_bytes: \d+$/m,
"- size_bytes: <masked>",
);
}
const GOLDEN_PROMOTE = `---
kind: brain-log
date: 2026-06-05
tags: [brain, brain/log]
---
# Brain log — 2026-06-05
## 12:00:00Z — snapshot
- run_id: dream-2026-06-05-120000
- reason: dream
- size_bytes: <masked>
- origin_channel: unset
## 12:00:00Z — dream
- run_id: dream-2026-06-05-120000
- new_unconfirmed:
- [[pref-deploy-cadence|Ship the fold with the rule it folds.]]
- moved_to_processed:
- sig-2026-06-01-only
- origin_channel: unset
`;
const GOLDEN_REBUT = `---
kind: brain-log
date: 2026-06-05
tags: [brain, brain/log]
---
# Brain log — 2026-06-05
## 12:00:00Z — snapshot
- run_id: dream-2026-06-05-120000
- reason: dream
- size_bytes: <masked>
- origin_channel: unset
## 12:00:00Z — dream
- run_id: dream-2026-06-05-120000
- new_unconfirmed:
- [[pref-deploy-cadence-rebut|Ship the fold with the rule it folds.]]
- retired:
- [[ret-deploy-cadence|Rule of record for deploy-cadence.]] (rebutted)
- moved_to_processed:
- sig-2026-06-01-only
- origin_channel: unset
`;