Skip to content

Configuration

Jump to bottom
Jean-Baptiste THERY edited this page Jul 18, 2026 · 7 revisions

Configuration

Ragmir reads .ragmir/config.json from the current directory or an ancestor. Start with rgr setup and edit JSON only for a concrete need.

{
  "sources": ["docs/**/*.md", "src", "!docs/archive/**"],
  "privacyProfile": "private",
  "retrievalProfile": "balanced",
  "embeddingProvider": "local-hash"
}

Common fields

Field Default Why change it
sources [] Add paths, globs, and ! exclusions
privacyProfile private Use strict for the strongest local floor
retrievalProfile balanced Choose fast, quality, or an explicit custom budget
embeddingProvider local-hash Select transformers only after an explicit preload
embeddingModelRevision Pinned for bundled profiles Keep model identity reproducible
embeddingModelDigest null until model pull Verify the resolved local artifact tree
topK 8 Change the default passage count
mcpMaxTopK 10 Bound passage requests from MCP consumers
mcpMaxOutputBytes 32768 Bound variable-size MCP tool and resource JSON; the server also enforces an absolute 1 MiB ceiling
chunkSize / chunkOverlap 1200 / 200 Tune chunking, then rebuild
maxFileBytes 50000000 Lower the per-file parser budget; 50 MB is the hard ceiling
ingestConcurrency 4 Bound concurrent parsers; values above 8 are rejected
sourceFingerprintMode fast Use strict when sync tools may preserve changed-file metadata
incrementalFailurePolicy preserve-last-good Choose whether stale evidence remains available after a failed changed file
workloadLimits Bounded defaults Tune active work, queue length, and queue deadlines only after benchmarking
includeExtensions [] Add safe custom text extensions

Changing an embedding provider, model, or chunking field requires a rebuild. After a package update, use rgr upgrade so Ragmir stages that rebuild without deleting the active index first.

Stable team source configuration

Prefer stable directories and globs over a tracked configuration regenerated from whichever files exist on one machine. The active .ragmir/config.json stays local and ignored. A project can version a reviewed template while keeping machine-specific paths local. Git-backed teams use rgr team sync for the normal loop: fetch the current upstream, apply only a safe fast-forward, then ingest locally. --no-pull keeps branch updates manual and --check previews without changes.

When Git is current but results still differ, use rgr team snapshot and rgr team compare for advanced source-contract and per-file drift diagnostics. The lower-level corpusFingerprint remains a quick equality signal.

Semantic retrieval

rgr setup --semantic
rgr ingest --rebuild

This preloads the configured Transformers model once and leaves remote model loading disabled for normal retrieval. rgr models pull --enable enables the same provider after initial setup.

Privacy profiles

  • private defaults remote model loading to disabled and keeps redaction enabled; remote Transformers loading still requires an explicit opt-in.
  • strict also bounds MCP output and disables every external extractor.
  • trusted and custom are explicit operator choices for different controls.

The privacy profile is a safety floor, separate from retrieval quality.

Local extractors

rgr ocr doctor
rgr ocr setup --language eng+fra

OCR is optional and page-aware. Custom extractor commands must be JSON argument arrays. They execute without a shell and must print text to stdout.

Environment overrides

Use RAGMIR_* environment variables for local experiments, then run rgr status --json to inspect the effective configuration.

For a long-running process with multiple isolated project workflows, create one client per project root with createRagmirClient({ cwd }), keep process-wide environment overrides stable after startup, and close every client during shutdown. Ragmir serializes writers across local OS processes with a private heartbeat lock under storageDir; readers stay available. This is not a distributed lock, so do not put one writable index on a shared network filesystem.

Parser safety limits

Run rgr limits to inspect fixed parser ceilings. Office archives allow at most 512 text entries, 25 MB per entry, and 50 MB of expanded text in total. PDF extraction is capped at 1,000 pages and 25 million text characters. Combined stdout and stderr from a local external extractor are capped at 25 MB; files above maxFileBytes are skipped and reported.

Canonical source: docs/configuration.md.

Ragmir

Project

Clone this wiki locally