Ratel: A Context Engineering Layer That Indexes Tools and Skills Instead of Loading Them All
Context engineering for AI agents. ~80% fewer tokens. Fix tool overload. Skills and memory with in-process BM25 and semantic retrieval. Progressive Disclosure. No vector DB.
At a glance
- What is it?
- Ratel is an MIT-licensed TypeScript and Python SDK that puts a BM25 or semantic index in front of your agent's tool and skill definitions, so only the capabilities a turn needs get injected into the prompt. It is aimed at agents that have outgrown a flat tool list, and it is not a drop-in replacement for a vector database or a full RAG stack.
- Who is it for?
- Adopt Ratel if your agent already has more tools than the model can reliably choose between, and if you are willing to restructure tool exposure around search_capabilities, invoke_tool and get_skill_content. Do not adopt it if you have a handful of tools, or if you need a hosted retrieval service with a managed index.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem Ratel targets: paying for tool schemas the turn never touches
Every tool schema, every skill body and every standing instruction sits in the system prompt, and the model is billed for all of it on every call. The README frames the cost side plainly: send them all up front and you pay for them all, every turn. The accuracy side is the more interesting claim. As the context grows, the README states models get worse at picking the right option and drift off task. That is a selection problem, not a knowledge problem. A model that has 60 tools in front of it and needs one of them is being asked to do retrieval with no index.
Ratel's answer is to move that selection out of the prompt and into a searchable catalog. The intended audience is anyone running an agent with a growing tool surface: MCP servers, coding agents, or a product agent that has accumulated integrations over time. The repository also points at a companion project, ratel-ai/ratel-mcp, described as "Ratel in front of your MCP setup," which is the clearest signal of who this is for. If your MCP client currently dumps every server's tool list into context, that is the scenario the project was built around.
Two catalogs, three tools, and a search step between the model and the executor
The mechanism is visible in the quickstart. You build a ToolCatalog and a SkillCatalog, register entries into each, and then hand your agent framework three generated tools: searchCapabilitiesTool(catalog, skills), invokeToolTool(catalog) and getSkillContentTool(skills). The agent no longer sees your real tools directly. It sees a search function and an invocation function.
When the agent needs to act, per the README, it calls search_capabilities. Ratel searches the tool index and the skill index separately and returns focused results from each. A tool result can then be invoked by id through invoke_tool. Skill instructions stay out of context until the agent explicitly loads one with get_skill_content. That last detail is the part worth dwelling on: skills are not injected as descriptions, they are gated behind a second call. The README calls this progressive disclosure, and it means a skill body costs tokens only after the model has decided the skill is relevant.
The default ranking is BM25, applied to schema-aware tool metadata and to skill names, descriptions and tags. The README describes retrieval as fast and deterministic, which is a real property of BM25 and not marketing: the same query against the same index produces the same ranking, with no embedding call in the loop. Semantic and hybrid ranking are opt-in per catalog or per call. When enabled, SDK callers register (which embeds) and search dense indexes asynchronously, using either an in-process model or an OpenAI-compatible embedding endpoint. That is an important architectural split. The default path has no network dependency; the semantic path does, unless you supply the in-process model.
Getting it running: install, register, wire the three tools
The README gives two install paths. For TypeScript, pnpm add @ratel-ai/sdk. For Python, pip install ratel-ai. There is also a Rust core published as ratel-ai-core on crates.io, and the repo layout shows the SDKs are NAPI-bound (TypeScript) and PyO3-bound (Python) wrappers around it, so the retrieval engine is native code reached from both languages.
The TypeScript registration API takes an id, name, description, inputSchema, outputSchema and an execute function. The Python version takes an ExecutableTool with id, name, description, input_schema and execute. Skills are registered with id, name, description, a tools array naming the tool ids the skill depends on, and a body containing the instructions. In the README example, the skill inspect-local-file lists read_file in its tools array and its body says to read the requested file and ground the answer in its contents.
The wiring step is the one that changes your agent's shape. You pass search, invoke and loadSkill into your framework as tools, replacing whatever direct tool list you had. The repository ships adapters for the Vercel AI SDK (@ratel-ai/vercel-ai-sdk) and Mastra (@ratel-ai/mastra), plus end-to-end examples under examples/ for the Vercel AI SDK and Pydantic AI. There is also a protocol/ directory described as a catalog-source wire contract, which suggests catalogs can be sourced from somewhere other than in-process registration, though the README does not spell out that flow. Note the README's build and test section is truncated at the word Prerequis, so the exact build prerequisites for the Rust core are not something I can state from this material.
Where the design creates friction
The largest trade-off is that you are inserting a model-driven search step between intent and action. The agent must decide to search, form a query, read results, and then invoke by id. That is one or two extra round trips compared with a flat tool list where the model calls the tool directly. For an agent with five tools, this is pure overhead and a new failure mode: the model can search badly, or skip searching and hallucinate a tool id. Ratel is the wrong tool in that case, and the README's own framing supports it. The problem statement is tool overload, so the project is only worth its complexity once overload exists.
Second, the default BM25 ranking is lexical. A user request phrased with different vocabulary than your tool description may not surface the right tool. The README's answer is opt-in semantic or hybrid ranking, but that path requires an embedding model, either in-process or via an OpenAI-compatible endpoint, and the README notes those searches are asynchronous. So the zero-infrastructure promise applies to the BM25 configuration specifically. Turn on semantic ranking and you have reintroduced an embedding dependency, just not a vector database.
Third, the current release line is at sdk-ts-v0.13.0-rc.4 and sdk-py-v0.13.0-rc.4, all dated early September 2026. Release candidates at a 0.13 version mean the API surface is still moving. If you are pinning versions in a production agent, expect to read release notes between upgrades rather than assuming the catalog registration signature is frozen.
How this differs from a vector database RAG setup
The obvious comparison is a conventional retrieval stack: embed your tool descriptions, store them in a vector database such as pgvector or Qdrant, run a similarity search per turn, and inject the top matches. Ratel takes the same broad idea and moves it in-process. There is no separate service to run, no index to keep in sync across deployments, and no network hop on the default BM25 path. The README states the no-vector-DB position directly: no vector DB, no infra.
The difference is not only deployment shape. A vector database gives you one retrieval mode, dense similarity. Ratel defaults to BM25 and treats dense ranking as an opt-in layer, so you can run hybrid or lexical-only depending on the catalog or the individual call. It also splits tools from skills into separate indexes and returns results from each, which a single embedding collection would not do without extra filtering logic. Where a vector store wins is scale and operations: managed replication, sharding, and a query language you already know. Ratel's index lives in your process, which is the point, and also the ceiling. If you need the catalog shared across a fleet of workers with independent scaling, the README does not describe a hosted or distributed mode. The protocol/ directory hints at a catalog-source contract that might cover this, but I cannot confirm it from the supplied material.
Licence, maintenance and the cost of upgrading
The repository is MIT-licensed, though the README's own badge reads Apache-2.0 & MIT, so the licensing picture is not fully consistent between the metadata and the badge. That discrepancy is worth resolving before you rely on either. Nothing here constitutes legal advice; if licence terms matter to your distribution model, read the LICENSE file and the per-package manifests rather than the badge.
On maintenance, the facts available are narrow. The last push is dated 2026-09-10, and the three most recent releases are all 0.13.0 release candidates for the TypeScript and Python SDKs. There is a docs site, a Discord, a separate skills repository and a benchmark harness repository. That is a real ecosystem around the core, but it is also several moving parts to track. The upgrade cost is concentrated in three places: the Rust core that both SDKs bind to, the SDK registration API, and the framework adapters. A breaking change in the core can surface in both languages at once, and the adapters for Vercel AI SDK and Mastra are separate packages on their own release cadence. Pin your versions and read the release notes for the rc line before bumping.
The README also links benchmark results at benchmark.ratel.sh and the harness at ratel-ai/ratel-bench. I have not run those benchmarks and cannot vouch for the numbers. If the token reduction claim matters to your decision, that harness is where to reproduce it on your own tool set rather than taking the headline figure.
Facts versus skills: the re-injection detail worth understanding
One mechanism sits slightly apart from the search flow. The README describes constant grounding your agent always needs, such as a shop's address or a brand's voice, as being registered as facts and pushed into context, re-injected only when it is not already fresh in the transcript. This is a different problem from tool selection. Facts are not retrieved on demand by the model; they are conditionally re-inserted by the runtime based on whether the transcript still carries them. The README does not show a code example for registering facts, so the exact API for this is not something I can give you. It appears in the conceptual description only.
That gap matters if facts are the feature you actually want. The quickstart covers catalogs, tools and skills in both languages. Facts are described but not demonstrated. Before building around them, check the docs site rather than the README.
Editorial conclusion
Adopt Ratel if your agent already has more tools than the model can reliably choose between, and if you are willing to restructure tool exposure around search_capabilities, invoke_tool and get_skill_content. Do not adopt it if you have a handful of tools, or if you need a hosted retrieval service with a managed index. Before committing, verify three things: that the Rust core builds on your target platform through NAPI or PyO3, that your chosen ranking mode is actually available in your SDK version, and how your framework adapter maps the three returned tools into its own tool-calling interface.
Community notes