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
/**
* The dream pass's per-topic transition decision.
*
* One reason to change: what a cluster of active signals on a topic
* *means*. Everything else about the pass - retire timing, disk writes,
* log shape - lives elsewhere. Given a scan and the config, this module
* decides, for each topic with active signals, exactly one of:
*
* - suppress the signals (a user-rejected retired pref covers them),
* - quarantine the cluster (self-approval guardrail not satisfied),
* - create a new unconfirmed preference,
* - note them redundant against the active preference of record,
* - accumulate them as a rebuttal (retiring the active pref, or
* logging a retain-pinned when it is pinned),
* - or record the topic as an unresolved contradiction.
*
* Every one of those decisions is per TOPIC, so this module also owns what a
* topic is for the pass: signals, preferences and retired records are indexed
* by `topicKey` (the fold), while everything the plan reports keeps a raw
* spelling from the vault (the display form). Key and label are separate
* words here on purpose - see `preferredTopicDisplay`.
*
* Pure: no I/O, no clock beyond the `now` it is handed.
*/
import { strictestVisibilityOf } from "../graph/visibility.ts";
import { isExpired } from "./expiration.ts";
import { applySelfApprovalGuardrail } from "./trust/self-approval-guardrail.ts";
import {
emptyPlan,
filterWithinWindow,
PREF_ID_PREFIX,
preferenceSlug,
recordSignalMove,
RETIRED_ID_PREFIX,
topicKey,
type PlanState,
type PreferenceRecord,
type RetiredRecord,
type ScanResult,
type SignalRecord,
} from "./dream-plan.ts";
import type { DreamWarning } from "./dream-types.ts";
import { resolveGuardrails } from "./policy.ts";
import { isPinned } from "./pin.ts";
import { countSigns, dominantSignOf } from "./sign.ts";
import { extractTemporalConstraints } from "./temporal-extract.ts";
import { renderPrefLink } from "./wikilink.ts";
import {
BRAIN_RETIRED_REASON,
BRAIN_SIGNAL_SIGN,
type BrainConfig,
type BrainSignal,
type BrainSignalSign,
} from "./types.ts";
const DAY_MS = 24 * 60 * 60 * 1000;
/** Suffix that keeps a rebuttal's new pref from colliding with the pref it retires. */
const REBUT_SLUG_SUFFIX = "-rebut";
export function planTopics(scan: ScanResult, cfg: BrainConfig, now: Date): PlanState {
const plan = emptyPlan();
const reservedSlugs = collectReservedPreferenceSlugs(scan);
// Expiration filter (C5), plan-side. The query read path drops a signal
// past its caller-set `expiration_date` from recall; the consolidation
// pass honours the same window here, or an ambient fact whose TTL lapsed
// inside the contradiction window is still clustered, still counted
// toward the candidate threshold, and finally consolidated into a
// preference that carries no expiration of its own. Dropped BEFORE
// clustering, a lapsed signal takes no part in grouping, promotion,
// suppression or sign derivation; the file is never moved, exactly as on
// the read path - the archive step treats it like any other unconsumed
// signal.
const signals = dropExpiredSignals(scan.signals, now);
// Group active signals by folded topic key. We only consider active
// signals for the create/rebut decisions; processed signals stay in the
// global log via `evidenced_by` already.
const byTopic = new Map<string, TopicGroup>();
// Archived signals were inbox signals until a previous pass archived them,
// and the sign derivation below treated them as members of the active
// group. Kept per key so it still does: archiving must not change which
// way a preference points (see `deriveActiveSign`).
const archivedByTopic = new Map<string, SignalRecord[]>();
for (const rec of signals) {
if (rec.archived) {
const key = topicKey(rec.signal.topic);
const arr = archivedByTopic.get(key);
if (arr) arr.push(rec);
else archivedByTopic.set(key, [rec]);
continue;
}
if (!rec.active) continue;
const raw = rec.signal.topic;
const key = topicKey(raw);
const group = byTopic.get(key);
if (group) {
group.sigs.push(rec);
group.display = preferredTopicDisplay(group.display, raw);
} else byTopic.set(key, { display: raw, sigs: [rec] });
}
// Index existing active preferences by the same key.
const prefs = indexPreferencesByTopicKey(scan.preferences, plan);
// Index retired by the same key for supersede and suppression
// bookkeeping. It has to fold with the rest: the loop below looks these
// up with the group's key, so leaving this map on raw bytes would make a
// user-rejected suppressor invisible to the very signals it exists to
// suppress.
const retiredByTopic = new Map<string, RetiredRecord[]>();
for (const r of scan.retired) {
const key = topicKey(r.topic);
const arr = retiredByTopic.get(key);
if (arr) arr.push(r);
else retiredByTopic.set(key, [r]);
}
for (const [key, group] of byTopic) {
// A contended key has no single rule of record, so there is no answer to
// "does this signal reinforce or rebut?" - and the wrong answer retires a
// preference the operator wrote. The pass plans nothing here and says so
// (`plan.topicKeyContentions` becomes one warning per key on the run
// summary); the signals stay in inbox/ and are re-evaluated on the next
// pass, once the vault has one owner for the key.
if (prefs.contended.has(key)) continue;
const topic = group.display;
const sigs = group.sigs;
const active = prefs.byKey.get(key);
if (active) {
handleSignalsOnActivePref(
active,
sigs,
archivedByTopic.get(key) ?? [],
plan,
cfg,
now,
signals,
reservedSlugs,
);
continue;
}
const candidateSigs = applySignalSuppression(topic, sigs, retiredByTopic.get(key), plan);
if (candidateSigs.length === 0) continue;
planTopicWithoutActivePref(
topic,
key,
candidateSigs,
plan,
cfg,
now,
retiredByTopic,
reservedSlugs,
);
}
return plan;
}
/** Active signals sharing one folded key, plus the spelling that names them. */
interface TopicGroup {
display: string;
readonly sigs: SignalRecord[];
}
/**
* The same expired-signal filter the query read path applies, lifted to the
* plan's record shape: `SignalRecord` carries the date one level down, on the
* parsed signal. `isExpired` fails OPEN on an unparseable date (a corrupted
* value never silently hides a signal here, exactly as it never does on
* recall), and a record without `expiration_date` is always kept.
*/
function dropExpiredSignals(records: ReadonlyArray<SignalRecord>, now: Date): SignalRecord[] {
return records.filter(
(rec) =>
rec.signal.expiration_date === undefined || !isExpired(rec.signal.expiration_date, now),
);
}
/**
* Choose the raw spelling that represents a folded group.
*
* The display form is never the folded key: an operator reading the dream
* report - and the filename of any preference promoted from the group - must
* see what a signal actually said, not a lowercased, NFC-flattened rendering
* of it that appears in no file in the vault.
*
* The rule is the SMALLEST member in UTF-16 code-unit order, not the first one
* scanned. `scanBrain` walks `readdirSync` (`dream-scan.ts:35`), which returns
* entries in whatever order the filesystem stores them, so "first wins" would
* make the report - and the promoted preference's filename - depend on which
* machine ran the pass. A total order over the raw strings is a property of
* the corpus alone, so the same corpus always elects the same representative.
* Code-unit order rather than `localeCompare` for the same reason the fold
* itself is structural: the choice must not consult a locale.
*/
function preferredTopicDisplay(a: string, b: string): string {
return b < a ? b : a;
}
/** The preference index for one pass, plus the keys it refused to index. */
interface PreferenceTopicIndex {
readonly byKey: Map<string, PreferenceRecord>;
readonly contended: Set<string>;
}
/**
* Index active preferences by folded topic key and record every key more than
* one topic claims.
*
* Byte-identical topics keep the historical rule - the first wins, design doc
* §7.4's "one preference per topic" makes a true duplicate a doctor-level
* issue rather than a dream concern. What the fold introduces is different: two
* preferences that were distinct subjects before it now resolve to one key,
* and the pass has no basis for choosing between them. Those keys are dropped
* from the index and recorded on the plan, so the ambiguity is reported rather
* than settled by scan order.
*/
function indexPreferencesByTopicKey(
preferences: ReadonlyArray<PreferenceRecord>,
plan: PlanState,
): PreferenceTopicIndex {
const byKey = new Map<string, PreferenceRecord>();
const claimants = new Map<string, PreferenceRecord[]>();
for (const p of preferences) {
const key = topicKey(p.pref.topic);
if (!byKey.has(key)) byKey.set(key, p);
const arr = claimants.get(key);
if (arr) arr.push(p);
else claimants.set(key, [p]);
}
const contended = new Set<string>();
for (const [key, records] of claimants) {
const topics = [...new Set(records.map((r) => r.pref.topic))].toSorted();
if (topics.length < 2) continue;
contended.add(key);
byKey.delete(key);
plan.topicKeyContentions.push({
key,
topics,
prefIds: records.map((r) => r.pref.id).toSorted(),
});
}
// Sorted for the same reason the representative is chosen by order rather
// than by arrival: the report must not vary with directory enumeration.
plan.topicKeyContentions.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
return { byKey, contended };
}
/** Warning code carried by every topic-key contention on a run summary. */
export const TOPIC_KEY_CONTENTION_CODE = "topic-key-contention";
/**
* Render the plan's topic-key contentions as run-summary warnings.
*
* A contention is a standing vault condition, not a mutation, so it does not
* by itself make a run "changed" - forcing a snapshot and a log write on every
* pass for a condition only the operator can clear would be churn. The warning
* rides on BOTH summary shapes (no-op and changed), which is why it is the
* channel: the CLI prints every warning to stderr and the JSON summary carries
* it, so a pass that decided nothing for a key still says which key and why.
*/
export function topicKeyContentionWarnings(plan: PlanState): DreamWarning[] {
return plan.topicKeyContentions.map((c) => ({
code: TOPIC_KEY_CONTENTION_CODE,
message:
`preferences ${c.prefIds.join(", ")} claim one topic key ${JSON.stringify(c.key)} ` +
`(topics ${c.topics.map((t) => JSON.stringify(t)).join(", ")}). ` +
`The pass planned nothing for that key; give it one owner by renaming a ` +
`topic or retiring one of the rules.`,
}));
}
/**
* v0.10.1 _summary §6: when a retired pref for this topic carries a
* `user_rejected_reason`, the user explicitly rejected the rule — re-growing
* it from fresh signals is exactly what they were asking us not to do.
* Suppress every matching signal, emit one `signal-suppressed` event per
* signal pointing at the retired pref + the reason, and move them straight
* to processed.
*
* Per-signal scope match: an unscoped suppressor swallows every signal on
* the topic; a scoped suppressor only swallows signals sharing its scope (a
* signal without scope still matches an unscoped suppressor but never a
* scoped one). Multiple retired prefs on the same topic are tried in order —
* the first matching suppressor wins. Non-matching signals fall through and
* remain eligible for candidate-pref planning.
*/
function applySignalSuppression(
topic: string,
sigs: SignalRecord[],
retiredForTopic: RetiredRecord[] | undefined,
plan: PlanState,
): SignalRecord[] {
const suppressors = (retiredForTopic ?? []).filter((r) => !!r.user_rejected_reason);
if (suppressors.length === 0) return sigs;
const remaining: SignalRecord[] = [];
for (const sig of sigs) {
const suppressor = suppressors.find((r) => {
if (!r.scope) return true;
if (!sig.signal.scope) return false;
return r.scope === sig.signal.scope;
});
if (!suppressor) {
remaining.push(sig);
continue;
}
plan.signalsSuppressed.push({
signal: `[[${sig.signal.id}]]`,
retired: renderPrefLink({
id: suppressor.id,
principle: suppressor.principle,
}),
reason: suppressor.user_rejected_reason!,
topic,
});
recordSignalMove(plan, sig);
}
return remaining;
}
/**
* No active pref for this topic → either promote, quarantine, or note a
* contradiction. `topic` is the group's display spelling (what the plan and
* the report say); `key` is its folded form (what the maps are indexed by).
*/
function planTopicWithoutActivePref(
topic: string,
key: string,
candidateSigs: SignalRecord[],
plan: PlanState,
cfg: BrainConfig,
now: Date,
retiredByTopic: Map<string, RetiredRecord[]>,
reservedSlugs: Set<string>,
): void {
const windowedSigs = filterWithinWindow(candidateSigs, cfg.dream.contradiction_window_days, now);
const positives = windowedSigs.filter((s) => s.signal.signal === BRAIN_SIGNAL_SIGN.positive);
const negatives = windowedSigs.filter((s) => s.signal.signal === BRAIN_SIGNAL_SIGN.negative);
const dominant = positives.length >= negatives.length ? positives : negatives;
const minoritySize = Math.min(positives.length, negatives.length);
const dominantSize = dominant.length - minoritySize; // cancellation
if (dominantSize < cfg.dream.candidate_threshold) {
if (positives.length > 0 && negatives.length > 0) plan.contradictionTopics.add(topic);
return;
}
if (quarantineIfGuarded(topic, dominant, dominantSize, plan, cfg, now)) return;
// Decide supersede: if a retired pref for the same topic exists,
// wire it through.
const retiredForTopic = retiredByTopic.get(key);
const supersedesRecord =
retiredForTopic && retiredForTopic.length > 0 ? retiredForTopic[0]! : undefined;
const source = dominant[0]!.signal;
// Slug from topic for the canonical filename, but reserve slugs
// already present in retired/. Otherwise a superseding preference
// can be created as `pref-topic` while `ret-topic` already exists;
// its later retirement would fail trying to overwrite that retired
// file.
const slug = allocatePreferencePlanSlug(topic, reservedSlugs);
// evidencedBy = wikilinks to ALL active signals (dominant + minority)
// that contributed to this topic in the window. We deliberately
// include the minority signals so the audit trail preserves the
// contradiction story even after the file moves to processed/.
const evidencedBy = windowedSigs.map((s) => `[[${s.signal.id}]]`);
plan.newUnconfirmed.push({
slug,
topic,
scope: source.scope,
principle: source.principle,
evidencedBy,
sign: source.signal,
// Drafted from every windowed signal (the principle is the dominant
// one's, the evidence cites them all) and quoting the superseded
// record's principle: the strictest of their visibilities.
visibility: strictestVisibilityOf([
...windowedSigs.map((s) => s.visibility ?? []),
supersedesRecord?.visibility ?? [],
]),
...deriveSignalTemporal(source, now),
...(supersedesRecord
? {
supersedes: renderPrefLink({
id: supersedesRecord.id,
principle: supersedesRecord.principle,
}),
}
: {}),
});
// Every contributing signal in the window gets moved.
for (const s of windowedSigs) {
recordSignalMove(plan, s);
}
}
/**
* v0.10.16: extra self-approval guardrail. Defaults (min_signals=2,
* min_distinct_agents=1, min_age_days=0) make this check a no-op for
* clusters that already passed `candidate_threshold`. Operators may opt
* into stricter thresholds via `_brain.yaml:guardrails:*`. A failed gate
* routes the cluster to `quarantined` instead of creating a new
* unconfirmed preference; the contributing signals stay in inbox/ so the
* cluster naturally re-evaluates on the next pass once more evidence
* accumulates.
*
* Returns true when the cluster was quarantined and must not promote.
*/
function quarantineIfGuarded(
topic: string,
dominant: ReadonlyArray<SignalRecord>,
dominantSize: number,
plan: PlanState,
cfg: BrainConfig,
now: Date,
): boolean {
const distinctAgents = new Set(dominant.map((s) => s.signal.agent)).size;
let earliestSignalMs = Number.POSITIVE_INFINITY;
for (const s of dominant) {
const t = Date.parse(s.signal.created_at);
if (Number.isFinite(t) && t < earliestSignalMs) earliestSignalMs = t;
}
const ageDays = Number.isFinite(earliestSignalMs)
? Math.max(0, Math.floor((now.getTime() - earliestSignalMs) / DAY_MS))
: 0;
const verdict = applySelfApprovalGuardrail(
{
signal_count: dominantSize,
distinct_agents: distinctAgents,
age_days: ageDays,
},
resolveGuardrails(cfg),
);
if (verdict.decision !== "quarantine") return false;
plan.quarantined.push({
topic,
signal_count: dominantSize,
distinct_agents: distinctAgents,
age_days: ageDays,
failed_gates: verdict.failed_gates,
});
return true;
}
/**
* Determine the active preference's sign. Order of preference:
*
* 1. Walk `evidenced_by` wikilinks and look up each referenced
* signal in the global scan; the dominant sign among them is
* the pref's "sign of record". This is the design-correct
* derivation since the writer baked those evidence pointers in.
*
* 2. If no `evidenced_by` resolves (e.g. a hand-crafted pref or a
* pref whose source signals were manually pruned), look at all
* historical signals on the same topic in the global scan.
*
* 3. If still nothing, assume the active pref is on the OPPOSITE
* sign of the incoming dominant sign. This makes a unanimous
* flood of new signals always count as rebuttal — which is the
* conservative, fail-loud choice: the operator gets a clear
* rebut/retire signal and can manually intervene if the system
* misread their intent.
*/
function deriveActiveSign(
active: PreferenceRecord,
sigs: SignalRecord[],
allSignals: ReadonlyArray<SignalRecord>,
): BrainSignalSign {
const signCounts = (records: ReadonlyArray<SignalRecord>): { pos: number; neg: number } =>
countSigns(records.map((r) => r.signal.signal));
// Tier-1 derivation now lives in the shared `sign.ts` helper so the
// semantic-health contradiction detector and this pass agree on one
// definition. `dominantSignOf` returning a concrete sign is exactly
// the old `evidenceRecords.length > 0` branch (every signal carries a
// polarity, so a resolved evidence link always counts); `"unknown"`
// is the old "no evidenced signal resolved" fall-through.
const signSignById = new Map(allSignals.map((r) => [r.signal.id, r.signal.signal]));
const evidenceSign = dominantSignOf(active.pref.evidenced_by, signSignById);
if (evidenceSign !== "unknown") return evidenceSign;
// Folded, like every other topic comparison in this pass: a historical
// signal spelled differently from the preference it evidences is still a
// signal on the preference's subject.
const activeKey = topicKey(active.pref.topic);
const topicRecords = allSignals.filter((r) => topicKey(r.signal.topic) === activeKey);
if (topicRecords.length > sigs.length) {
// There are processed signals for this topic that are NOT among
// the active inbox set — use them.
const c = signCounts(topicRecords.filter((r) => !sigs.includes(r)));
return c.pos >= c.neg ? BRAIN_SIGNAL_SIGN.positive : BRAIN_SIGNAL_SIGN.negative;
}
// Fallback: assume the active pref is OPPOSITE to the incoming
// dominant sign. A unanimous flood thus reads as rebuttal.
const c = signCounts(sigs);
return c.pos > c.neg ? BRAIN_SIGNAL_SIGN.negative : BRAIN_SIGNAL_SIGN.positive;
}
function handleSignalsOnActivePref(
active: PreferenceRecord,
sigs: SignalRecord[],
archivedOnTopic: ReadonlyArray<SignalRecord>,
plan: PlanState,
cfg: BrainConfig,
now: Date,
allSignals: ReadonlyArray<SignalRecord>,
reservedSlugs: Set<string>,
): void {
// The archived signals on this topic join the group for the sign
// derivation only: before they were archived they sat in the inbox, and
// tiers 2 and 3 below read the group as "the inbox signals on this topic".
const activeSign = deriveActiveSign(active, [...sigs, ...archivedOnTopic], allSignals);
const oppositeSign: BrainSignalSign =
activeSign === BRAIN_SIGNAL_SIGN.positive
? BRAIN_SIGNAL_SIGN.negative
: BRAIN_SIGNAL_SIGN.positive;
const windowed = filterWithinWindow(sigs, cfg.dream.contradiction_window_days, now);
const sameSign = windowed.filter((s) => s.signal.signal === activeSign);
const opposing = windowed.filter((s) => s.signal.signal === oppositeSign);
const activeLink = renderPrefLink({
id: active.pref.id,
principle: active.pref.principle,
});
// Same-sign → note redundant + move to processed.
for (const s of sameSign) {
plan.notedRedundant.push({
preference: activeLink,
signal: `[[${s.signal.id}]]`,
});
recordSignalMove(plan, s);
}
// Opposite-sign → accumulate toward rebuttal.
if (opposing.length < cfg.dream.candidate_threshold) {
if (opposing.length > 0) plan.contradictionTopics.add(active.pref.topic);
return;
}
if (isPinned(active.pref)) {
plan.retainPinned.push({
preference: activeLink,
reason: BRAIN_RETIRED_REASON.rebutted,
});
// Rebuttal signals on a pinned pref still get moved out — they
// were addressed (the system saw them) and clogging the inbox
// doesn't help.
for (const s of opposing) recordSignalMove(plan, s);
return;
}
const slug = preferenceSlug(active.pref.id);
plan.retires.push({
slug,
principle: active.pref.principle,
reason: BRAIN_RETIRED_REASON.rebutted,
});
for (const s of opposing) recordSignalMove(plan, s);
// Create a new unconfirmed pref for the new direction.
// Build a fresh slug to avoid filename collision with the
// retiring pref (which lives under preferences/<slug>.md and
// will move to retired/<slug>.md). The simplest scheme: the
// same slug, since `moveToRetired` unlinks the source first.
// For safety against a half-completed move, we suffix with
// `-rebut`.
const source = opposing[0]!.signal;
plan.newUnconfirmed.push({
slug: allocatePreferencePlanSlug(`${slug}${REBUT_SLUG_SUFFIX}`, reservedSlugs),
topic: active.pref.topic,
scope: source.scope,
principle: source.principle,
evidencedBy: opposing.map((s) => `[[${s.signal.id}]]`),
sign: oppositeSign,
// Drafted from the opposing signals and quoting the rebutted
// preference's principle: the strictest of their visibilities.
visibility: strictestVisibilityOf([
...opposing.map((s) => s.visibility ?? []),
active.visibility ?? [],
]),
...deriveSignalTemporal(source, now),
supersedes: activeLink,
});
}
function collectReservedPreferenceSlugs(scan: ScanResult): Set<string> {
const out = new Set<string>();
for (const p of scan.preferences) {
const slug = strictSlugFromId(p.pref.id, PREF_ID_PREFIX);
if (slug) out.add(slug);
}
for (const r of scan.retired) {
const slug = strictSlugFromId(r.id, RETIRED_ID_PREFIX);
if (slug) out.add(slug);
}
return out;
}
/**
* Strict counterpart to `preferenceSlug`: an id that does not carry the
* expected prefix reserves nothing, because it names no file the writer
* would ever produce.
*/
function strictSlugFromId(id: string, prefix: string): string | null {
return id.startsWith(prefix) && id.length > prefix.length ? id.slice(prefix.length) : null;
}
function allocatePreferencePlanSlug(base: string, reserved: Set<string>): string {
let candidate = base;
let suffix = 2;
while (reserved.has(candidate)) {
candidate = `${base}-${suffix}`;
suffix++;
}
reserved.add(candidate);
return candidate;
}
/**
* Brain lifecycle suite (F5). Derive a preference's bi-temporal validity
* from the source signal: prefer the signal's explicit `valid_from` /
* `valid_until`, otherwise extract formal ISO temporal tokens from the
* signal's principle + raw text. Returns `{}` when neither yields a
* constraint, so callers spread it without changing byte output.
*/
function deriveSignalTemporal(
sig: BrainSignal,
now: Date,
): { valid_from?: string; valid_until?: string } {
if (sig.valid_from || sig.valid_until) {
return {
...(sig.valid_from ? { valid_from: sig.valid_from } : {}),
...(sig.valid_until ? { valid_until: sig.valid_until } : {}),
};
}
const text = `${sig.principle ?? ""}\n${sig.raw ?? ""}`;
return extractTemporalConstraints(text, { now });
}