Skip to content

Getting Started

Jump to bottom
Jean-Baptiste THERY edited this page Jul 14, 2026 · 2 revisions

Getting started

This guide takes a repository from no Ragmir state to verified cited context for a coding agent or script. Ragmir requires Node.js 20 or later and keeps generated state under the ignored .ragmir/ directory.

1. Install Core in the repository

With pnpm:

pnpm add -D @jcode.labs/ragmir

With npm:

npm install --save-dev @jcode.labs/ragmir

The examples below use pnpm exec rgr. Replace it with npx rgr in an npm project.

2. Initialize local state

pnpm exec rgr setup --agents codex

Setup creates .ragmir/config.json, adds the local state directory to Git ignore rules, prepares the project runner, and installs the selected project-scoped agent helper. Replace codex with a comma-separated list such as claude,codex,kimi,opencode,cline, or omit --agents when a script will call the CLI or TypeScript API directly. Core uses the offline local-hash retrieval provider unless semantic retrieval is selected explicitly.

3. Select the evidence

Add only the paths the knowledge base should search. Entries may be files, directories, globs, or ! exclusions.

pnpm exec rgr sources add "docs/**/*.md" "src" "!docs/archive/**"
pnpm exec rgr sources list

Use separate Ragmir bases when parts of a monorepo have different trust boundaries or unrelated knowledge. rgr bases shows which base is active from the current directory.

4. Preview before indexing

Preview applies the active extraction, redaction, and chunking rules without writing an index.

pnpm exec rgr preview --path docs --max-files 5 --max-chunks 3

Review the source paths, redacted text, structural context, citations, and chunk-size summary. Adjust the source list or configuration before continuing if the preview includes material that should not be retrievable.

5. Ingest and search

pnpm exec rgr ingest
pnpm exec rgr search "Which decision changed the rollout?" --top-k 5

Ingestion is incremental. Each result identifies the source file and indexed chunk, with line ranges and PDF pages when available. Use --compact for a smaller machine-readable handoff or --json in automation.

6. Verify the knowledge base

pnpm exec rgr doctor
pnpm exec rgr audit --unsupported
pnpm exec rgr security-audit
  • doctor checks setup, index freshness, and local integrations.
  • audit --unsupported compares configured sources with the index and reports skipped files.
  • security-audit checks ignored state, redaction, retrieval bounds, and other local controls.

Run pnpm exec rgr ingest --rebuild after changing the embedding provider, embedding model, or chunking fields. Ordinary source edits only need incremental ingest.

Supported content

Ragmir handles common project and knowledge-base material:

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

Images and legacy .doc files need an explicitly configured local extractor. Ragmir does not claim universal binary support, so use audit --unsupported to see exactly what was skipped and why.

Choose the next interface

Goal Continue with
Operate the index from a terminal or script CLI Reference
Adapt a complete project workflow Use Cases
Give a coding agent or script bounded cited passages Agent Integration
Embed retrieval in a Node.js application TypeScript API
Tighten local privacy controls Security Hardening
Generate answers with an optional local model Offline Chat
Render a local audio brief Offline TTS

The repository README is the canonical source for installation, supported content, and current workflows.

Ragmir

Project

Clone this wiki locally