Obsidian-Ollama RAG System

This project implements a Retrieval-Augmented Generation (RAG) system that allows you to chat with your Obsidian notes using Ollama's language models. All processing happens locally on your machine, ensuring your notes remain private and secure. The system can be used both as a standalone Python application and as an MCP server integrated with Claude Desktop.

!Obsidian-Ollama RAG System

📋 Table of Contents

• Features
• Prerequisites
• Installation
• Configuration
• Usage
• Advanced Usage
• MCP Server Integration
• Troubleshooting
• FAQ

✨ Features

• 100% Local & Private: All processing happens on your machine - no data leaves your computer
• Seamless Obsidian Integration: Connect directly to your Obsidian vault
• Powerful RAG System: Uses vector embeddings to retrieve relevant context from your notes
• Multiple Models: Compatible with various Ollama models (llama3.2, mistral, gemma, etc.)
• Interactive Chat Interface: User-friendly command-line interface for querying your notes
• Claude Desktop Integration: MCP server support for seamless integration with Claude Desktop
• Customizable: Adjust embedding parameters, chunk sizes, and retrieval settings

🔧 Prerequisites

Before you begin, ensure you have the following installed:

• Python 3.10 or later
• Ollama: For running the language models locally (Download here)
• Obsidian: With a vault containing your notes (Download here)
• Claude Desktop (Optional): For MCP server integration

🚀 Installation

Step 1: Clone or Download the Repository

git clone https://github.com/username/obsidian-ollama-rag.git
cd obsidian-ollama-rag

Step 2: Install uv (if not already installed)

curl -LsSf https://astral.sh/uv/install.sh | sh

Step 3: Create and Activate Virtual Environment

uv venv
.venv/Scripts/activate  # On Windows
source .venv/bin/activate  # On Unix-like systems

Step 4: Install Dependencies

uv pip install -e .

Step 5: Install and Start Ollama

1. Download and install Ollama from ollama.com/download
2. Start the Ollama server:

   ollama serve
   

Step 6: Pull a Language Model

The default configuration uses llama3.2, but you can choose any model available in Ollama:

ollama pull llama3.2  # Default model (2GB)

Alternative models:

ollama pull gemma:2b  # Smaller model (1.4GB)
ollama pull mistral    # Larger model (7GB)

Step 7: Verify Your Setup

Run the setup checker to verify everything is configured correctly:

python3 check_setup.py

⚙️ Configuration

Configure Your Obsidian Vault Path

Edit config.py to point to your Obsidian vault:

# Path to your Obsidian vault
OBSIDIAN_VAULT_PATH = "/path/to/your/obsidian/vault"

Customize Model and Processing Settings

In the same config.py file, you can adjust:

# Ollama settings
OLLAMA_HOST = "http://localhost:11434"  # Default Ollama API endpoint
MODEL_NAME = "llama3.2"  # Change to your preferred model

# Document processing settings
CHUNK_SIZE = 500  # Size of text chunks for processing
CHUNK_OVERLAP = 50  # Overlap between chunks to maintain context

# Vector database settings
VECTOR_DB_PATH = "./chroma_db"  # Where to store the vector database

🖥️ Usage

Interactive Chat Mode

The easiest way to use the system is through the interactive chat interface:

python3 interactive_chat.py

This will:

1. Load your Obsidian notes
2. Process them into a vector database (first run only)
3. Start an interactive chat session where you can ask questions about your notes

Example Queries

Once the chat interface is running, you can ask questions like:

• "What are the main topics in my notes?"
• "Summarize what I know about Docker containers"
• "What did I write about Python decorators?"
• "Find information about my project ideas"

Exit the Chat

Type exit, quit, or press Ctrl+C to exit the chat interface.

🔌 MCP Server Integration

Starting the MCP Server

The system runs as an MCP server on port 3000 by default:

python server.py

Configuring Claude Desktop

1. Open your claude_desktop.config.json
2. Add the Obsidian RAG server configuration under the mcpServers section:

{
  "mcpServers": {
    "obsidian-rag": {
      "command": "pwsh",
      "args": [
        "-NoProfile",
        "-Command",
        "& {$env:PORT='3000'; uv pip run python server.py}"
      ],
      "cwd": "path/to/obsidian-ollama-rag"
    }
  }
}

Alternative shell configurations:

// Bash
{
  "command": "bash",
  "args": ["-c", "PORT=3000 uv pip run python server.py"]
}

// CMD
{
  "command": "cmd",
  "args": ["/c", "set PORT=3000 && uv pip run python server.py"]
}

The configuration uses:

• uv pip run: Runs Python in the project's virtual environment
• PORT=3000: Sets the server port (can be changed if needed)
• PowerShell/Bash/CMD variants for different systems

Port Configuration

The server uses port 3000 by default. If you need to use a different port:

1. Set the PORT environment variable before starting the server:

   # Windows PowerShell
   $env:PORT='3001'; python server.py
   
   # Unix-like systems
   PORT=3001 python server.py
   

2. Update the port in your claude_desktop.config.json accordingly

Troubleshooting Port Issues

If you encounter port binding errors:

1. Check if the port is already in use:

   # Windows
   netstat -ano | findstr :3000
   
   # Unix-like systems
   lsof -i :3000
   

2. Try a different port by setting the PORT environment variable

3. Ensure you're not running multiple instances of the server

4. Close other applications that might be using the port

Using with Claude Desktop

Once configured, you can use these commands in Claude Desktop:

• Query your notes:

  @obsidian-rag.query "What are the main topics in my notes?"
  

• Reload the vector store:

  @obsidian-rag.reload_vectorstore
  

MCP Server Features

The MCP server provides:

• Real-time querying of your Obsidian vault
• Source attribution for answers
• Vector store management
• Automatic server startup with Claude Desktop
• Local processing ensuring privacy

🔍 Advanced Usage

Rebuilding the Vector Database

If you've added new notes to your Obsidian vault, you'll need to rebuild the vector database:

# Run this command to force a rebuild of the vector database
python3 -c "from rag import create_vector_store; create_vector_store(force_reload=True)"

Or simply delete the chroma_db directory and restart the interactive chat.

Using Different Models

1. Pull a different model with Ollama:

   ollama pull gemma:2b
   

2. Update your config.py to use the new model:

   MODEL_NAME = "gemma:2b"
   

3. Rebuild your vector database to use the new embeddings:

   python3 -c "from rag import create_vector_store; create_vector_store(force_reload=True)"
   

Optimizing for Performance

If the system is slow or using too much memory:

1. Use a smaller model (e.g., gemma:2b instead of llama3.2)
2. Reduce the CHUNK_SIZE in config.py (e.g., from 500 to 300)
3. Limit the scope of your Obsidian vault by creating a dedicated vault with only the notes you want to query

🔧 Troubleshooting

Common Issues

"Ollama server not running"

Ensure the Ollama server is running with:

ollama serve

"Model not found"

Pull the model specified in your config:

ollama pull llama3.2  # or whatever model you're using

"No documents found in Obsidian vault"

Check your vault path in config.py and ensure it contains markdown (.md) files.

"Memory issues or slow performance"

Try a smaller model or reduce chunk size as described in the Advanced Usage section.

"MCP server connection issues"

• Verify the server is running (python server.py)
• Check the port (8080) is not in use
• Ensure the path in claude_desktop.config.json is correct

Running the Setup Checker

Use the setup checker to diagnose issues:

python3 check_setup.py

❓ FAQ

Q: Can I use this with multiple Obsidian vaults?

A: Yes, just update the OBSIDIAN_VAULT_PATH in config.py to point to the vault you want to use. You may want to create separate copies of the project for each vault.

Q: Will this work with other note-taking apps?

A: The system is designed for Obsidian's markdown files, but it should work with any directory containing markdown files. Just update the path in config.py.

Q: How much disk space does this use?

A: The vector database typically uses 10-20% of the original text size. The Ollama models vary in size from 1GB to 8GB depending on which you choose.

Q: Is my data secure?

A: Yes, all processing happens locally on your machine. No data is sent to external servers.

Q: Can I use both the standalone and MCP server versions?

A: Yes, you can run either or both. The MCP server is designed to work alongside the standalone version without conflicts.

Q: How do I update to newer versions of this tool?

A: Pull the latest changes from the repository or download the newest release.

---

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgements

• LangChain for the RAG framework
• Ollama for the local language model inference
• Obsidian for the excellent note-taking app
• Claude Desktop for the MCP integration capabilities