---
title: Introducción
description: >-
  Runic es una caché entre sesiones y un libro mayor de tokens para las
  decisiones ya resueltas de un agente.
---
Los agentes vuelven a decidir cosas que ya han decidido. El mismo PR se resume dos veces, el mismo archivo se revisa dos veces, la misma entrada del registro de cambios se genera dos veces — y cada vez, el agente paga el precio completo para regenerar una respuesta que ya produjo. Runic recuerda la respuesta en su lugar.

:::tip
**Pregunta una vez. Paga una vez.**
:::

## Qué es Runic

Runic se coloca junto a lo que un agente ya utiliza para actuar —incluidas las llamadas a herramientas MCP— como una comprobación opcional: *"¿ya resolví esta decisión exacta antes?"*

- **Una caché**, indexada mediante una firma normalizada de coincidencia exacta de una decisión que el agente ya tomó — `{ intent, params }`, nunca texto de tarea sin procesar, nunca un rastro de razonamiento.
- **Un libro mayor**, que registra los tokens gastados (informados por el agente) frente a los tokens ahorrados al reutilizar. Contabilidad pura, sin imposición.
- **Ámbito por sesión.** El uso compartido entre sesiones/agentes es una fase posterior, una vez que se demuestre que la reutilización por sesión importa.

## Lo que Runic deliberadamente no es

- **No es una capa de ejecución.** Runic nunca llama a una capacidad, despliega nada ni ejecuta código — el agente lo hace por sí mismo, como ya lo haga.
- **No es un sistema de permisos ni de aislamiento.** No hay nada que comprobar si no se ejecuta nada.
- **No es una caché semántica.** La coincidencia es exacta sobre la decisión resuelta, no aproximada sobre la redacción que llevó a ella. Consulta [Alcance](/scope) para entender por qué eso es una restricción, no un atajo.

## Instalación

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

## El 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)
```

Dos funciones constituyen todo el contrato orientado al agente. Todo lo demás en este repositorio respalda esas dos llamadas.

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

## Cifras reales, no estimaciones

Runic nunca mide el coste de los tokens por sí mismo — el agente lo informa, usando lo que realmente haya devuelto su propio proveedor. Una ejecución real contra OpenRouter, resolviendo 48 decisiones de las cuales solo 8 eran realmente únicas:

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

Consulta [Pruebas de rendimiento](/benchmarks) para saber cómo reproducirlo tú mismo, además de un barrido sintético que muestra que el mismo mecanismo se mantiene con 10.000 decisiones.

## Paquetes

| Paquete | Función |
| --- | --- |
| [`@runic-labs/sdk`](/sdk) | `askRunic` / `storeResult` — todo el contrato orientado al agente |
| [`@runic-labs/cache`](/cache) | almacén de firma → artefacto (en memoria + respaldado por archivos) |
| [`@runic-labs/ledger`](/ledger) | contabilidad de gastado frente a ahorrado |
| [`@runic-labs/cli`](/cli) | `runic cache status`, `runic ledger status` |

## Siguientes pasos

- [Inicio rápido](/quickstart) — conecta Runic a tu agente en unos minutos
- [Cómo funciona](/how-it-works) — el algoritmo de firma y por qué la coincidencia es exacta
- [Alcance](/scope) — qué se eliminó del plan anterior de capa de ejecución y por qué

## Contribuir

Runic es de código abierto y acepta contribuciones. Consulta `CONTRIBUTING.md` en el repositorio para ver las directrices.

## Licencia

MIT