This release transforms vault navigation from a token-heavy operation into an efficient, metadata-driven system. 90-99% token reduction on common queries through intelligent API design.

📊 Performance Impact

Query Type	Before	After	Savings
”Find most recent note”	60,300 tokens	450 tokens	99.3% ⭐
“Find largest files”	30,300 tokens	850 tokens	97.2%
“Browse folder recursively”	144,000 tokens	2,400 tokens	98.3%

Real-world impact: For users making 10 time-based queries/day, this saves ~~9M tokens/month (~~$30-90/month at GPT-4 pricing).

✨ New Features

1. Metadata Support (Opt-In)

Added include_metadata flag to existing tools for filesystem attribute access without content retrieval.

Enhanced Tools:

list_obsidian_notes(include_metadata=False)
search_obsidian_notes(query, include_metadata=False, sort_by=None)

Metadata Fields:

modified: ISO timestamp of last modification
created: ISO timestamp of creation (cross-platform compatible)
size: File size in bytes

Token Cost:

Without metadata: ~15-20 tokens per note
With metadata: ~40-50 tokens per note
Overhead: ~25-30 tokens per note

Why It’s Worth It:

Retrieving 1 note to check timestamp: ~3,000 tokens
Metadata for 10 notes: ~250 tokens
Break-even: Metadata pays for itself after checking just 1 note

2. Smart Sorting

Added sort_by parameter to leverage metadata efficiently.

Options:

"modified" - Sort by modification time (newest first)
"created" - Sort by creation time
"size" - Sort by file size (largest first)
"name" - Alphabetical (default)

Value: Eliminates need for client-side sorting or retrieving multiple notes to compare.

3. Folder-Specific Operations

New list_notes_in_folder() tool for targeted folder queries.

list_notes_in_folder(
    folder_path="Mental Health",
    vault="nader",
    recursive=False,
    include_metadata=True,
    sort_by="modified"
)

Efficiency:

Old approach: List entire vault (1000 notes) → filter client-side → retrieve for metadata
New approach: List only folder contents (50 notes) with metadata already included
60-98% more efficient - scales with folder size, not vault size

4. Note Move/Rename with Backlink Updates

New move_obsidian_note() tool for vault refactoring.

move_obsidian_note(
    old_title="Mental Health/Old Name",
    new_title="Archive/New Name",
    update_links=True  # Default: update all backlinks
)

Features:

Handles rename, move, or combined operations
Updates wikilinks: [[old]] → [[new]]
Updates markdown links: [text](old.md) → [text](new.md)
Preserves aliases: [[old|alias]] → [[new|alias]]
Auto-creates parent directories
Returns links_updated count for verification

Safety:

Error handling for conflicts (destination exists)
No partial operations (atomic moves)
Vault integrity maintained

🔧 Implementation Details

New Helper Functions

Metadata Extraction:

def get_note_metadata(note_path: Path) -> dict[str, Any]:
    """Extract filesystem metadata in a cross-platform friendly way."""
    # Handles macOS/Windows/Linux differences in creation time

Folder Operations:

def resolve_folder_path(vault: VaultMetadata, folder_path: str) -> Path:
    """Resolve folder path with sandbox constraints."""
 
def list_notes_in_folder_core(
    vault: VaultMetadata,
    folder_path: str,
    recursive: bool,
    include_metadata: bool,
    sort_by: str
) -> dict[str, Any]:
    """Core implementation for folder-specific listing."""

Move/Rename:

def move_note(
    old_title: str,
    new_title: str,
    vault: VaultMetadata,
    update_links: bool
) -> dict[str, Any]:
    """Move/rename note with validation."""
 
def _update_backlinks(
    vault: VaultMetadata,
    old_title: str,
    new_title: str
) -> int:
    """Update all references to moved note."""

Updated Helper Functions

Extended with metadata support:

list_notes(vault, include_metadata=False)
search_notes(query, vault, include_metadata=False, sort_by=None)

New MCP Tools

list_notes_in_folder() - Folder-specific listing with metadata
move_obsidian_note() - Move/rename with backlink updates

Updated MCP Tools

Now support metadata:

list_obsidian_notes(vault, include_metadata)
search_obsidian_notes(query, vault, include_metadata, sort_by)

🧪 Test Results

v1.3 Testing

Metadata & Sorting

✅ Most recent note in vault (14 notes): 660 tokens vs ~42,000 tokens (98.4% savings)
✅ Largest LLM notes (15 matches): 850 tokens vs ~30,000 tokens (97.2% savings)
✅ Recursive folder listing (47 notes): 2,382 tokens vs ~144,000 tokens (98.3% savings)
✅ Backward compatibility (no metadata): Identical performance to v1.2

Move/Rename Operations

✅ Simple rename (same folder): Updated 2 backlinks successfully
✅ Move to new folder: Created folder automatically, updated 2 backlinks
✅ Combined move + rename: Both operations successful, 2 backlinks updated
✅ Error handling: Correctly prevented overwriting existing note

Link Format Coverage:

✅ Wikilinks: [[note]]
✅ Aliased wikilinks: [[note|alias]]
✅ Markdown links: [text](note.md)

📐 Design Philosophy

1. Opt-In Overhead

include_metadata=False by default ensures zero breaking changes and zero cost increase for existing workflows.

2. Separation of Concerns

Metadata (timestamps, size) vs. content (markdown body). Don’t retrieve content to access filesystem attributes.

3. Use-Case Driven

Optimized for actual query patterns observed in real usage:

“Find most recent note” (temporal filtering)
“Find largest files” (size-based filtering)
“Browse specific folder” (spatial navigation)

4. YAGNI Principle

Deliberately chose NOT to implement:

list_folders() - Folder structure visible in note paths
get_folder_stats() - Can derive from list_notes_in_folder() results

Additional tools only add value if they solve problems the existing tools can’t. Ship lean, iterate based on real feedback.

💡 Key Architectural Insights

Why This Works

Traditional Pattern:

List All → Filter Client-Side → Retrieve Multiple → Compare → Answer
Cost: 60,000+ tokens

New Pattern:

List with Metadata (sorted) → Answer
Cost: 450 tokens

By moving sorting and filtering to the metadata layer, we eliminate 99% of content retrieval operations for time/size-based queries.

Token Math

Metadata overhead per note: ~25-30 tokens
Cost to retrieve 1 note for timestamp: ~3,000 tokens
Break-even: Metadata pays for itself if you’d check even 1 note’s timestamp

Most time-based queries require checking 3-10+ notes → Metadata is 12-40× more efficient

🚀 Migration Guide

Existing Code (No Changes Required)

All existing tool calls work identically:

# These still work exactly as before
list_obsidian_notes()
search_obsidian_notes("Python")

New Capabilities

Time-based queries:

# Old way: Retrieve all notes to check dates
list_obsidian_notes()  # → Get paths
for note in notes:
    retrieve_obsidian_note(note)  # Check modification time
# Cost: 60,000+ tokens
 
# New way: Metadata + sorting
list_obsidian_notes(include_metadata=True, sort_by="modified")
# Cost: 450 tokens (first result is most recent)

Folder-specific queries:

# Old way: List entire vault, filter client-side
list_obsidian_notes()  # → 1000 notes
# Filter for "Mental Health" folder client-side
# Cost: ~15,000 tokens
 
# New way: Folder-specific listing
list_notes_in_folder("Mental Health", include_metadata=True)
# Cost: ~500 tokens (only 50 notes in folder)

Vault refactoring:

# New capability: Safe rename/move with backlink updates
move_obsidian_note(
    old_title="Projects/Old Name",
    new_title="Archive/New Name",
    update_links=True
)
# Returns: {"links_updated": 5, "status": "moved"}

📝 Documentation Updates

Added metadata usage examples to tool docstrings
Updated AGENTS.md with token optimization strategies
Added real-world test results to README
Created comprehensive token savings analysis

🎯 Future Considerations

Potential v1.4 Features (only if demand emerges):

Frontmatter metadata extraction (custom YAML fields)
Tag-based filtering (if Obsidian tags are parsed)
Content-length previews (first N characters without full retrieval)
Batch operations (move multiple notes atomically)

Philosophy: Add features when users hit real limitations, not speculatively.

📊 Bottom Line

v1.3 delivers 90-99% token savings on common queries through intelligent API design focused on real use cases.

The key insight: Don’t make the LLM retrieve content to access filesystem metadata. By separating concerns (metadata vs. content), we enable dramatically more efficient operations without sacrificing functionality or backward compatibility.
Token efficiency isn’t just about cost—it’s about enabling capabilities that were previously impractical.

The Latent Space

Explorer