researcher-admin

name	researcher-admin
description	Set up and manage researcher document repositories; use when adding repos, indexing documents, checking status, configuring embedding providers, or running the MCP server
metadata	{"version":"0.5.4","author":"Stacey Vetzal"}

researcher-admin: Set Up and Maintain Repositories

Use the researcher CLI to add repositories, run indexing, configure embedding providers, manage the MCP server, and keep your knowledge base up to date.

Quick Reference

Task	Command	JSON flag
Add a repository	researcher repo add <name> <path>	--json
Update a repository	researcher repo update <name>	--json
List repositories	researcher repo list	--json
Remove a repository	researcher repo remove <name>	--json
Index all repos	researcher index	--json
Index one repo	researcher index <name>	--json
Check index status	researcher status	--json
Check one repo status	researcher status <name>	--json
Remove a document	researcher remove <repo> <doc-path>	--json
Show config	researcher config show	—
Set a config value	researcher config set <key> <value>	—
Show config file path	researcher config path	—
Start MCP server (stdio)	researcher serve	—
Start MCP server (HTTP)	researcher serve --port 8392	—

---

Repository Management

Add a Repository

researcher repo add NAME PATH [OPTIONS]

Flag	Default	Purpose
--file-types	md,txt,pdf,docx,html	Comma-separated extensions to index
--embedding-provider	chromadb	Embedding provider: chromadb, ollama, openai
--embedding-model	provider default	Override the model name
--exclude / -e	none	Glob pattern to exclude (repeatable)
--image-pipeline	standard	Image processing pipeline: standard (OCR) or vlm (Vision Language Model)
--image-vlm-model	granite_docling	VLM preset name (only used when --image-pipeline=vlm)
--audio-asr-model	turbo	Whisper ASR model for audio files. Options: tiny, base, small, medium, large, turbo
--json / -j	off	Output result as JSON

Examples:

# Add notes dir with defaults
researcher repo add my-notes ~/Notes

# Add only markdown files
researcher repo add docs ~/Projects/my-app/docs --file-types md

# Add with local Ollama embeddings
researcher repo add research ~/Research --embedding-provider ollama

# Add with OpenAI embeddings and specific model
researcher repo add work ~/Work/notes --embedding-provider openai --embedding-model text-embedding-3-large

# Exclude node_modules and all dot-folders (e.g. .git, .venv)
researcher repo add webapp ~/Projects/webapp --exclude node_modules --exclude '.*'

# Exclude build artefacts
researcher repo add project ~/Projects/myapp --exclude node_modules --exclude dist --exclude build --exclude '.*'

# Use VLM pipeline for richer image understanding (downloads model on first use)
researcher repo add screenshots ~/Screenshots --image-pipeline vlm

# Use a smaller/faster VLM model
researcher repo add screenshots ~/Screenshots --image-pipeline vlm --image-vlm-model smoldocling

# Add with audio/video indexing using a specific ASR model
researcher repo add meetings ~/Recordings --audio-asr-model small

# Add a repo for lecture recordings using the highest-accuracy Whisper model
researcher repo add lectures ~/Lectures --file-types mp3,mp4,wav --audio-asr-model large

Common --exclude patterns:

Pattern	Excludes
node_modules	npm/yarn dependency directories
.*	All dot-folders and dot-files (.git, .venv, .DS_Store, etc.)
dist	Build output directories
build	Compiled output directories
__pycache__	Python bytecode cache directories
*.min.js	Minified JavaScript files

Patterns are matched against each component of the relative file path using Unix shell-style wildcards (fnmatch). A file is excluded if any path component matches any pattern. Repeating --exclude adds multiple patterns.

To change file types, embedding settings, or exclusions after a repository has been added, use repo update instead of removing and re-adding the repository.

Update a Repository

Use repo update to change any configuration setting on an existing repository without removing and re-adding it. Only the flags you supply are changed; omitted flags leave the existing values untouched.

researcher repo update NAME [OPTIONS]

Flag	Default	Purpose
--file-types	unchanged	Comma-separated extensions — replaces the existing list entirely
--embedding-provider	unchanged	Embedding provider — replaces the existing value
--embedding-model	unchanged	Model name — replaces the existing value ("" clears it)
--exclude / -e	none added	Glob pattern to add to the existing exclusion list (repeatable; deduplicates)
--no-purge	off	Skip auto-purging indexed docs that now match new exclusion patterns
--image-pipeline	unchanged	Image processing pipeline: standard (OCR) or vlm (Vision Language Model)
--image-vlm-model	unchanged	VLM preset name (only used when --image-pipeline=vlm)
--audio-asr-model	unchanged	Whisper ASR model for audio files. Options: tiny, base, small, medium, large, turbo
--json / -j	off	Output result as JSON

Additive exclude behaviour. Unlike repo add, the --exclude flag on repo update appends new patterns to the existing list rather than replacing it. Patterns that are already present are silently deduplicated. Passing no --exclude flag leaves the exclusion list unchanged.

Automatic purge on new exclusions. When at least one genuinely new pattern is added, the command immediately purges any previously-indexed documents whose paths now match the updated exclusion list. This keeps the index consistent without requiring a separate researcher index run. Use --no-purge to defer cleanup — for example, when adding multiple repos and running a single researcher index pass at the end.

Examples:

# Add an exclusion pattern and automatically purge matching indexed docs
researcher repo update my-notes --exclude dist

# Add multiple patterns, skip auto-purge (run researcher index later)
researcher repo update my-notes -e dist -e build --no-purge

# Switch embedding provider (no other settings change)
researcher repo update my-notes --embedding-provider ollama

# Update file types only
researcher repo update my-notes --file-types md,txt,pdf

# Combine: change provider and add an exclusion in one step
researcher repo update my-notes --embedding-provider openai --embedding-model text-embedding-3-large --exclude dist

# Use instead of remove+re-add when only config needs changing
researcher repo update my-notes --file-types md,txt --embedding-provider ollama

# Switch an existing repo to VLM image processing
researcher repo update my-vault --image-pipeline vlm --image-vlm-model smoldocling

# Switch to a more accurate ASR model for existing audio repository
researcher repo update meetings --audio-asr-model large

Tip: Prefer repo update over repo remove + repo add when you only need to adjust configuration. repo remove discards the entire index, forcing a full re-index; repo update preserves existing indexed documents and only removes those that become excluded.

JSON schema (researcher repo update NAME --json):

{
  "name": "my-notes",
  "path": "/Users/me/Notes",
  "file_types": ["md", "txt"],
  "embedding_provider": "chromadb",
  "embedding_model": null,
  "exclude_patterns": ["node_modules", "dist"],
  "image_pipeline": "standard",
  "image_vlm_model": null,
  "audio_asr_model": "turbo",
  "purged_documents": 3
}

purged_documents is the count of previously-indexed documents removed because they matched the new exclusion patterns. It is 0 when:

• --no-purge was supplied, or
• no new patterns were added (all supplied patterns were already present), or
• no previously-indexed documents happened to match the new patterns.

List Repositories

researcher repo list [--json]

Shows all configured repositories, their paths, file types, and embedding provider.

Remove a Repository

researcher repo remove NAME [--json]

Removes the repository configuration and its entire index data from ~/.researcher/repositories/. This is a destructive operation — the full index is discarded and must be rebuilt with researcher index if the repository is re-added.

Before removing: if you only need to change file types, embedding provider, or exclusion patterns, use repo update instead. repo update preserves the existing index and avoids a full re-index.

---

Embedding Providers

chromadb (default)

• Built-in; no external service required
• Uses ChromaDB's default embedding model
• Best for: getting started quickly, offline use

ollama (local AI)

• Requires Ollama running locally
• Default model: nomic-embed-text
• Best for: privacy-sensitive content, no API costs
• Setup: ollama pull nomic-embed-text && ollama serve

openai (cloud)

• Requires OPENAI_API_KEY environment variable
• Default model: text-embedding-3-small
• Best for: highest quality embeddings, large repositories
• Setup: export OPENAI_API_KEY=sk-...

---

Image Processing

By default, researcher uses OCR (optical character recognition) to extract text from image files (.png, .jpg, .jpeg, etc.). For richer semantic understanding — useful for screenshots, diagrams, and figures — you can switch to a Vision Language Model (VLM) pipeline.

standard (default)

Uses Docling's built-in OCR pipeline. Fast, no additional model downloads required.

vlm (Vision Language Model)

Sends images through a VLM that can understand layout, charts, code blocks, and natural-language descriptions of visual content. Models are downloaded on first use and cached locally.

Enable VLM for a new repository:

researcher repo add screenshots ~/Screenshots --image-pipeline vlm

Switch an existing repository to VLM:

researcher repo update my-vault --image-pipeline vlm --image-vlm-model smoldocling

Available VLM Presets

Preset	Size	Download	Best for	Notes
granite_docling	258M	~500 MB	General screenshots, UI, diagrams. Default.	IBM Granite-based; excellent balance of speed and quality
smoldocling	256M	~500 MB	Speed-critical; low-resource environments	Lightweight; minor quality gap vs granite_docling
granite_vision	2B	~2.4 GB	Visual layouts, tables, charts, infographics	IBM Granite vision; stronger on complex layouts
deepseek_ocr	3B	~6.7 GB	Math, formulas, dense OCR documents	Outputs Markdown, not DocTags
qwen	3B	~5-6 GB	UI/screen grounding; edge deployment	Strong JSON output support
got_ocr	580M	~3-4 GB	High-precision OCR; math, sheet music	F1 ~0.95+ on English/Chinese OCR
phi4	5.6B	~10 GB	Multimodal (image + audio); math reasoning	Matches Gemini Flash on document understanding
pixtral	12B	~24 GB	Complex multi-image; handwriting	Mistral-based; handles arbitrary image sizes
gemma_12b	12B	~20 GB	Complex multi-page; 128K context	Requires high-end GPU
gemma_27b	27B	~50 GB	Maximum accuracy	Highest resource requirement
dolphin	varies	varies	Alternative ByteDance model

Note: Models download automatically on the first indexing run after switching to vlm. Download sizes range from ~500 MB (smoldocling, granite_docling) to ~50 GB for the largest models. Ensure sufficient disk space and a stable internet connection before the first run.

---

Audio Processing

Researcher can transcribe audio and video files using OpenAI Whisper models via Docling's ASR (Automatic Speech Recognition) pipeline. Transcribed text is chunked and indexed alongside all other document types.

Supported audio/video formats include: .mp3, .mp4, .wav, .m4a, .ogg, .flac, .webm, and others supported by Docling's audio backend.

To index audio files, add their extensions to --file-types:

researcher repo add meetings ~/Recordings --file-types mp3,mp4,wav,m4a

The ASR model is configured per repository with --audio-asr-model. Models are downloaded on first use and cached locally.

Available ASR (Whisper) Models

Model	Params	Download	WER	Speed	Best for
tiny	39M	~140 MB	Highest	~1-2x real-time	Edge devices, real-time, extreme resource constraints
base	74M	~290 MB	High	~2-3x	Mobile, basic transcription
small	244M	~770 MB	Medium	~5-10x	Good balance, local deployment
medium	769M	~1.5 GB	Lower	~10-20x	Cloud deployments, standard use
large	1.55B	~2.9 GB	~3-4%	~20-40x	Maximum accuracy, offline batch processing
turbo	809M	~1.6 GB	~1.9%	~216x real-time	Default. Large-v2 quality at 6x the speed

WER = Word Error Rate (lower is better). Speed is relative to audio duration (e.g. 216x means a 1-hour recording transcribes in ~17 seconds).

Recommendations:

• Most users: turbo (default) — near-large accuracy at a fraction of the cost
• Resource-constrained: small or base
• Maximum accuracy: large
• Real-time / live use: tiny or base

Examples:

# Default (turbo) — good for most meeting recordings
researcher repo add meetings ~/Recordings --file-types mp3,mp4,wav

# High accuracy for lecture archive
researcher repo add lectures ~/Lectures --file-types mp4,m4a --audio-asr-model large

# Lightweight for a low-powered machine
researcher repo add podcasts ~/Podcasts --file-types mp3 --audio-asr-model small

# Switch an existing repo to a more accurate model
researcher repo update meetings --audio-asr-model medium

---

Indexing

Index All Repositories

researcher index [--json]

Index a Specific Repository

researcher index <repo-name> [--json]

How indexing works:

• Scans the repository path for files matching configured --file-types
• Uses SHA-256 checksums to detect changes — already-indexed unchanged files are skipped
• New and modified files are re-chunked and re-embedded
• Deleted files are removed from the index

Run indexing:

• After adding a new repository for the first time
• After adding, editing, or deleting documents
• On a schedule (cron) to keep an auto-updating knowledge base current

---

Document Removal

Remove a specific document from the index without re-indexing the whole repo:

researcher remove <repo-name> <document-path> [--json]

Example:

researcher remove my-notes ~/Notes/old-meeting-2023.md

The document path should match the path as it was indexed. Use researcher status to confirm removal.

---

Index Status

# All repositories
researcher status [--json]

# One repository
researcher status <repo-name> [--json]

Shows per-repository statistics: document count, fragment count, embedding provider, and last-indexed information.

---

Agent Use: JSON Mode

Always use --json (or -j) when processing admin command output programmatically. This bypasses Rich terminal formatting and writes clean JSON to stdout. Progress spinners are suppressed in JSON mode.

researcher index --json schema

{
  "repositories": [
    {
      "repository": "my-notes",
      "documents_indexed": 5,
      "documents_skipped": 37,
      "documents_failed": 0,
      "fragments_created": 50,
      "errors": []
    }
  ]
}

researcher status --json schema

{
  "repositories": [
    {
      "repository_name": "my-notes",
      "total_documents": 42,
      "total_fragments": 318,
      "last_indexed": "2026-02-20T10:00:00"
    }
  ]
}

last_indexed is an ISO 8601 string when set, or null if the repository has never been indexed.

researcher repo list --json schema

{
  "repositories": [
    {
      "name": "my-notes",
      "path": "/Users/me/Notes",
      "file_types": ["md", "txt"],
      "embedding_provider": "chromadb",
      "embedding_model": null,
      "exclude_patterns": ["node_modules", ".*"],
      "image_pipeline": "standard",
      "image_vlm_model": null,
      "audio_asr_model": "turbo"
    }
  ]
}

exclude_patterns is always present; it is an empty array when no patterns have been configured. image_pipeline is always present ("standard" or "vlm"). image_vlm_model is null unless a specific VLM preset was set. audio_asr_model is always present (default: "turbo").

researcher repo add NAME PATH --json schema

{
  "name": "my-notes",
  "path": "/Users/me/Notes",
  "file_types": ["md", "txt"],
  "embedding_provider": "chromadb",
  "embedding_model": null,
  "exclude_patterns": ["node_modules", ".*"],
  "image_pipeline": "standard",
  "image_vlm_model": null,
  "audio_asr_model": "turbo"
}

exclude_patterns is always present; it is an empty array when no --exclude flags were supplied. image_pipeline is always present ("standard" or "vlm"). image_vlm_model is null unless a specific VLM preset was set. audio_asr_model is always present (default: "turbo").

researcher repo update NAME --json schema

{
  "name": "my-notes",
  "path": "/Users/me/Notes",
  "file_types": ["md", "txt"],
  "embedding_provider": "chromadb",
  "embedding_model": null,
  "exclude_patterns": ["node_modules", "dist"],
  "image_pipeline": "vlm",
  "image_vlm_model": "smoldocling",
  "audio_asr_model": "turbo",
  "purged_documents": 3
}

purged_documents is 0 when --no-purge is used, when no new patterns were added, or when no previously-indexed documents matched the new patterns.

researcher repo remove NAME --json schema

{"name": "my-notes", "removed": true}

researcher remove REPO DOC --json schema

{
  "repository": "my-notes",
  "document_path": "/Users/me/Notes/old.md",
  "removed": true
}

Error schema (any command with --json)

{"error": "Repository 'foo' not found"}

Exit code is 1 on error regardless of JSON mode.

---

Configuration

Show Current Configuration

researcher config show

Output example:

default_embedding_model: null
default_embedding_provider: chromadb
mcp_port: 8392
repositories: [...]

Set a Configuration Value

researcher config set <key> <value>

Key	Example	Purpose
default_embedding_provider	openai	Provider used when --embedding-provider is not set on repo add
default_embedding_model	text-embedding-3-small	Model used when --embedding-model is not set
mcp_port	8392	Default HTTP port for researcher serve --port

Examples:

# Switch default provider to Ollama globally
researcher config set default_embedding_provider ollama

# Set a global default model
researcher config set default_embedding_model nomic-embed-text

# Change default HTTP port
researcher config set mcp_port 9000

Config File Location

researcher config path
# → ~/.researcher/config.yaml

---

Serving the MCP Server

stdio Mode (for Claude Code)

researcher serve

Used when Claude Code (or another MCP client) launches researcher as a subprocess. Configure in your Claude Code MCP settings:

{
  "mcpServers": {
    "researcher": {
      "command": "researcher",
      "args": ["serve"]
    }
  }
}

HTTP Mode (for other clients)

researcher serve --port 8392

Starts an HTTP MCP server. Useful for connecting multiple clients or running as a background service.

---

MCP Admin Tools

When the MCP server is running, these tools are available:

add_to_index

add_to_index(repository, document_path)

Index a single document into an existing repository without re-running a full index.

remove_from_index

remove_from_index(repository, document_path)

Remove a specific document from the index.

list_repositories

list_repositories()

Returns all configured repository names and paths.

get_index_status

get_index_status(repository?)

Returns indexing statistics. Omit repository for all repos.

---

Storage Layout

~/.researcher/
├── config.yaml          # Main configuration (repos, defaults, port)
└── repositories/        # Index data per repository
    ├── my-notes/        # ChromaDB collection for "my-notes"
    └── research/        # ChromaDB collection for "research"

---

Supported File Types

Extension	Format
.md	Markdown
.txt	Plain text
.pdf	PDF documents
.docx	Word documents
.html	HTML pages
.pptx	PowerPoint presentations
.xlsx	Excel spreadsheets
.csv	CSV data files
.png	PNG images
.jpg / .jpeg	JPEG images
.tiff	TIFF images
.bmp	BMP images
.mp3	MP3 audio
.mp4	MP4 video
.wav	WAV audio
.m4a	M4A audio
.ogg	OGG audio
.flac	FLAC audio
.webm	WebM audio/video

The default set when adding a new repository is md,txt,pdf,docx,html. Customize per repository with --file-types on repo add, or change the list at any time with repo update --file-types.

Audio and video files are transcribed using the configured Whisper ASR model. Image files are processed using either the standard OCR pipeline or a VLM pipeline.

---

Common Setup Workflow

# 1. Add a repository
researcher repo add my-notes ~/Notes

# 2. Run initial indexing
researcher index my-notes

# 3. Check it worked
researcher status my-notes

# 4. Search to verify
researcher search "test query" --repo my-notes

# 5. Configure MCP server in Claude Code settings, then serve
researcher serve