---
title: '@runic-labs/cache'
description: >-
  Armazenamento de artefatos indexado por assinatura — em memória e baseado em
  arquivos.
sidebar:
  order: 4
---
`@runic-labs/cache` mapeia uma assinatura de decisão normalizada para o artefato produzido por ela. A maioria das integrações não precisa deste pacote diretamente — `@runic-labs/sdk` o encapsula — mas ele é útil para configurações personalizadas de armazenamento ou para inspecionar os detalhes internos do cache.

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

## `signature(decision)`

Normaliza uma `Decision` e retorna sua assinatura SHA-256. As chaves de objeto em `params` são ordenadas recursivamente para que a ordem das chaves nunca afete o hash. Consulte [Como funciona](/how-it-works) para ver o algoritmo completo.

```ts
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?)`

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

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

Por padrão, usa um `FileCacheStore` em `.runic/cache.json` (ou `$RUNIC_HOME/cache.json`) se nenhum armazenamento for informado.

| Prop | Type | Default | Description |
| - | - | - | - |
| `get(decision)?` | `CachedEntry \| null` | - | Looks up a decision. Bumps hit stats on a hit. |
| `set(decision, artifact, meta)?` | `CachedEntry` | - | Stores an artifact for a decision. meta = { tokensSpent }. |
| `list()?` | `CachedEntry[]` | - | All entries currently in the store. |
| `clear()?` | `void` | - | Removes all entries. |

## Backends de armazenamento

### `MemoryCacheStore`

Somente em memória; permanece ativo durante toda a vida do processo. É usado tanto por benchmarks quanto por testes, para que as execuções sejam autocontidas e reproduzíveis.

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

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

### `FileCacheStore`

Persiste em um arquivo JSON para que um processo de CLI e um processo de agente possam ler o mesmo cache sem um servidor em execução.

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

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

Um arquivo corrompido ou parcialmente gravado é tratado como vazio em vez de gerar um erro — uma falha durante a gravação nunca deve derrubar a próxima leitura.

## Implementando seu próprio `CacheStore`

Ambos os armazenamentos integrados implementam a mesma interface pequena, portanto um armazenamento baseado em Redis ou SQLite é um substituto direto:

```ts
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` é chamado internamente a cada acerto no cache para incrementar `hitCount` e `lastUsedAt` — implemente-o como uma operação de leitura-modificação-gravação no armazenamento de suporte que você escolher.

## Próximos passos

- [Ledger](/ledger) — a camada correspondente de contabilização de gastos/economias
- [SDK](/sdk) — o contrato de duas funções que a maioria das integrações realmente usa