Introdução

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.

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 para entender por que isso é uma restrição, não um atalho.

Instalação

npm install @runic-labs/sdk

pnpm add @runic-labs/sdk

yarn add @runic-labs/sdk

bun add @runic-labs/sdk

O ciclo

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.

// 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
}

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;
}

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:

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

Veja 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

Próximos passos

• Início rápido — conecte o Runic ao seu agente em poucos minutos
• Como funciona — o algoritmo de assinatura e por que a correspondência é exata
• Escopo — 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