Ragmir

Confidential local RAG for your coding agents.

Stop sending confidential documents directly to the cloud.

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.

Related MCP server: LumenCore

Pick the interface your workflow needs

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"]

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. Every tool advertises non-destructive behavior, and every tool and resource JSON response is subject to a byte budget. Search, ask, research, and evaluation conservatively advertise open-world behavior because explicitly enabled semantic models may download public weights. Tools that may initialize local state or append metadata-only access logs do not claim read-only or idempotent behavior.

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.

Share one source of truth across a team

Ragmir is local and confidential by design. It has no built-in cloud synchronization. Give every developer the same source folder through a tool such as the Google Drive desktop app or a team script, keep the Ragmir version, configuration, embedding provider, and model aligned, then ingest locally. The result is an equivalent local index on each workstation, not a shared database.

Always sync before rgr ingest, then run rgr audit. A missing, partially synced, or extra file in the selected raw or source folder makes that developer's index diverge. Ragmir hashes file content on every inventory pass, so a changed file is still detected when a sync tool preserves its size and modification time. Teams can automate setup with initProject, addSourceEntries, and createRagmirClient; Ragmir remains the local retrieval layer, not the synchronization layer.

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. After activation, older generated tables stay available so searches that already opened them can finish safely. rgr destroy-index removes all generated index storage.

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

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

Packages

Installing Core does not install Chat or TTS. Add only the optional package needed by the workflow. Choose Chat with --profile lite, fast, or quality; choose offline TTS with --lang en, fr, or es. The package guides explain the model sizes, preload step, and online boundaries.

Runnable examples

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.

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.