Vault Optimizer Strategist

Performance and storage optimization agent that analyzes, compresses, and restructures Obsidian vaults for maximum speed and minimal disk footprint.

When to Use This Agent

Choose this agent when you need to:

• Diagnose slow vault startup times or laggy search performance
• Identify and compress oversized images and attachments consuming excessive storage
• Archive stale content that has not been accessed or modified in configurable timeframes
• Generate a storage breakdown report showing disk usage by content type and directory

Consider alternatives when:

• You need to improve content quality rather than performance (use Content Curator Pro)
• Your vault is small (under 500 notes) and performance is not a concern

Quick Start

Configuration

Copy
name: vault-optimizer-strategist
type: agent
category: obsidian-ops-team

Example Invocation

Copy
claude agent:invoke vault-optimizer-strategist "Optimize vault performance and generate storage report"

Example Output

=== Vault Optimization Report ===
Vault: ~/KnowledgeBase (2,341 files, 4.7 GB total)

STORAGE BREAKDOWN:
  Markdown notes:  142 MB (3.0%)
  Images (PNG):    2.1 GB (44.7%) → 847 MB after compression
  Images (JPG):    1.4 GB (29.8%) → 1.1 GB after compression
  PDFs:            890 MB (18.9%)
  Other:           168 MB (3.6%)

OVERSIZED FILES: 23 markdown files exceed 1 MB
  - meeting-notes/2025-all-hands-transcript.md (3.4 MB)
  - research/dataset-analysis-raw.md (2.1 MB)

ARCHIVAL CANDIDATES: 187 files unmodified for 730+ days
ESTIMATED SAVINGS: 1.54 GB (32.8% reduction)

PERFORMANCE IMPACT:
  Startup time estimate: 4.2s → 2.8s (33% improvement)
  Search index size: 89 MB → 61 MB

Core Concepts

Optimization Categories Overview

Aspect	Details
Image Compression	Lossless PNG optimization and JPEG quality reduction to 85%
File Archival	Moving files unmodified beyond the staleness threshold to _archive
Index Trimming	Excluding archived and binary files from the search index
Structure Defragmentation	Flattening deeply nested empty directories

Optimization Pipeline Architecture

┌─────────────┐     ┌─────────────┐
│  Storage     │────▶│  Compression│
│  Analyzer    │     │  Engine     │
└─────────────┘     └─────────────┘
        │                   │
        ▼                   ▼
┌─────────────┐     ┌─────────────┐
│  Archival    │────▶│  Index      │
│  Manager     │     │  Rebuilder  │
└─────────────┘     └─────────────┘

Configuration

Parameter	Type	Default	Description
max_md_size_mb	float	1.0	Maximum markdown file size in MB before flagging for splitting
jpeg_quality	integer	85	JPEG compression quality percentage for image optimization
archive_after_days	integer	730	Days without modification before a file becomes an archival candidate
archive_directory	string	"_archive/"	Target directory for archived files
png_lossless	boolean	true	Use lossless compression for PNG files to preserve quality

Best Practices

1. Always Back Up Before Running Optimization Image compression and file archival are destructive operations that cannot be fully reversed. Create a vault snapshot or ensure your vault is under version control before running any optimization pass.

2. Compress Images Incrementally Processing thousands of images simultaneously can take hours and strain system resources. Use batch sizes of 100-200 images per run and validate quality on a sample before processing the full set.

3. Review Archival Candidates Before Moving The staleness threshold is a heuristic, not a guarantee of irrelevance. Some reference documents are rarely modified but frequently consulted. Check access patterns, not just modification dates, before archiving.

4. Split Oversized Markdown Files by Section Files exceeding 1 MB typically contain multiple distinct topics that should be separate notes. Split them along heading boundaries and create a MOC linking the resulting fragments to preserve navigability.

5. Exclude Plugin Data from Optimization Obsidian plugin directories (.obsidian/plugins/) contain configuration and cache files that should not be compressed or archived. Add .obsidian/ to the exclusion list to prevent breaking plugin functionality.

Common Issues

1. Image compression artifacts visible on high-resolution displays The default 85% JPEG quality is a balanced setting, but retina displays may reveal artifacts. Increase jpeg_quality to 92 for vaults where image fidelity is critical, accepting the trade-off of larger file sizes.

2. Archived files still appear in search results After archiving, the search index may retain stale entries. Trigger an index rebuild by restarting Obsidian or running the agent with --rebuild-index to exclude archived files from future search results.

3. Link breakage after moving files to the archive directory The agent updates wikilinks in active notes to point to archived locations, but external tools or bookmarks may still reference the original paths. Consider using Obsidian aliases to maintain backward compatibility.