Repository navigation
Agent Integration
For a repository-aware first installation, use the canonical prompt in Getting Started. It detects the package manager and existing Ragmir state, asks before changes or downloads, then configures and verifies the selected clients.
Ragmir indexes selected project files locally and gives the AI or automation you choose cited
passages through CLI, TypeScript, or a stdio MCP server. Core keeps the corpus and generated index
on the workstation, works offline by default with local-hash, and never uploads source documents
or calls a model.
| Path | What stays local | What crosses the boundary |
|---|---|---|
| Hosted coding agent | Corpus, index, and retrieval | Only passages returned to the consumer |
| Local coding agent or script | Corpus, index, retrieval, and consumer | Nothing unless that consumer uses a network service |
| Ragmir Chat | Corpus, index, retrieval, and answer generation | One explicit model download during setup, then no network |
rgr setup --agents claude,codex,kimi,opencode,cline
rgr doctorSetup creates an ignored .ragmir/run.cjs project runner, local MCP helpers, and project-scoped skill links for the selected clients. Re-run installation when you need a different scope or copy mode:
rgr install-agent --agents codex,claudeProject scope is the default. --mode copy is a fallback for filesystems that cannot follow symlinks. Ragmir refuses to overwrite unmanaged same-name skills unless --force is explicitly selected.
Read ragmir://context first when the client supports resources. It identifies the active knowledge base, readiness, freshness, source coverage, and available operations.
| Resource | Use |
|---|---|
ragmir://context |
Active base identity, readiness, freshness, coverage, and capabilities |
ragmir://sources |
Source coverage, skipped-file counts, and index drift, with complete totals and per-file lists capped at 50 |
Use compact retrieval first, then expand one returned citation only when more context is required:
-
ragmir_statusverifies the active base. -
ragmir_route_promptdecides whether retrieval is useful. -
ragmir_search,ragmir_ask, orragmir_researchreturns bounded cited evidence. -
ragmir_expandopens one exact indexed chunk with a small neighbor window. -
ragmir_auditandragmir_security_auditverify coverage and privacy posture.
The server also exposes ragmir_evaluate for local golden-query checks and ragmir_usage_report for metadata-only retrieval usage. Search, ask, research, expansion, audit, and evaluation accept an optional maxBytes. Every tool and resource JSON response stays below the configured mcpMaxOutputBytes budget and an absolute 1 MiB ceiling.
ragmir_ask returns cited evidence, not a model-generated answer. A hosted consumer receives the passages it requests, so use a local consumer when that handoff is not acceptable.
Every tool advertises non-destructive behavior. Search, ask, research, and evaluation conservatively
advertise open-world behavior because explicitly enabled semantic models may download public
weights. The prompt router, security audit, and usage report also advertise read-only, idempotent
behavior. Other tools conservatively do not because they can initialize ignored local state or
append metadata-only access logs. ragmir_evaluate accepts only an existing project-relative golden
file and rejects absolute paths, traversal, and symlinks outside the project. Strict mode returns
that relative path, replaces evaluation failures with a generic message, and masks configured
model, storage, source, and access-log paths in diagnostic responses.
Embedding applications can use createMcpServer(cwd) to construct a server around a caller-owned
transport, or connectMcpServer(transport, cwd) to connect it and receive a closeable handle.
serveMcp(cwd) remains the simplest local stdio entry point. A server lazily reuses one
RagmirClient per effective configuration for its pinned project root, refreshes it after
configuration changes, and closes the active client during shutdown. Request cancellation reaches
retrieval, audit, evaluation, security, usage, and bounded resource operations. Native filesystem
and LanceDB calls that cannot receive an AbortSignal directly are checked immediately before and
after the call. Ragmir does not open an HTTP port, so a network-facing host owns its authentication
and authorization boundary.
Use Git, Drive, or the team's existing file workflow to synchronize one source-of-truth folder, then let each developer ingest locally. Version stable directory or glob contracts instead of a generated enumeration of files present on one workstation.
rgr team snapshot --label alice --output .ragmir/team/alice.json
rgr team compare .ragmir/team/alice.json --local-label christopheThe snapshot contains relative paths, checksums, readiness, version, and index settings, never source
text or an absolute project path. The comparison names configuration drift plus local-only,
peer-only, and changed files and provides ordered actions. It does not choose which copy is correct:
confirm the declared Git commit, Drive revision, or shared folder, synchronize sources, ingest, and
compare fresh snapshots until status=synchronized.
Operational readiness and security advisories are separate. A comparison can report
status=synchronized together with local or peer advisory counts when the indexed bytes and
operational configuration match but one workstation still needs rgr security-audit. Existing
v2.19 snapshots remain compatible; Ragmir derives their operational state from stored corpus and
health fields without changing the snapshot schema.
Treat snapshots as sensitive metadata and share them only with teammates authorized for the corpus.
Use sourceFingerprintMode: "strict" when a sync tool can preserve metadata while replacing
content. Synchronize source files, not an actively written .ragmir/storage/ directory.
The bundled Ragmir skill instructs an agent to warn the user in the user's language when a supplied peer snapshot differs, summarize the exact drift, and avoid silently overwriting either side. When only security advisories remain, it reports them as non-blocking follow-ups instead of asking the user to choose an authority or rebuild a healthy index.
rgr bases --json
rgr --project-root apps/web search "checkout contract"Ragmir selects the nearest .ragmir/config.json. Root and nested bases keep separate storage. Generated MCP helpers pin RAGMIR_PROJECT_ROOT, and nested bases use deterministic server names so an agent does not silently query the wrong index.
If a client can see more than one Ragmir server, call ragmir_status and verify knowledgeBaseId before retrieval.
Canonical source: docs/agent-integration.md.