Personal Notes Assistant (Obsidian RAG)

This project provides a Retrieval-Augmented Generation (RAG) server for your Obsidian vault. It indexes your Markdown notes into a Milvus vector database and allows you to query your knowledge base using either a local Large Language Model (LLM) via Ollama or the OpenAI API.

The server automatically watches your vault for changes and keeps the knowledge base synchronized in real-time.

Table of Contents

• Features
• Prerequisites
• Setup & Installation
• LLM Provider Configuration
  • Using Ollama
  • Using OpenAI
• Running the Server
• Usage with Claude Desktop

Features

• Obsidian Integration: Directly connects to and indexes your Obsidian vault.
• Real-time Sync: Automatically updates the database when notes are created or modified.
• Vector Search: Employs sentence-transformers and Milvus to find relevant notes efficiently.
• Flexible LLM Support: Works with both OpenAI's API and local models through Ollama.
• Tool-based Interface: Exposes its functionality through a standardized MCP server interface.

Prerequisites

Before you begin, ensure you have the following installed:

• Python 3.9+
• uv (for Python package management)
• Docker and Docker Compose (for running Milvus).
• An Obsidian vault with your notes.
• Ollama (optional, only if you plan to use local models).

Setup & Installation

1. Clone the Repository

   git clone https://github.com/coeusyk/personal-notes-assistant.git
   cd personal-notes-assistant
   

2. Run Milvus with Docker

   This project includes a docker-compose.yml file to run a Milvus instance.

   docker-compose up -d
   

3. Install Python Dependencies

   This project uses uv to manage dependencies in a virtual environment.

   # Create a virtual environment
   uv venv
   
   # Activate the virtual environment
   .venv\Scripts\activate # On Linux use `source .venv/bin/activate`
   
   # Install dependencies
   uv pip install -e .
   

4. A Note on PyTorch with CUDA Support (Optional)

   By default, the command above installs the CPU-only version of PyTorch. If you have a compatible NVIDIA GPU and want to enable CUDA for hardware acceleration, you must manually install the correct version of PyTorch.

   First, uninstall the existing version:

   uv pip uninstall torch
   

   Then, visit the official PyTorch website to find the correct installation command for your specific system and CUDA version. For example, the command might look like this:

   # Example command, check the official website for the correct one for your setup
   uv pip install torch --index-url https://download.pytorch.org/whl/cu121
   

5. Configure Environment Variables

   Create a .env file by copying the sample file. This is where you will configure the application.

   cp .env.sample .env
   

   Open the new .env file and set the OBSIDIAN_VAULT_PATH. Then, follow the instructions in the next section to configure your chosen LLM provider.

LLM Provider Configuration

You must choose between using Ollama (for local models) or OpenAI.

Option 1: Using Ollama (Default)

To use a local model running on your machine, you first need to install Ollama.

1. Install Ollama:

   Download and install Ollama for your operating system from the official website.

2. Download an LLM:

   After installing Ollama, you need to pull a model. Open your terminal and run the following command. For example, to download the mistral:7b-instruct model:

   ollama pull mistral:7b-instruct
   

   Ensure the Ollama application is running. You can find other models in the Ollama library.

3. Configure your .env file for Ollama:

   # --- Required Settings ---
   OBSIDIAN_VAULT_PATH="C:/Path/To/Your/Vault"
   
   # --- LLM Provider Settings ---
   LLM_PROVIDER=ollama
   
   # --- Ollama Settings ---
   OLLAMA_URL=http://localhost:11434
   LLM_MODEL=mistral:7b-instruct
   
   # --- Milvus Settings (Defaults) ---
   MILVUS_HOST=localhost
   MILVUS_PORT=19530
   

Option 2: Using OpenAI

To use OpenAI's models, you will need an API key.

1. Configure your .env file for OpenAI:

   # --- Required Settings ---
   OBSIDIAN_VAULT_PATH="C:/Path/To/Your/Vault"
   
   # --- LLM Provider Settings ---
   LLM_PROVIDER=openai
   
   # --- OpenAI Settings ---
   OPENAI_API_KEY=your-openai-api-key-here
   LLM_MODEL=gpt-3.5-turbo
   
   # --- Milvus Settings (Defaults) ---
   MILVUS_HOST=localhost
   MILVUS_PORT=19530
   

Running the Server

Milvus must already be running (docker-compose up -d) before you start the server — it connects to Milvus on startup and will fail if it isn't reachable.

With Milvus up and your .env file configured, start the main application:

python main.py

If you installed the project with uv pip install -e ., the run-obsidian-rag console script is also available and does the same thing:

run-obsidian-rag

Keep this process running while you interact with it from clients such as Claude Desktop.

Usage with Claude Desktop

You can drive this server directly from Anthropic’s Claude Desktop via the Model‑Context Protocol (MCP). Claude automatically discovers servers declared in its configuration.

1. Configure Claude Desktop

First, edit (or create) the claude_desktop_config.json file in the appropriate location for your operating system:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add (or merge) the following JSON configuration. This tells Claude how to find and run the project.

{
  "mcpServers": {
    "obsidian-rag": {
      "command": "uv",
      "args": [
        "--directory",
        "<PATH_TO_PERSONAL_NOTES_ASSISTANT>",
        "run",
        "main.py"
      ],
      "env": {
        "OBSIDIAN_VAULT_PATH": "<PATH_TO_OBSIDIAN_VAULT>",
        "MILVUS_HOST": "localhost",
        "MILVUS_PORT": "19530"
      }
    }
  }
}

You must replace the placeholder values and configure the environment variables:

| Placeholder | Description | | ------------------------------------ | -------------------------------------------------- | | <PATH_TO_PERSONAL_NOTES_ASSISTANT> | The absolute path to this project's root directory. | | <PATH_TO_OBSIDIAN_VAULT> | The absolute path to your Obsidian vault. |

Important: Configure your LLM provider within the env block above. The example uses Ollama. If you are using OpenAI, you would set LLM_PROVIDER to openai and add your OPENAI_API_KEY.

2. Restart Claude Desktop

Fully quit and relaunch the Claude Desktop application. When the hammer/tool icon appears in the message composer, the server has been detected and is ready.

3. Chat with Your Notes

Ask Claude questions like, "Search my vault for Vector Databases." Claude will transparently invoke the obsidian-rag tool and include answers sourced directly from your notes in its response.

How It Works

1. Claude identifies that your query could be answered by one of its available tools.
2. It calls the search_notes MCP tool exposed by this server.
3. The server retrieves relevant note chunks from Milvus and synthesizes an answer using your configured LLM.
4. Claude merges that answer into its final response back to you.