Inicio rápido

Conecta askRunic y storeResult a un agente existente en unos minutos.

Instalar

npm install @runic-labs/sdk

pnpm add @runic-labs/sdk

yarn add @runic-labs/sdk

bun add @runic-labs/sdk

@runic-labs/sdk depende de @runic-labs/cache y @runic-labs/ledger — no necesitas instalarlos por separado a menos que quieras construir instancias de almacenamiento personalizadas tú mismo (consulta Caché y Libro mayor).

Envuelve la llamada que tu agente ya realiza

Encuentra el lugar en tu agente donde convierte una tarea en una llamada a un LLM o herramienta, y envuélvela con askRunic / storeResult:

import { askRunic, storeResult } from "@runic-labs/sdk";

async function reviewFile(repo: string, file: string) {
  const decision = { intent: "review_code", params: { repo, file } };

  const cached = await askRunic(decision);
  if (cached) {
    console.log(`cache hit — saved ${cached.tokensSpent} tokens`);
    return cached.artifact;
  }

  const response = await callYourLLM(promptFor(repo, file));
  await storeResult(decision, response.text, response.tokensUsed);
  return response.text;
}

Esa es toda la integración. No se requiere configuración para empezar — askRunic/storeResult usan un almacenamiento predeterminado respaldado por archivos en .runic/ dentro de tu directorio de trabajo.

Elegir `intent` y `params`

La firma es de coincidencia exacta, así que decide qué hace realmente que dos llamadas sean «la misma decisión» en tu caso de uso:

Bueno: { intent: "summarize_pr", params: { repo: "acme/widgets", pr: 482 } } — mismo repositorio, mismo número de PR, misma intención, cada vez que se consulta sobre este PR exacto.
Malo: { intent: "summarize_pr", params: { prompt: fullPromptString } } — incluir el texto sin procesar del prompt como parámetro significa que cualquier cambio de redacción (incluso espacios en blanco) produce un fallo de caché, anulando el propósito.

Incluye en params solo los parámetros que realmente identifican la decisión. Deja el texto del prompt, los rastros de razonamiento y cualquier cosa no determinista completamente fuera de la firma — consulta Cómo funciona para saber por qué.

Inspecciona lo que está en caché

npm install -g @runic-labs/cli

pnpm add -g @runic-labs/cli

npm install -g @runic-labs/cli

bun add -g @runic-labs/cli

runic cache status
runic ledger status

Consulta CLI para ver ejemplos completos de salida.

Apunta a una ubicación de almacenamiento diferente

De forma predeterminada, Runic escribe en .runic/ dentro de process.cwd(). Anúlalo con una variable de entorno si tu agente se ejecuta desde un directorio de trabajo diferente de aquel donde quieres que resida el estado:

RUNIC_HOME=/var/lib/my-agent/runic node agent.js

Usa almacenamiento en memoria en su lugar (pruebas, ejecuciones efímeras)

import { createRunicClient } from "@runic-labs/sdk";
import { createCache, MemoryCacheStore } from "@runic-labs/cache";
import { createLedger, MemoryLedgerStore } from "@runic-labs/ledger";

const runic = createRunicClient({
  cache: createCache(new MemoryCacheStore()),
  ledger: createLedger(new MemoryLedgerStore()),
});

const cached = await runic.askRunic({ intent: "summarize_pr", params: { repo, pr } });

Esto es exactamente lo que usan benchmarks/reuse-sweep y benchmarks/openrouter-savings, por lo que no persiste nada entre ejecuciones separadas del script.

Cómo funciona — el algoritmo de firma en detalle
Benchmarks — reproduce cifras reales de ahorro de tokens