## TL;DR

The agent's vendor list is a static snapshot, so every merchant that appeared after the snapshot lands in unknown and gets no policy checks. Build a refresh pipeline: ingest new merchants from recent transactions on a schedule, normalize names, and re-run classification. Until the pipeline exists, work the unknown queue manually so new merchants get categorized.

## Error

```text
agent's vendor database went stale  -  new merchants all landed in unknown
```

## Steps

1. Confirm staleness: check the vendor database's last update date and count the unknowns. Expected: the database is months old and unknowns are growing.
2. Build the refresh: on a weekly schedule, extract distinct merchants from recent transactions, normalize the names, and merge them into the vendor database. Expected: new merchants enter the database automatically.
3. Add a human review queue for merchants the auto-classifier cannot categorize confidently. Expected: ambiguous merchants get a human decision, which feeds back into the database.
4. Backfill: run the refreshed classifier over the unknown backlog. Expected: the unknown queue shrinks dramatically.
5. Add a monitor: alert when the unknown rate exceeds a threshold or the refresh job fails. Expected: staleness is caught in days, not months.

## When to use

- New merchants consistently land in unknown.
- The vendor database has not been updated in months.
- Policy checks are skipped for unknown merchants.

## When not to use

- One specific merchant is misclassified (a data fix, not a pipeline fix).
- The merchants are genuinely unidentifiable (sparse descriptors).
- The database is current but the classifier is wrong.

## Tool compatibility

Applies to custom audit agents with vendor classification (Python, agent frameworks, vendor APIs; current 2026 releases).

### Variant phrasings

### unknown merchant rate climbing in the audit

The database is stale. Refresh it and backfill.

### new vendors skipped by policy checks

Unknown merchants bypass the rules. Classify them.

### vendor list is a year old

Rebuild it from recent transaction history and automate refreshes.

## Why it happens

Merchant populations churn constantly: new vendors, rebrands, and descriptor changes. A static vendor database decays from the day it is built, and the decay is silent because unknown is a valid category that raises no error. The refresh pipeline treats the vendor database as a living dataset fed by the transaction stream itself, which is the only source guaranteed to contain the merchants being audited.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_HDKjSEEcW45Gx9WaYiIwyw