---
title: '@runic-labs/ledger'
description: 使用したトークンと節約したトークンの追記専用の集計。
sidebar:
  order: 5
---
`@runic-labs/ledger` は純粋な記録管理です。予算を強制することも、呼び出しを拒否することも、報告していないコストを見積もることもありません。答えるのは一つの問いだけです。*これらの決定を解決するのに実際どれだけのコストがかかり、そのうち再利用によってどれだけ回避できたのか？*

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

## `createLedger(store?)`

```ts
import { createLedger, FileLedgerStore, defaultLedgerFilePath } from "@runic-labs/ledger";

const ledger = createLedger(new FileLedgerStore({ filePath: defaultLedgerFilePath() }));
```

ストアを渡さない場合、デフォルトでは `.runic/ledger.json`（または `$RUNIC_HOME/ledger.json`）配下の `FileLedgerStore` になります。

| Prop | Type | Default | Description |
| - | - | - | - |
| `recordMiss(signature, tokensSpent)?` | `void` | - | キャッシュミスを記録します。エージェントが独自に生成し、tokensSpent を消費しました。 |
| `recordHit(signature)?` | `void` | - | キャッシュヒットを記録し、このシグネチャに対する元のミスと同じ tokensSpent を記録します。 |
| `summary()?` | `LedgerSummary` | - | 集計済みの合計値。以下を参照してください。 |
| `all()?` | `LedgerEvent[]` | - | 完全な生イベントログ。 |
| `clear()?` | `void` | - | すべてのイベントを削除します。 |

## `LedgerSummary`

```ts
interface LedgerSummary {
  totalSpent: number;
  totalSaved: number;
  hitsBySignature: Record<string, number>;
}
```

```ts
const summary = ledger.summary();
const totalHits = Object.values(summary.hitsBySignature).reduce((a, b) => a + b, 0);
const tokensWithoutRunic = summary.totalSpent + summary.totalSaved;
const savingsPercent = Math.round((summary.totalSaved / tokensWithoutRunic) * 100);
```

これは `benchmarks/openrouter-savings` と `benchmarks/reuse-sweep` の両方が最終的な数値を表示するために使う計算と完全に同じです。詳しくは [ベンチマーク](/benchmarks) を参照してください。

## `recordHit` が `tokensSpent` 引数を受け取らない理由

ヒットの価値は、*そのシグネチャに対する元のミスのコスト*として定義されます。レジャーは、呼び出し元が各ヒットで正しく繰り返し指定することを信用するのではなく、自身でそれを検索します。何らかの理由でヒットしているシグネチャに先行するミスがない場合（通常の利用では起こらないはずですが、レジャーは起こり得ないと決めつけません）、推測するのではなく `0` を記録します。

## ストレージバックエンド

`@runic-labs/cache` と同じパターンです。テストや一時的な実行には `MemoryLedgerStore`、別々のプロセス起動をまたいだ永続化には `FileLedgerStore` を使用します。別のバックエンドには、`LedgerStore` インターフェースを自分で実装してください。

```ts
interface LedgerStore {
  append(event: LedgerEvent): void;
  all(): LedgerEvent[];
  clear(): void;
}
```

## 次へ

- [キャッシュ](/cache) — 対応するシグネチャキー付きストア
- [CLI](/cli) — `runic ledger status` はコマンドラインからこの概要を読み取ります