hermes - 💡(How to fix) Fix PRD: Brain-as-source-of-truth integration for Hermes

Problem Statement

The user has an existing personal Brain at /home/shlee/Brain that already contains long-lived operating principles, project knowledge, workflow rules, failure records, and system boundaries. Hermes has memory, skills, session search, llm-wiki, and curator capabilities, but its user-specific knowledge layer is still comparatively empty. Rebuilding the same knowledge from scratch inside Hermes would duplicate effort and risk divergence from the Brain.

The user wants Hermes to continue using its native knowledge mechanisms while treating the Brain as the highest-authority source of truth. Hermes should not replace, move, or blindly ingest the Brain. Instead, Hermes should add a thin derived layer on top of the Brain: compact memory routing facts, reusable skills for Brain workflows, and a Brain-aware wiki/query adapter. Any new Hermes-derived knowledge that deserves long-term retention should become a reviewable Brain candidate before it can affect Brain final documents.

Solution

Introduce a Brain-as-source-of-truth integration model for Hermes. The Brain remains the authoritative Markdown knowledge base. Hermes adds derived layers that make the Brain discoverable and usable:

• Persistent memory stores only compact routing facts and safety boundaries for Brain work.
• Skills encode repeatable Brain workflows such as orientation, query, lint, compatibility assessment, and candidate generation.
• A wiki/adapter layer teaches Hermes how to treat the existing Brain schema as the active long-term wiki rather than initializing a separate replacement wiki.
• New Hermes work that may be worth preserving is routed into a candidate/inbox workflow, not directly into final Brain documents.
• Automation is introduced only after read-only assessment, dry-run reporting, explicit approval, and rollback planning.

The implementation should preserve current Brain principles: source preservation, safety first, rollback possibility, user approval for risky writes, and no wholesale raw log/session ingestion.

User Stories

1. As the Brain owner, I want Hermes to recognize /home/shlee/Brain as the authoritative knowledge source, so that Hermes does not rebuild personal knowledge from scratch.
2. As the Brain owner, I want Hermes to read the Brain orientation documents before Brain-related work, so that it follows the existing operating rules.
3. As the Brain owner, I want Hermes memory to contain only compact routing facts, so that memory stays small and does not become a duplicate Brain.
4. As the Brain owner, I want Hermes skills to encode Brain workflows, so that repeated Brain operations are reliable and consistent.
5. As the Brain owner, I want Hermes to distinguish Brain final documents from candidate/inbox documents, so that unreviewed information does not become authoritative.
6. As the Brain owner, I want any initial integration to be read-only first, so that the current Brain state is preserved while compatibility is assessed.
7. As the Brain owner, I want a rollback point before changes, so that I can recover from mistakes.
8. As the Brain owner, I want Hermes to avoid trigger/hook-based automatic knowledge updates at first, so that existing Brain accumulation rules remain unchanged.
9. As the Brain owner, I want Hermes to create dry-run reports before any sync-like operation, so that I can approve or reject proposed changes.
10. As the Brain owner, I want Hermes to preserve raw sources and avoid wholesale transcript ingestion, so that the Brain remains curated rather than noisy.
11. As a Hermes operator, I want clear rules for when information belongs in memory, a skill, a wiki reference, or a Brain candidate, so that knowledge is routed correctly.
12. As a Hermes operator, I want tests or verification checks around any Brain adapter logic, so that future changes do not silently break Brain orientation.
13. As a Hermes operator, I want the integration to use existing Hermes mechanisms where possible, so that it does not fork a new knowledge system.
14. As a Hermes operator, I want future automation to be gated by manual procedure, documentation, dry-run, validation, and explicit approval, so that convenience does not outrank safety.
15. As a future subagent, I want implementation issues to be small, vertical, and acceptance-testable, so that I can work AFK without broad context.

Implementation Decisions

• The Brain remains the source of truth. Hermes must not physically migrate, replace, or overwrite the Brain as part of the default integration.
• The integration is registration/orientation-first, not migration-first.
• Hermes persistent memory is used for routing and safety facts only. It should not store long Brain content.
• Hermes skills are used for procedures, not for copying every Brain knowledge card.
• The existing llm-wiki workflow should become Brain-aware by respecting local Brain equivalents such as BRAIN_SCHEMA.md, START_HERE.md, BRAIN_STATE.md, PRINCIPLES.md, WORKFLOW_PRINCIPLES.md, and SYSTEMS.md.
• New Hermes-derived knowledge must flow through an inbox/candidate review path before touching final Brain documents.
• Any automation, watcher, cron job, hook, or external sync is out of the initial scope unless explicitly approved later.
• The first implementation phase should prefer documentation, adapter rules, dry-run checks, and tests over direct mutation of Brain content.
• The project should keep using the existing issue tracker, triage label vocabulary, and single-context repo conventions already documented under docs/agents/.

Testing Decisions

• Tests should verify observable Brain workflow behavior through public interfaces or CLI/tool-facing boundaries rather than private implementation details.
• Good tests should cover routing decisions: what becomes memory, what becomes a skill, what remains Brain reference material, and what becomes a candidate.
• Good tests should cover safety behavior: final Brain documents are not modified during read-only assessment or dry-run operations.
• Good tests should cover local Brain schema orientation: Hermes recognizes Brain-specific equivalents instead of assuming generic llm-wiki filenames only.
• Good tests should cover failure modes: missing Brain path, missing orientation document, dirty worktree, absent labels, and unsupported automation requests.
• Implementation should use a strict red-green-refactor loop for code changes. Each production behavior should have a failing test first, then minimal implementation, then passing verification.
• Subagent implementation tasks should include their own TDD evidence and should be independently reviewed for spec compliance and code quality.

Out of Scope

• Moving /home/shlee/Brain to a new location.
• Reformatting the whole Brain into Hermes-native wiki files.
• Copying every Brain document into Hermes memory or skills.
• Automatic real-time bidirectional synchronization.
• New hooks, triggers, watchers, cron jobs, or daemons that update knowledge without explicit user approval.
• Wholesale ingestion of raw chat transcripts, logs, credentials, tokens, cookies, private keys, or other sensitive data.
• Changing Brain final documents before a dry-run report and explicit approval.
• Migrating old runtime automations without separate compatibility review.

Further Notes

A checkpoint commit was requested before starting this work so that rollback remains available. The safest delivery path is:

1. Preserve current state with a git checkpoint.
2. Publish this PRD.
3. Break the PRD into small tracer-bullet issues.
4. Ask for approval of the issue breakdown before publishing implementation issues.
5. Implement each issue with TDD and subagent-driven development.
6. Verify each claim with fresh evidence before reporting completion.