Architecture
The layers of Ratel Core — Rust engine, SDK bindings, catalogs, retrieval, telemetry — and how one agent turn flows through them.
Ratel separates what your agent can do from what the model must read right now. Your Ratel Core application owns the full catalog. The model gets a small view selected for the current request and a controlled way to reach the rest.
The pieces
Five layers, all in your process:
- Rust engine.
ratel-ai-coreowns the registries (ToolRegistry,SkillRegistry), the three retrieval engines (BM25, semantic over a localbge-small-en-v1.5, hybrid fused with Reciprocal Rank Fusion), and the local trace stream. - SDK bindings.
@ratel-ai/sdk(napi) andratel-ai(PyO3) are thin, mirrored bindings over that same engine — in-process, no server, no API key. - Catalogs.
ToolCatalogandSkillCatalogpair metadata with executable handlers and hold local tools, MCP server tools, and skills as separate corpora, so tool and skill rankings never crowd each other out. - Retrieval pipeline. BM25 is the deterministic default. Semantic and hybrid are opt-in per catalog or per call, still against a local index.
- Telemetry stream. Every search, expansion, and invocation emits a trace event
into a sink you configure — off by default, like OpenTelemetry export,
which speaks the
ratel.*span vocabulary.
What happens on a turn
Ratel Core SDK
user request → local retrieval → top-K tools + capability tools → model
↕
ToolCatalogRatel Local exposes the same catalog semantics and wire contract over MCP, either as its CLI-managed gateway or embedded in a Node process.
Register once
A tool enters the catalog with an id, a retrievable name and description, JSON input and
output schemas, and an executor. MCP imports produce the same shape automatically. Skill
metadata lives in the separate SkillCatalog.
Retrieve locally
For the incoming request, Ratel ranks the catalog in-process. BM25 is the deterministic default. Semantic and hybrid retrieval are opt-in and still use a local index rather than a hosted vector database.
Give the model a small starting set
An SDK integration can inject the top-K matches as normal framework tools. The capability tools stay available alongside them. A Ratel Local integration begins with the capability tools because the upstream catalog remains behind the MCP boundary.
Expand only when needed
If the starting set is insufficient, the model calls search_capabilities and gets
separately ranked tool and skill hits, each with the id and schema needed for the next
call. A matched skill exposes its body only through get_skill_content. See
Progressive disclosure for the exact contracts.
Invoke by id
The model calls invoke_tool with the selected toolId and nested args. Ratel
dispatches to the local handler or upstream MCP server and returns the result to the
normal agent loop. Tool permissions, authentication, and side effects still belong to the
tool and its host; retrieval does not bypass them.
What stays out of the prompt
- Definitions for tools that did not match the current request.
- Full skill bodies until the agent chooses to load one.
- Upstream MCP inventories when Ratel Local is the only server exposed to the host.
- Retrieval infrastructure: the default index runs locally with no Ratel service call.
What remains is ordinary agent behavior: your model provider still handles the model request, and invoked tools keep the permissions you configured.
Keep building with Ratel Core
Build the SDK path
Let a coding agent integrate Ratel, or follow the TypeScript and Python quickstarts.
What this saves
The token and accuracy cost of oversized tool lists — and what this architecture buys back.
Using Claude Code, Codex, or Cursor?
Claude Code and Codex can import or link through Ratel Local. Cursor uses manual MCP configuration. Both paths end at the same capability tools.