workspace-qdrant-mcp

Project-scoped vector database for AI assistants, providing hybrid semantic + keyword search with automatic project detection.

Features

• Hybrid Search - Combines semantic similarity with keyword matching using Reciprocal Rank Fusion
• Project Detection - Automatic Git repository awareness and project-scoped collections
• 6 MCP Tools - search, retrieve, rules, store, grep, list
• Code Intelligence - Tree-sitter semantic chunking + LSP integration for active projects
• Code Graph - Relationship graph with algorithms (PageRank, community detection, betweenness centrality)
• High-Performance CLI - Rust-based wqm command-line tool
• Background Daemon - memexd for continuous file monitoring and processing

Quick Start

Prerequisites

• Qdrant - docker run -d -p 6333:6333 -v qdrant_storage:/qdrant/storage qdrant/qdrant
• C compiler - Required for compiling Tree-sitter grammars on first use. Tree-sitter grammars are distributed as C source and compiled locally.
  • macOS: xcode-select --install (Xcode Command Line Tools)
  • Linux: apt install build-essential (Debian/Ubuntu) or dnf groupinstall "Development Tools" (Fedora)
  • Windows: Install Visual Studio Build Tools with C++ workload

Install

Option 1: Homebrew (Recommended — macOS & Linux)

brew install ChrisGVE/tap/workspace-qdrant
brew services start workspace-qdrant

Option 2: Pre-built Binaries

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/ChrisGVE/workspace-qdrant-mcp/main/scripts/download-install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/ChrisGVE/workspace-qdrant-mcp/main/scripts/download-install.ps1 | iex

Installs wqm and memexd to ~/.local/bin (Linux/macOS) or %LOCALAPPDATA%\wqm\bin (Windows).

Option 3: Build from Source

git clone https://github.com/ChrisGVE/workspace-qdrant-mcp.git
cd workspace-qdrant-mcp
./install.sh

See Installation Reference for detailed instructions and platform-specific notes. For Windows, see the Windows Installation Guide.

Configure MCP

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "workspace-qdrant-mcp": {
      "command": "node",
      "args": ["/path/to/workspace-qdrant-mcp/src/typescript/mcp-server/dist/index.js"],
      "env": {
        "QDRANT_URL": "http://localhost:6333"
      }
    }
  }
}

Claude Code:

claude mcp add workspace-qdrant-mcp -- node /path/to/workspace-qdrant-mcp/src/typescript/mcp-server/dist/index.js

Verify

wqm --version
wqm status health

CLAUDE.md Integration

Add the following to your project's CLAUDE.md (or your global ~/.claude/CLAUDE.md) so Claude Code uses workspace-qdrant proactively:

## workspace-qdrant

The `workspace-qdrant` MCP server provides codebase-aware search, a library knowledge base, a scratchpad for accumulated insights, and persistent behavioral rules. The tool schemas are self-describing; these instructions cover *when* and *how* to use them.

### Primary Search and Knowledge Base

**Use `workspace-qdrant` first whenever context is uncertain** — first session on a project, returning after a significant gap, or exploring an unfamiliar subsystem. It is faster and more accurate than walking files manually, and it retrieves findings from prior sessions that would otherwise be lost.

**Three-step protocol:**
1. **Search** with `workspace-qdrant` (`search`, `grep`, `list`, or `retrieve`)
2. **Fall back** to `Grep`, `Glob`, `WebSearch` only when workspace-qdrant is insufficient or unavailable
3. **Store** any new findings, analysis, or design rationale via `store` so they are retrievable in future sessions

When a fresh handover or strong prior context already covers what you need, skip the exploratory search — but always store new findings at the end.

**Collections and their purpose:**
- `projects` — indexed codebase; use `scope="project"` (current project) or `scope="all"` (across all projects)
- `libraries` — external reference docs, API specs, third-party documentation; add via `store` with `collection="libraries"` and search with `includeLibraries=true`
- `scratchpad` — analysis, design rationale, research transcripts, architectural insights; complements session handovers by building a growing, semantically searchable knowledge layer across sessions
- `rules` — persistent behavioral rules; load at session start via `rules` → `action="list"`

**Practical notes:**
- Use `grep` for exact strings or regex; `list` with `format="summary"` to explore project structure
- Store external docs or specs into `libraries` so they are searchable alongside code
- Use the scratchpad to record *why* decisions were made, not just *what* was done — future sessions can retrieve the reasoning

### Sub-Agents

Sub-agents start with only the prompt you give them — they have no session history or handover context. They must always use `workspace-qdrant` first for any code exploration, without exception. Include this verbatim in every agent prompt:

> "You have no prior context about this codebase. Use `workspace-qdrant` as your mandatory first tool for ALL code searches — symbols, functions, architecture, patterns, prior findings. Use `search`, `grep`, `list`, or `retrieve` before touching any file with Read/Grep/Glob. Store any new findings, analysis, or design rationale via `store` (scratchpad for insights, libraries for reference docs) so they persist for future sessions."

### Project Registration

At session start, check whether the current project is registered with workspace-qdrant. If it is not, ask the user whether they want to register it (do not register silently). Once registered, the daemon handles file watching and ingestion automatically — no further action is needed.

### Behavioral Rules

The `rules` tool manages persistent rules that are injected into context across sessions. Rules are **user-initiated only** — add rules when the user explicitly instructs you to, never autonomously. Use `action="list"` at session start to load active rules.

### Issue Reporting

workspace-qdrant is under active development. If you encounter errors, unexpected behavior, or limitations with any workspace-qdrant tool, report them as GitHub issues at https://github.com/ChrisGVE/workspace-qdrant-mcp/issues using the `gh` CLI.

MCP Tools

Tool	Purpose
search	Hybrid semantic + keyword search across indexed content
retrieve	Direct document lookup by ID or metadata filter
rules	Manage persistent behavioral rules
store	Store content, register projects, save notes
grep	Exact substring or regex search using FTS5
list	List project files and folder structure

See MCP Tools Reference for parameters and examples.

Collections

Collection	Purpose	Isolation
projects	Project code and documentation	Multi-tenant by tenant_id
libraries	Reference documentation (books, papers, docs)	Multi-tenant by library_name
rules	Behavioral rules and preferences	Multi-tenant by project_id
scratchpad	Temporary working storage	Per-session

CLI Reference

# Service management
wqm service start              # Start background daemon
wqm service status             # Check daemon status
wqm status health              # System health check

# Search and content
wqm search "query"             # Search collections
wqm ingest file path.py        # Ingest a file
wqm rules list                 # List behavioral rules

# Project and library
wqm project list               # List registered projects
wqm project watch pause        # Pause file watchers
wqm library list               # List libraries
wqm tags list                  # List tags with counts

# Administration
wqm admin collections list     # List collections
wqm admin rebuild all          # Rebuild all indexes
wqm admin backup create        # Backup snapshots
wqm admin stats overview       # Search analytics

# Code graph
wqm graph stats --tenant <t>   # Node/edge counts
wqm graph query --node-id <id> --tenant <t> --hops 2   # Related nodes
wqm graph impact --symbol <name> --tenant <t>           # Impact analysis
wqm graph pagerank --tenant <t> --top-k 20              # PageRank centrality

# Setup
wqm init completions zsh       # Shell completions
wqm init man install           # Install man pages
wqm init hooks install         # Install Claude Code hooks (respects CLAUDE_CONFIG_DIR)

# Queue and monitoring
wqm queue stats                # Queue statistics

See CLI Reference for complete documentation.

Configuration

Environment Variables

Variable	Default	Description
QDRANT_URL	http://localhost:6333	Qdrant server URL
QDRANT_API_KEY	-	API key (required for Qdrant Cloud)
FASTEMBED_MODEL	all-MiniLM-L6-v2	Embedding model

Claude Code Integration

wqm init hooks reads and writes Claude Code's settings.json. The location is resolved from:

Variable	Default	Description
CLAUDE_CONFIG_DIR	~/.claude	Claude Code config directory used by wqm init hooks install/uninstall/status. Set this for Claude Code Enterprise or any non-default install.

Example — Claude Code Enterprise:

export CLAUDE_CONFIG_DIR=~/.config/claude/claude-ent
wqm init hooks install

Observability

The daemon exposes metrics and traces. Both are disabled by default.

Prometheus (/metrics, pull)

Enable via config or env var, then scrape:

# in the daemon config
observability:
  telemetry:
    prometheus:
      enabled: true
      port: 9464
      bind: 0.0.0.0

or:

WQM_PROMETHEUS_ENABLED=true WQM_PROMETHEUS_PORT=9464 memexd --foreground
curl http://localhost:9464/metrics | head

The --metrics-port <N> CLI flag is a shortcut that forces enabled=true and overrides the port. See docs/observability/prometheus-scrape-example.yaml for a scrape_configs snippet and docs/observability/memexd-telemetry-dashboard.json for a Grafana 10 dashboard.

OTLP traces (push)

#[tracing::instrument] spans on the queue processor, watcher, gRPC, embedding, and Qdrant paths are exported over OTLP/gRPC when:

observability:
  telemetry:
    service_name: memexd
    otlp:
      enabled: true
      endpoint: http://collector.example:4317
      protocol: grpc   # http/protobuf is also recognized (logs a warning)
      sample_rate: 0.1

Standard OpenTelemetry env vars are honored: OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_PROTOCOL, OTEL_EXPORTER_OTLP_HEADERS, OTEL_TRACES_SAMPLER_ARG.

OTLP metrics export is not currently implemented — Prometheus is the canonical metrics surface.

Architecture

                    +-----------------+
                    |  Claude/Client  |
                    +--------+--------+
                             |
                    +--------v--------+
                    |   MCP Server    |  (TypeScript)
                    +--------+--------+
                             |
              +--------------+--------------+
              |                             |
     +--------v--------+           +--------v--------+
     |   Rust Daemon   |           |     Qdrant      |
     |    (memexd)     |           | Vector Database |
     +--------+--------+           +-----------------+
              |
     +--------v--------+
     |  File Watcher   |
     |  Code Graph     |
     |  Embeddings     |
     +-----------------+

The Rust daemon handles file watching, embedding generation, code graph extraction, and queue processing. All writes route through the daemon for consistency.

Documentation

User guides:

• Quick Start — get running in 5 minutes
• User Manual — full usage guide
• LLM Integration — best practices for Claude

Reference:

• Installation | Windows
• CLI Reference — all wqm commands
• MCP Tools — tool parameters and examples
• Configuration — all options and defaults
• Architecture — component overview

See the Documentation Index for specifications, ADRs, and developer resources.

Development

# TypeScript MCP server
cd src/typescript/mcp-server && npm install && npm run build && npm test

# Rust daemon and CLI (from src/rust/)
cargo build --release
cargo test

# Graph benchmarks
cargo bench --package workspace-qdrant-core --bench graph_bench

# Binaries output to:
# - target/release/wqm
# - target/release/memexd

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT License - see LICENSE for details.

---

Inspired by claude-qdrant-mcp