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

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:
- 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.
- 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 | 04-Archives/Daily/YYYY/MM/DD/*.md → 04-Archives/Memory-Review/*.md → Hermes MEMORY.md / USER.md |
- 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. - Stage. Facts and learnings worth preserving are written as candidates into
04-Archives/Memory-Review/. Nothing auto-promotes to permanent memory without review. - 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) andsota-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): Usessentence-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 inDashboard.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 | git clone https://github.com/mistrysiddh/hermes-brain-template.git my-second-brain |
Option 3: Instant 60-Second Verification (No Hermes Needed)
Verify the bundled machinery right after installation:
1 | # 1. Self-test the bundled MCP server |
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 plugindata.jsonfiles are excluded by default. - Safe Template Updates: Running
update.sh/update.ps1pulls the latest code, templates, and skills while strictly preserving yourUser-Profile.mdand personal notes. - Local Git Safety Net:
session_git_snapshot.pyauto-commits a local snapshot at session end (never pushes), and refuses to commit if it spots API keys or private keys. Wire it toon_session_endas a cheap undo button for bad multi-file agent edits. - Template Drift Checker:
template_drift.pycompares 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.lockprotection so background crons and on-demandarchive_now.pyruns never corruptmanifest.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.
Links & Community
- ⭐ GitHub Repository: github.com/mistrysiddh/hermes-brain-template
- 🌐 Interactive Showcase: mistrysiddh.github.io/hermes-brain-template
- 📺 Install Walkthrough: Watch on YouTube
- 💬 Discussions & Ideas: GitHub Discussions
Give your agent a memory you can actually inspect, govern, and trust.
PHP2Shell: Inside the Worst PHP RCE in Years (CVE-2026-109618 & CVE-2026-109619)
Next DocumentI Built My Own Self-Hosted AI Assistant (No OpenAI Subscription Needed)
Related Documents
Other specifications filed under the same module.
DWG-77201
MOD-09 · Self Hosting
Setting Up WireGuard VPN in 15 Minutes
A fast, practical WireGuard VPN setup guide — server config, client config, and how to actually connect, from scratch in about 15 minutes.
DWG-40538
MOD-09 · Self Hosting
Docker Compose for Homelab Beginners
A practical walkthrough of Docker Compose for homelabbers — a reverse proxy, an app, and a database wired together with one YAML file.
DWG-04592
MOD-09 · Self Hosting
I Built My Own Self-Hosted AI Assistant (No OpenAI Subscription Needed)
A practical walkthrough of building a self-hosted AI assistant using OpenClaw and Hermes — no cloud subscriptions, no vendor lock-in, full control over your data.
Field Notes & Comments
Session-local discussion — comments here are not persisted to a server in this build.
Loading discussion module…