Directory Indexer

Turn your directories into an AI-powered knowledge base.

Self-hosted semantic search for local files. Enable AI assistants to search your documents using vector embeddings and MCP integration.

Setup

Directory Indexer runs locally on your machine or server. It uses an embedding provider (such as Ollama) to create vector embeddings of your files and stores them in a Qdrant vector database for fast semantic search. Both services can run remotely if needed.

Setup requires two services:

1. Qdrant Vector Database

Choose one option:

Docker (recommended for most users):

docker run -d --name qdrant \
    -p 127.0.0.1:6333:6333 \
    -v qdrant_storage:/qdrant/storage \
    qdrant/qdrant

• This option requires Docker
• Runs Qdrant on docker container, uses a named volume qdrant_storage for persistent storage.

Alternative: Install natively from qdrant.tech

2. Embedding Provider

Choose one option:

Option A: Ollama (recommended - free, runs locally)

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh  # Linux/macOS
# For Windows: Download from https://ollama.ai

# Pull the embedding model
ollama pull nomic-embed-text

• You can also run Ollama via Docker
  • GPU support may require additional configuration

Option B: OpenAI (requires paid API key)

export OPENAI_API_KEY="your-api-key-here"

Quick Verification

Test your setup:

# Check Qdrant
curl http://localhost:6333/collections

# Check Ollama
curl http://localhost:11434/api/tags

If either fails, directory-indexer will show a helpful error with setup guidance.

Installation

npm install -g directory-indexer

Usage

MCP Integration

Configure with Claude Desktop:

{
  "mcpServers": {
    "directory-indexer": {
      "command": "directory-indexer",
      "args": ["serve"]
    }
  }
}

Start the MCP server:

directory-indexer serve

Your AI assistant (Claude, Cline, Copilot, etc.) can now search your indexed documents semantically. Ask: "Find API authentication examples", "Show me incidents similar to this", or "Find troubleshooting guides on SQL deadlocks".

CLI Commands

# Index your directories
# Linux/macOS
directory-indexer index /home/user/projects/api-docs /mnt/work/incident-reports
# Windows
directory-indexer index "C:\work\documentation" "D:\projects\my-app\docs"

# Search semantically
directory-indexer search "database timeout errors"

# Find similar files
# Linux/macOS
directory-indexer similar /mnt/work/incident-reports/redis-outage.md
# Windows
directory-indexer similar "C:\work\incidents\redis-outage.md"

# Get file content
directory-indexer get /home/user/projects/api-docs/auth-guide.md

# Show status
directory-indexer status

Configuration

Directory Indexer uses environment variables for configuration. Set these if your services run on different ports or require API keys:

# Service endpoints (defaults shown)
export QDRANT_ENDPOINT="http://localhost:6333"
export OLLAMA_ENDPOINT="http://localhost:11434"

# Optional data directory (default: ~/.directory-indexer)
# Linux/macOS
export DIRECTORY_INDEXER_DATA_DIR="/opt/directory-indexer-data"
# Windows
set DIRECTORY_INDEXER_DATA_DIR=D:\data\directory-indexer

# Optional Qdrant collection name (default: directory-indexer)
# Note: Setting to "test" enables auto-cleanup for testing
export DIRECTORY_INDEXER_QDRANT_COLLECTION="my-custom-collection"

# Optional API keys
export QDRANT_API_KEY="your-qdrant-key"
export OLLAMA_API_KEY="your-ollama-key"  # if using hosted Ollama

For MCP clients (like Claude Desktop), configure with environment variables:

{
  "mcpServers": {
    "directory-indexer": {
      "command": "directory-indexer",
      "args": ["serve"],
      "env": {
        "QDRANT_ENDPOINT": "http://localhost:6333",
        "OLLAMA_ENDPOINT": "http://localhost:11434",
        "DIRECTORY_INDEXER_DATA_DIR": "/opt/directory-indexer-data"
      }
    }
  }
}

Supported Files

• Text: .md, .txt
• Code: .rs, .py, .js, .ts, .go, .java, etc.
• Data: .json, .yaml, .csv, .toml
• Config: .env, .conf, .ini

Documentation

• API Reference: Complete CLI and MCP tool documentation
• Contributing: Development setup and guidelines
• Design: Architecture and technical decisions

Usage Examples

Once indexed, try these queries with your AI assistant:

Search by concept:

• "Find API authentication examples"
• "Show me error handling patterns"
• "Find configuration for Redis"

Find similar content:

• "Show me incidents similar to this outage report" (when you have an incident file open)
• "Find documentation like this API guide" (when viewing an API doc)
• "What files are similar to my deployment script?"

Troubleshoot issues:

• "Find troubleshooting guides on SQL deadlocks"
• "Show me solutions for timeout errors"
• "Find debugging tips for performance issues"

License

MIT