ratel

Most agents stuff every tool, skill, and memory into the context window each turn — burning tokens, drifting on the long tail. Ratel sits between the agent and its catalog, and resolves only what matters for this turn.

Integrate Ratel in 60 seconds

The fastest way to get Ratel into your agent is the Ratel skills suite — five Claude Code / Cursor / Codex skills that integrate Ratel, plan observability, design dashboards, audit your codebase, and analyse live traces.

Install all five:

npx skills add ratel-ai/skills --all

Or paste this into your coding agent — it installs the suite and walks you through a concrete Ratel integration plan:

Run npx skills add ratel-ai/skills --all and use the skills to integrate Ratel in this project.

Want a read on the rest of your agent first? The same suite ships a free, static ratel-assessment — no engagement required. Paste this instead:

Run npx skills add ratel-ai/skills --all and use the skills to assess the agents in this codebase and show me where Ratel would help.

Full skills suite: ratel-ai/skills

What is Ratel

This repo is the library. An in-process context engineering platform for AI agents — a catalog, a retrieval engine, and the runtime hooks that decide what ends up in the model's context window on every turn.

• Wedge today: tool selection. Register tools (or ingest an upstream MCP server) into a ToolCatalog; the model sees the handful that matter for the current turn, not the full list.
• Same primitives now rank skills too — reusable playbooks alongside tools; memories and message history extend them as they land on the roadmap.
• Stack: Rust core (ratel-ai-core) + TypeScript SDK (@ratel-ai/sdk, NAPI-bound) + Python SDK (ratel-ai, PyO3-bound) + auxiliary CLI (@ratel-ai/cli) for the artifacts the library produces (telemetry today; trace-consolidation server later).
• No vector DB. No embedding pipeline. No service to deploy.

See docs/overview.md for the thesis, docs/roadmap.md for what's coming.

The Ratel project

Three repos, one story:

Why Ratel

• Retrieval, not stuffing. BM25 over a schema-aware text projection of every tool — deterministic, no embeddings, no inference cost on the retrieval path (ADR‑0004).
• ~2 tools per turn. Replace-by-default tool injection (ADR‑0003): the agent's tool list at any turn is the top‑K hits. Less context, less drift, lower cost.
• In-process, no infra. Pre-built native bindings for darwin / linux / win — no Rust toolchain to install.
• Framework-agnostic. ToolCatalog returns generic ExecutableTool objects you wrap in a few lines (Vercel AI SDK example shipped in examples/ai-sdk, examples/mcp-chat). Or skip the framework and expose the catalog over MCP.

Proof: where Ratel is most valuable today

Numbers from the MetaTool agent benchmark — full per-pool breakdown and methodology in ratel-ai/ratel-bench › RESULTS.md. The benchmark harness lives in its own public repo: ratel-ai/ratel-bench.

Choose your path

If you want to embed the library in your own agent or runtime, pick one of these shapes — same Rust core under each:

If instead you want to drop Ratel between an MCP host and your existing upstream MCP servers (Claude Code, Cursor, ChatGPT) — the showcase product — use @ratel-ai/mcp-server from ratel-ai/ratel-mcp: npx -y @ratel-ai/mcp-server mcp import.

The Rust HTTP server is on the roadmap, not yet shipped.

Quickstart

TypeScript SDK — embed Ratel in a TS / Node agent

pnpm add @ratel-ai/sdk

import { ToolCatalog, searchCapabilitiesTool, invokeToolTool } from "@ratel-ai/sdk";

const catalog = new ToolCatalog();
catalog.register({
  id: "read_file",
  name: "read_file",
  description: "Read a file from local disk.",
  inputSchema: { properties: { path: { type: "string" } } },
  outputSchema: { properties: { contents: { type: "string" } } },
  execute: async ({ path }) => ({ contents: await fs.readFile(path, "utf8") }),
});

// Hand these two tools to your agent loop.
// The full catalog stays out of the model's context — the agent reaches it via search_capabilities / invoke_tool.
const search = searchCapabilitiesTool(catalog);
const invoke = invokeToolTool(catalog);

• End-to-end Vercel AI SDK: examples/ai-sdk/
• Ingest an upstream MCP server: registerMcpServer
• Full SDK reference: src/sdk/ts/README.md

Python SDK — embed Ratel in a Python agent

pip install ratel-ai

from ratel_ai import ToolCatalog, ExecutableTool, search_capabilities_tool, invoke_tool_tool

catalog = ToolCatalog()
catalog.register(
    ExecutableTool(
        id="read_file",
        name="read_file",
        description="Read a file from local disk.",
        input_schema={"properties": {"path": {"type": "string"}}},
        output_schema={"properties": {"contents": {"type": "string"}}},
        execute=lambda args: {"contents": open(args["path"]).read()},
    )
)

# Hand these two tools to your agent loop.
# The full catalog stays out of the model's context — the agent reaches it via search_capabilities / invoke_tool.
search = search_capabilities_tool(catalog)
invoke = invoke_tool_tool(catalog)

• End-to-end Pydantic AI: examples/pydantic-ai/
• Full SDK reference: src/sdk/python/README.md

Showcase: drop Ratel between Claude Code and your existing MCP servers

For the canonical "Ratel as a