Repository navigation
Home
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
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 use? If team, what Git/Drive/folder revision is authoritative and who may receive metadata-only snapshots?
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 teams, ingest locally, create an ignored metadata-only snapshot, compare it, explain every drift, and never choose authority automatically.
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.
| 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 | MIT packages, a static telemetry-free website, 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.
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"]
Ragmir opens no HTTP port. A network-facing application owns transport security, authentication, authorization, and rate limits.
| 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.
flowchart LR
A["Shared source folder"] --> B["Versioned source contract"]
B --> C["Local ingest per developer"]
C --> D["Ready index"]
D --> E["Export team snapshot"]
E --> F["Compare and resolve exact drift"]
Teams use Git, Drive, or their existing file workflow to synchronize one source of truth, then
build one local index per developer. rgr team snapshot exports authorized metadata without source
text or absolute project paths. rgr team compare names version, configuration, local-only,
peer-only, and changed-file drift, then gives ordered repair steps. Ragmir never guesses which copy
is authoritative. Matching operational indexes remain synchronized when a privacy advisory still
needs separate review. Existing v2.19 snapshots remain comparable after an upgrade; their
operational readiness is derived from stored corpus and health metadata.
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.
- Getting Started
- Use Cases
- Agent Integration
- CLI Reference
- TypeScript API
- Configuration
- Security Hardening
- Offline Chat
- Offline TTS
- Troubleshooting
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.