# 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:**
```bash
git clone <repository-url> background-vault-analysis
cd background-vault-analysis
npm install
npm run build
```

2. **Test the system:**
```bash
node dist/test.js
```

3. **Configure your MCP client:**

Add to your MCP configuration (e.g., Claude Desktop):
```json
{
  "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:**
```javascript
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:**
```javascript
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:**
```javascript
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:**
```javascript
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
```javascript
// 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
```javascript
// 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
```javascript
// 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
```bash
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](https://obsidian.md/) - The knowledge management application
- [Model Context Protocol](https://modelcontextprotocol.io/) - The underlying communication protocol
- [Brain Manager](../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.*