# Ratel Documentation

> Ratel is the context engineering platform for AI agents, an in-process library
> that engineers the context your agent actually needs on every turn. These docs
> cover Ratel Core (the TypeScript and Python SDKs and the Rust engine behind
> them), Ratel Local (the MCP Gateway for Claude Code, Codex, and Cursor), and
> Ratel Cloud (hosted context analytics, coming soon).

- [Ratel documentation](https://docs.ratel.sh/docs): Start with Ratel Core, then explore Cloud analytics and Local MCP retrieval.

## Ratel Core

- [What is Ratel?](https://docs.ratel.sh/docs/core): Ratel is an open-source context gateway for AI agents — it keeps your tool and skill catalog out of the prompt and retrieves only what each turn needs.
- [Features](https://docs.ratel.sh/docs/core/features): Everything Ratel Core does, one page per feature.
- [Quick start](https://docs.ratel.sh/docs/core/quickstart): The fastest way into Ratel: install the open-source skills into your coding agent and let it integrate Ratel for you — or jump to the TypeScript and Python quickstarts.
- [What's new](https://docs.ratel.sh/docs/core/whats-new): Release history of ratel-ai-core, the Rust engine both SDKs bundle, with links to every package changelog.
- [FAQ](https://docs.ratel.sh/docs/core/faq): Common questions about Ratel Core.
- [Install](https://docs.ratel.sh/docs/core/install): Install the Ratel SDK for TypeScript or Python, or run Ratel Local for MCP clients.
- [Architecture](https://docs.ratel.sh/docs/core/architecture): The layers of Ratel Core — Rust engine, SDK bindings, catalogs, retrieval, telemetry — and how one agent turn flows through them.
- [Efficiency](https://docs.ratel.sh/docs/core/efficiency): What Ratel changes in the model's context, and what that saves in tokens and accuracy.
- [Benchmark](https://docs.ratel.sh/docs/core/benchmark): How ratel-bench measures Ratel's token savings and accuracy, and where the results live.
- [Licensing](https://docs.ratel.sh/docs/core/licensing): The ratel-ai-core engine is Apache-2.0; everything else is MIT.
- [Tools, MCP & Skills](https://docs.ratel.sh/docs/core/tools-mcp-skills): What goes into Ratel's catalogs: local tools, MCP server tools, and skills — registered once, ranked per turn by search_capabilities, loaded on demand.
- [Progressive disclosure](https://docs.ratel.sh/docs/core/progressive-disclosure): Start with a minimal tool surface and pull in more on demand: the contracts for search_capabilities, invoke_tool, and get_skill_content.
- [Keyword search](https://docs.ratel.sh/docs/core/keyword-search): Ratel's default retrieval: BM25 over a schema-aware text projection of every tool and skill definition — in-process, deterministic, no model, no vector DB, no service.
- [Semantic & hybrid search](https://docs.ratel.sh/docs/core/semantic-hybrid-search): Opt-in semantic and hybrid retrieval: local embeddings, RRF fusion with BM25, and the pre-built embedding cache behind them.
- [Adaptive ranking](https://docs.ratel.sh/docs/core/adaptive-ranking): Retrieval that learns from your agent's real usage. Coming soon.
- [Compaction](https://docs.ratel.sh/docs/core/compaction): Keep long-running agent context lean without losing what matters. Coming soon.
- [Telemetry](https://docs.ratel.sh/docs/core/telemetry): Capture Ratel's search and invoke funnel as local trace events, or export it as OpenTelemetry spans, greenfield or alongside an existing provider.
- [SDKs](https://docs.ratel.sh/docs/core/sdks): Two first-party SDKs, TypeScript and Python, over one Rust core. In-process, no infra, no API key.
- [Related projects](https://docs.ratel.sh/docs/core/related-projects): The Ratel ecosystem around the Core SDKs: the core repo, Ratel Local, the benchmark, the skills suite, and Ratel Cloud.
- [Install](https://docs.ratel.sh/docs/core/typescript/install): Install @ratel-ai/sdk: requirements, prebuilt native targets, optional packages, and the embedding model download.
- [Quickstart](https://docs.ratel.sh/docs/core/typescript/quickstart): Install @ratel-ai/sdk, put your tools and prompt playbooks in Ratel catalogs, and hand any agent loop the three capability tools.
- [Register tools](https://docs.ratel.sh/docs/core/typescript/register-tools): Define executable tools, register them in a ToolCatalog, rank without execution via ToolRegistry, and spot-check what surfaces.
- [Register MCP servers](https://docs.ratel.sh/docs/core/typescript/register-mcps): Ingest an MCP server's tools with registerMcpServer: namespaced ids, the returned handle, error propagation, and many servers on one ranked surface.
- [Register skills](https://docs.ratel.sh/docs/core/typescript/register-skills): SkillCatalog: register Markdown playbooks that rank in their own corpus and surface next to tools.
- [Use the discovery tools](https://docs.ratel.sh/docs/core/typescript/discovery-tools): Wrap the catalog in search_capabilities and invoke_tool, assemble each turn's toolset with a top-K pre-filter, and pick a retrieval method per call.
- [Framework integrations](https://docs.ratel.sh/docs/core/typescript/framework-integrations): Wire Ratel into the Vercel AI SDK: one adapter to the framework's tool type, one loop that assembles the capability tools plus a top-K pre-filter.
- [Telemetry & OTel](https://docs.ratel.sh/docs/core/typescript/telemetry): Wire local trace sinks onto your catalogs and export the same funnel as OpenTelemetry spans, greenfield or alongside an existing provider.
- [Packages](https://docs.ratel.sh/docs/core/typescript/packages): The four TypeScript packages: SDK, telemetry vocabulary, OTLP exporter, and the package behind Ratel Local.
- [Install](https://docs.ratel.sh/docs/core/python/install): Install ratel-ai: requirements, prebuilt wheels, the mcp and otlp extras, and the embedding model download.
- [Quickstart](https://docs.ratel.sh/docs/core/python/quickstart): Install ratel-ai, put your tools and prompt playbooks in Ratel catalogs, and hand any agent loop the three capability tools.
- [Register tools](https://docs.ratel.sh/docs/core/python/register-tools): Define executable tools, register them in a ToolCatalog, rank without execution via ToolRegistry, and spot-check what surfaces.
- [Register MCP servers](https://docs.ratel.sh/docs/core/python/register-mcps): Ingest an upstream MCP server's tools with register_mcp_server: namespaced ids, the session-owning handle, error propagation, one ranked surface.
- [Register skills](https://docs.ratel.sh/docs/core/python/register-skills): Register Markdown playbooks in a SkillCatalog and surface them through search_capabilities alongside tools.
- [Use the discovery tools](https://docs.ratel.sh/docs/core/python/discovery-tools): Hand the agent search_capabilities, invoke_tool, and get_skill_content, then assemble each turn's toolset with a top-K pre-filter.
- [Framework integrations](https://docs.ratel.sh/docs/core/python/framework-integrations): Wire Ratel into Pydantic AI: one adapter to the framework's tool type, one loop that assembles the capability tools plus a top-K pre-filter.
- [Telemetry & OTel](https://docs.ratel.sh/docs/core/python/telemetry): Capture Ratel's search and invoke funnel as local trace events, or export it as OpenTelemetry spans — greenfield or alongside an existing provider.
- [Packages](https://docs.ratel.sh/docs/core/python/packages): The two Python packages behind the SDK, with links to their generated API references and changelogs.
- [Package list](https://docs.ratel.sh/docs/core/packages): Package map for Ratel Core and Local, with raw API references generated from source doc comments.
- [ratel-ai-core](https://docs.ratel.sh/docs/core/packages/rust/ratel-ai-core): The Rust core behind both SDKs — BM25/semantic/hybrid retrieval registries and the local trace stream.
- [Changelog](https://docs.ratel.sh/docs/core/packages/rust/ratel-ai-core/changelog): Release history of ratel-ai-core.
- [ratel-ai-telemetry (Rust)](https://docs.ratel.sh/docs/core/packages/rust/ratel-ai-telemetry): Raw API of the ratel-ai-telemetry crate — the Rust vocabulary for the ratel.* semantic conventions.
- [Changelog](https://docs.ratel.sh/docs/core/packages/rust/ratel-ai-telemetry/changelog): Release history of ratel-ai-telemetry.
- [@ratel-ai/sdk](https://docs.ratel.sh/docs/core/packages/typescript/sdk): Raw API of @ratel-ai/sdk — every exported class, function, type, and constant of the TypeScript SDK.
- [Changelog](https://docs.ratel.sh/docs/core/packages/typescript/sdk/changelog): Release history of @ratel-ai/sdk.
- [@ratel-ai/telemetry](https://docs.ratel.sh/docs/core/packages/typescript/telemetry): Raw API of @ratel-ai/telemetry — the OTel-free ratel.* semantic-convention vocabulary for TypeScript.
- [Changelog](https://docs.ratel.sh/docs/core/packages/typescript/telemetry/changelog): Release history of @ratel-ai/telemetry.
- [@ratel-ai/telemetry-otlp](https://docs.ratel.sh/docs/core/packages/typescript/telemetry-otlp): Raw API of @ratel-ai/telemetry-otlp — one-call OTLP exporter wiring for Ratel telemetry in Node.
- [Changelog](https://docs.ratel.sh/docs/core/packages/typescript/telemetry-otlp/changelog): Release history of @ratel-ai/telemetry-otlp.
- [@ratel-ai/mcp-server](https://docs.ratel.sh/docs/core/packages/typescript/mcp-server): Package reference for the MCP server, CLI, and library that power Ratel Local.
- [ratel-ai](https://docs.ratel.sh/docs/core/packages/python/ratel-ai): Raw API of ratel-ai — every exported class, function, and constant of the Python SDK.
- [Changelog](https://docs.ratel.sh/docs/core/packages/python/ratel-ai/changelog): Release history of ratel-ai.
- [ratel-ai-telemetry (Python)](https://docs.ratel.sh/docs/core/packages/python/ratel-ai-telemetry): Raw API of ratel-ai-telemetry — the ratel.* overlay on OpenTelemetry gen_ai spans for Python.
- [Changelog](https://docs.ratel.sh/docs/core/packages/python/ratel-ai-telemetry/changelog): Release history of ratel-ai-telemetry.

## Ratel Cloud

- [Ratel Cloud](https://docs.ratel.sh/docs/cloud): Hosted analytics for context usage and retrieval performance.

## Ratel Local

- [Introduction](https://docs.ratel.sh/docs/local): Ratel Local — MCP Gateway that fronts Claude Code / Codex / Cursor with capability search.
- [Quickstart: Claude Code & Codex](https://docs.ratel.sh/docs/local/quickstart): Put Ratel Local in front of an MCP setup and verify capability search in under five minutes.
- [Cursor](https://docs.ratel.sh/docs/local/cursor): Add Ratel Local to Cursor through its standard MCP configuration.
- [MCP servers](https://docs.ratel.sh/docs/local/mcp-servers): Configure upstream MCP servers, scopes, transports, and the Ratel Local process.
- [Import or link](https://docs.ratel.sh/docs/local/import-or-link): Move native MCP entries behind Ratel Local or connect a host without migrating them.
- [Browser UI](https://docs.ratel.sh/docs/local/browser-ui): Manage Ratel Local configuration from its loopback-only browser app.
- [Managing skills with the CLI](https://docs.ratel.sh/docs/local/managing-skills): Use the ratel-mcp skill command group to move agent skills behind Ratel Local, wire the prompt-time preload hook, and debug skill ranking.
- [OAuth upstreams](https://docs.ratel.sh/docs/local/oauth): Authorize remote MCP servers, inspect token status, and recover from expired credentials.
- [Statusline & telemetry](https://docs.ratel.sh/docs/local/statusline-telemetry): Inspect Ratel Local events and show estimated context savings in Claude Code.
- [Embed as a library](https://docs.ratel.sh/docs/local/library): Build and serve a Ratel Local gateway from your own Node process.
- [Troubleshooting](https://docs.ratel.sh/docs/local/troubleshooting): Diagnose host wiring, upstream startup, authentication, project scopes, networking, and version drift.

## Full text

- [llms-full.txt](https://docs.ratel.sh/llms-full.txt): every page concatenated as Markdown