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 mutation stage: turn a decided plan into disk state.
*
* One reason to change: the ORDER and mechanics of the writes. Nothing
* here decides anything about the vault's contents — every choice was
* already made by the planning stages. What this module owns is the
* sequence that keeps the on-disk invariants true:
*
* 1. Write new unconfirmed preferences (so signal moves can find
* them).
* 2. Apply refresh (counters, confidence, promotion) to existing
* preferences.
* 3. Move retiring preferences out (after the refresh has had a
* chance to surface the most recent counters in the retired
* file). NOTE: refresh skips entries that will retire.
* 4. Move consumed signals into `processed/`.
*
* Log emission is stage 5 and lives in `dream-report.ts`.
*
* Workrun checkpoints are emitted here rather than by the orchestrator
* because a marker must mean "every durable effect attributed to that
* phase is already on disk" — only the code that performs the writes
* knows where that point is.
*/
import { legacyVaultOf } from "./no-vault.ts";
import type { Authority } from "../store/constants.ts";
import { existsSync, mkdirSync } from "node:fs";
import { basename } from "node:path";
import { appendDecisionChangeReceipt } from "./decisions/receipts.ts";
import { preferenceSlug, type PlanState } from "./dream-plan.ts";
import { SafeguardAbortError, SafeguardTimeoutError, type Safeguard } from "./safeguard.ts";
import type { RefreshResult } from "./dream-refresh.ts";
import type { DreamGatedRetireEntry } from "./dream-types.ts";
import { WORKRUN_PHASE, type WorkrunHandle } from "./dream-workrun.ts";
import { collectEvidenceForSlug } from "./evidence.ts";
import { runHealEnrichment } from "./heal-run.ts";
import { CHAIN_DECAY_STALE_DAYS } from "./inject-governor.ts";
import { appendLogEvent } from "./log.ts";
import { archivedSignalPath, brainDirs, preferencePathOf, processedSignalPath } from "./paths.ts";
import { loadPreference, moveToRetired } from "./preference.ts";
import { isRetiredEntry, preferencesStoreOnly, storePreferenceEntry } from "./preference-store.ts";
import { writePreferenceTxn } from "./preference-txn.ts";
import { isoSecond } from "./time.ts";
import { assertVaultIdentityForWrite } from "./vault-identity.ts";
import {
BRAIN_LOG_EVENT_KIND,
BRAIN_PREFERENCE_STATUS,
BRAIN_RETIRED_REASON,
type BrainConfig,
type BrainPreference,
type BrainRetiredReason,
} from "./types.ts";
import { renameWithRetry } from "../fs-atomic.ts";
import { parseFrontmatter } from "../vault.ts";
import { routeSignalState, signalsStoreOnly } from "./signal-state.ts";
import { readStoreEntities } from "../store/read/store-entities.ts";
import { REMOTE_DENY_VISIBILITY_TOKEN } from "../graph/visibility.ts";
/**
* The authority of every dream write under brain store dual writes: dream
* is an automatic pass, so it decides as an agent even when an operator
* started it from the CLI.
*/
const DREAM_AUTHORITY = "agent" satisfies Authority;
const DAY_MS = 24 * 3600 * 1000;
/** Agent of record when the caller declared no name. */
const DEFAULT_DREAM_AGENT = "dream";
export interface DreamApplyInput {
readonly vault: string | null;
readonly cfg: BrainConfig;
readonly now: Date;
readonly plan: PlanState;
readonly refresh: RefreshResult;
/** Identity threaded into edit-history and decision receipts. */
readonly agentName: string | undefined;
/** `[[Brain/log/<date>]]`, stamped as `retired_by` on each move. */
readonly wikilinkToRun: string;
/** Resolved `dream.heal_enrich` gate for this run. */
readonly healEnrichEnabled: boolean;
/**
* The pass's cooperative deadline, forwarded to the one sub-unit here
* that is unbounded in the vault's size: the opt-in heal enrichment,
* which reads and rewrites every user page outside `Brain/`. Nothing
* else in this module iterates over anything but the decided plan, so
* nothing else needs it.
*/
readonly safeguard?: Safeguard;
readonly workrun: WorkrunHandle | null;
}
export interface DreamApplyResult {
/** Signal ids actually moved into `processed/`. */
readonly moved: string[];
/** Signal ids actually moved into `inbox/archived/`. */
readonly archived: string[];
/** Retires the destructive-from-confirmed gate declined. */
readonly gatedRetires: DreamGatedRetireEntry[];
/** User pages the opt-in heal phase enriched. */
readonly healEnriched: number;
}
/**
* Signal ids a dry run WOULD move. Reported so the caller's summary is
* accurate without touching disk.
*/
export function plannedSignalMoveIds(plan: PlanState): string[] {
return Array.from(plan.signalsToMove.values(), (sig) => sig.id);
}
/** Signal ids a dry run WOULD archive; the archive step's dry-run count. */
export function plannedSignalArchiveIds(plan: PlanState): string[] {
return Array.from(plan.signalsToArchive.values(), (sig) => sig.id);
}
export function applyDreamPlan(input: DreamApplyInput): DreamApplyResult {
const { vault, cfg, now, plan, refresh, wikilinkToRun, workrun } = input;
const agent = input.agentName ?? DEFAULT_DREAM_AGENT;
// This module renames signal files directly, so it owes the vault-identity
// assertion on its own entry rather than trusting whoever called it. The
// check is an idempotent in-memory pin and the caller's `openWorkrun` has
// already satisfied it for this root, so it never fires twice in anger.
// With no vault the store writes check the store identity (D14 item 13).
if (vault !== null) assertVaultIdentityForWrite(vault);
writePreferences(input, agent);
writeConfidenceReceipts(vault, refresh, agent, now);
// Synthesize is durable here and nowhere earlier: every new
// unconfirmed preference, every refreshed preference and every
// confidence receipt has landed. `promote_complete` is the pre-F2
// name for the same writes, so it moves with it rather than being
// left behind claiming a batch that had not started.
workrun?.checkpoint(WORKRUN_PHASE.promoteComplete);
workrun?.checkpoint(WORKRUN_PHASE.synthesizeComplete);
const gatedRetires = executeRetires(vault, cfg, now, plan, wikilinkToRun);
// Every planned retire has been moved (or explicitly gated) by here.
workrun?.checkpoint(WORKRUN_PHASE.retireComplete);
const moved = moveConsumedSignals(vault, plan);
const archived = archiveStaleSignals(vault, plan);
const healEnriched = input.healEnrichEnabled
? runHealEnrichmentSafely(vault, input.safeguard)
: 0;
// Heal's second half (the optional enrichment) is durable here; its
// first half was the retire loop above. The marker sits at the later
// of the two, so it is never a claim about work still to come.
workrun?.checkpoint(WORKRUN_PHASE.healComplete);
return { moved, archived, gatedRetires, healEnriched };
}
/**
* Steps 1 and 2: create the freshly-promoted preferences, then rewrite
* the refreshed ones.
*
* Edit-history (F4): every dream-pass write records its content
* before/after so a preference's evolution stays auditable. The agent of
* record is whoever invoked the dream run.
*
* v0.12.0 Brain Integrity Suite: both loops route through
* `writePreferenceTxn` so `_revision` auto-stamps and `_content_hash`
* lands automatically on confirmed promotions. The empty expectations
* array is deliberate - dream's plan-time logic has already decided to
* proceed; the txn just owns the bookkeeping.
*/
function writePreferences(input: DreamApplyInput, agent: string): void {
const { vault, cfg, now, plan, refresh } = input;
const historyOpts = { agent, now: () => now };
for (const np of plan.newUnconfirmed) {
// Fresh pref has no apply-evidence yet; recentApplied/recentViolated
// start empty and stay so until the next dream pass after the
// first `brain_apply_evidence` event.
writePreferenceTxn(
vault,
{
slug: np.slug,
topic: np.topic,
principle: np.principle,
created_at: isoSecond(now),
unconfirmed_until: isoSecond(addDays(now, cfg.dream.unconfirmed_window_days)),
status: BRAIN_PREFERENCE_STATUS.unconfirmed,
evidenced_by: np.evidencedBy,
// No evidence yet → Wilson lower bound on (0, 0) is 0. Pre-
// seed the field so refresh on the next pass does not have
// to treat `null` as "needs update" (which would lift
// `changed: false` no-ops into spurious rewrites).
confidence_value: 0,
recentApplied: [],
recentViolated: [],
...(np.scope ? { scope: np.scope } : {}),
// The scope is read back from stored signals: a legacy value
// must not abort the pass (see `lenientScopeTags`).
lenientScopeTags: true,
...(np.supersedes ? { supersedes: np.supersedes } : {}),
// F5: bi-temporal validity extracted from the source signal.
...(np.valid_from ? { valid_from: np.valid_from } : {}),
...(np.valid_until ? { valid_until: np.valid_until } : {}),
// The strictest visibility of the records it was drafted from.
...(np.visibility.length > 0 ? { visibility: np.visibility } : {}),
},
[],
{ overwrite: false, authority: DREAM_AUTHORITY },
historyOpts,
);
}
// Cross-topic rule promotion (t_642bc2b8): the planned rule is an
// ordinary unconfirmed preference through the same txn chokepoint -
// `inferred` provenance plus the evidence wikilinks and `related`
// lineage are what make it a promotion rather than a new claim.
// `overwrite: false` like the topic plan: the planner's content-slug
// dedup already decided the file is new, and a surprise collision
// must fail loudly rather than clobber.
for (const ct of plan.crossTopicRules) {
writePreferenceTxn(
vault,
{
slug: ct.slug,
topic: ct.topic,
principle: ct.principle,
created_at: isoSecond(now),
unconfirmed_until: isoSecond(addDays(now, cfg.dream.unconfirmed_window_days)),
status: BRAIN_PREFERENCE_STATUS.unconfirmed,
evidenced_by: ct.evidencedBy,
// No evidence yet, matching the topic plan's pre-seeding.
confidence_value: 0,
recentApplied: [],
recentViolated: [],
provenance: "inferred",
related: ct.related,
// The strictest visibility of the sources (review finding 63):
// the rule restates a source's principle verbatim, so it may
// never land at default visibility behind a restricted source.
// Written only when non-empty, like the topic plan's stamp.
...(ct.visibility.length > 0 ? { visibility: ct.visibility } : {}),
// The sources' shared owner token, so owner-scoped recall keeps
// the rule as private as its sources; ownerless rules omit it.
...(ct.owner ? { owner: ct.owner } : {}),
},
[],
{ overwrite: false, authority: DREAM_AUTHORITY },
historyOpts,
);
}
for (const update of refresh.updated.values()) {
// Rebuild the evidence slice from the log on every pass so the
// pref body stays in sync with the counters even when the
// counters themselves stayed put (e.g. dropping the
// v0.9.x placeholder body during a no-counter-change run).
const ev = collectEvidenceForSlug(vault, update.slug, {
sinceIso: update.created_at,
});
// The freshness trend was classified at PLAN time (planRefresh)
// so the no-op pre-flight rendered these exact bytes.
writePreferenceTxn(
vault,
{
slug: update.slug,
topic: update.topic,
principle: update.principle,
created_at: update.created_at,
unconfirmed_until: update.unconfirmed_until,
status: update.status,
evidenced_by: update.evidenced_by,
confirmed_at: update.confirmed_at,
applied_count: update.applied_count,
violated_count: update.violated_count,
last_evidence_at: update.last_evidence_at,
confidence: update.confidence,
confidence_value: update.confidence_value,
pinned: update.pinned,
recentApplied: ev.applied,
recentViolated: ev.violated,
...(update.freshness_trend !== undefined
? { freshness_trend: update.freshness_trend }
: {}),
// Derived-fact fields (finding 77): the update carries a promoted
// rule's provenance and lineage through its counter changes, in
// the same render position the writer uses, so the bytes match
// the no-op pre-flight and the fields survive every rewrite.
...(update.provenance !== undefined ? { provenance: update.provenance } : {}),
...(update.related !== undefined && update.related.length > 0
? { related: update.related }
: {}),
// The record's `visibility:` tokens (review round 2), threaded like
// provenance and related: the update write is the only thing that
// keeps the line on a restricted rule through its counter changes,
// and the no-op pre-flight needs the input to carry it to match the
// bytes on disk. Written only when non-empty, like every stamp.
...(update.visibility !== undefined && update.visibility.length > 0
? { visibility: update.visibility }
: {}),
...(update.scope ? { scope: update.scope } : {}),
lenientScopeTags: true,
},
[],
{ overwrite: true, authority: DREAM_AUTHORITY },
historyOpts,
);
}
}
/**
* Belief lifecycle suite (B4): the preference-confidence update path
* emits a decision-change receipt for each material confidence band
* change captured this pass. `bandDrops` is the existing, already-
* computed set of material weakenings (a band actually dropped), so
* this rides on data the refresh already produced without touching its
* byte-identical no-op guarantees. The receipt's idempotency key
* (subject + before + after) makes a re-run a no-op. Fail-soft.
*/
function writeConfidenceReceipts(
vault: string | null,
refresh: RefreshResult,
agent: string,
now: Date,
): void {
// Decision-change receipts are a vault lane until the decisions lane has
// a record kind (design D14 item 2); with no vault they are not written.
if (vault === null) return;
for (const d of refresh.bandDrops) {
const before = `confidence:${d.previous}${d.previous_value !== null ? `(${d.previous_value.toFixed(2)})` : ""}`;
const after = `confidence:${d.next}(${d.next_value.toFixed(2)})`;
try {
appendDecisionChangeReceipt(vault, {
subject: d.id,
before,
after,
confidenceDelta: d.previous_value !== null ? d.next_value - d.previous_value : null,
actor: agent,
rationale: `applied ${d.applied} / violated ${d.violated}`,
reasonCode: "confidence-refresh",
ts: now.toISOString(),
});
} catch {
// Accountability mirror is best-effort; the refreshed preference
// bytes remain authoritative.
}
}
}
/** Step 3: move each planned retire into `retired/`, honouring the evidence gate. */
function executeRetires(
vault: string | null,
cfg: BrainConfig,
now: Date,
plan: PlanState,
wikilinkToRun: string,
): DreamGatedRetireEntry[] {
// v0.12.0 Brain Integrity Suite: declined retires accumulate here.
// Always an array (even when no gate is configured) so the eventual
// DreamRunSummary.gated_retires field is consistently shaped.
const gatedRetires: DreamGatedRetireEntry[] = [];
const gateThreshold = cfg.retire.confirmed_evidence_min_threshold;
for (const r of plan.retires) {
const fromPath = preferencePathOf(vault, r.slug);
// The page on an unswitched machine, the store's fold once switched.
if (!preferenceHeld(vault, r.slug, fromPath)) continue;
// v0.12.0 Brain Integrity Suite: destructive-from-confirmed gate.
// When the operator has set retire.confirmed_evidence_min_threshold,
// refuse to retire a confirmed (unpinned) pref whose accumulated
// evidence count is below the configured floor. Operator-initiated
// retires bypass.
if (gateThreshold !== undefined && gateThreshold > 0) {
try {
const existing = loadPreference(vault, r.slug);
if (existing !== null && shouldGateRetireFromConfirmed(existing, r.reason, gateThreshold)) {
gatedRetires.push({
pref_id: existing.id,
topic: existing.topic,
applied_count: existing.applied_count,
violated_count: existing.violated_count,
threshold: gateThreshold,
attempted_reason: r.reason,
});
continue;
}
} catch {
// Parse failure - fall through to the normal retire path
// (moveToRetired will surface the error through stderr below).
}
}
try {
moveToRetired(vault, fromPath, r.reason, {
now,
authority: DREAM_AUTHORITY,
retired_by: wikilinkToRun,
...(r.supersededBy ? { superseded_by: r.supersededBy } : {}),
});
// Belief lifecycle suite (A4): record the accelerated retirement of
// a low-recall superseded ancestor as a dedicated audit event.
if (r.chainDecay) {
appendLogEvent(vault, {
timestamp: isoSecond(now),
eventType: BRAIN_LOG_EVENT_KIND.chainDecay,
body: {
preference: `[[ret-${r.slug}]]`,
reason: r.reason,
stale_days: String(CHAIN_DECAY_STALE_DAYS),
},
});
}
} catch (err) {
// A retire failure is logged via the `skip-corrupted-frontmatter`
// pathway only if it stemmed from a parse error during the
// plan; here the file may have been moved already (rare race).
// Surface the cause so an operator chasing a missing retire can
// see which slug tripped.
process.stderr.write(
`warning: retire stale pref ${r.slug} failed: ${(err as Error).message}\n`,
);
}
}
return gatedRetires;
}
/** Whether the active preference `slug` exists: its page, or the store's fold once switched. */
function preferenceHeld(vault: string | null, slug: string, pagePath: string): boolean {
if (!preferencesStoreOnly(vault)) return existsSync(pagePath);
const found = storePreferenceEntry(slug);
return found !== undefined && !isRetiredEntry(found);
}
/**
* Step 4: move every consumed signal out of `inbox/`. On a store-only
* machine (task 2.10) a move is a `signal-state` record (`consumed`) and no
* file moves; an unswitched machine renames the file and dual-writes the
* record.
*/
function moveConsumedSignals(vault: string | null, plan: PlanState): string[] {
const moved: string[] = [];
const storeOnly = signalsStoreOnly(vault);
// Read once: recording one signal's move does not change whether another
// is live, and each append would otherwise invalidate the fold cache.
const live = storeOnly ? liveStoreSignals() : null;
for (const sig of plan.signalsToMove.values()) {
// The legacy destination, resolved only by the legacy move.
const dest = (): string =>
processedSignalPath(legacyVaultOf(vault, "moveConsumedSignals"), sig.date, sig.slug);
try {
if (live !== null && !live.has(sig.id)) continue;
// Judged before the move, from the page the scan read.
const meta = storeOnly ? undefined : readFrontmatterOf(sig.path);
routeSignalState({
vault,
id: sig.id,
state: "consumed",
authority: DREAM_AUTHORITY,
legacyFrontmatter: meta,
legacy: () => renameWithRetry(sig.path, dest()),
});
moved.push(sig.id);
} catch (err) {
// Best-effort: a missing source signal (already moved) is
// benign on rerun. Still surface so a real I/O issue is visible.
process.stderr.write(
`warning: move signal ${sig.id} to processed/ failed: ${(err as Error).message}\n`,
);
}
}
return moved;
}
/**
* Step 4b: move every signal the archive policy selected (see
* `signal-archive.ts`) from `inbox/` to `inbox/archived/`, byte for byte.
*
* Never overwrites: a destination that exists is left alone and the signal
* stays in the inbox (the planner already skips names it saw in the
* archive; this covers a file that appeared since the scan). A failed move
* is reported and the signal stays where it was, so a rerun picks it up.
*
* On a store-only machine (task 2.10) the archive is a `signal-state`
* record (`archived`); no folder is created and no file moves.
*
* No deadline checkpoint inside the loop, like the processed/ move above: a
* pass stopped half way would leave archived files the run's log never
* names. The pass's own post-mutation checkpoint follows immediately.
*/
function archiveStaleSignals(vault: string | null, plan: PlanState): string[] {
const archived: string[] = [];
if (plan.signalsToArchive.size === 0) return archived;
const storeOnly = signalsStoreOnly(vault);
const live = storeOnly ? liveStoreSignals() : null;
// The legacy destination, resolved only off the store-only path.
const archivedPath = (path: string): string =>
archivedSignalPath(legacyVaultOf(vault, "archiveStaleSignals"), basename(path));
if (!storeOnly) {
mkdirSync(brainDirs(legacyVaultOf(vault, "archiveStaleSignals")).archived, {
recursive: true,
});
}
for (const sig of plan.signalsToArchive.values()) {
try {
if (live !== null) {
if (!live.has(sig.id)) continue;
} else {
const dest = archivedPath(sig.path);
if (existsSync(dest)) {
process.stderr.write(
`warning: archive signal ${sig.id}: ${basename(dest)} already exists in ` +
`inbox/archived/; left in the inbox\n`,
);
continue;
}
}
routeSignalState({
vault,
id: sig.id,
state: "archived",
authority: DREAM_AUTHORITY,
legacyFrontmatter: storeOnly ? undefined : readFrontmatterOf(sig.path),
legacy: () => renameWithRetry(sig.path, archivedPath(sig.path)),
});
archived.push(sig.id);
} catch (err) {
process.stderr.write(
`warning: archive signal ${sig.id} to inbox/archived/ failed: ${(err as Error).message}\n`,
);
}
}
return archived;
}
/** The ids the store's signal fold holds in the inbox (store-only moves). */
function liveStoreSignals(): ReadonlySet<string> {
const live = new Set<string>();
for (const [id, signal] of readStoreEntities()?.signals ?? []) {
if (signal.state === "active") live.add(id);
}
return live;
}
/**
* The frontmatter of a signal page, judged for the dual write before it
* moves. A page that cannot be read is judged private (fail closed).
*/
function readFrontmatterOf(path: string): Record<string, unknown> {
try {
return parseFrontmatter(path)[0];
} catch {
return { visibility: [REMOTE_DENY_VISIBILITY_TOKEN] };
}
}
/**
* Heal phase (F6): opt-in deterministic vault enrichment, run after the
* retire/move mutations (heal-after-mutations). Off by default so the
* default install stays byte-identical; a failure is a warning, never
* fatal to the dream pass.
*
* A SAFEGUARD STOP IS NOT SUCH A FAILURE, and the difference is the whole
* reason this catch is narrowed. "Heal could not enrich a page" is a
* hygiene miss the pass survives; "the operator cancelled" and "the pass
* is past its budget" are decisions about the RUN, and swallowing either
* into a stderr warning plus `0` would report a pass that enriched
* nothing where the truth is a pass that was stopped. The pass's own
* post-mutation checkpoint would throw an instant later anyway - so
* absorbing it here only ever bought a wrong `heal_enriched: 0` on the
* way to the same error.
*/
function runHealEnrichmentSafely(vault: string | null, safeguard: Safeguard | undefined): number {
// Heal enrichment rewrites user notes; with no vault there are none.
if (vault === null) return 0;
try {
return runHealEnrichment(vault, safeguard ? { safeguard } : {}).enriched;
} catch (err) {
if (err instanceof SafeguardTimeoutError || err instanceof SafeguardAbortError) throw err;
process.stderr.write(`warning: heal enrichment failed: ${(err as Error).message}\n`);
return 0;
}
}
/**
* Brain Integrity Suite (v0.12.0). Pure decision function for the
* destructive-from-confirmed gate. Exported so the gate logic can be
* unit-tested without driving a full dream run.
*
* Returns `true` when the candidate retire MUST be held back. The
* caller is responsible for recording a {@link DreamGatedRetireEntry}
* and skipping the actual `moveToRetired` call.
*/
export function shouldGateRetireFromConfirmed(
existing: BrainPreference,
reason: BrainRetiredReason,
threshold: number | undefined,
): boolean {
if (threshold === undefined || threshold <= 0) return false;
if (reason === BRAIN_RETIRED_REASON.userRejected) return false;
if (reason === BRAIN_RETIRED_REASON.mergedInto) return false;
if (existing.status !== BRAIN_PREFERENCE_STATUS.confirmed) return false;
if (existing.pinned) return false;
const evidenceCount = (existing.applied_count ?? 0) + (existing.violated_count ?? 0);
return evidenceCount < threshold;
}
/**
* Slugs whose retire the gate declined. The log body and the
* DreamRunSummary must agree on this set, or the next dream pass would
* parse a `pref-foo` log claiming the pref was retired while the file is
* still in `preferences/`.
*/
export function gatedRetireSlugs(gatedRetires: ReadonlyArray<DreamGatedRetireEntry>): Set<string> {
return new Set(gatedRetires.map((g) => preferenceSlug(g.pref_id)));
}
function addDays(d: Date, days: number): Date {
return new Date(d.getTime() + days * DAY_MS);
}