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 audit trail: everything the run says about itself in
* `Brain/log/<today>.md`.
*
* One reason to change: what an operator (or the digest parser, or the
* next dream pass) must be able to read back about a run. This module
* owns the event ORDER, the per-event timestamp cursor and the summary
* payload's shape. It decides nothing about the vault's contents.
*
* Only ever invoked on the changed, non-dry-run path — a no-op run
* writes no events at all, which is what keeps an idempotent rerun
* byte-identical.
*/
import { vaultRelativeOf } from "./no-vault.ts";
import { preferenceSlug, type PlanState, type ScanResult } from "./dream-plan.ts";
import { writeCrossTopicLedger, type CrossTopicLedger } from "./dream-plan-cross-topic.ts";
import type { RefreshResult } from "./dream-refresh.ts";
import { WORKRUN_PHASE, type WorkrunHandle } from "./dream-workrun.ts";
import { appendLogEvent } from "./log.ts";
import type { ReconcileOutcomes } from "./reconcile-outcomes.ts";
import { writeRollupLedger, type RollupLadderPlan } from "./rollup-ladder.ts";
import { isoSecond } from "./time.ts";
import { renderPrefLink } from "./wikilink.ts";
import { BRAIN_LOG_EVENT_KIND } from "./types.ts";
/** Spacing between consecutive events so their log headings stay distinct. */
const EVENT_STAMP_STEP_MS = 1000;
/** Marks a retain-pinned event as an attempted-but-blocked retire. */
const RETIRE_BLOCKED_PINNED = "pinned";
export interface DreamReportInput {
readonly vault: string | null;
readonly now: Date;
readonly runId: string;
readonly scan: ScanResult;
readonly plan: PlanState;
readonly refresh: RefreshResult;
readonly reconcile: ReconcileOutcomes;
readonly rollupPlan: RollupLadderPlan;
/**
* The updated cross-topic daily budget (t_642bc2b8) to persist when a
* promotion fired this run; null when none did, so a below-threshold
* or budgeted-out run never touches the ledger - the same
* byte-identical opt-out the rollup ledger uses.
*/
readonly crossTopicLedger: CrossTopicLedger | null;
/** Signal ids that actually reached `processed/`. */
readonly moved: ReadonlyArray<string>;
/** Signal ids moved into `inbox/archived/` by this run. */
readonly archived: ReadonlyArray<string>;
/** Retires the evidence gate declined; excluded from the `retired` row. */
readonly gatedSlugs: ReadonlySet<string>;
/** True when the invoking agent differs from the vault's declared primary. */
readonly isNonPrimary: boolean;
readonly callerAgent: string;
readonly workrun: WorkrunHandle | null;
}
/**
* Emit the run's log entries: skip-corrupted-frontmatter first
* (chronological sense: corruption was detected during planning), then
* per-topic events, then the run summary last.
*/
export function writeDreamLog(input: DreamReportInput): void {
const { vault, plan, reconcile, workrun } = input;
const nextStamp = createStampCursor(input.now);
for (const corrupt of input.scan.corrupted) {
appendLogEvent(vault, {
timestamp: nextStamp(),
eventType: BRAIN_LOG_EVENT_KIND.skipCorruptedFrontmatter,
body: {
path: vaultRelativeOf(corrupt.path, vault),
},
});
}
for (const noted of plan.notedRedundant) {
appendLogEvent(vault, {
timestamp: nextStamp(),
eventType: BRAIN_LOG_EVENT_KIND.notedRedundant,
body: {
preference: noted.preference,
signal: noted.signal,
},
});
}
// Reconcile phase (F3): one event per open question + per
// auto-resolution. Persisted only on this changed path so a no-op
// run stays byte-identical.
for (const q of reconcile.openQuestions) {
appendLogEvent(vault, {
timestamp: nextStamp(),
eventType: BRAIN_LOG_EVENT_KIND.reconcile,
body: {
topic: q.topic,
domain: q.domain,
reason: q.reason,
...(q.scope ? { scope: q.scope } : {}),
positives: String(q.positive_count),
negatives: String(q.negative_count),
},
});
}
for (const r of reconcile.autoResolved) {
appendLogEvent(vault, {
timestamp: nextStamp(),
eventType: BRAIN_LOG_EVENT_KIND.reconcile,
body: {
topic: r.topic,
domain: r.domain,
resolution: "auto-resolved",
winner_sign: r.winner_sign,
margin_days: String(r.margin_days),
},
});
}
// Reconcile's only durable artifact is the pair of event loops just
// above: the classification itself is in-memory and vanishes with the
// process. The pre-mutation burst used to claim this phase complete
// before a single preference had been written, which is precisely the
// journal-lies failure this release removes. The marker therefore
// trails `heal_complete` in the file - emission order is execution
// order, not the reporting order of DREAM_PHASE_ORDER.
workrun?.checkpoint(WORKRUN_PHASE.reconcileComplete);
for (const suppressed of plan.signalsSuppressed) {
appendLogEvent(vault, {
timestamp: nextStamp(),
eventType: BRAIN_LOG_EVENT_KIND.signalSuppressed,
body: {
signal: suppressed.signal,
retired: suppressed.retired,
topic: suppressed.topic,
reason: suppressed.reason,
},
});
}
for (const retain of plan.retainPinned) {
// `retain-pinned` is not in the strict BrainLogEventKind enum
// (the design doc names a generic `retire` event with an
// attempted-but-blocked reason). We log it as a `retire` event
// with a `blocked: pinned` payload field so the parser
// round-trips cleanly and the doctor command can flag it.
appendLogEvent(vault, {
timestamp: nextStamp(),
eventType: BRAIN_LOG_EVENT_KIND.retire,
body: {
preference: retain.preference,
reason: retain.reason,
blocked: RETIRE_BLOCKED_PINNED,
},
});
}
appendLogEvent(vault, {
timestamp: nextStamp(),
eventType: BRAIN_LOG_EVENT_KIND.dream,
body: buildSummaryBody(input),
});
// S3: persist the advanced rollup-ladder counters only when a rung
// fired. A below-threshold run never touches the ledger, so its
// absence is the byte-identical opt-out.
if (input.rollupPlan.fired) writeRollupLedger(vault, input.rollupPlan.ledger);
// Cross-topic promotion (t_642bc2b8): persist the advanced per-owner
// daily budget beside the rollup ledger, under the same discipline -
// written only when a promotion actually fired, through the shared
// atomic writer.
if (input.crossTopicLedger) writeCrossTopicLedger(vault, input.crossTopicLedger);
}
/**
* Monotonic per-emission timestamp source. Each event advances the cursor
* so two events in the same run never share a log heading.
*/
function createStampCursor(now: Date): () => string {
let cursorMs = now.getTime();
return () => {
const ts = new Date(cursorMs);
cursorMs += EVENT_STAMP_STEP_MS;
return isoSecond(ts);
};
}
/**
* The `dream` summary event's payload. Every row is conditional: a key
* that would carry an empty list is omitted entirely, which is what keeps
* a minimal run's event byte-identical to earlier releases.
*
* Link rendering threads the in-memory principle alongside the id so the
* digest / Obsidian view can hover-preview the rule without an extra file
* open.
*/
function buildSummaryBody(input: DreamReportInput): Record<string, string | ReadonlyArray<string>> {
const { plan, refresh, rollupPlan, gatedSlugs } = input;
const slugToPrefPrinciple = new Map<string, string>();
for (const rec of input.scan.preferences) {
slugToPrefPrinciple.set(preferenceSlug(rec.pref.id), rec.pref.principle);
}
const newUnconfirmedIds = plan.newUnconfirmed.map((p) =>
renderPrefLink({ id: `pref-${p.slug}`, principle: p.principle }),
);
const confirmedIds = Array.from(refresh.confirmed.values()).map((slug) =>
renderPrefLink({
id: `pref-${slug}`,
principle: refresh.updated.get(slug)?.principle ?? slugToPrefPrinciple.get(slug) ?? "",
}),
);
const retiredEntries = plan.retires
.filter((r) => !gatedSlugs.has(r.slug))
.map((r) => `${renderPrefLink({ id: `ret-${r.slug}`, principle: r.principle })} (${r.reason})`);
const body: Record<string, string | ReadonlyArray<string>> = {
run_id: input.runId,
};
if (newUnconfirmedIds.length > 0) body["new_unconfirmed"] = newUnconfirmedIds;
if (confirmedIds.length > 0) body["confirmed"] = confirmedIds;
if (retiredEntries.length > 0) body["retired"] = retiredEntries;
if (input.moved.length > 0) body["moved_to_processed"] = input.moved;
if (input.archived.length > 0) body["archived_signals"] = input.archived;
if (plan.contradictionTopics.size > 0) {
body["contradictions"] = Array.from(plan.contradictionTopics);
}
if (plan.signalsSuppressed.length > 0) {
body["suppressed"] = plan.signalsSuppressed.map((s) => `${s.signal} ← ${s.retired}`);
}
// Folded topic keys the pass planned nothing for because two preferences
// claim them. The run summary's warnings carry the same finding to the
// caller; this row is the durable half, so a run that mutated something
// else leaves the ambiguity in the audit trail rather than only on stderr.
if (plan.topicKeyContentions.length > 0) {
body["topic_key_contentions"] = plan.topicKeyContentions.map(
(c) => `${c.key}: ${c.prefIds.join(", ")}`,
);
}
if (refresh.bandDrops.length > 0) {
// Format matches the digest's tolerant `parseShiftLine` parser:
// `[[pref-…|principle]] <from> -> <to> (applied: N, violated: M)`.
body["confidence_shifts"] = refresh.bandDrops.map((d) =>
[
renderPrefLink({ id: d.id, principle: d.principle }),
d.previous,
"->",
d.next,
`(applied: ${d.applied}, violated: ${d.violated})`,
].join(" "),
);
}
if (input.isNonPrimary) {
// Audit-trail row matching the structured warning. Stored
// alongside `run_id` so a non-primary dream pass is greppable in
// the log without parsing the structured warnings array.
body["non_primary_agent"] = input.callerAgent;
}
// S3: record each fired rollup rung's counter reset in the dream
// report. Absent below threshold, so a non-firing run's summary event
// is byte-identical to the pre-rollup behaviour.
if (rollupPlan.fired) {
body["rollups"] = rollupPlan.entries.map(
(e) => `${e.tier} -> ${e.produces} (${e.fromCount} -> ${e.toCount})`,
);
}
// Cross-topic promotion (t_642bc2b8): each promoted rule rendered
// like a new unconfirmed pref, with its source lineage after an arrow
// so the audit trail shows what the rule generalises without opening
// a single source file. Absent when nothing fired.
if (plan.crossTopicRules.length > 0) {
body["cross_topic_rules"] = plan.crossTopicRules.map(
(r) =>
`${renderPrefLink({ id: `pref-${r.slug}`, principle: r.principle })} ← ${r.related.join(", ")}`,
);
}
return body;
}