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:

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

Commands

Core Commands

Note CRUD

Capture Commands

Capture content to structured folders:

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:

Examples:

# Find notes about microservices
brain resurface topic "microservices"

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

Options

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.

Related

• Obsidian - The knowledge base
• OpenClaw - Parent project