---
title: Introdução
description: >-
  Runic é um cache entre sessões e um livro-razão de tokens para decisões que um
  agente já resolveu.
---
Os agentes tomam novamente decisões que já tomaram. O mesmo PR é resumido duas vezes, o mesmo arquivo é revisado duas vezes, a mesma entrada do changelog é gerada duas vezes — e, a cada vez, o agente paga o preço integral para regenerar uma resposta que já produziu. O Runic se lembra da resposta.

:::tip
**Pergunte uma vez. Pague uma vez.**
:::

## O que é o Runic

O Runic fica ao lado de tudo o que um agente já usa para agir — incluindo chamadas de ferramentas MCP — como uma verificação opcional: *"já resolvi esta decisão exata antes?"*

- **Um cache**, indexado por uma assinatura normalizada de correspondência exata de uma decisão que o agente já tomou — `{ intent, params }`, nunca texto bruto da tarefa, nunca um rastreamento de raciocínio.
- **Um livro-razão**, que registra tokens gastos (informados pelo agente) em comparação com tokens economizados na reutilização. Apenas contabilidade, sem imposição.
- **Escopo por sessão.** O compartilhamento entre sessões/agentes é uma fase posterior, quando for comprovado que a reutilização por sessão importa.

## O que o Runic deliberadamente não é

- **Não é uma camada de execução.** O Runic nunca chama uma capacidade, faz deploy de algo ou executa código — o agente faz isso por conta própria, da forma como já faz.
- **Não é um sistema de permissões ou sandboxing.** Não há nada para verificar se nada é executado.
- **Não é um cache semântico.** A correspondência é exata na decisão resolvida, não aproximada na formulação que levou a ela. Veja [Escopo](/scope) para entender por que isso é uma restrição, não um atalho.

## Instalação

```package-install
npm i @runic-labs/sdk
```

## O ciclo

```txt
agent resolves a task into a structured decision
        │
        ▼
askRunic({ intent, params })
        │
        ├─ hit  → return cached artifact, log tokens saved
        └─ miss → agent generates its own way (as it does today)
                        │
                        ▼
                storeResult({ intent, params }, artifact, tokensSpent)
```

Duas funções constituem todo o contrato voltado ao agente. Tudo o mais neste repositório dá suporte a essas duas chamadas.

<CodeGroup>

```ts Without Runic
// Every call regenerates the answer, even for a decision you've
// already resolved once today.
async function summarizePr(repo: string, pr: number) {
  const result = await callYourLLM(promptFor(repo, pr));
  return result; // paid full price, every single time
}
```

```ts With Runic
import { askRunic, storeResult } from "@runic-labs/sdk";

async function summarizePr(repo: string, pr: number) {
  const decision = { intent: "summarize_pr", params: { repo, pr } };

  const cached = await askRunic(decision);
  if (cached) return cached.artifact; // no LLM call, no tokens spent

  const result = await callYourLLM(promptFor(repo, pr));
  await storeResult(decision, result, result.tokensUsed);
  return result;
}
```

</CodeGroup>

## Números reais, não estimativas

O Runic nunca mede o custo de tokens por conta própria — o agente o informa, usando o que seu próprio provedor realmente retornou. Uma execução real no OpenRouter, resolvendo 48 decisões, das quais apenas 8 eram de fato únicas:

```json
{
  "decisions": 48,
  "uniqueDecisions": 8,
  "apiCalls": 8,
  "cacheHits": 40,
  "tokensSpent": 2582,
  "tokensSaved": 12910,
  "tokensWithoutRunic": 15492,
  "savingsPercent": 83
}
```

Veja [Benchmarks](/benchmarks) para saber como reproduzir isso por conta própria, além de uma varredura sintética que mostra que o mesmo mecanismo se mantém em 10.000 decisões.

## Pacotes

| Pacote | Faz |
| --- | --- |
| [`@runic-labs/sdk`](/sdk) | `askRunic` / `storeResult` — todo o contrato voltado ao agente |
| [`@runic-labs/cache`](/cache) | armazenamento de assinatura → artefato (em memória + baseado em arquivo) |
| [`@runic-labs/ledger`](/ledger) | contabilidade de gastos em comparação com economias |
| [`@runic-labs/cli`](/cli) | `runic cache status`, `runic ledger status` |

## Próximos passos

- [Início rápido](/quickstart) — conecte o Runic ao seu agente em poucos minutos
- [Como funciona](/how-it-works) — o algoritmo de assinatura e por que a correspondência é exata
- [Escopo](/scope) — o que foi removido do plano anterior de camada de execução e por quê

## Contribuindo

O Runic é de código aberto e aceita contribuições. Consulte `CONTRIBUTING.md` no repositório para ver as diretrizes.

## Licença

MIT