# 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 the Ratel SDK (the TypeScript and Python SDKs over one Rust engine),
> Ratel Local (the MCP Gateway for Claude Code, Codex, and Cursor), and
> Ratel Cloud (hosted context analytics, coming soon).

## Ratel SDK

- [What is Ratel?](https://www.ratel.sh/docs): 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.
- [Quick start](https://www.ratel.sh/docs/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.
- [Install](https://www.ratel.sh/docs/install): Install the Ratel SDK for TypeScript or Python, or run Ratel Local for MCP clients.
- [What's new](https://www.ratel.sh/docs/whats-new): Release history of ratel-ai-core, the Rust engine both SDKs bundle, with links to every package changelog.
- [FAQ](https://www.ratel.sh/docs/faq): Common questions about Ratel.
- [Optimize agent capabilities](https://www.ratel.sh/docs/optimization): Put every tool, MCP server, and skill in a searchable catalog and disclose only what each turn needs: fewer tokens per turn, tool selection as good or better.
- [Observe your agent](https://www.ratel.sh/docs/observability): Capture Ratel's search and invoke funnel as local trace events, or export it as OpenTelemetry spans, greenfield or alongside an existing provider.
- [Self-improving agent](https://www.ratel.sh/docs/self-improvement): Adaptive usage ranking feeds what your agent actually invokes back into retrieval. Experimental opt-in, off by default.
- [Managing chat history](https://www.ratel.sh/docs/chat-history): Keep long-running conversations lean without losing what matters. Coming soon.
- [Agent memory](https://www.ratel.sh/docs/agent-memory): Long-lived memory your agent can store and retrieve like any other capability. Coming soon.
- [Architecture](https://www.ratel.sh/docs/architecture): The layers of the Ratel SDK (Rust engine, SDK bindings, catalogs, retrieval, telemetry) and how one agent turn flows through them.
- [Tools, MCP & Skills](https://www.ratel.sh/docs/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 tools](https://www.ratel.sh/docs/progressive-disclosure-tools): The language-neutral contract for the three capability tools: search_capabilities, invoke_tool, and get_skill_content; request and result shapes, the error table, and how to construct them.
- [Recall modes](https://www.ratel.sh/docs/recall-modes): Two ways the catalog's top-K reaches the model: eager recall appended by the host, or on-demand search the model runs itself. Both preserve prompt caching.
- [Retrieval and search](https://www.ratel.sh/docs/retrieval-and-search): How Ratel ranks the catalog: BM25 keyword search over a schema-aware projection by default, semantic and hybrid ranking when you opt in, and how to choose between them.
- [Embedding models](https://www.ratel.sh/docs/embedding-models): Configure the model behind semantic and hybrid search: a HuggingFace repo, a local checkpoint, Ollama, or any OpenAI-compatible endpoint.
- [Benchmark](https://www.ratel.sh/docs/benchmark): How ratel-bench measures Ratel's token savings and accuracy, and where the results live.
- [Licensing](https://www.ratel.sh/docs/licensing): The ratel-ai-core engine is Apache-2.0; everything else is MIT.
- [Skillset](https://www.ratel.sh/docs/skillset): The Ratel skills suite: five open-source skills that audit your agent codebase, plan observability, integrate Ratel, and fix what the audit finds.
- [SDKs](https://www.ratel.sh/docs/sdks): Two first-party SDKs, TypeScript and Python, over one Rust core. In-process, no infra, no API key.
- [Related projects](https://www.ratel.sh/docs/related-projects): The Ratel ecosystem around the Ratel SDK: the core repo, Ratel Local, the benchmark, the skills suite, and Ratel Cloud.
- [Install](https://www.ratel.sh/docs/typescript/install): Install @ratel-ai/sdk: requirements, prebuilt native targets, optional packages, and the embedding model download.
- [Quickstart](https://www.ratel.sh/docs/typescript/quickstart): Install @ratel-ai/sdk, create the ratel() core, register your tools and prompt playbooks, and hand any agent loop the three capability tools.
- [Register tools](https://www.ratel.sh/docs/typescript/register-tools): Define executable tools, register a batch in one r.tools.register call, search and invoke through the guarded handle, and drop to the shared ToolCatalog or ToolRegistry underneath.
- [Register MCP servers](https://www.ratel.sh/docs/typescript/register-mcps): Ingest an MCP server's tools into the ratel() core with registerMcpServer: namespaced ids, the returned handle, error propagation, and many servers on one ranked surface.
- [Register skills](https://www.ratel.sh/docs/typescript/register-skills): r.skills: register Markdown playbooks that rank in their own corpus and surface next to tools — the core's SkillCatalog, exposed raw.
- [Use the discovery tools](https://www.ratel.sh/docs/typescript/discovery-tools): Hand any loop the three capability tools from r.modelTools(), rank the catalog host-side with r.tools.search and r.recall, and pick a retrieval method per call.
- [Semantic & hybrid search](https://www.ratel.sh/docs/typescript/semantic-search): Opt into dense retrieval in TypeScript: fix the method on ratel(), embed at register, rank with searchAsync, and handle the typed embedding errors.
- [Framework integrations](https://www.ratel.sh/docs/typescript/framework-integrations): Official adapters for the Vercel AI SDK and Mastra: ratel().adaptTo(...) speaks each framework's native tool and message shapes, with per-turn recall built in.
- [Telemetry & OTel](https://www.ratel.sh/docs/typescript/telemetry): Wire a local trace sink through ratel({ trace }) and export the same funnel as OpenTelemetry spans, greenfield or alongside an existing provider.
- [Packages](https://www.ratel.sh/docs/typescript/packages): The five TypeScript packages: SDK, Vercel AI SDK adapter, Mastra adapter, telemetry vocabulary, and the package behind Ratel Local.
- [Install](https://www.ratel.sh/docs/python/install): Install ratel-ai: requirements, prebuilt wheels, the mcp and otlp extras, and the embedding model download.
- [Quickstart](https://www.ratel.sh/docs/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://www.ratel.sh/docs/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://www.ratel.sh/docs/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://www.ratel.sh/docs/python/register-skills): Register Markdown playbooks in a SkillCatalog and surface them through search_capabilities alongside tools.
- [Use the discovery tools](https://www.ratel.sh/docs/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.
- [Semantic & hybrid search](https://www.ratel.sh/docs/python/semantic-search): Opt into dense retrieval in Python: embed at register, search with search_async, and handle the typed embedding errors.
- [Framework integrations](https://www.ratel.sh/docs/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://www.ratel.sh/docs/python/telemetry): Capture Ratel's search and invoke funnel as local trace events, or export it as OpenTelemetry traces and Logs, greenfield or alongside an existing provider.
- [Packages](https://www.ratel.sh/docs/python/packages): The two Python packages behind the SDK, with links to their generated API references and changelogs.
- [Package list](https://www.ratel.sh/docs/packages): Package map for the Ratel SDK and Ratel Local, with raw API references generated from source doc comments.
- [ratel-ai-core](https://www.ratel.sh/docs/packages/rust/ratel-ai-core): The Rust core behind both SDKs — BM25/semantic/hybrid retrieval registries and the local trace stream.
- [Changelog](https://www.ratel.sh/docs/packages/rust/ratel-ai-core/changelog): Release history of ratel-ai-core.
- [ratel-ai-telemetry (Rust)](https://www.ratel.sh/docs/packages/rust/ratel-ai-telemetry): Raw API of the ratel-ai-telemetry crate — the Rust vocabulary for the ratel.* semantic conventions.
- [Changelog](https://www.ratel.sh/docs/packages/rust/ratel-ai-telemetry/changelog): Release history of ratel-ai-telemetry.
- [@ratel-ai/sdk](https://www.ratel.sh/docs/packages/typescript/sdk): Raw API of @ratel-ai/sdk — every exported class, function, type, and constant of the TypeScript SDK.
- [Changelog](https://www.ratel.sh/docs/packages/typescript/sdk/changelog): Release history of @ratel-ai/sdk.
- [@ratel-ai/vercel-ai-sdk](https://www.ratel.sh/docs/packages/typescript/vercel-ai-sdk): Raw API of @ratel-ai/vercel-ai-sdk — the official Vercel AI SDK adapter: the aiSdk() factory for ratel().adaptTo(), speaking ai@5-7 tool and message shapes.
- [Changelog](https://www.ratel.sh/docs/packages/typescript/vercel-ai-sdk/changelog): Release history of @ratel-ai/vercel-ai-sdk.
- [@ratel-ai/mastra](https://www.ratel.sh/docs/packages/typescript/mastra): Raw API of @ratel-ai/mastra — the official Mastra adapter: the mastra() factory for ratel().adaptTo() plus recallProcessor(), speaking @mastra/core tool and message shapes.
- [Changelog](https://www.ratel.sh/docs/packages/typescript/mastra/changelog): Release history of @ratel-ai/mastra.
- [@ratel-ai/telemetry](https://www.ratel.sh/docs/packages/typescript/telemetry): Raw API of @ratel-ai/telemetry — the OTel-free ratel.* semantic-convention vocabulary for TypeScript.
- [Changelog](https://www.ratel.sh/docs/packages/typescript/telemetry/changelog): Release history of @ratel-ai/telemetry.
- [@ratel-ai/ratel-local](https://www.ratel.sh/docs/packages/typescript/mcp-server): Package reference for the MCP server, CLI, and library that power Ratel Local.
- [ratel-ai](https://www.ratel.sh/docs/packages/python/ratel-ai): Raw API of ratel-ai — every exported class, function, and constant of the Python SDK.
- [Changelog](https://www.ratel.sh/docs/packages/python/ratel-ai/changelog): Release history of ratel-ai.
- [ratel-ai-telemetry (Python)](https://www.ratel.sh/docs/packages/python/ratel-ai-telemetry): Raw API of ratel-ai-telemetry — the ratel.* overlay on OpenTelemetry gen_ai spans for Python.
- [Changelog](https://www.ratel.sh/docs/packages/python/ratel-ai-telemetry/changelog): Release history of ratel-ai-telemetry.

## Ratel Cloud

- [Ratel Cloud](https://www.ratel.sh/docs/cloud): Hosted telemetry, dashboards, and APIs for your agent.
- [Send telemetry](https://www.ratel.sh/docs/cloud/opentelemetry): Point any OpenTelemetry exporter at Ratel Cloud. No Ratel SDK needed.
- [Embeddings](https://www.ratel.sh/docs/cloud/embeddings): Hosted, OpenAI-compatible embeddings authenticated by your project key.
- [Tool Picker](https://www.ratel.sh/docs/cloud/tool-picker): Send what the agent wants to do. Get back the tools to call from your own catalog, ranked and scored.
- [Credits and billing](https://www.ratel.sh/docs/cloud/credits): How the hosted APIs are paid for. One balance per API, allowance first, then prepaid credit.

## Ratel Local

- [Introduction](https://www.ratel.sh/docs/local): Ratel Local: MCP Gateway that fronts Claude Code / Codex / Cursor with capability search.
- [Quickstart: Claude Code & Codex](https://www.ratel.sh/docs/local/quickstart): Install Ratel Local, run the setup wizard, and verify capability search.
- [Cursor](https://www.ratel.sh/docs/local/cursor): Add Ratel Local to Cursor through its standard MCP configuration.
- [Daemon](https://www.ratel.sh/docs/local/daemon): Understand and manage the persistent Ratel Local background service.
- [MCP servers](https://www.ratel.sh/docs/local/mcp-servers): Configure upstream MCP servers, scopes, transports, and the Ratel Local process.
- [Retrieval](https://www.ratel.sh/docs/local/retrieval): Configure model-free BM25, semantic, or hybrid capability search by scope.
- [Import or link](https://www.ratel.sh/docs/local/import-or-link): Move native MCP entries behind Ratel Local or connect a host without migrating them.
- [Browser UI](https://www.ratel.sh/docs/local/browser-ui): Manage projects, gateways, agents, retrieval, and upstreams in the persistent daemon UI.
- [Managing skills](https://www.ratel.sh/docs/local/managing-skills): Import, register, inspect, and remove skills by Ratel Local scope.
- [OAuth upstreams](https://www.ratel.sh/docs/local/oauth): Authorize remote MCP servers, inspect token status, and recover from expired credentials.
- [Statusline & local telemetry](https://www.ratel.sh/docs/local/statusline-telemetry): Inspect local Ratel events and show estimated context savings in Claude Code.
- [Experimental Cloud telemetry](https://www.ratel.sh/docs/local/cloud-telemetry): Enable the default-off Ratel Cloud relay and native agent exporters with explicit consent.
- [Embed as a library](https://www.ratel.sh/docs/local/library): Build and serve a Ratel Local gateway from your own Node process.
- [Troubleshooting](https://www.ratel.sh/docs/local/troubleshooting): Diagnose the daemon, agent connector, project scope, upstreams, retrieval, and telemetry.

## Full text

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