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.

In-process context engineering platform for AI agents — a catalog, a retrieval engine, and an in-process runtime 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 extend to skills, memories, and message history as they land on the roadmap.
• Stack: Rust core (ratel-ai-core) + TypeScript SDK + CLI that drops Ratel between an MCP host (Claude Code, Cursor, ChatGPT) and upstream MCP servers.
• No vector DB. No embedding pipeline. No service to deploy.

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

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

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.

Three shapes, same Rust core. Pick one — or mix them:

The MCP-server library that powers the CLI's gateway lives in a sibling repo: ratel-ai/ratel-mcp. Python SDK and Rust HTTP server are on the roadmap, not yet shipped.

TypeScript SDK — embed Ratel in a TS / Node agent

pnpm add @ratel-ai/sdk

import { ToolCatalog, searchToolsTool, 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_tools / invoke_tool.
const search = searchToolsTool(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

MCP server — expose a catalog over MCP for Claude / Cursor / ChatGPT

The MCP-server library and its serve CLI live in a sibling repo: ratel-ai/ratel-mcp. The published @ratel-ai/mcp-server package on npm is unchanged; @ratel-ai/cli in this repo depends on it and exposes the same gateway via ratel serve.

CLI — migrate an existing Claude Code MCP setup into Ratel

pnpm add -g @ratel-ai/cli

ratel mcp import   # interactive: scans ~/.claude.json + per-project .mcp.json,
                   # cherry-pick which upstreams to move into Ratel,
                   # rewrites Claude Code to launch `ratel serve`.

ratel backup undo  # roll back any time — every change writes a timestamped backup under ~/.ratel/backups/.

ratel mcp add mirrors claude mcp add flag-for-flag. Three-scope hierarchy (user / project / local), OAuth flow, full verb reference: src/integrations/cli/README.md.

Rust library — direct, no JS in the loop

cargo add ratel-ai-core

In-process BM25 retrieval over a schema-aware text projection of each tool. See src/core/lib/README.md and docs.rs/ratel-ai-core.

• Tool selection is the v0.1.x shipping path. Ratel sits between agent and catalog.
• Each turn, the agent either calls search_tools(query) or — in pre-filter mode — receives the top‑K hits resolved at message start. The full list never enters context.
• The catalog holds local executables, upstream MCP servers' tools (via registerMcpServer), or both — the model sees a unified, ranked surface.
• Under the hood: ratel-ai-core, a Rust BM25 index over a deterministic, schema-aware text projection of each tool. No embeddings, no vector DB, no inference latency on the retrieval path.

Longer take + skills / telemetry / memories / context graph: docs/overview.md.

• examples/ai-sdk/ — Vercel AI SDK with pre-filter + dynamic gateway
• examples/mcp-chat/ — Vercel AI SDK REPL ingesting an upstream MCP server via registerMcpServer

Tool selection is the wedge, not the destination. Same catalog, same retrieval engine, same in-process runtime — widening into the rest of the agent's context surface:

• v0.1.x — telemetry + UI inspector, JSON→TOON encoding, MCP tools/list_changed, first-class skills, LLM-driven catalog suggestions, multi-agent decomposition hints, semantic re-ranking over BM25, opt-in self-hosted trace server.
• v0.2.x — chat management — store / compact / prune / navigate long histories.
• v0.3.x — memories — prior decisions, preferences, and artifacts ranked into the current turn.
• v0.4.x — context graph — unified tools-skills-memories substrate.
• v0.5.x — Python SDK — second host language on the Rust core.

Dated milestones: docs/roadmap.md. Thesis: docs/overview.md.

src/
├── core/lib/                  # ratel-ai-core — Rust crate; BM25 retrieval engine
├── sdk/ts/                    # @ratel-ai/sdk — TypeScript SDK (NAPI-bound)
└── integrations/
    └── cli/                   # @ratel-ai/cli — `ratel` CLI
examples/                      # Runnable end-to-end examples
docs/                          # Overview, roadmap, ADRs

The benchmark harness lives in its own public repo: ratel-ai/ratel-bench.

Prerequisites: Rust stable (pinned via rust-toolchain.toml), Node 24+, pnpm 10.28+.

# Rust
cargo build --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --check --all
cargo test --workspace

# TS
pnpm install
pnpm -r build
pnpm -r typecheck
pnpm -r lint
pnpm -r test

CI runs both pipelines on every PR (.github/workflows/{rust,ts}.yml).

Full record in docs/adr/. Cross-cutting locks worth knowing up front:

• ADR 0002 — TS↔Rust binding via NAPI-RS
• ADR 0003 — Tool selection: replace by default, suggest opt-in
• ADR 0004 — BM25 tool indexing strategy
• ADR 0006 — Benchmark corpus and eval modes

• Humans: CONTRIBUTING.md
• Coding agents in this repo: AGENTS.md
• LLM index of the docs: llms.txt

Elastic License 2.0, with a grant making it free for OSI-approved open-source projects. Non-OSS / commercial production use requires a commercial license. See LICENSE.md.