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.
Brain lifecycle suite - deterministic consolidation, audit, and brief
Status: draft Author: claude-vps-agent (via feature-release-playbook) Audience: implementation
Problem statement
Open Second Brain's nightly consolidation (dream) is a single opaque pass,
preference mutations leave no per-preference trail, contradictions collapse to
one flat topic list, and there is no session-start brief. This suite makes the
dream pass an explicit ordered pipeline, gives every preference an authoritative
mutation history, classifies contradictions by domain, surfaces a budgeted
brief, and extracts formal temporal constraints from signal text - all
deterministically and without any hardcoded natural language.
Scope
Six deterministic, language-agnostic features (chosen set, implemented one-by-one via TDD):
- Per-preference mutation audit log - append-only JSONL per pref id, captured at the mutation chokepoints (
writePreferenceTxn,moveToRetired,mergePreferences), recording op / agent / reason / revision + content-hash before-after. Read surface:brain_audit(MCP) +o2b brain audit <pref-id>(CLI). - Multi-phase dream pipeline - the proven
dream()internals stay verbatim; a thin orchestration layer names the existing seams as ordered phases (close -> reconcile -> synthesize -> heal -> log), emits one workrun checkpoint + one structured summary per phase, and exposesDreamRunSummary.phases. - Reconcile domain classification - a deterministic classifier buckets the run's contradictions into domains (claims / entity / decisions / source-freshness) from structural signals only, auto-resolves the unambiguous source-freshness case, and flags the rest as
open_questionsinstead of force-merging. Replaces the flatcontradictionstopic list (kept as a derived view for back-compat). - Morning brief / day-close - a read-only, budgeted summary (recent activity + top confirmed preferences + open questions from the last reconcile). Read surface:
brain_morning_brief(MCP) +o2b brain morning-brief(CLI). Reuses the v0.20.0recall-budgetchar primitive. - Temporal extraction from signal text - a pure parser that recognises ISO-8601 dates, intervals, and durations (relative to an injected
now) in a signal's text and fills the EXISTING bi-temporalvalid_from/valid_untilfields on the promoted preference when empty. ISO tokens only - no localized month/day names. - Heal-phase vault enrichment - in the dream heal phase, complete a missing
titlefrom the page's first H1 and insert wikilinks for exact title/alias matches to existing pages. Opt-in (dream.heal_enrich_enabled, default false) because it rewrites user files; disabled = no-op.
Out of scope
- Rewriting or relocating the proven
dream()plan/execute logic (Variant 2 rejected). - Any LLM fan-out / parallel reconciliation agents (the upstream inspiration's 4-agent design is explicitly NOT adopted).
- Generic external "memory ingest pipeline" beyond the brief.
- LLM-based enrichment inference (due-date guessing, workload reasoning).
- Localized natural-language temporal parsing (only formal ISO tokens).
- A frontend / UI for reviewing open questions.
Chosen approach
Variant 1 - orchestration wrapper with chokepoint audit. The phase
pipeline is a thin orchestrator over the existing scanBrain -> planTopics
-> planRefresh -> planAutoRetires -> execute seams: each seam is labelled a
phase, emits a WORKRUN_PHASE checkpoint, and contributes a structured
DreamPhaseSummary. No proven logic moves. The new deterministic capabilities
(domain classifier, temporal extractor, heal enrichment) are pure functions
called inside their owning phase. The audit trail is captured at the write
primitives so it is authoritative (true before/after content hashes) and also
catches non-dream manual edits.
Design decisions
- Audit at the chokepoint, not by projection.
writePreferenceTxn/moveToRetired/mergePreferencesalready compute_revisionand_content_hash; they gain an optional audit sink and append one record only when the content hash actually changes (before != after). A no-op dream run touches no preference content, so it writes no audit line -> the default byte-identical contract holds. - Per-pref-id JSONL file (
Brain/log/pref-audit/<pref-id>.jsonl) so an operator cancatone preference's whole lifecycle. Append-only, same atomic-append assumption asdream-workrun. The op kind is a small closed enum tolerant of unknown values on read. - Phases are additive labels, not control-flow surgery.
WORKRUN_PHASEgainsclose_complete/reconcile_complete/synthesize_complete/heal_complete; readers already must tolerate unknown phases.DreamRunSummary.phasesis a new optional-shaped array; existing fields are unchanged and the no-op path returnsphases: []. - Domain classification is structural. Domain is derived from signal shape:
source-freshnesswhen the contradiction is resolvable byrecorded_at/created_atrecency beyond a margin;entitywhen signals carry entity wikilinks insource;decisionswhen scope marks a decision; elseclaims. Onlysource-freshnessauto-resolves (toward the strictly fresher side); everything else becomes an open question. No language inspection. - Temporal extraction is ISO-only and additive. Recognises
YYYY-MM-DD,YYYY-MM-DD/YYYY-MM-DD, and ISO-8601 durations (P7D,P2W,P1M,P1Y) computed against the injectednow. Fillsvalid_from/valid_untilon a promoted preference only when the field is empty; never overwrites. - Heal enrichment is opt-in. It rewrites user vault files, so it is gated
behind
dream.heal_enrich_enabled(default false). Disabled = the heal phase is a checkpoint-only no-op. Linking is exact title/alias match only. - Morning brief reuses primitives. Char budgeting via the existing
applyCharBudget(recall-budget.ts); preference ordering by confidence then recency (same comparator family aspre-compress-pack.ts).
File changes
New core modules:
src/core/brain/pref-audit.ts- audit record type,appendPrefAudit,readPrefAudit.src/core/brain/dream-phases.ts-DREAM_PHASEorder,DreamPhaseSummary, phase-summary builders.src/core/brain/reconcile-domains.ts-classifyContradiction,resolveContradiction,DreamOpenQuestion.src/core/brain/morning-brief.ts-buildMorningBrief.src/core/brain/temporal-extract.ts-extractTemporalConstraints.src/core/brain/heal-enrich.ts-deriveTitleFromContent,linkExactMentions,planHealEnrichment.
Modified core:
src/core/brain/dream.ts- phase checkpoints + summaries; call classifier in reconcile, temporal-extract in synthesize promote, heal-enrich in heal; thread audit sink.src/core/brain/preference-txn.ts,merge.ts,preference.ts(moveToRetired) - optional audit sink param.src/core/brain/dream-workrun.ts- new phase constants.src/core/brain/types.ts-DreamRunSummary.phases,open_questions; newBRAIN_LOG_EVENT_KIND.reconcile; audit op enum; config fields.src/core/brain/paths.ts-prefAuditDir/prefAuditPath.src/core/brain/policy.ts-dream.heal_enrich_enabledconfig resolution.src/core/brain/morning-brief.ts(new, self-contained) - composes the brief from existing read helpers (readLogDay, confirmed-preference scan,open_questions); does NOT modifydigest.ts.
Note: BrainPreference already carries optional valid_from / valid_until /
recorded_at (added v0.10.18), so feature 5 only fills those existing fields on
the promoted preference - no schema change, no migration.
MCP + CLI surface:
src/mcp/brain-tools.ts(+instructions.ts,tools.ts) -brain_audit,brain_morning_brief(tool count 42 -> 44).src/cli/brain/verbs/audit.ts,morning-brief.ts+src/cli/brain.ts,help-text.ts.
Docs:
README.md,docs/how-it-works.md,docs/cli-reference.md,docs/mcp.md,CHANGELOG.md.
Risks and open questions
- Byte-identical default. Audit (mutation-gated), phases (additive), open questions (replace a derived list), temporal (fill-when-empty), heal (opt-in) are each designed to leave a default no-op dream run byte-identical. The QA phase must assert a no-op run produces zero new files.
- Concurrent-device audit appends. Per-pref JSONL append from two devices
could interleave; acceptable under the single-primary-agent dream convention
(same assumption as
dream-runs/). Documented, not solved here. - Domain classifier conservatism. Auto-resolving only source-freshness keeps false auto-merges at zero; all judgemental domains stay operator-facing open questions. This is intentional under the "no cheap wins" rule.