Markdown Brain

A Markdown-first knowledge system for Obsidian and AI agents such as Hermes and OpenClaw. Keep your notes readable, portable, and under your control while giving an agent enough structure to search and update them safely.

Your notes probably started simple: a few folders, some links, maybe a template. Then the vault grew.

Now the same project appears under three names. Old decisions sit next to current plans with no indication of which one still applies. Index pages drift out of date. Search returns too much. An AI assistant can read the files, but it has no reliable way to tell current truth from historical evidence, and broad rewrites can damage the parts you wrote by hand.

Markdown Brain adds a small, explicit operating system around ordinary Markdown. It gives notes a consistent contract, separates current state from history, generates disposable navigation, and validates the vault after changes. Markdown remains the source of truth. There is no required database, embedding service, or proprietary storage layer.

Is this only for Hermes?

No. The maintenance tool is a standalone Python program, and the notes remain ordinary Markdown. You can use it manually, from Obsidian, or through any agent that can read files and run Python.

The repository also follows the common SKILL.md package layout:

• Hermes Agent can load the repository as a reusable skill. Hermes is the primary integration and the one used to develop this project.
• OpenClaw also loads skills from directories containing a SKILL.md file. Its official CLI can install this repository directly from Git.
• Other agents can use the same operating rules if they support SKILL.md skills. If they do not, clone the repository and give the agent SKILL.md as its instructions while letting it call the Python tool.

The agent integration supplies the judgment and safe workflow. scripts/brain_maintain.py supplies deterministic normalization, indexing, search, validation, stale-note reporting, and backups. Neither part requires your Markdown to live inside Hermes or OpenClaw.

See the official Hermes skills documentation and OpenClaw skills documentation for their respective loading rules.

Why use this instead of a typical Markdown brain?

A normal folder of .md files gives you portable storage. Markdown Brain keeps that portability and adds a maintenance contract that both people and agents can follow.

Typical Markdown folder	Markdown Brain
Each note can use different metadata and status values.	Managed notes share a small schema while preserving custom fields.
Current plans and old history often end up mixed together.	The upper deck holds current truth; the lower deck preserves dated history and evidence.
Index pages are maintained by hand and eventually drift.	Home pages, area indexes, manifests, and health reports are generated from source notes.
Search often depends on filenames or broad full-text matches.	Search includes titles, aliases, tags, summaries, and content through a rebuildable manifest.
An agent may create duplicates or rewrite an entire file.	The skill requires search-before-create, read-before-write, targeted edits, and validation after changes.
Broken links, stale active notes, and duplicate titles accumulate quietly.	Validation and stale-note reports surface those problems without silently deleting or inventing content.
Automation may make a database or vector store authoritative.	Markdown remains canonical; generated files can be deleted and rebuilt.

If a small Markdown folder already works well, you may not need this. Markdown Brain becomes useful when the vault has enough projects, decisions, history, or agent activity that consistency and safe maintenance are no longer automatic.

The problem it solves

A folder of Markdown files is easy to start and hard to maintain at scale.

Common failure modes include:

• Metadata fields and status values drift between notes.
• Meeting history gets mixed into the current project state.
• Hand-maintained indexes quietly become wrong.
• Agents create duplicate notes because they do not search first.
• Agents rewrite whole files when only one section needs to change.
• Broken links and stale active notes accumulate unnoticed.
• A database or vector store becomes authoritative, making the vault harder to inspect or move.
• Consultants and agencies accidentally mix knowledge from different clients.

Markdown Brain addresses those problems without replacing your existing Markdown workflow.

How it works

Markdown notes (canonical and human-readable)
        |
        |-- frontmatter: identity, type, status, dates, tags, aliases
        |-- upper deck: concise current truth
        `-- lower deck: dated history and evidence
        |
        v
Generated Home, indexes, manifest, and health report
        |
        v
Agent or human -> search -> targeted read -> safe update -> validation

The generated files are views, not a second source of truth. Delete them and run the index command to rebuild them from the notes.

1. A consistent note contract

Managed notes use a small core schema:

---
brain_schema: 1
title: Customer onboarding redesign
type: project
status: active
created: 2026-07-01
updated: 2026-07-21
area: Product
tags: [onboarding, ux]
aliases: [Onboarding v2]
---

You can keep custom fields. The normalizer adds missing managed fields without deleting metadata it does not recognize.

2. Current truth stays separate from history

Evolving notes can use two explicit sections.

# Customer onboarding redesign

<!-- brain:upper-deck -->

## Current state

The team approved the three-step onboarding flow. Engineering is waiting for final copy.

## Decisions

- Email verification happens after workspace creation.

## Open loops

- [ ] Approve the welcome-screen copy.

<!-- brain:lower-deck -->

---

## History and evidence

### 2026-07-18 - Design review

**Source:** Product and design meeting

- The five-step proposal was rejected because too many users abandoned setup.
- The team selected the three-step alternative.

The upper deck is what an agent should read first when asked, "Where does this project stand?" The lower deck explains how the project got there.

3. Navigation is generated from source notes

The maintenance tool can build:

• Home.md for vault-wide navigation and recent updates
• <Area>/_Index.md files for area-level note catalogs
• generated status tables inside existing content-index.md notes
• _System/brain-manifest.json for deterministic routing and search
• _System/health-report.md for metadata, deck, stale-note, duplicate-title, and wikilink findings

Generated Markdown is confined to explicit markers:

<!-- markdown-brain:auto:start -->
...generated content...
<!-- markdown-brain:auto:end -->

Manual prose outside those markers stays untouched.

Where Markdown Brain helps

Markdown Brain is useful when you have more knowledge than a simple folder search can comfortably manage, but you still want plain files.

Personal knowledge and research

Keep references, decisions, ideas, and long-running research connected without forcing every note into a database. Search aliases and summaries, then inspect the evidence behind a conclusion.

Project and product work

Ask for the current state of a project without loading months of meeting notes. New evidence goes into history; the current-state summary gets reconciled rather than contradicted.

Consulting and agency work

Maintain a separate vault for each client. This gives each client an explicit trust boundary and prevents one client's generated indexes or search results from leaking into another's work.

Content operations

Track drafts and approvals in source-note frontmatter while generating a content catalog from those notes. The note owns its status; the index only displays it.

Ministry, nonprofit, and community work

Organize sermon research, meeting outcomes, programs, people, and recurring decisions in a format that remains readable in Obsidian and accessible to an agent.

Teams adopting AI agents

Give an agent rules for searching before creating, reading before writing, preserving unknown content, and validating after every knowledge change.

Example workflows

Find before creating

Before adding a new onboarding note, search titles, aliases, tags, summaries, and content:

python3 scripts/brain_maintain.py search /path/to/vault "onboarding redesign"

If the subject already exists, update that note instead of creating another version of the same idea.

Update a project after a meeting

1. Read the whole project note.
2. Add the meeting outcome to the lower deck with its date and source.
3. Reconcile the upper deck so it reflects the new current state.
4. Update the updated property.
5. Regenerate indexes and validate the vault.

This keeps the project summary accurate without throwing away the decision trail.

Review stale knowledge

python3 scripts/brain_maintain.py stale /path/to/vault --days 60

This surfaces active notes that may need review. It does not automatically archive or delete them.

Check vault health

python3 scripts/brain_maintain.py validate /path/to/vault

Validation reports problems instead of silently "fixing" ambiguous content. Schema errors and duplicate titles need attention; some broken conceptual links may be legitimate cleanup work rather than reasons to generate empty notes.

Installation

Requirements

• Python 3.10 or newer
• A directory of Markdown files
• Obsidian is optional but fully compatible
• An AI agent is optional unless you want the reusable skill behavior

The maintenance tool uses only the Python standard library. There is no pip install step.

Fastest install for Hermes Agent

Clone the complete repository into the Hermes skills directory:

mkdir -p ~/.hermes/skills/note-taking && \
git clone https://github.com/arnoldgamboa/markdown-brain.git \
  ~/.hermes/skills/note-taking/markdown-brain

Then confirm that Hermes sees it:

hermes skills list
hermes -s markdown-brain

If you use a named profile, a custom HERMES_HOME, or an external skill directory, clone it into that profile or configured directory instead. Keep the complete repository together because the skill refers to its scripts, templates, and reference files.

Fastest install for OpenClaw

OpenClaw can install this repository directly from Git. To make it available to every local OpenClaw agent:

openclaw skills install git:arnoldgamboa/markdown-brain@main --global
openclaw skills info markdown-brain
openclaw skills check

Remove --global to install it only in the active workspace. According to OpenClaw's official loading rules, workspace installs go into <workspace>/skills, while global managed skills go into ~/.openclaw/skills.

See the official OpenClaw skills reference and openclaw skills CLI reference.

Install with a prompt

If your agent can use the terminal and local files, paste this prompt:

Install Markdown Brain from https://github.com/arnoldgamboa/markdown-brain
as a reusable skill for this agent. Put the complete repository in this
agent's supported skills directory so SKILL.md, scripts, templates, and
references stay together. Verify that the skill is discoverable, then run:

python3 -B scripts/test_brain_maintain.py

Do not modify my notes yet. Ask me for my vault path and a backup location.
Create a backup outside the vault, run normalize without --apply, and show me
the preview before making bulk changes.

An agent without a formal skill system can still follow the same prompt: clone the repository anywhere, read SKILL.md as the operating instructions, and run the Python script from the cloned directory.

Use the maintenance tool without an agent

git clone https://github.com/arnoldgamboa/markdown-brain.git
cd markdown-brain
python3 -B scripts/test_brain_maintain.py

No Obsidian plugin is required. Point the script at any compatible Markdown directory.

First run on an existing vault

Back up the vault before a bulk migration.

BRAIN_TOOL="/path/to/markdown-brain/scripts/brain_maintain.py"
VAULT="/path/to/your-vault"
BACKUPS="/path/outside/your-vault/backups"

# 1. Create a compressed backup and checksum.
python3 "$BRAIN_TOOL" backup "$VAULT" --output-dir "$BACKUPS"

# 2. Preview normalization. This does not write changes.
python3 "$BRAIN_TOOL" normalize "$VAULT"

# 3. Apply additive normalization after reviewing the preview.
python3 "$BRAIN_TOOL" normalize "$VAULT" --apply

# 4. Build navigation, manifest, and health report.
python3 "$BRAIN_TOOL" index "$VAULT"

# 5. Validate the result.
python3 "$BRAIN_TOOL" validate "$VAULT"

# 6. Confirm a representative search works.
python3 "$BRAIN_TOOL" search "$VAULT" "a project or subject you know"

Run normalization a second time after migration. A stable vault should report no further changes.

Detailed bootstrap, migration, and rollback instructions are in references/operations.md. The full metadata contract is in references/schema.md.

Starting a new vault

1. Create your domain or area folders.
2. Copy the templates you need from templates/.
3. Create notes with the required frontmatter.
4. Use decks for evolving knowledge such as projects, meetings, decisions, clients, people, and ideas.
5. Keep long-form artifacts, such as essays or manuscripts, as normal documents unless they genuinely need a history layer.
6. Run index and validate after the initial notes are in place.

A practical starting structure might look like this:

My-Vault/
├── 00 - Inbox/
├── 10 - Personal/
├── 20 - Work/
├── 30 - Projects/
├── 50 - Resources/
└── _System/

The exact folder names are yours. Markdown Brain derives navigation from the vault rather than requiring this specific layout.

What the tool changes

The normalizer and indexer are deliberately conservative:

• They add missing managed metadata.
• They preserve custom frontmatter and manual body content.
• They can add deck scaffolding to suitable evolving notes.
• They replace only bounded generated blocks in Markdown indexes.
• They write rebuildable system artifacts under _System/.

They do not silently rename notes, delete notes, erase history, or make a database authoritative.

Safety and privacy

• Keep credentials and secrets out of notes. Redact them during ingestion.
• Back up before bulk normalization.
• Read before writing and prefer targeted section edits.
• Keep client vaults separate.
• Treat generated manifests and indexes as disposable.
• Review validation findings instead of generating speculative notes to satisfy every link.
• Do not publish a live personal or client vault with this skill repository.

Tradeoffs and limitations

Markdown Brain favors transparency over automation at any cost.

• It does not provide real-time collaboration or merge conflict resolution.
• It does not encrypt your vault.
• It does not replace a task manager, CRM, or document database.
• Search is deterministic text and metadata search, not semantic retrieval.
• Large vaults may eventually benefit from a disposable full-text or vector index.
• The deck model is useful for evolving knowledge, not every Markdown document.
• Validation can identify ambiguous or broken structures, but a human still decides what the correct knowledge should be.

If you need a hosted knowledge graph with transactional workflows and permissions, this project may be too small. If you want portable notes with enough structure for reliable agent use, it may be a good fit.

Repository guide

• SKILL.md: behavior and safety rules for compatible AI agents
• references/schema.md: frontmatter schema and note types
• references/operations.md: bootstrap, migration, maintenance, and rollback
• templates/: starter note templates
• scripts/brain_maintain.py: deterministic maintenance CLI
• scripts/test_brain_maintain.py: standard-library test suite

Running the tests

python3 -B scripts/test_brain_maintain.py

The test suite covers additive normalization, idempotency, generated indexes, search, validation warnings, and backup integrity.

Contributing

Issues and pull requests are welcome.

Good contributions include:

• reproducible fixes for vaults with unusual but valid Markdown
• additional tests for preservation and idempotency
• clearer migration or rollback documentation
• improvements to deterministic search and health reporting
• templates that remain generic and preserve the core schema

Please use sanitized example notes. Do not attach personal, pastoral, company, or client vaults to an issue.

Before opening a pull request:

python3 -B scripts/test_brain_maintain.py

Changes to normalization or indexing should remain deterministic, idempotent, and additive unless a breaking change is clearly documented.

Community and support

Markdown Brain is maintained as an open-source project, not as a published copy of anyone's private vault.

• Read CONTRIBUTING.md before proposing code or documentation changes.
• Use the bug report for reproducible problems.
• Use the feature request for focused proposals.
• Follow the CODE_OF_CONDUCT.md when participating.
• Report vulnerabilities privately according to SECURITY.md.
• Learn more about the maintainer at arnold.gamboa.ph.

Pull requests run the standard-library test suite on Python 3.10, 3.11, 3.12, and 3.13.

License

Markdown Brain is available under the MIT License.