Skip to content
Hermes Brain: An Obsidian Second Brain Your AI Agent Can't Forget
DWG-42175
MOD-09 · Self Hosting

Hermes Brain: An Obsidian Second Brain Your AI Agent Can't Forget

An open-source vault template that archives every Hermes/OpenClaw session, equips multi-harness agent skills, and lets you approve what becomes memory

Siddh Mistry Siddh Mistry October 30, 2026 Updated November 02, 2026 8 min read
Designer
Siddh Mistry
Module
MOD-09 — Self Hosting
Runtime
8 min read
Documentation Length
1753 words / 12391 chars
Revision
REV-I
Version Released
v1.37.0

Hermes Brain graph view


The Problem: Your Agent Remembers Everything, Except When It Matters

In my last post I walked through running OpenClaw on Hermes on my own hardware. It works well, but after weeks of daily usage, two fundamental pain points kept surfacing:

  1. Context lived in chat logs I would never scroll back through. A critical architectural decision made during a 2:00 AM debugging session three weeks ago was effectively lost.
  2. Agent memory was an opaque black box. Whatever the agent decided to remember, it silently stashed away. I had no easy way to inspect it, verify it, or say: “no, that assumption is wrong.”

So I built Hermes Brain: an Obsidian vault template that sits next to your agent and turns every session into plain, searchable markdown, with a human-in-the-loop review step before anything becomes permanent memory.

It is free, MIT-licensed, and lives here: github.com/mistrysiddh/hermes-brain-template.

Since its initial release, the project has grown through 40+ releases into a full-fledged agent intelligence system (currently v1.37.0), featuring 15+ multi-harness agent skills, offline semantic search, cognitive reflection cycles, a decision log, and automated vault curation.


How It Works: The 3-Stage Memory Pipeline

The foundation of Hermes Brain is a disciplined three-stage progression:

1
2
3
04-Archives/Daily/YYYY/MM/DD/*.md  →  04-Archives/Memory-Review/*.md  →  Hermes MEMORY.md / USER.md
(raw session archive) (staged candidate facts, (durable, injected into
human-reviewed) every turn, promoted by hand)
  1. Archive. An automated background job dumps every Hermes session to markdown. Transcripts are deduplicated, scrubbed for secrets (API keys, IP addresses, tokens) on the way in, and indexed in manifest.jsonl.
  2. Stage. Facts and learnings worth preserving are written as candidates into 04-Archives/Memory-Review/. Nothing auto-promotes to permanent memory without review.
  3. Promote. You review candidates (via Obsidian Kanban boards, or through promote_memory.py --review) and approve the ones you want. Only then do they reach the agent’s durable system prompt memory.

Your agent gets a persistent memory, and you retain the editor’s pen.


What’s Inside the Vault

The vault implements the PARA method (Projects, Areas, Resources, Archives) augmented with a _System/ automation core:

Folder What lives there
01-Projects/ Active projects, Architecture Decision Records (ADR/), and Dataview project databases (Projects.base)
02-Areas/ Human alignment profile (User-Profile.md), installed skills catalog, team rosters, and the [[Personality-Judgment-Framework]]
03-Resources/ Maps of Content (AI/ML, Cybersecurity, Agentic Architecture, Tech Stack), technical guides, deep research notes, plus Decisions/, Principles/ and Axioms.md
04-Archives/ Daily session timeline, chat correlations, memory review Kanban staging, audit reports, and Cron/ logs and cron-run sessions (kept separate from real chats)
_System/ Note templates, visual architecture canvases (Memory-Pipeline.canvas), and cross-platform automation scripts

It comes preconfigured with Dataview, Kanban, Local REST API, and Smart Connections plugins, two dark themes (Tokyo Night and Nemoclaw), and a unified Dashboard.md tracking active projects, token telemetry, archiver health, and skill analytics.

It also bundles an MCP Server (hermes_brain_mcp.py) that exposes tools like vault_search, read_note, and stage_memory_candidate directly to local and remote LLM agents.


Decisions, Principles & Axioms

Added in v1.24, this is a knowledge layer built for how agents actually reason, not just search:

  • Decisions/: log hard-to-reverse choices with a mandatory Alternatives Rejected section. It is the most valuable part, because it stops your agent re-proposing an idea you already considered and rejected months ago.
  • Principles/: standing rules distilled from repeated decisions (“we always do X”, not just “we chose X on this date”).
  • Axioms.md: the few foundational beliefs everything else derives from. It ships empty on purpose, because these should be yours.

Notes link to each other (derived_from, evidenced_by), so an agent can trace why a rule exists.


Multi-Harness Agent Skills & GitHub Agents

Hermes Brain is no longer just a passive note repository. It ships with a suite of multi-harness agent skills (AGENTS.md) designed to run as standalone CLI tools or as GitHub Agents (.github/agents/ / @hermes-brain <skill>):

  • 🔍 self-critique (self_critique.py): Runs comprehensive vault health audits — flagging broken wikilinks, missing YAML frontmatter, path inconsistencies, and secret leaks.
  • 🛠️ auto-remediate (auto_remediate.py): Safely and automatically applies fixes for issues surfaced by self-critique.
  • 🧬 knowledge-synthesis (knowledge_synthesis.py): Performs BASB and Zettelkasten knowledge consolidation — extracting atomic notes, progressive summaries, Maps of Content (MOCs), and bidirectional backlinks.
  • 🌙 dream-cycle (dream_cycle.py): Autonomous cognitive reflection — connects disparate sessions, identifies knowledge drift, drafts ADRs, and prepares memory candidates.
  • 📡 radar (radar.py): Standing surveillance on blogs, news feeds, and arXiv papers, producing curated daily/weekly intelligence digests.
  • 📊 metrics (metrics.py): Generates timestamped snapshots of vault growth, link density, tag distribution, and stale content.
  • 🎯 quiz (quiz.py): Generates active-recall questions directly from your notes to reinforce learned concepts.
  • 🧠 converse-learn (converse_learn.py): Reviews sessions and extracts learnings into memory, lessons, skills, or project docs, confirmation-first.
  • 🗂️ zknote (zknote.py): Zettelkasten workflow with fleeting and literature notes, MOC building, note splitting, and orphan and weak-link detection.
  • 🧹 merge-duplicate (merge_duplicate.py): Finds near-duplicate notes (Jaccard similarity), flags divisive topics instead of auto-merging, and can atomize large notes by heading.
  • 🧭 unstuck-decide (unstuck_decide.py): Structured antidotes for roadblocks, plus pros/cons, 2x2 matrix, and weighted-criteria decision modes.
  • 📝 auto-changelog (auto_changelog.py): Builds a Keep-a-Changelog file from conventional commits.
  • 👋 onboarding (onboarding.py): Conversational setup of your profile, integrations, and PARA structure check.
  • ✍️ prompt-quality (prompt_quality.py): Scores prompts 0-100 on clarity, specificity, actionability, structure, and completeness, with improvement tips.
  • 🔁 self-improvement (self_improvement_agent.py): Routes grunt work to small models and orchestration to large ones, with a self-evaluation loop.
  • 🔬 pm-skills (pm_skills_examination.py) and sota-scan (sota_scan.py): Compare skill-pack repos, and benchmark this repo against comparators with a ranked gap list.
  • 🤖 Specialized Subagents (subagents.py): Decomposed roles (researcher, graph-analyst, curator, ingestor, linker, reviewer) that execute focused vault tasks without overloading context.

Every skill defaults to --dry-run and only writes with --apply/--save, so you stay the approver here too.


Local Semantic Search & Intelligent Analytics

Unlike cloud-dependent memory tools, Hermes Brain emphasizes local privacy:

  • Local Vector Search (semantic_search.py): Uses sentence-transformers/all-MiniLM-L6-v2 (a lightweight 22MB CPU model) to build an incremental semantic index over your sessions and notes. It runs entirely offline with zero cloud API costs, accessible via CLI or an embedded HTTP endpoint powering natural-language queries directly in Dashboard.md.
  • Automated Topic Tagging (session_tagger.py): Extracts topics using lightweight pattern matching, creating global tag clouds and tracking 14-day topic trends.
  • Predictive Skill Forecasting (skill_forecast.py): Analyzes vault activity logs alongside your installed skill index to suggest what skills, tools, or workflows your agent should acquire next.

Why Not Just Use a Vector-DB Memory Service?

Feature Hermes Brain Raw Chat Logs Vector-DB Memory (e.g. Mem0) Generic Obsidian
Human review before “memory” ✅ Staged candidate review ❌ Lost in logs ❌ Auto-embedded, opaque N/A
Readable without special tooling ✅ Pure Markdown ✅ Unstructured ❌ Requires vendor UI/API ✅
No vendor lock-in ✅ Pure Git repo ✅ ❌ Proprietary ✅
Multi-harness agent skills ✅ 15+ built-in skills ❌ ❌ ❌
Offline semantic search ✅ 22MB local model ❌ Varies Optional plugin
Out-of-the-box agent wiring ✅ MCP + Hermes cron N/A ❌ Custom setup ❌

If you want completely hands-off semantic recall, a hosted vector database works. If you want to see, verify, and govern what your AI knows in files you control forever, Hermes Brain is built for you.


Installing & Verifying in Under 2 Minutes

Pick whichever method fits your setup:

Option 1: One-Line Terminal Install (Linux, macOS, WSL)

1
curl -fsSL https://raw.githubusercontent.com/mistrysiddh/hermes-brain-template/main/_System/Scripts/Installers/install.sh | bash

(Windows PowerShell equivalent: irm https://raw.githubusercontent.com/mistrysiddh/hermes-brain-template/main/_System/Scripts/Installers/install.ps1 | iex)

Option 2: Clone & Local Setup

1
2
3
git clone https://github.com/mistrysiddh/hermes-brain-template.git my-second-brain
cd my-second-brain
./_System/Scripts/Installers/install.sh

Option 3: Instant 60-Second Verification (No Hermes Needed)

Verify the bundled machinery right after installation:

1
2
3
4
5
6
# 1. Self-test the bundled MCP server
python _System/Scripts/hermes_brain_mcp.py --test
# Output ends with: "All hermes-brain-mcp self-tests PASSED"

# 2. Check pending candidate memory facts (prints [] on fresh install)
python _System/Scripts/promote_memory.py --list

The installer also runs verify_install automatically, checking the folder structure, required plugins, MCP server, memory pipeline, and User-Profile.md integrity.

Grow Into It: Opt-in Feature Packs

_System/Scripts/features/ lets you adopt the template gradually: beginner (archiving and memory promotion, the default), analyst (semantic search, tagging, dashboards), poweruser (forecasting, audit, drift checks), and experimental.

Other Ways to Try

  • One paste into Hermes (INSTALL_PROMPT.md): Copy the master prompt directly into your Hermes chat to install the vault and schedule the hourly cron job automatically.
  • Scratch Vault (try.sh / try.ps1): Spins up a throwaway temporary vault so you can experiment without modifying your live environment.
  • GitHub Codespaces: One-click zero-install browser environment using the GitHub Codespaces template badge.

Privacy & Operational Safety

  • Structure Only: The repository contains no private chat history, API keys, or personal data. A GitHub Action workflow (personal-data-guard) actively blocks accidental secrets.
  • Git-Ignored Personal Paths: Daily/, Memory-Review/, .smart-env/, and plugin data.json files are excluded by default.
  • Safe Template Updates: Running update.sh / update.ps1 pulls the latest code, templates, and skills while strictly preserving your User-Profile.md and personal notes.
  • Local Git Safety Net: session_git_snapshot.py auto-commits a local snapshot at session end (never pushes), and refuses to commit if it spots API keys or private keys. Wire it to on_session_end as a cheap undo button for bad multi-file agent edits.
  • Template Drift Checker: template_drift.py compares your vault to the latest release by SHA256 and marks each file safe-to-update, customized, outdated, or missing.
  • Process Concurrency Locking: The session archiver uses exclusive .hourly_archive.lock protection so background crons and on-demand archive_now.py runs never corrupt manifest.jsonl.

Do I Need Hermes or a Local LLM?

  • No local LLM required: The core vault, archiving engine, memory pipeline, and multi-harness skills run fast on pure Python. Only the optional trend-digest scripts use Ollama or sentence-transformers.
  • No Hermes required for the vault: The PARA architecture, templates, Dataview queries, and Kanban boards work as a standalone Obsidian second brain. Hermes or OpenClaw is only needed when you want automated transcript feeds.

Give your agent a memory you can actually inspect, govern, and trust.

§ 05 SECTION

Related Documents

Other specifications filed under the same module.

§ 06 SECTION

Field Notes & Comments

Session-local discussion — comments here are not persisted to a server in this build.

Loading discussion module…