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

# 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

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

{
  "mcpServers": {
    "workspace-qdrant-mcp": {
      "command": "workspace-qdrant-mcp",
      "env": {
        "QDRANT_URL": "http://localhost:6333"
      }
    }
  }
}

claude mcp add workspace-qdrant-mcp -- workspace-qdrant-mcp

wqm --version
wqm status health

## 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.

# 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