ratel

Open source

Context engineering for AI agents. ~80% fewer tokens. Fix tool overload. Skills and memory with in-process BM25 and semantic retrieval. Progressive Disclosure.

397 stars0 likes0 views

Website GitHub

About

Context engineering for AI agents. ~80% fewer tokens. Fix tool overload. Skills and memory with in-process BM25 and semantic retrieval. Progressive Disclosure.

Introduction

The context engineering layer for AI agents. Selects only the tools and skills relevant to each turn, recovering accuracy lost to tool overload and cutting what you pay per call. No vector DB, no infra.

Why

Cost: Every tool schema, every skill, and a growing list of instructions in the system prompt are tokens you pay for on every call. Send them all up front and you pay for them all, every turn.
Accuracy: Models get worse as that context grows. Crowd it with tools, skills, and instructions a turn doesn't need and the model picks the wrong option and drifts off task.
Ratel fixes both: it indexes your tools and skills into a catalog the agent progressively discloses, searching for what each turn needs and injecting only the matching capabilities instead of loading everything up front. Constant grounding your agent always needs — a shop's address, a brand's voice — is registered as facts and pushed into context, re-injected only when it isn't already fresh in the transcript.

Across local, open-source, and frontier model setups, Ratel cuts token usage and recovers accuracy lost to tool overload, with no vector DB required. Full results: benchmark.ratel.sh

Quickstart

Guides: Quickstart · TypeScript SDK · Python SDK

Examples: Vercel AI SDK · Pydantic AI

Typescript

Install the SDK first:

bash

pnpm add @ratel-ai/sdk

Then create and use your Catalogs:

…

Python

Install the SDK first:

bash

pip install ratel-ai

Then create and use your Catalogs:

…

How it works

When your agent needs to act, it calls search_capabilities. Ratel searches separate tool and skill indexes and returns focused results from each. Tools can be invoked by id; skill instructions stay out of context until the agent loads a relevant playbook with get_skill_content.

The indexes use BM25 by default, the same algorithm behind most search engines, applied to schema-aware tool metadata and skill names, descriptions, and tags. Retrieval is fast and deterministic. Semantic and hybrid ranking are opt-in per catalog or per call; SDK callers register (which embeds) and search dense indexes asynchronously, using either an in-process model or an OpenAI-compatible embedding endpoint.

Full docs

Related projects

Related open-source projects extend and validate this repository:

Project	Repo	What it is
ratel-local	ratel-ai/ratel-mcp	The local distribution for your Coding Agents: Ratel in front of your MCP setup.
ratel-bench	ratel-ai/ratel-bench	The benchmark harness behind benchmark.ratel.sh.

Repo layout

…

Build & test

Prerequisites: Rust stable, Node 24+, pnpm 10.28+. Python SDK: Python 3.9+ and uv.

bash

cargo build --workspace && cargo test --workspace   # Rust
pnpm install && pnpm -r build && pnpm -r test       # TypeScript
# Python: see src/sdk/python/README.md

Contributing

CONTRIBUTING.md
AGENTS.md — for coding agents working in this repo

License

The ratel-ai-core engine is licensed under Apache-2.0 — an explicit patent grant for the engine others embed. Everything else (SDKs, telemetry helpers, examples) is MIT. See ADR-0009 for the rationale.