Ragmir

Local RAG for your coding agents.

Ragmir indexes the project files you choose, keeps the index on your machine, and gives coding
agents and local scripts bounded evidence with verifiable citations. Connect through project-scoped
agent skills, a local MCP server, the CLI, or the TypeScript API. The default path needs no account,
hosted document store, 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. 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

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.

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.

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

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.