ragi

Local-first RAG indexing and semantic search MCP server.

Requires Node 22 or newer.

Published/runtime usage is Node-first. bunx is not supported (bunx does not properly install transitive dependencies of published packages).

Quick Start

# Install dependencies
npm install

# Build and start MCP server
npm run build
npm start

# Or use npx without a global install
npx -y @susutawar/ragi@latest

# Or install globally, then run the bin directly
npm install -g @susutawar/ragi
ragi

Usage

# Initialize skill locally
npx -y @susutawar/ragi@latest init

# Initialize skill globally
npx -y @susutawar/ragi@latest init --global

# Check installations
npx -y @susutawar/ragi@latest init --check

# Refresh MCP definitions to the current @latest package spec
npm run mcp:update

npx -y @susutawar/ragi@latest init now:

• asks which agent(s) are used in the current project,
• supports a broader curated harness matrix with full, manual MCP, and skills only support tiers,
• checks whether the installed ragi skill is missing, current, or outdated before copying,
• checks whether ragi is already registered with the selected agent host(s) before offering MCP setup,
• checks ~/.config/ragi/config.json and can scaffold it when missing or invalid,
• prefers global/user MCP registration by default when the agent's config format is supported,
• falls back to printing manual MCP registration instructions for unsupported agents.

--force overwrites outdated installed skills during init. Without --force, interactive runs ask before updating and non-interactive runs leave stale installs untouched.

After init edits a writable MCP config, restart that host so it reloads the updated definition. For manual hosts, init now prints the exact next command or UI step to finish setup.

Configuration

The default runtime config lives at ~/.config/ragi/config.json.

Use a project .ragrc only when this repo needs to override the global ragi defaults:

{
  "embedding": {
    "provider": "transformers_js",
    "model": "Xenova/all-MiniLM-L6-v2"
  },
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434"
    },
    "llama_cpp": {
      "baseUrl": "http://localhost:8080"
    }
  }
}

Recommended model choices by provider:

• ollama: nomic-embed-text
• transformers_js: Xenova/all-MiniLM-L6-v2
• llama_cpp: an embedding-capable model served by your llama.cpp instance

The providers.*.baseUrl values control where ragi looks for each local service. When embedding.provider is ollama or llama_cpp and embedding.baseUrl is unset, ragi uses the matching provider-specific baseUrl from the global config.

Or use environment variables (RAGI_* takes precedence):

• RAGI_VECTOR_STORE
• RAGI_EMBEDDING_PROVIDER
• RAGI_EMBEDDING_MODEL
• RAGI_EMBEDDING_BASE_URL

Troubleshooting

If Node reports a sharp.node error while using the default transformers_js embedding provider:

• avoid mixing bun install and npm install in the same node_modules
• reinstall dependencies with the same package manager you plan to run with
• if you use npx -y @susutawar/ragi@latest, let npm resolve a fresh package install instead of reusing a mixed local install

bunx @susutawar/ragi is not supported because bunx does not install transitive dependencies of published packages. Use npx instead.

When running npx @susutawar/ragi from inside this repo (development), run npm install first — the postinstall script creates a local bin shim so npx resolves correctly on Windows.