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
/**
* Shared scan-record and plan-state shapes for the dream pass.
*
* Extracted from dream.ts so the planning sub-modules
* (reconcile-outcomes.ts, dream-refresh.ts) and the orchestrator can
* exchange typed state without a single-file dependency knot. Pure
* data shapes plus three stateless helpers; no I/O. `topicKey` lives here
* rather than at one consumer because the plan and the reconcile pass that
* reads the plan must agree on what one topic IS, and two copies of that rule
* would be one drift away from a contradiction the plan flags but reconcile
* cannot find.
*/
import { foldQuoteVariantsByClass, normalizeEntityShape } from "./entities/canonical.ts";
import type { BrainPreference, BrainRetiredReason, BrainSignal, BrainSignalSign } from "./types.ts";
/**
* The key one topic owns in the consolidation pass.
*
* The read path canonicalises an entity reference before it compares it
* (`search/entity-alias.ts` folds query entities through
* `normalizeEntityName`); the consolidation path compared raw bytes, so two
* signals whose topics differed only by Unicode normal form, letter case, an
* internal whitespace run, or a curly-versus-straight quote were consolidated
* as unrelated subjects. The shape pass is the identity kernel's own -
* `normalizeEntityShape` is NFC, trim, whitespace collapse, lowercase, every
* step structural, so the rule behaves identically for a script with no case
* distinction and for one that has it.
*
* The quote step is the kernel's OTHER fold, and deliberately so. The kernel
* sends every quote class to the ASCII single quote, which merges a
* typographic DOUBLE quote with an apostrophe: `prefer-“single”-quotes` and
* `prefer-'single'-quotes` became one key, contended, and the pass then
* planned nothing for either - two live rules inert and an inbox that only
* grows. A topic key is computed per run and written nowhere, so it can
* afford the faithful fold that a persisted identity key cannot; see
* `foldQuoteVariantsByClass` and the note on `foldQuoteVariants` for what
* re-targeting a stored key would cost.
*
* A key is an index, never a label. Everything an operator reads back keeps
* the raw spelling a signal actually used - see `preferredTopicDisplay` in
* `dream-plan-topics.ts`.
*
* NOT every raw topic comparison in the Brain goes through this function, and
* the ones that do not are named rather than left implied: `query.ts`'s
* preference lookup and `intent-review.ts`'s pre-dream clustering both
* compare raw bytes, so the review can cluster signals differently from the
* plan that acts on them. Folding those is a behaviour change to the read
* path and to a report shape, which is a separate unit; what this release
* adds is a doctor check (`topic-key-collision` in
* `doctor/preference-hygiene.ts`) so the contention warning's remedy - find
* the near-duplicate pair and give the key one owner - has a tool behind it.
*/
export function topicKey(rawTopic: string): string {
return foldQuoteVariantsByClass(normalizeEntityShape(rawTopic));
}
/**
* Two or more preferences whose topics fold onto one {@link topicKey}.
*
* Before the fold they were separate subjects and each answered its own
* signals; after it they contend, and "one preference per topic" can no
* longer decide which of them a signal on that key bears on. The pass records
* the contention and plans nothing for the key rather than picking a winner
* by scan order - retiring the wrong rule is not a recoverable mistake.
*
* Byte-identical topics are NOT a contention: that is the pre-existing
* duplicate the design doc §7.4 invariant already covers, it keeps its
* historical first-wins handling, and reporting it here would be this unit
* inventing a finding it did not cause.
*/
export interface TopicKeyContention {
/** The folded key both preferences resolve to. */
readonly key: string;
/** The distinct raw topics claiming it, in code-unit order. */
readonly topics: ReadonlyArray<string>;
/** The ids of every claiming preference, in code-unit order. */
readonly prefIds: ReadonlyArray<string>;
}
/** Id prefix the preference writer stamps on every live rule. */
export const PREF_ID_PREFIX = "pref-";
/** Id prefix a preference carries once it has moved into `retired/`. */
export const RETIRED_ID_PREFIX = "ret-";
/**
* The filename slug behind a preference id.
*
* Every writer emits `pref-<slug>`, but the on-disk artifacts are
* user-editable and a hand-authored file may carry a bare id. The dream
* pass has always read such an id as being its own slug, so the strip is
* tolerant rather than strict.
*/
export function preferenceSlug(id: string): string {
return id.startsWith(PREF_ID_PREFIX) ? id.slice(PREF_ID_PREFIX.length) : id;
}
export interface SignalRecord {
readonly path: string;
readonly signal: BrainSignal;
/** True iff the file lives in `inbox/` (not `processed/` or `archived/`). */
readonly active: boolean;
/**
* True iff the file lives in `inbox/archived/`: an inbox signal a previous
* pass archived because it had left the contradiction window unconsumed.
*/
readonly archived?: true;
/**
* The record's normalised `visibility:` tokens (`pageVisibility`), read by
* the scan. A preference the pass drafts from records carries the
* strictest of theirs, so a page drafted from reserved text stays
* reserved. Absent (or empty) means default visibility.
*/
readonly visibility?: ReadonlyArray<string>;
}
export interface PreferenceRecord {
readonly path: string;
readonly pref: BrainPreference;
/**
* Raw `superseded_by` frontmatter pointer (Belief lifecycle suite, A4).
* The typed parser drops it, so scanBrain captures it from raw
* frontmatter to drive accelerated decay of low-recall superseded
* ancestors. `null` when the memory is a chain tip.
*/
readonly supersededBy: string | null;
/**
* The record's normalised `visibility:` tokens (`pageVisibility`), read by
* the scan. A preference the pass drafts from records carries the
* strictest of theirs, so a page drafted from reserved text stays
* reserved. Absent (or empty) means default visibility.
*/
readonly visibility?: ReadonlyArray<string>;
}
export interface RetiredRecord {
readonly path: string;
readonly topic: string;
readonly id: string;
readonly principle: string;
readonly scope?: string;
/**
* The free-form user reason passed to `o2b brain reject --reason`.
* Presence triggers signal-suppression for future signals on the
* same (topic, scope) — see §6 of the OSB features summary.
*/
readonly user_rejected_reason?: string;
/**
* The record's normalised `visibility:` tokens (`pageVisibility`), read by
* the scan. A preference the pass drafts from records carries the
* strictest of theirs, so a page drafted from reserved text stays
* reserved. Absent (or empty) means default visibility.
*/
readonly visibility?: ReadonlyArray<string>;
}
export interface CorruptedEntry {
readonly path: string;
}
export interface ScanResult {
readonly signals: SignalRecord[];
readonly preferences: PreferenceRecord[];
readonly retired: RetiredRecord[];
readonly corrupted: CorruptedEntry[];
/**
* Preferences the scan skipped because a tombstone marks them
* (`_status: tombstoned`, Belief lifecycle suite t_7d5a3589). The pass
* never plans over them, but the path-only entries still matter to the
* cross-topic slug check (finding 64): a tombstoned `pref-cross-*` file
* holds the exact path a re-promotion would write, and `overwrite:
* false` must never find that path occupied by surprise. Absent on a
* scan built by hand.
*/
readonly tombstonedPreferences?: ReadonlyArray<CorruptedEntry>;
/**
* Every entry name in `inbox/archived/`, parseable or not. The archive
* step checks a move's destination name against this listing rather than
* against the parsed records, so a tombstoned or corrupt file there still
* takes its name. Absent on a scan built by hand.
*/
readonly archivedNames?: ReadonlySet<string>;
}
/**
* Entry surfacing a signal cluster that the self-approval guardrail
* (v0.10.16) held back from promotion because one or more configured
* thresholds were not met. Distinct from `suppressed` (which fires
* on a user-rejected retired preference); a quarantined cluster
* stays inbox-side and may promote on the next dream pass once
* more evidence accumulates.
*/
export interface DreamQuarantinedEntry {
/** Topic slug whose signals are held below the promotion threshold. */
readonly topic: string;
/** Count of accumulated same-sign signals. */
readonly signal_count: number;
/** Number of distinct agents that raised same-sign signals. */
readonly distinct_agents: number;
/** Age (in days) of the earliest signal in the cluster. */
readonly age_days: number;
/**
* Which threshold(s) blocked promotion: any subset of
* `min_signals`, `min_distinct_agents`, `min_age_days`.
*/
readonly failed_gates: ReadonlyArray<string>;
}
export interface PlanState {
/** Topic slug → planned new unconfirmed preference. */
readonly newUnconfirmed: NewUnconfirmedPlan[];
/** Preferences to retire (after refresh). */
readonly retires: RetirePlan[];
/** Same-sign signals on active prefs → moved + log event. */
readonly notedRedundant: NotedRedundantPlan[];
/** Pinned prefs that would have retired but stay because pinned. */
readonly retainPinned: RetainPinnedPlan[];
/** Signal id → record to move out of inbox/. */
readonly signalsToMove: Map<string, SignalMovePlan>;
/** Topic slugs flagged contradicted but no transition this run. */
readonly contradictionTopics: Set<string>;
/**
* Signals dropped because their (topic, scope) matches a user-rejected
* retired pref carrying a `user_rejected_reason`. Each entry produces
* one `signal-suppressed` log event AND a move into `processed/` so
* the inbox does not accumulate.
*/
readonly signalsSuppressed: SignalSuppressedPlan[];
/**
* Signal clusters held back from promotion by the self-approval
* guardrail (v0.10.16). The cluster passed the existing
* `candidate_threshold` but failed one or more configured
* thresholds in `BrainGuardrailConfig`. Preserved across the plan
* so it surfaces on the DreamRunSummary without affecting the
* existing move-to-processed semantics.
*/
readonly quarantined: DreamQuarantinedEntry[];
/**
* Folded topic keys claimed by more than one preference. Every entry is a
* key the pass deliberately planned nothing for; the run summary carries
* one warning per entry so the ambiguity reaches an operator instead of
* being resolved by directory-enumeration order.
*/
readonly topicKeyContentions: TopicKeyContention[];
/**
* Inbox signals this pass archives because they can no longer become
* candidates (see `signal-archive.ts`). Keyed by signal id; never
* overlaps {@link signalsToMove}.
*/
readonly signalsToArchive: Map<string, SignalArchivePlan>;
/**
* Cross-topic rule promotions (t_642bc2b8): one new unconfirmed
* preference per elected cross-bucket cluster, at most one per owner
* token per calendar day. Planned by `dream-plan-cross-topic.ts`
* after the refresh pass (it needs post-refresh confirmation state);
* every write happens in the apply stage like every other entry.
*/
readonly crossTopicRules: CrossTopicRulePlan[];
}
export interface SignalArchivePlan {
readonly id: string;
/** Absolute path of the inbox file. */
readonly path: string;
}
export interface SignalSuppressedPlan {
readonly signal: string;
/** Pre-rendered `[[ret-slug|principle]]` wikilink for the suppressor. */
readonly retired: string;
readonly reason: string;
readonly topic: string;
}
/**
* One planned cross-topic rule promotion (t_642bc2b8).
*
* The promoted artifact is an ordinary unconfirmed preference whose
* evidence is the set of per-topic rules it generalises, so nothing in
* the persistence format is new. What the planner decides:
*
* - `slug` is content-derived (`cross-<sha256-12>` over the sorted
* source ids), so the same source set always maps to one file and a
* rerun dedups itself below the changed gate.
* - `topic` is the deterministic join of the sorted raw topic
* displays - a key no signal will ever carry, which is exactly why
* the rule cannot re-enter the per-topic "one preference per topic"
* world. Topic-keyed recall will not surface it; the `related`
* lineage and `evidenced_by` wikilinks are the way back.
* - `principle` is one source's principle verbatim (the
* lexicographically smallest source's) - the kernel stays LLM-free
* and the rule says exactly what its sources say. The cross-topic
* fact lives in the evidence, not in invented prose.
* - `owner` carries the sources' shared owner token when they have
* one, so owner-scoped recall keeps the rule as private as its
* sources; ownerless sources produce an ownerless rule.
* - `visibility` is the strictest of the sources' `visibility:` token
* sets (`strictestVisibilityOf`, the topic plan's own rule): the
* rule restates a source's principle verbatim, so it may never be
* more public than the most restricted member. An intersection that
* misses falls closed on the reserved token. Empty means default
* visibility, and the writer omits the field then.
*/
export interface CrossTopicRulePlan {
/** `cross-<sha256-12>`; the file basename without the `pref-` prefix. */
readonly slug: string;
/** Deterministic join of the sorted source topic displays. */
readonly topic: string;
/** One source's principle, verbatim. */
readonly principle: string;
/** `[[pref-<slug>]]` wikilinks to every source, in code-unit order. */
readonly evidencedBy: ReadonlyArray<string>;
/** The source preference ids (`pref-<slug>`), in code-unit order. */
readonly related: ReadonlyArray<string>;
/**
* The strictest `visibility:` tokens of the cluster members. Written
* to the promoted rule's frontmatter when non-empty; empty is default
* visibility.
*/
readonly visibility: ReadonlyArray<string>;
/** The sources' shared owner token; absent for ownerless sources. */
readonly owner?: string;
}
export interface NewUnconfirmedPlan {
readonly slug: string;
readonly topic: string;
readonly scope: string | undefined;
readonly principle: string;
readonly evidencedBy: ReadonlyArray<string>;
readonly sign: BrainSignalSign;
/**
* Wikilink string (`[[ret-<slug>]]` or `[[pref-<slug>]]`) to the
* preference this new entry supersedes, if any. Threaded through to
* `writePreference` so the resulting frontmatter carries
* `supersedes:` for audit-trail continuity across rebuttals.
*/
readonly supersedes?: string;
/**
* Brain lifecycle suite (F5). Bi-temporal validity derived from the
* source signal at plan time (explicit signal fields preferred, else
* extracted from the signal's ISO temporal text). Threaded to the
* preference writer on promotion.
*/
readonly valid_from?: string;
readonly valid_until?: string;
/**
* The strictest `visibility:` tokens of every record the entry is drafted
* from (its evidencing signals and the record it supersedes). Written to
* the new preference's frontmatter when non-empty.
*/
readonly visibility: ReadonlyArray<string>;
}
export interface RetirePlan {
readonly slug: string;
/**
* Principle of the preference being retired, captured at plan time
* so the dream summary log payload can render a titled wikilink
* (`[[ret-slug|principle]]`) without re-reading the file after move.
*/
readonly principle: string;
readonly reason: BrainRetiredReason;
readonly supersededBy?: string;
/**
* Belief lifecycle suite (A4, t_d9365884): this retire fired on the
* accelerated chain-decay window (a low-recall superseded ancestor),
* i.e. it would not yet have retired under the normal stale window. The
* apply path emits a `chain-decay` event for these.
*/
readonly chainDecay?: boolean;
}
export interface NotedRedundantPlan {
/** Pre-rendered `[[pref-id|principle]]` wikilink for the active pref. */
readonly preference: string;
readonly signal: string;
}
export interface RetainPinnedPlan {
/** Pre-rendered `[[pref-id|principle]]` wikilink for the pinned pref. */
readonly preference: string;
readonly reason: BrainRetiredReason;
}
export interface SignalMovePlan {
readonly id: string;
readonly date: string;
readonly slug: string;
readonly path: string;
}
export function emptyPlan(): PlanState {
return {
newUnconfirmed: [],
retires: [],
notedRedundant: [],
retainPinned: [],
signalsToMove: new Map(),
contradictionTopics: new Set(),
signalsSuppressed: [],
quarantined: [],
topicKeyContentions: [],
signalsToArchive: new Map(),
crossTopicRules: [],
};
}
export function recordSignalMove(plan: PlanState, rec: SignalRecord): void {
if (!rec.active) return;
const id = rec.signal.id;
if (plan.signalsToMove.has(id)) return;
// Derive date + slug from the id (`sig-YYYY-MM-DD-<slug>`).
const m = /^sig-(\d{4}-\d{2}-\d{2})-(.+)$/.exec(id);
if (!m) return;
plan.signalsToMove.set(id, {
id,
date: m[1]!,
slug: m[2]!,
path: rec.path,
});
}
export function filterWithinWindow(
sigs: SignalRecord[],
windowDays: number,
now: Date,
): SignalRecord[] {
const minTime = now.getTime() - windowDays * 24 * 3600 * 1000;
return sigs.filter((s) => {
const t = Date.parse(s.signal.created_at);
return Number.isFinite(t) && t >= minTime;
});
}