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.
Trust and operator surfaces - variants audit trail
This file is the audit trail of the architectural brainstorm for v0.10.16. Per the feature-release-playbook, all variants are recorded verbatim from the consultant pass plus the final orchestrator rationale, so a future reader can see the alternatives that lost and why.
Source
- Primary consultant: Claude Code via
claude -p. Output captured verbatim incli-output/claude.md. - Fallback consultant: not invoked. Primary returned three parseable variants and a recommendation on first run.
- Date of pass: 2026-05-25.
Variants (verbatim from primary consultant)
Variant 1: Flat layered expansion, no new MCP tool
- Approach: Drop each feature as a peer module in its matching layer (atoms next to existing atoms, helpers next to existing helpers), and extend
brain_doctor/brain_dream/brain_digest/brain_feedbackin-place with new fields. The operator dashboard becomes an extension ofDigestJson(newtrust_verdict,uncertain_count,quarantined_count,verification_delta_summaryfields), not a new tool. No new directory; eight features land as ~8 small peer modules across existing folders. - Trade-offs:
- Pro: smallest surface-area delta, mirrors v0.10.14 / v0.10.10 style (extend, don't add tools).
- Pro: each feature stays independently testable; bundle = sum of parts.
- Pro: lowest risk of cross-feature coupling regressions.
- Con: the "trust the brain's self-reporting" theme is invisible at the file-tree level - eight tiny additions sprinkled across
src/core/brain/. - Con: dashboard via field-expansion of
DigestJsonmakes that type wider and less focused; operators must still mentally compose multiple sections. - Con: no single import path that a future contributor can point at as "the trust layer".
- Complexity: medium
- Risk: low
Variant 2: New trust/ subsystem with one new consumer tool
- Approach: Introduce
src/core/brain/trust/housing the new helpers (compute-verification-delta.ts,compute-trust-verdict.ts,assess-rule-quality.ts,check-role-permission.ts,instruction-file-ceiling.ts,self-approval-guardrail.ts), each a pure function over atoms. Atoms (uncertainty arrays, verdict field, promotion config) still land on the existing summary types, but everything that computes them lives intrust/. Add one new MCP toolbrain_operator_summaryas the aggregating consumer; existing tools import the helpers but keep their current shape and contracts. - Trade-offs:
- Pro: follows v0.10.15 precedent (
page-meta/,maintenance/subdirs) - gives the release a coherent identity and a single grep target. - Pro: helpers are pure, so cross-feature interaction is forced through typed function boundaries instead of ad-hoc field reads.
- Pro: dashboard tool can iterate independently without re-shaping
DigestJson;brain_digeststays small and digestible. - Pro: tests mirror cleanly under
tests/core/brain/trust/. - Con: requires choosing a subsystem name now; "trust" may age poorly if scope drifts.
- Con: one extra MCP tool to document, version, and keep aligned with
brain_digest(overlap risk). - Con: slightly more upfront design than Variant 1 - need to define the trust-layer's read-only contract against atoms.
- Pro: follows v0.10.15 precedent (
- Complexity: medium
- Risk: low
Variant 3: Capability-kernel refactor around writes
- Approach: Make role-separated permissions (#8) the keystone - introduce a
BrainCapabilitykernel that intercepts every brain write (brain_feedback,brain_dream,brain_apply_evidence), and rebuild the other seven features as policies hanging off that kernel (quality gate as a pre-write policy, self-approval guardrail as a promotion policy, verification delta as a post-write policy, etc.). Existing handlers insrc/mcp/brain-tools.tsget rewritten to flow through the kernel. - Trade-offs:
- Pro: structurally enforces #8 - role boundaries can't be bypassed because the kernel mediates every write.
- Pro: future brain tools inherit role separation, quality gates, and verification for free.
- Pro: the cleanest long-term mental model - one seam, many policies.
- Con: violates the project's "extend without rewriting" rule and "no backwards-compat shims" posture -
brain-tools.tshandlers get re-shaped. - Con: largest blast radius across 1865+ tests; bundling a refactor with eight features in one release inflates review surface and CHANGELOG scope.
- Con: kernel design is the kind of premature abstraction the layered-DAG convention exists to prevent; v0.10.15 explicitly chose peer modules over a kernel.
- Con: high risk that one of the eight features stalls and blocks the other seven because they share a critical-path module.
- Complexity: large
- Risk: high
Consultant recommendation
Variant 2.
Variant 2 fits the established v0.10.15 precedent (a named subdirectory of pure helpers per release) and gives the eight-feature bundle the coherent identity its theme demands, without the rewriting risk of Variant 3 or the file-tree invisibility of Variant 1. Atoms remain field-additions on existing summaries (satisfying "extend without rewriting"), helpers are pure and independently testable, and one new consumer tool (
brain_operator_summary) cleanly absorbs the dashboard role sobrain_digeststays focused. It preserves the layered DAG rule while making the release legible as a single architectural move.
Orchestrator decision
Chosen: Variant 2 (agreeing with the consultant).
Rationale: the recommendation matches three independent project signals the consultant could not fully see:
- v0.10.15 explicitly built
src/core/brain/page-meta/andsrc/core/brain/maintenance/as named per-release subsystems; choosingtrust/continues that pattern and lets the next maintenance release add a peer subsystem without re-cutting the schema. - The active Brain preference
pref-self-review-after-implementationmandates the superpowers code-review pass; pure helpers under one subdirectory are easier to review as a unit than scattered diffs. - Variant 3 violates the project's CLAUDE.md-level rule "do not propose Hermes-convention or schema-design violations" by implication - the kernel refactor would re-shape
brain-tools.tshandlers that have been stable across the last seven releases.
The only deviation from the consultant's writeup: the subsystem name trust/ (over alternatives like governance/ or gates/) is kept because it matches the release theme exactly. If the scope later grows to cover non-trust governance, a renaming refactor is a cheap follow-up.
Variants not pursued
- Per-feature subdirectories (e.g.
src/core/brain/quality-gate/,src/core/brain/verification/) - rejected because eight tiny subdirectories defeat the unifying theme and balloon the cross-import graph. - Storing verification verdicts persistently (e.g.
Brain/verification/<date>.jsonl) - rejected because it duplicates information already derivable from the daily log + the preferences/retired folders. Computing on read keeps the vault layout stable. - LLM-driven quality gate - rejected because Open Second Brain's design principle is deterministic, no-LLM-in-the-loop algorithms. Quality gate uses structural heuristics only.