llms.txt

# Ragmir

Ragmir is an open-source confidential local RAG for coding agents, scripts, and Node.js
applications. It turns selected project files into cited evidence indexed and retrieved locally
through CLI, TypeScript, or a read-focused MCP server. Core works offline by default, never uploads
the corpus, and calls no model.

## Core facts

- Install: `pnpm add -D @jcode.labs/ragmir`
- Licensing: v3.0.0 and later use AGPL-3.0-only. JCode Works offers a separate commercial license
  for proprietary use, while earlier releases keep their published license.
- Agent-guided setup: use the canonical English prompt in
  https://raw.githubusercontent.com/jcode-works/jcode-ragmir/main/docs/quick-start.md
- First use: `pnpm exec rgr setup && pnpm exec rgr ingest`
- Resumable ingestion: `rgr ingest` commits 25 files per durable batch by default. Re-run it after an
  interruption, inspect progress with `rgr status --json`, and use `--batch-size` to change the
  checkpoint size. Rebuilds stay isolated until final manifest validation and activation.
- Optional ingestion observability: `rgr ingest --metrics --json` attributes queue, write-lock,
  discovery, hashing, parsing, redaction, chunking, embedding, Lance payload write, and maintenance
  time, plus throughput and bounded counters. Diagnostics omit project roots, paths, queries, and
  source text; timers and RSS samples stay disabled unless requested or locally subscribed.
- CLI: `rgr preview`, `rgr search "query" --explain`, `rgr bases`, `rgr doctor`, `rgr audit`, and
  `rgr security-audit`
- Lightweight health: `rgr status`, normal `rgr doctor`, and MCP context read compact manifest
  metadata without opening the vector table. Use `rgr doctor --deep` or `rgr audit` for explicit
  O(corpus) live diagnostics. Missing or invalid manifests are never ready.
- MCP retrieval: search, ask, and research start with at most three compact document citations by
  default; research may add up to three code matches. Expand one selected citation; use
  `compact: false` only for an explicit full payload. CLI compact output remains opt-in.
- Core behavior: cited retrieval only. `ask` returns evidence, while synthesis belongs to the calling
  agent or optional local chat add-on.
- Agentic RAG boundary: Ragmir supplies bounded, cited evidence to a host agent or automation;
  planning, tool use, and action authority remain in that host.
- Consumer choice: use the AI or automation you already have through CLI, TypeScript, or MCP. Use a
  local consumer or optional Chat when no retrieved passage may leave the machine.
- Portable knowledge: `rgr portable export` creates a frozen relocatable folder with the active
  index, required local embedding model, read-only launcher, two skills, MCP adapters, and SHA-256
  inventory. Raw sources and access logs are excluded; indexed passages remain sensitive.
- Persistent API: `createRagmirClient()` reuses one local connection and immutable read snapshot in
  a stateful Node.js worker, refreshes after atomic generation replacement, supports cancellation
  and timeouts, flushes metadata-only logs during close, and releases the model only after the final
  owner and active inference lease finish.
- Service boundary: Ragmir does not open an HTTP port. Network transports, authentication, and
  authorization belong to the embedding application.
- Default retrieval: local-hash, with no model download or Transformers.js, ONNX Runtime, or Sharp
  resolution. Semantic embeddings and local GGUF chat are explicit opt-ins.
- Embedding identity: bundled Transformers profiles use pinned model commits. Explicit model pull
  records a canonical artifact digest, and model revision plus digest participate in index, vector,
  and quality fingerprints. Changing either requires a rebuild.
- Optional packages: `@jcode.labs/ragmir-chat` offers `lite` Qwen, default `fast` Gemma, and explicit
  `quality` Gemma profiles; `@jcode.labs/ragmir-tts` supports offline `en`, `fr`, and `es`, plus
  explicit online Edge voices for `ja`, `th`, and `zh`.
- Model boundary: Chat profiles and TTS language models are optional. Ragmir Core, its CLI, API, and
  MCP server do not depend on any generative model.
- Privacy boundary: the corpus and index stay local. A cloud agent receives retrieved passages only
  when the user chooses that workflow, under that provider's data policy.
- OCR boundary: embedded PDF text comes first; a configured local executable runs only for blank
  pages. Generated setup batches bounded page groups and caches page text privately by source,
  engine version, language, DPI, parser policy, and command identity. OCR diagnostics contain counts
  and timings, not content. Ragmir has no cloud OCR integration.
- Retrieval inspection: preview redacted chunks without writing storage; optionally expose RRF,
  FTS/fallback and lexical-coverage diagnostics, filter candidates and hydrated neighbors by source
  or structural context, or force exact vector search for ANN diagnostics. Exact file paths use a
  bounded scalar variant; exact phrases, identifiers and rare terms expand the lexical pool only
  when it cannot fill `topK`. Diversification backfills ranked
  non-overlapping chunks after its source-diverse pass.
- Workload admission: search, embedding, and ingestion have separate bounded process-local queues
  per project root. Overload and queue timeout are retryable structured errors; explained searches
  expose queue wait, and shutdown drains accepted work before closing storage.
- Research: language-aware query variants use deterministic weighted cross-query RRF. The normal
  path reads manifest health; a full source audit is explicit. Timeout, code-file, code-byte,
  concurrency, evidence, and MCP byte budgets stay bounded and are reported.
- Adaptive indexing: exhaustive vector search stays active below 100,000 rows. Larger tables use a
  benchmarked IVF-PQ policy only with complete coverage; storage maintenance reports and repairs
  vector, full-text, and relative-path index coverage.
- Monorepos: the nearest configured base is active, nested indexes remain isolated, and generated MCP
  helpers pin a distinct base root.
- Team use: `rgr team sync` fetches the current branch upstream, applies only a clean non-divergent
  fast-forward, then refreshes the private local index. `--no-pull` disables branch updates and
  `--check` previews. Dirty, ahead, diverged, detached, offline, and no-upstream states never rewrite
  history. Advanced snapshots remain available for exact or non-Git drift diagnostics. Keep
  actively written `.ragmir/storage/` directories local to each workstation.
- Upgrade continuity: after a package update and before retrieval with the new runtime,
  `rgr upgrade --check` inspects compatibility and `rgr upgrade` refreshes managed helpers and
  safely stages any required rebuild. Ragmir never deletes the active index first. A long-running
  host can keep its loaded runtime serving, then cut over after `status=current` and `ready=true`.
- MCP resources: `ragmir://context` gives bounded readiness and capability context;
  `ragmir://sources` gives capped source detail with complete totals.
- MCP safety: all ten tools advertise non-destructive behavior; every tool and resource JSON
  response is byte-bounded. Budget pressure selects typed summaries with exact scalar values,
  omission counters, and the best search citation instead of shortening identifiers or paths.
  Search, ask, research, and evaluation conservatively advertise open-world behavior because
  explicitly enabled semantic models may download public weights. Tools that can initialize local
  state or append metadata-only logs use conservative read-only and idempotency hints. Each server
  refreshes its lazy client after effective configuration changes and closes it during shutdown.

## Documentation

- [Documentation wiki](https://github.com/jcode-works/jcode-ragmir/wiki)
- [Quick start](https://raw.githubusercontent.com/jcode-works/jcode-ragmir/main/docs/quick-start.md)
- [README](https://raw.githubusercontent.com/jcode-works/jcode-ragmir/main/README.md)
- [CLI reference](https://raw.githubusercontent.com/jcode-works/jcode-ragmir/main/docs/cli-reference.md)
- [API reference](https://raw.githubusercontent.com/jcode-works/jcode-ragmir/main/docs/api-reference.md)
- [Configuration](https://raw.githubusercontent.com/jcode-works/jcode-ragmir/main/docs/configuration.md)
- [Agent integration](https://raw.githubusercontent.com/jcode-works/jcode-ragmir/main/docs/agent-integration.md)
- [Portable knowledge bases](https://raw.githubusercontent.com/jcode-works/jcode-ragmir/main/docs/portable-knowledge-bases.md)
- [Troubleshooting](https://raw.githubusercontent.com/jcode-works/jcode-ragmir/main/docs/troubleshooting.md)
- [Security hardening](https://raw.githubusercontent.com/jcode-works/jcode-ragmir/main/SECURITY-HARDENING.md)