Background Vault Analysis System 🧠✨

A lightweight MCP (Model Context Protocol) server for intelligent, non-invasive analysis of Obsidian vaults. Provides actionable insights, change tracking, and comprehensive reporting to improve your knowledge management practices.

🚀 Features

🔍 Intelligent Vault Analysis

• Non-invasive scanning - Reads your vault without making any changes
• Markdown parsing - Extracts links, tags, frontmatter, and content structure
• Orphan detection - Identifies isolated notes that need connections
• Hub identification - Finds your most connected knowledge centers
• Content metrics - Word counts, link density, and structural analysis

💡 Actionable Insights

• Prioritized recommendations - High/medium/low priority actionable suggestions
• Structural insights - Improve vault organization and connectivity
• Content guidance - Optimize note length and detail
• Productivity tracking - Monitor writing patterns and vault growth

📊 Change Monitoring

• File-level tracking - Monitor additions, modifications, and deletions
• Activity patterns - Identify productive periods and trends
• Evolution analysis - Track how your vault grows over time
• Daily summaries - See recent activity at a glance

📋 Flexible Reporting

• Markdown reports - Human-readable analysis summaries
• JSON exports - Structured data for programmatic use
• CSV formats - Data analysis and spreadsheet integration
• Customizable sections - Focus on what matters to you

🛠️ Installation & Setup

Prerequisites

• Node.js v18 or higher
• Obsidian vault (any size)
• MCP-compatible client (Claude Desktop, etc.)

Quick Start

1. Clone and build:

git clone <repository-url> background-vault-analysis
cd background-vault-analysis
npm install
npm run build

2. Test the system:

node dist/test.js

3. Configure your MCP client:

Add to your MCP configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "background-vault-analysis": {
      "command": "node",
      "args": ["/path/to/background-vault-analysis/dist/index.js"]
    }
  }
}

📋 Available Tools

🔍 scan_vault

Performs comprehensive analysis of your Obsidian vault.

Parameters:

• vaultPath (required) - Path to your Obsidian vault
• mode - Analysis depth: quick, deep, or incremental (default: quick)
• focus - Analysis focus: health, content, relationships, or all (default: all)

Example:

await mcp.call('scan_vault', {
  vaultPath: '/Users/username/Documents/MyVault',
  mode: 'deep',
  focus: 'all'
});

💡 get_insights

Retrieves actionable insights and recommendations.

Parameters:

• vaultPath (required) - Path to your vault
• category - Filter by: orphans, connections, gaps, productivity, or all (default: all)
• timeframe - Time range: day, week, month, or all (default: all)
• priority - Priority filter: high, medium, low, or all (default: all)

Example:

await mcp.call('get_insights', {
  vaultPath: '/Users/username/Documents/MyVault',
  category: 'orphans',
  priority: 'high'
});

📊 track_changes

Monitors vault evolution and activity patterns.

Parameters:

• vaultPath (required) - Path to your vault
• since - Start date for analysis (ISO format, optional)
• granularity - Time resolution: hourly, daily, or weekly (default: daily)

Example:

await mcp.call('track_changes', {
  vaultPath: '/Users/username/Documents/MyVault',
  since: '2024-01-01',
  granularity: 'daily'
});

📋 generate_report

Creates comprehensive analysis reports.

Parameters:

• vaultPath (required) - Path to your vault
• format - Report format: markdown, json, or csv (default: markdown)
• sections - Include sections: ['overview', 'insights', 'metrics', 'changes']
• timeframe - Analysis period (optional)

Example:

await mcp.call('generate_report', {
  vaultPath: '/Users/username/Documents/MyVault',
  format: 'markdown',
  sections: ['overview', 'insights', 'metrics']
});

💾 Data Storage

The system stores analysis data in your home directory:

~/.background-vault-analysis/
├── vaults.json          # Vault registry
├── snapshots.json       # Analysis snapshots
├── insights.json        # Generated insights
└── changes.json         # Change tracking data

Privacy: All data stays local on your machine. No cloud storage or external services.

🎯 Usage Examples

Daily Vault Health Check

// Quick scan for immediate insights
const analysis = await mcp.call('scan_vault', {
  vaultPath: '/Users/username/MyVault',
  mode: 'quick',
  focus: 'health'
});

// Get high-priority recommendations
const insights = await mcp.call('get_insights', {
  vaultPath: '/Users/username/MyVault',
  priority: 'high'
});

Weekly Progress Review

// Track changes over the past week
const changes = await mcp.call('track_changes', {
  vaultPath: '/Users/username/MyVault',
  since: '2024-08-01',
  granularity: 'daily'
});

// Generate comprehensive report
const report = await mcp.call('generate_report', {
  vaultPath: '/Users/username/MyVault',
  format: 'markdown'
});

Deep Vault Analysis

// Full analysis with all insights
const analysis = await mcp.call('scan_vault', {
  vaultPath: '/Users/username/MyVault',
  mode: 'deep',
  focus: 'all'
});

// Export data for external analysis
const dataExport = await mcp.call('generate_report', {
  vaultPath: '/Users/username/MyVault',
  format: 'json'
});

🔧 Architecture

Components

• AnalysisDatabase - JSON-based local storage
• VaultAnalyzer - Core scanning and analysis engine
• InsightGenerator - Recommendation and insight creation
• ChangeTracker - File modification monitoring
• ReportGenerator - Multi-format report creation

Design Principles

• Non-invasive - Only reads, never modifies your vault
• Lightweight - Minimal dependencies and fast execution
• Local-first - All data stored locally for privacy
• Extensible - Modular design for easy feature additions

📊 Sample Output

Analysis Results

🔍 Vault Analysis Complete

Path: /Users/username/MyVault
Mode: quick
Focus: all

Results:
- Notes analyzed: 247
- Links found: 1,156
- Orphans detected: 23
- Analysis time: 145ms

Key Findings:
- Large vault with 247 notes - consider organization strategies
- High linking density (4.7 links/note) - excellent connectivity
- Low orphan rate (9%) - excellent note connectivity
- Found 12 hub notes with 10+ backlinks - great knowledge centers

Insights Example

💡 Vault Insights (all | all priority)

Found 3 actionable insights:

**23 Orphaned Notes Found** (medium)
9% of your notes (23 out of 247) have no incoming links, making them difficult to discover.
Action: Review orphaned notes and create connections to related content. Start with recent notes or those with valuable information.

**Knowledge Hub Notes Identified** (low)
You have 12 notes that serve as knowledge hubs with many connections. These are valuable reference points.
Action: Maintain and expand these hub notes. Consider adding overviews, summaries, or organizing them as MOCs (Maps of Content).

**Strong Note Connectivity** (low)
Your notes average 4.7 backlinks each, indicating good interconnectedness.
Action: Continue building connections between ideas. Consider creating overview notes that link to clusters of related content.

🤝 Contributing

This is a focused, lightweight tool designed for personal knowledge management. The codebase is well-structured and documented for easy understanding and modification.

Development Setup

npm install
npm run build
npm run test  # Run the test suite
npm run dev   # Build and run in development mode

Code Structure

src/
├── analysis/           # Core analysis components
│   ├── vault-analyzer.ts
│   └── change-tracker.ts
├── database/           # Data storage
│   └── analysis-db.ts
├── insights/           # Insight generation and reporting
│   ├── insight-generator.ts
│   └── report-generator.ts
├── index.ts           # Main MCP server
├── types.ts           # TypeScript definitions
└── test.ts            # Test suite

📄 License

MIT License - Use freely for personal and commercial projects.

🔗 Related Projects

• Obsidian - The knowledge management application
• Model Context Protocol - The underlying communication protocol
• Brain Manager - Comprehensive project and knowledge management system

---

Built with ❤️ for the Obsidian community

Helping you understand and improve your knowledge management practices through intelligent analysis.