Skip to content

Agent Integration

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

Agent integration

Ragmir is the local RAG layer for coding agents and scripts that need cited project passages through the CLI, TypeScript, or a stdio MCP server. Core never calls a model or generates answers.

Choose the handoff

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

Install native helpers

rgr setup --agents claude,codex,kimi,opencode,cline
rgr doctor

Setup 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,claude

Project 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.

MCP workflow

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

Use compact retrieval first, then expand one returned citation only when more context is required:

  1. ragmir_status verifies the active base.
  2. ragmir_route_prompt decides whether retrieval is useful.
  3. ragmir_search, ragmir_ask, or ragmir_research returns bounded cited evidence.
  4. ragmir_expand opens one exact indexed chunk with a small neighbor window.
  5. ragmir_audit and ragmir_security_audit verify 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, and expansion accept an optional maxBytes below the configured mcpMaxOutputBytes 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.

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. MCP cancellation propagates into retrieval operations. Ragmir does not open an HTTP port, so a network-facing host owns its authentication and authorization boundary.

Monorepos

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.

Ragmir

Project

Clone this wiki locally