Ragmir

Confidential local RAG for your coding agents.

Ragmir indexes the project files you choose on your machine and retrieves bounded, cited evidence offline by default. The corpus and generated index remain local, so confidential source files are not uploaded to a hosted RAG service. Connect through project-scoped agent skills, a local MCP server, the CLI, or the TypeScript API. The default local-hash path needs no account, API key, or model download.

Bring the coding agent or automation you already use. Ragmir Core retrieves evidence without calling a model. If no retrieved passage may leave the machine, use a local consumer or Ragmir Chat for cited answer generation from a verified local model.

Website · npm · Documentation · CLI reference · Examples

Give your coding agent cited project evidence

Ragmir requires Node.js 20 or later. Install it in the repository that owns the files you want to search:

pnpm add -D @jcode.labs/ragmir
pnpm exec rgr setup --agents codex,claude,kimi,opencode,cline
pnpm exec rgr sources add "docs/**/*.md"
pnpm exec rgr ingest
pnpm exec rgr doctor

Then ask the selected agent:

Use Ragmir to find which decision changed the rollout. Cite every claim and expand the strongest
citation before you propose an edit.

rgr setup creates ignored local state under .ragmir/, installs project-scoped native skills, and writes local MCP helpers. rgr ingest is incremental and commits resumable batches of 25 files by default. Re-run the same command after an interruption to continue from the last committed batch. The agent receives bounded passages with the source path, excerpt, chunk, line range, and PDF page when one is available.

Prefer a direct search? Run:

pnpm exec rgr search "Which decision changed the rollout?"

Using npm instead of pnpm? Replace pnpm add -D with npm install --save-dev and pnpm exec with npx. At a pnpm workspace root, use pnpm add -Dw; otherwise install Ragmir in the package that owns the source files.

Pick the interface your workflow needs

Interface	Use it for	Result
rgr CLI	Setup, ingest, search, audit, and maintenance	Human-readable or JSON output
TypeScript API	Embed retrieval in a script or stateful Node.js worker	Typed results with citations and explicit lifecycle
Local MCP server	Give your preferred agent bounded project context	Read-focused retrieval tools
Ragmir Chat	Keep answer generation on the workstation	Cited offline synthesis
Ragmir TTS	Turn a text brief into audio	Local WAV or explicit online MP3

Use the CLI or MCP for interactive agent work. Use the TypeScript API when a repeatable Node.js process owns the control flow. Ragmir does not open an HTTP port: applications own their network, authentication, and authorization boundary.

Ragmir Core stays retrieval-first. ask() returns cited context without calling an LLM. Local chat and audio are separate capabilities, so retrieval remains useful on machines that should not run a generative model.

How it works

flowchart LR
    A["Files selected by the project"] --> B["Extract and redact text"]
    B --> C["Chunk and index locally"]
    C --> D["Cited search results"]
    D --> E["CLI"]
    D --> F["TypeScript API"]
    D --> G["AI and automation over MCP"]
    D -. optional .-> H["Local GGUF chat"]
    B -. blank PDF pages .-> I["Configured local OCR"]

Loading

The generated index, model cache, reports, and access log stay under ignored .ragmir/ state. Project paths are resolved from the caller's working directory or explicit configuration, never from the installed npm package.

Common workflows

Connect a coding agent or script

Setup links skills into supported agents' native project folders and writes local MCP helpers backed by a generated project runner. Any other MCP client can launch .ragmir/run.cjs. Hermes, local scripts, CI, and internal services can use the same JSON CLI or TypeScript API without a dedicated connector.

The MCP surface is intentionally bounded and read-focused. Agents can request compact evidence first, then expand one returned citation without opening a second index or reading arbitrary files. MCP clients can read ragmir://context for a compact base, readiness, freshness, and capability overview before choosing a tool.

Core is model-agnostic: any compatible CLI, TypeScript, or MCP consumer can use the returned citations. A hosted AI receives the passages you return to it under that provider's data policy. A local consumer keeps the handoff on the workstation, and the optional Chat package adds local answer generation when the whole workflow must remain offline.

Route knowledge in a monorepo

pnpm exec rgr bases
pnpm exec rgr --project-root apps/web search "checkout contract"

Ragmir selects the nearest .ragmir/config.json from the working directory. A monorepo can keep a root base for shared knowledge and isolated bases in individual apps. rgr bases shows the active base, generated MCP helpers pin their project root, and nested bases receive distinct server names so agents do not silently query the wrong index.

Audit a knowledge base

pnpm exec rgr preview --path docs --max-chunks 3
pnpm exec rgr audit --unsupported
pnpm exec rgr security-audit
pnpm exec rgr research "release obligations" --compact

Use this path for policies, runbooks, specifications, contracts, and other corpora where the answer must remain traceable to evidence. preview shows redacted chunks, structural context, citations, and size distributions without writing an index.

Explain retrieval decisions

pnpm exec rgr search "release approval" --explain
pnpm exec rgr search "release approval" --context-path "Operations > Release"

Explanations expose reciprocal-rank-fusion contributions, vector and lexical ranks, backend scores, and matched terms without changing default ranking. Structural filters can target Markdown heading paths or JSON paths before candidate retrieval.

Enable semantic retrieval

pnpm exec rgr setup --semantic
pnpm exec rgr ingest --rebuild

The default local-hash provider is offline lexical/hash retrieval. Semantic mode uses Transformers.js and requires an explicit model download or a preloaded local model.

Resume a long ingestion

pnpm exec rgr ingest --batch-size 25
pnpm exec rgr status --json

Ragmir records per-file progress atomically under ignored .ragmir/storage/ state. Files from a committed batch are not parsed or embedded again after a restart. A full --rebuild writes to an isolated generation and activates it only after row and manifest validation, so an interrupted rebuild leaves the previous searchable index active.

Search scanned PDFs

pnpm exec rgr ocr setup --engine auto
pnpm exec rgr ingest --rebuild

Embedded PDF text is always preferred. OCR runs only for blank pages, through a configured local executable. Ragmir does not use a cloud OCR service.

Supported content

Ragmir handles common project and knowledge-base material, including:

• Markdown, plain text, source code, configuration, logs, CSV, JSON, JSONL, and YAML;
• PDF with page-aware citations, plus optional local OCR for blank pages;
• DOCX, PPTX, XLSX, OpenDocument files, EPUB, HTML, RTF, email, and notebooks;
• additional text extensions configured by the project.

Run rgr audit --unsupported to see what was skipped and why. Ragmir does not claim universal binary support.

TypeScript API

import { createRagmirClient, isRagmirError } from "@jcode.labs/ragmir"

const ragmir = await createRagmirClient({ cwd: process.cwd() })
try {
  await ragmir.ingest({ timeoutMs: 120_000 })

  const results = await ragmir.search("Which decision changed the rollout?", {
    topK: 5,
    explain: true,
    timeoutMs: 10_000,
  })

  for (const result of results) {
    console.log(result.citation, result.text)
  }
} catch (error) {
  if (isRagmirError(error)) console.error(error.code, error.retryable)
  else throw error
} finally {
  await ragmir.close()
}

Reuse one client per project root in a long-running process. It keeps one local LanceDB connection, serializes ingestion for the same index inside that process, accepts AbortSignal and timeoutMs, and waits for active operations during close(). One-shot ingest, search, ask, and research functions remain available for short scripts.

Core also exports previewChunks, audit, doctor, securityAudit, bounded context helpers, closeable MCP construction helpers, and setup helpers. See the API reference for the complete public surface.

Privacy boundaries

Capability	Default behavior	Network boundary
Core retrieval	Local files, local index, local-hash retrieval	No network service required
Preferred AI or automation	Receives only the passages the integration requests	The consumer's data policy applies; use a local consumer when passages must not leave
Semantic embeddings	Disabled until explicitly enabled	Model download is explicit; inference can then stay local
PDF and image OCR	Disabled until a local command is configured	No cloud OCR integration
Ragmir Chat	Local inference from a verified GGUF profile	Setup may download the selected profile; answer generation then stays local
Ragmir TTS	Local Transformers.js WAV rendering	Edge MP3 mode sends narration text when explicitly selected

Redaction reduces accidental exposure but is not a compliance certification. Review the security hardening guide before using sensitive corpora.

Packages

Package	Use it when you need
@jcode.labs/ragmir	CLI, retrieval API, MCP server, OCR configuration, and agent helpers
@jcode.labs/ragmir-chat	Optional cited generation with a local GGUF model
@jcode.labs/ragmir-tts	Optional local audio or explicit online voice rendering

Installing Core does not install Chat or TTS. Add only the optional package needed by the workflow.

Runnable examples

Example	What it proves
Confidential local RAG demo	End-to-end CLI ingestion, retrieval, redaction, audit, and evaluation
Library API demo	The public TypeScript API against a synthetic local corpus
Document evidence benchmark	Deterministic recall and exact file, line, chunk, and PDF-page citations

Every committed example uses fictional data. Keep private evaluation corpora and generated reports outside Git or under ignored local state.

Technology

• TypeScript and Node.js for the portable CLI, library, MCP server, and add-ons.
• LanceDB for embedded local storage.
• Transformers.js for optional semantic embeddings and offline audio models.
• Model Context Protocol TypeScript SDK for agent integrations.
• node-llama-cpp for optional local GGUF generation.
• Astro, React, and Tailwind CSS for the static, telemetry-free project site.

Documentation

Browse the project wiki to navigate the complete documentation. The versioned files below remain canonical for releases, npm packages, Context7, and pull-request review.

Guide	Read it when you need
Project wiki	Browse every guide from one documentation index
CLI reference	Commands, options, and JSON output
API reference	TypeScript exports and result shapes
Release history	Generated notes, compatibility changes, and verification artifacts
Changelog	Semantic Versioning and API compatibility policy
Configuration	Sources, privacy profiles, models, limits, and extractors
Agent integration	Native helpers and MCP clients
Troubleshooting	Empty indexes, OCR, retrieval, or local-model problems
Offline chat	Prepare and verify a GGUF model
Offline TTS	Prepare and render confidential narration

Contributing

The repository is a pnpm workspace and uses the Node.js version pinned in mise.toml:

pnpm bootstrap
pnpm validate
pnpm example

Read CONTRIBUTING.md before opening a pull request. Report vulnerabilities through SECURITY.md, not a public issue. Release history is available in GitHub Releases, with compatibility policy in CHANGELOG.md.

License

Ragmir is open source under the MIT License.

Created and maintained by Jean-Baptiste Théry through jCode Works.