# Obsidian Graph

> Semantic knowledge graph navigation for Obsidian or markdown vaults using AI-powered vector embeddings and PostgreSQL+pgvector

- **Type:** MCP server
- **Install:** `agentstack add mcp-drewburchfield-obsidian-graph`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [drewburchfield](https://agentstack.voostack.com/s/drewburchfield)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [drewburchfield](https://github.com/drewburchfield)
- **Source:** https://github.com/drewburchfield/obsidian-graph

## Install

```sh
agentstack add mcp-drewburchfield-obsidian-graph
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

[](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

**get_orphaned_notes:**
- 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
```
get_orphaned_notes(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

```bash
# 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

```bash
docker-compose build obsidian-graph
docker-compose restart obsidian-graph
```

### Debugging

```bash
# 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](https://github.com/drewburchfield)
- **Source:** [drewburchfield/obsidian-graph](https://github.com/drewburchfield/obsidian-graph)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-drewburchfield-obsidian-graph
- Seller: https://agentstack.voostack.com/s/drewburchfield
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.