FAQ

Basics

Do I need a vector database or an API key?

No. The default is BM25 keyword search running in your process — no model, no vector database, no service, no API key. Semantic and hybrid ranking are opt-in and still local: a small embedding model downloads once on first use and runs CPU-only.

How is this different from passing all my tools to the model?

Without Ratel, every schema is sent on every turn, so prompt cost scales with catalog size. With Ratel, the model reads only the top-K matches plus three capability tools, however large the catalog grows. Efficiency shows the before/after; progressive disclosure explains the mechanism.

Does hiding tools behind search hurt accuracy?

The benchmark says no: on the BFCL suite, 86–91% token savings come with accuracy at or near baseline, and smaller models actually gain. See Efficiency for the full table and benchmark.ratel.sh for live results.

What's the difference between a skill and a tool?

A tool is one operation the runtime executes. A skill is a Markdown playbook the agent reads — instructions for multi-step work, ranked in its own corpus so tools never crowd out a relevant skill. See Tools, MCP & Skills.

Integration

Which languages and frameworks does Ratel support?

Two first-party SDKs — @ratel-ai/sdk for TypeScript and ratel-ai for Python — with mirrored APIs over one Rust core. Framework wiring is a small adapter, documented for the Vercel AI SDK and Pydantic AI.

Can I use Ratel with Claude Code, Codex, or Cursor without writing code?

Yes — Ratel Local is one MCP server that fronts your whole tool estate and exposes just the capability tools; configuration is the only integration work. Claude Code and Codex can follow the Ratel Local quickstart. Cursor uses one manual MCP entry; version 0.4.0 has no Cursor import or link adapter.

Should I use Ratel Local or the SDK?

Pick Ratel Local when your tools already live behind MCP servers and you don't want to change agent code. Pick an SDK when you own the agent loop and want in-process control. Both expose the same capability tools.

Do my existing MCP servers work with Ratel?

Yes. Upstream MCP tools land in the same catalog as your local functions and rank as one surface. See Tools, MCP & Skills and Register MCP servers (TypeScript, Python).

Does retrieval bypass my tools' permissions or auth?

No. Permissions, authentication, and side effects still belong to the tool and its host — Ratel only changes which definitions reach the model. See Architecture.

Search quality

When should I switch from BM25 to semantic or hybrid search?

Stay on BM25 until you see missed recall — the first fix is usually better definitions, not a different engine. If you do opt in, hybrid is usually the safer choice. Semantic & hybrid search has the decision guide.

My tool never ranks for the queries I expect. How do I fix it?

Your vocabulary is the recall mechanism: BM25 indexes names, descriptions, and schema property names, so write "what it does" plus a "use when" clause in the caller's words. The checklist is on Keyword search.

Privacy & performance

Does any of my data leave my machine?

Not by default: retrieval runs in-process, telemetry is off until you opt in, and message/tool content never leaves the process unless you set a content-capture mode. See Telemetry.

Does Ratel work offline or air-gapped?

BM25 needs nothing — no model, no service. Semantic and hybrid download an embedding model once, then load offline; a mirror endpoint covers air-gapped setups. Details on Semantic & hybrid search.

What runtime overhead does Ratel add?

BM25 retrieval runs deterministically in your process with no model or service call. Semantic search adds a one-time model download and CPU-only inference; telemetry is a no-op until you opt in. See Telemetry.

I already run OpenTelemetry — will Ratel's telemetry conflict?

No: your existing provider already receives Ratel's ratel.* / gen_ai.* spans. Skip configureTelemetry, and add the Ratel span processor only if you also want to dual-export. See Telemetry.

Project

How is Ratel licensed? Can I use it commercially?

The ratel-ai-core engine is Apache-2.0; the SDKs, Ratel Local, and everything else are MIT. Both permit commercial use, modification, and redistribution — see Licensing.

Where do the token-savings numbers come from?

From the open harness ratel-ai/ratel-bench, which runs every scenario as baseline, oracle, and ratel-full. Benchmark covers the methodology; benchmark.ratel.sh has the live results.

What's on the roadmap?

Adaptive ranking and compaction are marked coming soon on Features. Ratel Cloud — hosted context analytics — is also coming soon.

Can my agent read these docs?

Yes — these docs publish /llms.txt and /llms-full.txt, regenerated from the authored content on every build.