Skip to content

Home

Jump to bottom
Jean-Baptiste THERY edited this page Jul 19, 2026 · 17 revisions

Ragmir

Confidential local RAG for coding agents, scripts, and Node.js applications.

Ragmir turns specifications, Word files, PDFs, spreadsheets, code, and local exports into cited evidence indexed and retrieved on your machine. Core works offline by default, never uploads your corpus, and calls no model. Connect the AI or automation you already use through CLI, MCP, or a typed TypeScript API, or keep the complete workflow local with the optional Chat package.

Website · npm · Repository · Releases · Licensing

Start in 60 seconds

The fastest path is to let your coding agent inspect the repository and tailor the setup.

Option 1: paste this into your coding agent 
Set up Ragmir in this repository. Work interactively: inspect first, ask one concise numbered batch of questions, wait for my answers, then execute. Never assume consent for dependency changes, model downloads, replacing skills, or sharing data.

Outcome: Core installed with the repository's package manager; useful sources selected; secrets and generated noise excluded; tools connected; cited retrieval verified. Semantic retrieval, team features, Chat, and TTS are optional.

1. Inspect without changes:
- Find the repository or monorepo root. Read package.json packageManager, lockfiles, workspace and Node/version-manager files, .gitignore, existing .ragmir state, README, AGENTS/CLAUDE/CODEX guidance, docs, specs/ADRs, apps/packages, important config, source, and tests.
- Detect Node 22+ and pnpm, npm, Yarn, or Bun. Prefer packageManager, then the lockfile. Respect workspace-root flags and mise/asdf/Volta. Never create a second lockfile. If signals conflict, ask.
- If Ragmir exists, inspect its version, config, status, sources, and rgr upgrade --check before changing it.

2. Ask only what the repository did not answer, then wait:
1) Which repository/monorepo base should own the knowledge base, and are nested app bases wanted?
2) Which clients: Claude Code, Codex, Kimi, OpenCode, Cline, another MCP client, or none?
3) Keep default offline local-hash, or allow one semantic-model download for better natural-language retrieval?
4) Solo or team? If team, is Git upstream authoritative, and should safe pulls be automatic or disabled with --no-pull?
5) Core only, or optional Chat? For Chat choose lite (~0.49 GB), fast (~3.35 GB), or quality (~5.15 GB).
6) Optional TTS? Ask language (en/fr/es offline; ja/th/zh require explicit Edge unless a local model is supplied) and whether text may reach Edge.
7) Which private/external folders are allowed, which must never be indexed, and may I install packages, edit local config, and run approved downloads now?

3. Implement after approval:
- Install @jcode.labs/ragmir as a dev dependency with the detected manager. Install Chat/TTS only if selected, at a compatible version.
- Run the matching rgr setup --no-ingest --agents <selected> command. Keep project scope. If a same-name skill is unmanaged, show the diff and ask before --force.
- Build a narrow .ragmir/config.json. Prefer stable relative globs for root guidance, docs/specs/ADRs, package READMEs/manifests, useful app config, and source/tests that explain behavior. Include locales only when useful.
- Exclude .env*, credentials, keys, unapproved dumps/customer data, dependencies, generated/build/cache/coverage/log folders, vendored code, binaries/media, and .ragmir storage/models. In monorepos, keep nested bases scoped and shared knowledge at root.
- Run preview and audit --unsupported before ingest. Review redactions, unsupported/oversized files, duplicates, chunks, and sensitive paths. Fix config first, then ingest.
- For an existing install, use rgr upgrade and doctor --fix as indicated. Never delete the active index first. Rebuild only for incompatible embedding, chunk, or index-policy changes.
- Enable semantic retrieval, preload Chat, or preload TTS only after consent. Use non-sensitive TTS preload text.
- For Git teams, run rgr team sync. It safely pulls and ingests; --no-pull keeps Git manual. Snapshots are advanced diagnostics.

4. Prove the result:
- Run rgr doctor --deep, rgr audit --unsupported, and rgr security-audit.
- Run representative searches with citations and --explain. Create a small local golden suite for project questions and run rgr evaluate; do not weaken gates to pass.
- Report detected tools, answers, packages, downloads, config/sources/exclusions, changed files, readiness, retrieval results, team status, and exact remaining actions.

Never commit .ragmir, corpus files, models, snapshots, logs, or secrets. Never claim offline, semantic, team synchronization, or retrieval quality without evidence.

Prefer manual setup? Ragmir requires Node.js 22 or later. Install it in the project that owns the files to search:

pnpm add -D @jcode.labs/ragmir
pnpm exec rgr setup --agents codex,claude,kimi,opencode,cline
pnpm exec rgr sources add "README.md" "docs/**/*.md"
pnpm exec rgr ingest
pnpm exec rgr search "Which decision changed the rollout?"

Using npm? Replace pnpm add -D with npm install --save-dev and pnpm exec with npx. At a pnpm workspace root, use pnpm add -Dw.

rgr setup creates ignored local state under .ragmir/ and connects the selected agents. Ingestion is incremental and resumable. Use rgr doctor to confirm readiness.

Why Ragmir

Strength What it gives you
Local by default Corpus, index, reports, and metadata-only logs stay under ignored .ragmir/ state
Verifiable evidence File and chunk references plus format-native source coordinates when available
Model-agnostic Core Cited retrieval for compatible agents, scripts, CLI, MCP, and TypeScript
Production-grade ingestion Bounded work, per-file durable progress, atomic rebuild activation, and local writer serialization
Inspectable retrieval Hybrid ranking explanations, evidence thresholds, stable tie-breaks, and vector diagnostics
Open source AGPL-3.0-only packages, a commercial option for proprietary use, and no hosted Ragmir account

The default local-hash provider needs no model download. Semantic Transformers.js embeddings, local OCR, Chat, and TTS are explicit optional setup steps.

How retrieval works

flowchart LR
    A["Project files you choose"] --> B["Extract and redact"]
    B --> C["Chunk and index locally"]
    C --> D["Retrieve bounded evidence"]
    D --> E["CLI"]
    D --> F["TypeScript"]
    D --> G["MCP agent"]
    D -. optional .-> H["Local Chat or audio"]
    B -. blank PDF pages .-> I["Configured local OCR"]
Loading

Ragmir opens no HTTP port. A network-facing application owns transport security, authentication, authorization, and rate limits.

Choose an interface

Interface Best for
rgr CLI Setup, ingest, cited search, audit, and maintenance
TypeScript API Scripts and long-running Node.js workers
Local MCP server Coding agents and compatible clients
Ragmir Chat Optional fully local answer generation
Ragmir TTS Local WAV or explicit online MP3 from reviewed text

Core remains retrieval-first: ask() returns cited context, not a generated answer. Chat and TTS are separate optional packages loaded only when their commands are used.

Teams

flowchart LR
    A["Merge into the declared upstream"] --> B["rgr team sync"]
    B --> C["Safe Git fast-forward"]
    C --> D["Incremental local ingest"]
    D --> E["Ready private index"]
Loading

Git-backed teams keep one private index per developer. The current branch upstream is the only declared authority, so Git handles review and Ragmir keeps private evidence fresh:

  1. Open and review a pull request (or merge request).
  2. Merge it into the declared upstream.
  3. Run rgr team sync on each workstation that needs fresh evidence.

Ragmir fast-forwards only a clean non-divergent branch and reindexes changed sources incrementally. Otherwise it leaves history and the valid index alone, then returns one action. Use --no-pull to keep branch updates manual or --check to preview. Snapshots are an advanced fallback for non-Git sources or exact drift analysis, including existing v2.19 snapshots.

After updating Ragmir, run rgr upgrade --check, then rgr upgrade when required. Any incompatible replacement is built and validated separately before atomic activation; the previous valid index is never deleted first. Privacy warnings remain visible as non-blocking advisories and do not mislabel an operational index as needing repair.

Guides

Start with Getting Started, then choose the focused guide for your interface or operational concern. The repository remains canonical for the complete README, API reference, examples, and release history.

Ragmir

Project

Clone this wiki locally