Confidential localRAG for yourcoding agents.

Ragmir turns specs, Word files, PDFs, and local exports into cited evidence indexed and retrieved locally. Core works offline by default, never uploads your corpus, and calls no model.

Install Ragmir See use cases

0Ragmir downloads/month on npm

Fewer tokens Retrieve only cited passages.

Verifiable citations Source, excerpt, and location.

Your agent, your boundary Hosted agent or local consumer.

Library + CLI + MCP One local retrieval layer.

zsh | ~/projects/account-recoveryLocal DOCX

Turn a private Word spec into cited code and tests without uploading the file.

Use cases

Six local workflows built around realistic project files.

From a portable OpenClaw base and private specifications to monorepos, synced Drive folders, media research, and administrative dossiers, each flow keeps indexing local, retrieves offline, and returns citations.

Build from a private Word spec.

Turn a private specification into implementation-ready evidence.

1 / 6

Local sources

Private Word specifications stay on the developer's machine.

01 · Trigger

Codex receives an account-recovery feature to build.

02 · Retrieval

Ragmir retrieves only the matching rules and cites their exact source.

03 · Cited result

Codex implements and tests the feature against those cited rules.

01 · Trigger
Codex receives an account-recovery feature to build.
Local sources
Private Word specifications stay on the developer's machine.
02 · Retrieval
Ragmir retrieves only the matching rules and cites their exact source.
03 · Cited result
Codex implements and tests the feature against those cited rules.

Ground OpenClaw in a portable Ragmir base.

Use Ragmir's own repository as the showcase corpus, then connect its generated adapter.

2 / 6

Local sources

Ragmir's code, documentation, and AI rules stay in its local index.

01 · Export

Ragmir exports a verified folder for the OpenClaw host's platform.

02 · MCP adapter

OpenClaw registers and probes the generated read-only MCP adapter.

03 · Retrieval

OpenClaw asks for three compact citations and expands only the evidence it needs.

04 · Grounded decision

The plan cites Ragmir's own rules; action approval stays with the host.

Local sources
Ragmir's code, documentation, and AI rules stay in its local index.
01 · Export
Ragmir exports a verified folder for the OpenClaw host's platform.
02 · MCP adapter
OpenClaw registers and probes the generated read-only MCP adapter.
03 · Retrieval
OpenClaw asks for three compact citations and expands only the evidence it needs.
04 · Grounded decision
The plan cites Ragmir's own rules; action approval stays with the host.

Onboard across a monorepo.

Answer architecture questions across root and package documentation.

3 / 6

01 · Trigger

A developer asks how authentication works across the monorepo.

02 · Retrieval

The developer queries each relevant root or package base separately; Ragmir never merges their indexes.

03 · Cited result

The agent returns an onboarding map with owners, dependencies, and sources.

01 · Trigger
A developer asks how authentication works across the monorepo.
02 · Retrieval
The developer queries each relevant root or package base separately; Ragmir never merges their indexes.
03 · Cited result
The agent returns an onboarding map with owners, dependencies, and sources.

Build from a synced Drive folder.

Reconcile product files before a coding agent implements a feature.

4 / 6

Local sources

Roadmap, spreadsheet, and architecture files share one synced local folder.

01 · Trigger

A coding agent receives a feature request with missing context.

02 · Retrieval

Ragmir retrieves matching requirements with citations; the agent compares them and identifies conflicts.

03 · Agent action

The agent orders the dependencies and acceptance criteria from that evidence.

04 · Cited result

The feature and tests stay traceable to the product sources.

01 · Trigger
A coding agent receives a feature request with missing context.
Local sources
Roadmap, spreadsheet, and architecture files share one synced local folder.
02 · Retrieval
Ragmir retrieves matching requirements with citations; the agent compares them and identifies conflicts.
03 · Agent action
The agent orders the dependencies and acceptance criteria from that evidence.
04 · Cited result
The feature and tests stay traceable to the product sources.

Draft a YouTube script backed by citations.

Ground a draft in research and voice rules before human approval.

5 / 6

Local sources

Research PDFs, notes, and voice rules stay in one local corpus.

01 · Trigger

A local drafting script starts with the next episode topic.

02 · Retrieval

Ragmir finds the relevant facts, quotes, and voice rules with citations.

03 · Cited result

Your AI drafts the episode from that evidence, then a human approves it.

01 · Trigger
A local drafting script starts with the next episode topic.
Local sources
Research PDFs, notes, and voice rules stay in one local corpus.
02 · Retrieval
Ragmir finds the relevant facts, quotes, and voice rules with citations.
03 · Cited result
Your AI drafts the episode from that evidence, then a human approves it.

Ground a visa project in local documents.

Keep a dated project checklist grounded in a changing local corpus.

6 / 6

01 · Trigger

A local project script gathers forms, receipts, and current official guidance.

02 · Retrieval

Ragmir finds matching requirements, deadlines, and missing evidence with citations.

03 · Cited result

The script updates a dated checklist for human verification before any action.

01 · Trigger
A local project script gathers forms, receipts, and current official guidance.
02 · Retrieval
Ragmir finds matching requirements, deadlines, and missing evidence with citations.
03 · Cited result
The script updates a dated checklist for human verification before any action.

Install

Install once. Retrieve through CLI, TypeScript, or MCP.

Add Ragmir Core to the repository that owns the files, choose the sources, then ingest. Generated state stays under ignored .ragmir/ folders, and the default local-hash path needs no account, API key, or model download.

Set up Ragmir

Let your coding agent tailor the setup, or choose your package manager and run the commands yourself.

Let your coding agent configure Ragmir

Paste this prompt into your coding agent. It inspects the repository, asks before making choices, installs the right packages, and verifies cited retrieval.

Set up Ragmir in this repository. Work interactively: inspect first, infer safe defaults, present a proposal, wait for approval, 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. Propose one setup summary, then ask once:
- Infer the owning base and useful clients from the repository. State any nested bases you propose.
- Default to offline local-hash and Core only, or optional Chat only when requested. Optional TTS stays off unless requested. Semantic, Chat, and TTS downloads require explicit approval; Edge text transfer requires separate approval.
- Default to solo unless the repository or request shows a team workflow. For a Git-backed team, propose the current upstream as authority and safe automatic pulls; offer --no-pull when Git updates must stay manual.
- List selected source globs, exclusions, any external/private folder, and the exact package, config, skill, and download actions you would perform.
- Ask only about unresolved choices that materially change source authority, data exposure, downloads, or external execution. Wait for one approval covering the proposal.

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.

Feature map

Local cited retrieval first. Optional local answers and audio when needed.

Core retrieves cited project evidence for your coding agent. Optional Chat generates local answers from those passages; optional TTS renders approved text as audio.

Core

Ragmir Core

Retrieve cited project evidence with adaptive local indexing for agents, scripts, and Node.js workers.

Install

Run

Preview redacted chunks and explain retrieval rankings.
Reuse one persistent local client in a Node.js worker.
Return verifiable file, line, chunk, and PDF page citations.
Run offline and keep generated state under ignored .ragmir/.

Optional

Ragmir TTS

Render reviewed, cited project text as local audio for agents and scripts.

Install

Run

Render local text as offline WAV or explicit online MP3.
Work from cited research and reports.
Render WAV offline after model preload.
Keep audio under ignored .ragmir/audio; Edge TTS stays opt-in.

Optional

Ragmir Chat

Turn retrieved project evidence into cited local answers for agents and scripts.

Install

Run

Ground every answer in cited Ragmir passages.
Choose verified Qwen or Gemma profiles.
Use Metal, CUDA, or Vulkan where supported.
Download during setup, then answer offline without a hosted API.

Agent workflows

An evidence layer for agents, not another memory system.

Connect Ragmir to the agent you prefer through CLI or MCP, or keep the complete workflow on the workstation. MCP starts with at most three compact citations by default; research may add three code matches. The agent expands only the evidence it needs. Core never depends on a specific model.

Agent setup command

Move one frozen knowledge base

Export the active index, required model, embedded read-only runtime, skills, and MCP adapters. Verify it after moving; raw source files and logs stay out.

Choose where the evidence goes

Send bounded cited passages to the agent you already use, keep the handoff local, use optional Chat for an offline answer, or consume retrieval results without any model.

Your preferred agent

Claude, Codex, Kimi, Hermes, and other compatible clients can consume cited passages through CLI or MCP. A hosted client's data policy applies to those passages.

Local agent

OpenCode or another local CLI or MCP consumer can keep retrieved passages on the workstation. No hosted Ragmir service is involved.

Offline answers

Optional Ragmir Chat generates cited answers from one verified local GGUF. Qwen and Gemma are included profile choices, not Core requirements.

Apps and automation

Local scripts, desktop tools, and CI jobs consume typed or JSON retrieval results with or without a generative model.

Local and confidential

Keep the corpus and index local. Control what leaves.

Ragmir has no telemetry and never uploads your corpus to a hosted RAG. Local consumers can keep the full workflow offline; a cloud agent receives retrieved passages under that provider's data policy when you choose that workflow.

Documents on disk

You point Ragmir at the relevant folder. Private files stay in the repository or the local workspace.

Git-ignored state

The index, reports, and generated integrations stay in the local git-ignored .ragmir/ folder.

Redaction and explicit limits

Redaction, size limits, and auditing of unsupported files avoid claiming to index more than what is reliable.

Minimal logs

Access logs contain metadata only, so usage can be checked without exposing sensitive content.

Useful by design

Built for the documents your code search does not see.

Ragmir turns private, scattered project documents into a local evidence layer that coding agents and scripts can query offline through MCP, CLI, or TypeScript.

Where Ragmir fits best

Project knowledge beyond code

Search PDFs, DOCX, XLSX, specifications, contracts, and runbooks alongside the repository they explain.

More context, fewer tokens

Start with at most three compact citations, then expand only the selected evidence instead of pasting a large or fragmented corpus into one prompt.

A corpus that stays yours

Keep the index local and pair Ragmir with a local consumer when no cited passage may leave the workstation.

Evidence agents and scripts can reuse

Give coding agents and local scripts traceable passages with file, line, chunk, and PDF page references.

FAQ

Frequently asked questions

What Ragmir keeps local, how teams align their sources, which optional setup commands use the network, and how to connect agents.

What is Ragmir?

Ragmir is an open-source confidential local RAG for coding agents and scripts on Node.js: a library, CLI, and local MCP server that turns the files you choose into cited, queryable context. It complements agent memory and native code search for specifications, runbooks, contracts, PDFs, and other project documents. The default path works offline with no model download.

Does Ragmir send my confidential code or documents?

Ragmir indexes only the local folders you choose and keeps generated state in the git-ignored .ragmir/ folder. Core retrieval has no telemetry or document upload. Explicit model setup downloads public model weights, never your documents; cloud agents can receive cited passages when you choose to use them.

Which AI agents and tools does Ragmir work with?

Ragmir Core is model-agnostic. Integrations cover Claude Code, Codex, Kimi, OpenCode, and Cline. Other MCP clients, local scripts, desktop tools, and CI jobs use the same cited results.

Can I move a Ragmir knowledge base to another agent or server?

Yes. rgr portable export creates one frozen folder with the active index, any required local embedding model, an embedded read-only runtime, two skills, MCP adapters, and a SHA-256 inventory. Move it to a matching Node.js 22 platform, verify it without a package-manager install or registry access, then connect Claude, Codex, Kimi, OpenCode, Cline, or a compatible MCP or CLI host. Later, --replace verifies the next export before switching the stable path and preserves the prior bundle as a timestamped backup. Raw source files and logs are excluded, but indexed passages remain sensitive; the host keeps action authority and network security.

How does a team share the same knowledge base?

Teams merge reviewed changes into a declared Git upstream, then run rgr team sync. Ragmir fast-forwards only a clean, non-divergent branch and refreshes each developer's private local index. --no-pull keeps branch updates manual; advanced metadata-only comparisons remain available for non-Git sources or exact drift diagnostics.

Does Ragmir require an API key, a model download, or an internet connection?

No for the default path. Local-hash retrieval runs offline with no model or API key. Team sync fetches the configured Git upstream only when invoked; --no-fetch keeps that run offline. For a fully offline workflow, use a local consumer or optional Ragmir Chat, which downloads and verifies one selected GGUF profile once, then generates locally. No Ollama, Python, or hosted LLM API is required.

Can I see where ingestion time and memory are spent?

Yes. Optional ingestion metrics attribute discovery, hashing, parsing, redaction, chunking, embedding, local index writes, maintenance, throughput, queues, cache state, and peak RSS. The bounded local diagnostic contains no project root, source path, source text, or query, and its timers stay off unless requested or subscribed.

How does Ragmir differ from IDE code indexing or hosted RAG?

Native code search handles structured code well. Ragmir targets project documents that need citations, keeps its index local, and exposes bounded passages through non-destructive MCP tools. Small output budgets keep exact citations and return typed summaries with omission counts.

Does Ragmir write the answers for me?

Ragmir Core returns cited passages from your local files; the agent or application you choose decides what to do with them. Optional rgr chat adds cited answer generation from a verified local profile when the response must also stay on the workstation.

Which file formats can Ragmir index?

Source code, text, Markdown, PDF, Office and OpenDocument, EPUB, HTML, CSV, JSON, and YAML, plus the custom text extensions you enable. Unsupported files are flagged explicitly. Scanned PDFs can use optional local OCR with bounded page batches and a private resumable cache.

Does Ragmir run as a web server or use a fixed port?

No. Use the local stdio MCP server for coding agents or embed the TypeScript client in a stateful Node.js process. Ragmir opens no HTTP port; a network-facing application owns authentication, authorization, rate limits, and transport security.

Start with the core AGPL-3.0 open source

Add confidential local RAG to your agent. Keep your project files local.

Connect cited passages to your preferred agent, or prepare a local Chat profile and keep retrieval and answer generation offline. No hosted Ragmir account is required.

Install Open GitHub | github.com/jcode-works/jcode-ragmir

Copied to clipboard