クイックスタート

数分で既存のエージェントに askRunic と storeResult を組み込みます。

インストール

npm install @runic-labs/sdk

pnpm add @runic-labs/sdk

yarn add @runic-labs/sdk

bun add @runic-labs/sdk

@runic-labs/sdk は @runic-labs/cache と @runic-labs/ledger に依存しています。カスタムのストアインスタンスを自分で構築したい場合を除き、これらを個別にインストールする必要はありません（Cache および Ledger を参照）。

エージェントがすでに行っている呼び出しをラップする

エージェント内でタスクを LLM またはツールへの呼び出しに変換している箇所を見つけ、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;
}

これで統合は完了です。開始にあたって設定は不要です。askRunic/storeResult は、作業ディレクトリ内の .runic/ 配下にあるデフォルトのファイルベースストアを使用します。

`intent` と `params` の選び方

シグネチャは完全一致で判定されるため、ユースケースにおいて 2 つの呼び出しを実際に「同じ決定」と見なす条件を決めます。

良い例: { intent: "summarize_pr", params: { repo: "acme/widgets", pr: 482 } } — 同じリポジトリ、同じ PR 番号、同じ intent であり、この特定の PR について問い合わせるたびに同じです。
悪い例: { intent: "summarize_pr", params: { prompt: fullPromptString } } — 生のプロンプトテキストをパラメータに含めると、文言の変更（空白だけの変更であっても）ごとにキャッシュミスとなり、目的を損ないます。

実際に決定を識別するパラメータだけを params に入れてください。プロンプトテキスト、推論トレース、非決定的なものはすべてシグネチャから除外します。理由については How it works を参照してください。

キャッシュされている内容を確認する

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

出力例の全体については CLI を参照してください。

別のストアの場所を指定する

デフォルトでは、Runic は process.cwd() の .runic/ に書き込みます。状態を保存したい場所とは異なる作業ディレクトリからエージェントを実行する場合は、環境変数で上書きします。

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

代わりにインメモリストレージを使用する（テスト、一時的な実行）

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

これは benchmarks/reuse-sweep と benchmarks/openrouter-savings が使用しているものとまったく同じため、個別のスクリプト実行間で何も永続化されません。

How it works — シグネチャアルゴリズムの詳細
Benchmarks — 実際のトークン節約量を再現する