🔎 Brain Search — a bounded retriever for an Obsidian vault

A Claude skill that lets Claude search and orient itself inside a large Obsidian "second brain" — without dumping the whole vault into context. It returns a bounded, ranked slice (never a firehose), so it stays fast and useful no matter how big the vault grows.

English · Français

---

Table of contents

• Why this exists
• The three modes
• Prerequisites
• Installation
• Usage
• Repository structure
• FAQ
• Contributing
• License & credits

---

Why this exists

As an Obsidian vault grows, "give the AI the whole map" stops working: a flat index of thousands of notes is too big to read and dilutes attention while burning context budget. What actually helps an LLM reason is not all the context — it's the right small slice.

brain-search is built on one rule: output is always bounded by the query or the structure, never by the vault size. A single dependency-free bash script (recomputed on the fly so it's always fresh) gives Claude five bounded views:

• 🗺️ map — a constant-size bird's-eye view (areas → note count → MOC link).
• 🔎 find — a ranked retriever that fuses titles, tags, headings and content, and returns the top 20 hits already annotated (type/status/tags) with a snippet. This is the part that beats raw grep: the canonical note floats to the top, and you know what to open without fumbling.
• 🕒 recent — notes changed in the last N days, newest first (catch-up / post-/compact).
• 📦 gather — concatenates the bodies of the top-N matches into one ready-to-reason block.
• 🧹 audit — surfaces folders missing a hub, something neither grep nor your MOCs can self-report.

It is the companion to the second-brain skill: you search with brain-search, you read/write with second-brain.

---

The five modes

A quick reference — what each gives you and when to reach for it:

Mode	What it gives you	When to use it
map	The whole vault's shape: areas, note counts, each area's MOC link — constant size, even for a huge vault.	Starting a broad task: know what topics exist and where to enter, without reading anything.
find <term>	A ranked top-20 of matching notes (title + tags + headings + content fused), each annotated with type/status/tags + a snippet, canonical note first.	"Where is X?", "Is there a note on Y?", or before writing (to avoid a duplicate). The everyday workhorse.
recent [N]	Notes changed in the last N days (default 14), newest first, with date.	"What changed lately?", catching up after time away, or rehydrating after a /compact.
gather <term>	The full bodies of the 5 most relevant notes, concatenated into one block (frontmatter stripped).	Reason over a whole topic at once — "load everything about Z" — instead of opening notes one by one.
audit	Folders that contain notes but have no README.md hub.	Periodic vault hygiene; keeping the tree navigable as it grows.

Rule of thumb: map to orient → find to locate → gather to load → recent to catch up → audit to tidy. For a raw full-text need find doesn't cover, fall back to grep.

map — orient (constant size)

# 🗺️ Vault — 211 notes, 4 areas

## WorkFlow/ — 117 notes · MOC: [[WorkFlow/README]]
  - Ingénieur DevOps & Cloud/ (45)
  - _Socle commun/ (38)
  ...
## Homelab/ — 69 notes · MOC: [[Homelab/Homelab]]
  - Networking/ (28)
  - Services/ (13)
  ...

find <term> — ranked search (the core)

<term> is a case-insensitive regex (e.g. reverse.proxy, vault|secret). Output is capped at 20:

# 🔎 "credential" — 11 note(s) found

- WorkFlow/.../Git - Configuration.md — Git - Configuration  {workflow, config, git, vcs}
  ↳ A configured credential manager avoids re-entering identifiers on every remote operation.
- WorkFlow/.../Shell WSL/Installation & config.md — Install & config — Shell WSL  [procédure]  {wsl, shell}
  ↳ ## 9. GitHub from WSL (gh, browser, credentials)
- Homelab/.../README.md — 📦 Services  [moc]  {moc, service} ⭐
  ...

The role bonus (hub/MOC ⭐) counts only when the note actually matches the query — so indexes never pollute unrelated searches.

recent [N] — what changed

# 🕒 Recent — notes changed (≤ 14 days), newest first
- Homelab/Services/vaultwarden.md — Vaultwarden  [service]  {service, lxc, secrets}  (2026-06-09)
- ...

gather <term> — aggregate to reason

Takes the 5 most relevant notes (same ranking as find) and concatenates their bodies (frontmatter stripped, 60 lines/note max) into one block — "the request + the relevant notes", loaded at once instead of opening five notes one by one.

audit — hygiene

# 🧹 Audit — note folders without a README hub
- Homelab/Compute/host/proxmox/  (no README hub)
- ...

---

Prerequisites

• Claude Code (CLI, desktop, or IDE) — or any Claude surface that supports Agent Skills.
• bash, awk, find, sort — present on macOS/Linux, in WSL, and in Git-Bash on Windows. No other dependencies.
• An Obsidian vault (or any folder of .md notes). Frontmatter (type, status, tags) and [[wikilinks]] make the output richer, but plain notes work too.

---

Installation

1. Install the skill

macOS / Linux

git clone https://github.com/hess0ul/brain-search.git
cp -r brain-search/brain-search ~/.claude/skills/brain-search

Windows (PowerShell)

git clone https://github.com/hess0ul/brain-search.git
Copy-Item -Recurse brain-search\brain-search $env:USERPROFILE\.claude\skills\brain-search

French version of the skill: copy brain-search/translations/fr/brain-search instead.

2. Point it at your vault

Set the vault root once (or run the script from inside your vault — it defaults to $PWD):

export BRAIN_VAULT="$HOME/Obsidian/MyVault"     # add to your shell rc to persist

3. Verify

bash ~/.claude/skills/brain-search/scripts/brain.sh map

---

Usage

S=~/.claude/skills/brain-search/scripts/brain.sh
bash "$S" map                 # what topics exist + where to enter
bash "$S" find "reverse.proxy" # ranked, annotated hits (top 20)
bash "$S" audit               # folders missing a hub

In a Claude session, just ask — "where is the note about X?", "what do we already have on Y?", "give me the map of the vault" — and Claude runs the right mode, then opens the relevant notes.

---

Repository structure

.
├── README.md                         # you are here (English)
├── README.fr.md                      # French
├── LICENSE                           # MIT
├── CHANGELOG.md
├── brain-search/                     # ← the skill (English, canonical) — install this
│   ├── SKILL.md
│   └── scripts/brain.sh              # map | find | recent | gather | audit
└── translations/
    └── fr/brain-search/              # the skill (French) — same structure

---

FAQ

How is this better than grep? grep -l X gives you a pile of paths to triage by hand. find X ranks them (canonical note first), annotates each with type/status/tags, shows a snippet, and caps the output at 20 — so you know what to open immediately, and the result never grows with the vault.

Does it need an index file or a database? No. It recomputes on every call (~0.4 s on a few hundred notes), so it's always fresh and there's nothing to maintain.

Does it scale to thousands of notes? That's the whole point: every mode returns a bounded slice. map is constant-size; find is capped at 20. (Large-scale orientation is mostly carried by the MOC hierarchy of the second-brain skill — brain-search complements it.)

Where does it read the vault from? $BRAIN_VAULT, or the current directory if that's unset.

---

Contributing

Issues and PRs welcome — ranking tweaks, an --orphans audit, multi-term AND search, and translations especially. Keep every mode bounded (no firehose) — that's the core invariant.

---

License & credits

MIT © 2026 hess0ul.

• Companion to the second-brain skill.
• Built for Claude Code Agent Skills. Pure bash, no dependencies.