@runic-labs/cache

署名キー付きアーティファクトストレージ — メモリ内およびファイルバックエンド。

@runic-labs/cache は、正規化された決定の署名を、それによって生成されたアーティファクトに対応付けます。ほとんどの統合ではこのパッケージを直接必要としません — @runic-labs/sdk がラップしています — ただし、カスタムストアのセットアップやキャッシュ内部の調査には便利です。

npm install @runic-labs/cache

pnpm add @runic-labs/cache

yarn add @runic-labs/cache

bun add @runic-labs/cache

signature(decision)

Decision を正規化し、その SHA-256 署名を返します。params 内のオブジェクトキーは再帰的にソートされるため、キー順がハッシュに影響することはありません。完全なアルゴリズムについては仕組みを参照してください。

import { signature } from "@runic-labs/cache";

signature({ intent: "summarize_pr", params: { repo: "acme/widgets", pr: 482 } });
// => same hash regardless of param key order

createCache(store?)

import { createCache, FileCacheStore, defaultCacheFilePath } from "@runic-labs/cache";

const cache = createCache(new FileCacheStore({ filePath: defaultCacheFilePath() }));

ストアが渡されない場合、デフォルトでは .runic/cache.json（または $RUNIC_HOME/cache.json）配下の FileCacheStore が使用されます。

ストレージバックエンド

MemoryCacheStore

メモリ内のみで、プロセスの存続期間中だけ保持されます。ベンチマークとテストの両方で使用されるため、実行は自己完結し、再現可能です。

import { createCache, MemoryCacheStore } from "@runic-labs/cache";

const cache = createCache(new MemoryCacheStore({ staleAfterMs: 60_000 }));

FileCacheStore

JSON ファイルに永続化するため、CLI プロセスとエージェントプロセスは、サーバーを稼働させずに同じキャッシュを読み取れます。

import { createCache, FileCacheStore } from "@runic-labs/cache";

const cache = createCache(new FileCacheStore({ filePath: "./my-agent/.runic/cache.json" }));

破損または部分的に書き込まれたファイルは、例外をスローするのではなく空として扱われます — 書き込み途中のクラッシュによって、次回の読み取りが失敗してはなりません。

独自の CacheStore を実装する

組み込みストアはどちらも同じ小さなインターフェースを実装しているため、Redis または SQLite をバックエンドとするストアはそのまま置き換えられます。

interface CacheStore {
  get(signature: string): CachedEntry | null;
  set(signature: string, artifact: unknown, meta: { tokensSpent: number }): CachedEntry;
  touch(signature: string): CachedEntry | null;
  list(): CachedEntry[];
  clear(): void;
}

touch は、hitCount と lastUsedAt を更新するために、キャッシュヒットのたびに内部で呼び出されます — 選択した任意のバッキングストアに対して、読み取り・変更・書き込みとして実装してください。

次へ

• Ledger — 対応する使用量／節約量の会計レイヤー
• SDK — ほとんどの統合が実際に使用する 2 関数の契約