Obsidian Graph

[](https://github.com/drewburchfield/obsidian-graph)

[](https://github.com/drewburchfield/obsidian-graph/actions/workflows/ci.yml) [](https://www.python.org/downloads/) [](https://opensource.org/licenses/MIT) [](https://modelcontextprotocol.io/) [](https://deepwiki.com/drewburchfield/obsidian-graph)

Semantic knowledge graph engine for markdown vaults. Discovers hidden connections between notes using AI-powered vector embeddings and PostgreSQL+pgvector. Accessible to any AI app or harness compatible with MCP.

Overview

Obsidian Graph builds a semantic knowledge graph of your markdown vault, discovering relationships between notes that go beyond keywords and explicit links. It embeds your notes as vectors using Voyage Context-3, stores them in PostgreSQL+pgvector, and provides tools for semantic search, multi-hop graph traversal, hub detection, and orphan analysis.

Designed for Obsidian vaults but works with any folder of markdown files. Connects to any AI app or harness compatible with the Model Context Protocol (MCP).

Features

• Semantic Search: Find notes by meaning, not just keywords
• Connection Discovery: Multi-hop BFS graph traversal to map note relationships
• Hub Analysis: Identify highly connected conceptual anchors (MOC candidates)
• Orphan Detection: Find isolated insights that need integration
• Auto-Indexing: Automatic file watching with 30-second debounce
• Superior Quality: Voyage Context-3 (1024d) vs typical 384d embeddings

Architecture

┌─ obsidian-graph container ─────────────────┐
│                                            │
│  MCP Client ◄──stdio──► server.py          │
│                            │               │
│                     ┌──────┴──────┐        │
│                     ▼             ▼        │
│              graph_builder   hub_analyzer  │
│              embedder.py     file_watcher  │
│                  │               │         │
│                  │ HTTPS         │ watch   │
│                  ▼               ▼         │
│            Voyage AI API    /vault (ro)    │
│                  │                         │
│                  │ 1024d vectors           │
│                  ▼                         │
│           vector_store.py                  │
│                  │                         │
└──────────────────┼─────────────────────────┘
                   │ SQL
                   ▼
┌─ obsidian-graph-pgvector container ────────┐
│  PostgreSQL 15 + pgvector (HNSW index)     │
└────────────────────────────────────────────┘

• Embeddings: Voyage Context-3 (1024 dimensions, contextualized)
• Vector Store: PostgreSQL 15+ with pgvector HNSW indexing
• Performance: 0.9ms search (555x better than target), 50% of counts are stale
• Identifies notes with many semantic connections
• High hub scores → good MOC (Map of Content) candidates

getorphanednotes:

• Uses materialized connection_count column
• Finds notes with few semantic connections
• Sorted by: connection count (ASC), modified date (DESC)
• Shows recent notes first (likely new insights)
• Helps identify notes needing integration

Chunking Support

For large notes (>30k tokens):

• Automatically split into sentence-aligned chunks (target: ~2000 characters, 0 overlap)
• Chunking algorithm breaks at sentence boundaries (. or \n\n) for readability
• Chunk sizes vary (1800-2200 chars) to preserve sentence integrity
• Embedded in batches of 60 chunks (preserves context)
• Voyage Context-3 maintains semantic coherence across chunks
• Each chunk stored separately with chunk_index
• Search returns individual chunks (can aggregate by path)

Example: 168k-char note → ~87 variable-sized chunks → 2 batches (60+27) → context preserved

Most Obsidian notes are =10 connections - candidates for Maps of Content (MOCs). Example: "decision-making.md" might connect to psychology, neuroscience, economics, and philosophy notes.

### Find Orphans

getorphanednotes(max_connections=2, limit=20)

Identifies isolated notes that need integration into knowledge graph. Sorted by modification date to surface recent unconnected insights.

## Performance

Validated metrics:

| Metric | Target | Actual | Status |
|--------|--------|--------|--------|
| Search latency | <500ms | 0.9ms | ✅ 555x better |
| Graph building (depth=3) | <2s | <2s | ✅ On target |
| Hub/orphan queries | <100ms | <100ms | ✅ Materialized |
| Similarity range | [0.0-1.0] | [0.0-1.0] | ✅ Validated |
| Embedding quality | 1024-dim | 1024-dim | ✅ Voyage Context-3 |

**Performance Note**: Metrics measured on development vault (~500 notes, M1 MacBook Pro). Actual performance depends on vault size, hardware (CPU/RAM/SSD), and database configuration. HNSW indexing provides O(log n) search, so performance degrades gracefully with vault size.

## Troubleshooting

### "Reduced rate limits of 3 RPM"
- **Cause**: No payment method on Voyage account
- **Solution**: Add payment method at https://dashboard.voyageai.com/
- **Note**: 200M free tokens still apply

### "PostgreSQL connection failed"
```bash
# Check postgres container
docker ps | grep obsidian-graph-pgvector
docker logs obsidian-graph-pgvector

# Verify credentials
grep POSTGRES_ .env

"Note not found" errors

• Ensure initial indexing completed: docker exec -i obsidian-graph python -m src.indexer
• Check vault path is mounted: docker exec -i obsidian-graph ls /vault

File changes not detected

• Verify OBSIDIAN_WATCH_ENABLED=true
• Check logs: docker logs obsidian-graph
• Look for: Watching vault: /vault [polling (interval: 30s)]
• File watcher starts after PostgreSQL connection
• Cloud sync users: Changes take up to polling interval (default 30s) plus cloud sync time
• Reduce detection time: Set OBSIDIAN_WATCH_POLLING_INTERVAL=15 in .env

Development

Running Tests

# Quick validation
docker exec -i obsidian-graph python test_e2e.py

# Unit tests (requires 300 RPM rate limits)
docker exec -i obsidian-graph pytest tests/ -v

Rebuilding

docker-compose build obsidian-graph
docker-compose restart obsidian-graph

Debugging

# View logs
docker logs -f obsidian-graph

# Interactive shell
docker exec -it obsidian-graph /bin/bash

# Check database
docker exec -it obsidian-graph-pgvector psql -U obsidian -d obsidian_graph

Comparison to mcp-obsidian

| Feature | mcp-obsidian | obsidian-graph | |---------|--------------|----------------| | Embeddings | 384-dim (all-MiniLM-L6-v2) | 1024-dim (Voyage Context-3) | | Vector Store | ChromaDB | PostgreSQL+pgvector | | Tools | 2 (search, reindex) | 5 (search, similar, graph, hubs, orphans) | | Search perf | Unknown | 0.9ms validated | | Graph traversal | ❌ No | ✅ BFS with cycle prevention | | Hub detection | ❌ No | ✅ Materialized stats |

License

MIT License - Copyright (c) 2025 Drew Burchfield

See LICENSE file for details.

Links

• Voyage AI: https://www.voyageai.com/
• pgvector: https://github.com/pgvector/pgvector
• MCP Protocol: https://modelcontextprotocol.io/

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: drewburchfield
• Source: drewburchfield/obsidian-graph
• License: MIT

Install and usage instructions live in the source repository linked above.