ForgeObsidianBrain

Analytics and capture layer for an AI's Obsidian vault. Auto-discovers vaults, manages note CRUD operations, captures fleeting thoughts, resurfaces forgotten knowledge, with fuzzy matching, regex patterns, and case-insensitive search.

Security Note: See SECURITY.md for full security model. This skill operates entirely locally with no network access.

Installation

# Clone or copy to your OpenClaw skills folder
cp -r skills/forge-obsidian-brain ~/.openclaw/workspace/skills/

# Make executable
chmod +x ~/.openclaw/workspace/skills/forge-obsidian-brain/scripts/brain.js

# Set up alias (optional)
alias brain="node ~/.openclaw/workspace/skills/forge-obsidian-brain/scripts/brain.js"

Configuration

Set the default vault path via environment variable:

export OBSIDIAN_VAULT="$HOME/obsidian-vault"

Or specify --vault <path> for any command.

The skill auto-discovers vaults by:

Checking OBSIDIAN_VAULT environment variable
Reading Obsidian's config (~/.config/obsidian/obsidian.json)
Falling back to ~/obsidian-vault

Commands

Core Commands

Command	Description
`discover`	Auto-detect vault location
`config`	Show Obsidian configuration
`init`	Create Brain folder structure
`sync`	Bidirectional sync with memory folder

Note CRUD

Command	Usage
`read <path>`	Read a note
`create <path> [content]`	Create a new note
`update <path> [content]`	Update existing note
`delete <path>`	Delete a note
`list [folder]`	List notes in folder
`search <query>`	Search notes by content (case-insensitive by default)
`search <query> --fuzzy`	Fuzzy search (typo-tolerant)
`search <query> --regex`	Regex pattern search
`exists <path>`	Check if note exists

Capture Commands

Capture content to structured folders:

Command	Description
`capture thought <text>`	Quick thought → `Brain/Thoughts/`
`capture research --url <url> --title <title>`	Research ref → `Brain/Research/`
`capture conversation --source <src> --id <id>`	Chat log → `Brain/Conversations/`

Examples:

# Fleeting thought
brain capture thought "I should refactor the auth module"

# Research capture
brain capture research \
  --url "https://martinfowler.com/articles/microservices.html" \
  --title "Microservices Guide" \
  --text "Key points about service boundaries"

# Conversation log
brain capture conversation \
  --source telegram \
  --id "12345" \
  --text "User asked about distributed systems"

Resurface Commands

Find relevant or neglected notes:

Command	Description
`resurface topic <query>`	Fuzzy search with relevance scoring
`resurface stale --days <n>`	Find notes untouched in N days

Examples:

# Find notes about microservices
brain resurface topic "microservices"

# Find all notes older than 30 days
brain resurface stale --days 30 --limit 20

Options

Flag	Description
`--vault <path>`	Override vault location
`--frontmatter '<json>'`	Add frontmatter to note
`--merge`	Merge instead of replace frontmatter
`--overwrite`	Allow overwriting existing notes
`--limit <n>`	Limit results (default: 5)
`--dry-run`	Preview sync without writing
`--days <n>`	Days threshold for stale search
`--fuzzy`	Use fuzzy matching for search
`--regex`	Use regex pattern for search
`--case-sensitive`	Force case-sensitive search

Workflow Examples

Daily Brain Maintenance

# 1. Initialize structure (once)
brain init

# 2. Capture a thought
brain capture thought "Kubernetes selectors are just labels as queries"

# 3. Save research for later
brain capture research \
  --url "https://distcc.github.io/" \
  --title "Distributed Compilation"

# 4. Check for stale notes to review
brain resurface stale --days 14

# 5. Sync to memory folder
brain sync

Search and Resurface

# Case-insensitive search (new default)
brain search "OpenClaw"

# Fuzzy search - matches "opneclaw" to "openclaw"
brain search "opneclaw" --fuzzy

# Regex search
brain search "^# .* Title" --regex

# Case-sensitive search
brain search "OpenClaw" --case-sensitive

# Resurface topic with fuzzy matching
brain resurface topic distributed --limit 10

# Output:
# {
#   "success": true,
#   "query": "distributed",
#   "totalMatches": 3,
#   "shown": 3,
#   "searchMode": "fuzzy",
#   "results": [
#     { "relativePath": "Brain/Research/...", "relevance": 5, "rank": 1, "matches": [...] },
#     ...
#   ]
# }

Folder Structure

After brain init, your vault gets these folders:

vault/
├── Brain/
│   ├── Thoughts/          # Quick captures
│   ├── Research/          # URL references
│   ├── Conversations/     # Chat logs
│   ├── Entities/          # Structured data
│   └── Relations/         # Connections
└── .obsidian/
    └── ...

Implementation Details

Vault Discovery: Cross-platform (Linux, macOS, Windows)
Note Format: Markdown with YAML frontmatter
Search: Uses grep for fast content matching
Sync: Bidirectional between ~/.openclaw/workspace/memory and vault Inbox
IDs: Base36 timestamps for collision-resistant filenames

Security

This skill operates entirely on the local filesystem with no network access:

No external APIs — No network requests are made
No data exfiltration — All data stays on your machine
No arbitrary code execution — execSync is used only for grep text search with strictly validated input
Plain source code — No obfuscation, all JavaScript is readable

See SECURITY.md for complete security documentation including data access patterns, credentials, and execution details.

Obsidian - The knowledge base
OpenClaw - Parent project