Mole: Een deep-research agent met een afdwingbaar budget, geverifieerde citaten en een privacygrens voor lokale data

Om kosten te beheersen, wordt elke model-aanroep gereserveerd tegen een budget voordat deze plaatsvindt en wordt dit pas daarna afgerekend. Hierdoor is het ingestelde budget een hard plafond. Mole draait als een enkel statisch binair bestand op je machine, maakt gebruik van je eigen API-sleutels en spreekt MCP (Model Context Protocol), waardoor een coding agent de tool kan aansturen. Dit kan door Mole simpelweg een vraag te stellen, of in 'toolkit-modus', waarbij de agent zelf de redenering uitvoert en Mole de niet-modelgerelateerde taken verzorgt.

Waarom Mole?

Mole biedt drie specifieke voordelen ten opzichte van chat-interfaces met websearch:

  • Afdwingbaar budget: Het budget is geen schatting, maar wordt strikt gehandhaafd. Elke aanroep wordt vooraf gereserveerd en achteraf afgerekend tegen een grootboek met niet-negatieve restricties in het databaseschema. Een instelling van --usd 0.50 betekent dat de run stopt bij vijftig cent. De gemeten overschrijding over de testcorpus is 0%.
  • Geverifieerde citaten: Elke bewering is gekoppeld aan een citaat dat is gecontroleerd tegen de bron. Beweringen waarvan het citaat niet letterlijk voorkomt op de pagina waar het is gevonden, worden direct bij extractie verworpen. Beweringen die overblijven kunnen later opnieuw worden gelezen tegen hun bron; indien een bewering niet wordt ondersteund, wordt dit in het rapport vermeld in plaats van dat de informatie stilletjes wordt verwijderd.
  • Lokale dataprivacy: Lokale data blijft lokaal. Wanneer Mole naar een CSV-bestand of map wordt gewezen, analyseert het deze zonder dat de inhoud de machine verlaat. Het model kiest een hypothese-sjabloon en kolomnamen, waarna Mole de SQL rendert en uitvoert. Alleen aggregaties (tellingen, gemiddelden, testresultaten, buckets van minstens vijf records) worden teruggestuurd. Via mole crossings kan precies worden ingezien welke data de machine heeft verlaten.

Installatie

Script (Linux en macOS, amd64 en arm64)

curl -fsSL https://raw.githubusercontent.com/lajosdeme/mole/main/install.sh | sh

Dit downloadt het release-archief, verifieert de SHA-256 checksum en installeert mole en mole-mcp in ~/.local/bin (of /usr/local/bin). Er wordt alleen sudo gebruikt als dat nodig is voor de doelmap. Gebruik --dry-run om te zien wat het script zou doen.

Homebrew (macOS en Linux)

brew install lajosdeme/mole/mole

Let op: Er is een andere tool genaamd 'mole' (een macOS cleanup tool) in homebrew/core. Gebruik de volledige naam om de research agent te installeren.

Arch Linux (via AUR)

yay -S mole-research-bin      # Prebuilt release binaries
yay -S mole-research          # Bouwen vanuit bron

Let op: De pakketnamen mole en mole-bin op de AUR behoren tot een SSH-tunneling tool.

Debian en Ubuntu (.deb)

curl -fsSLO https://github.com/lajosdeme/mole/releases/latest/download/mole_amd64.deb
sudo dpkg -i mole_amd64.deb

Er is ook een .rpm beschikbaar voor deze platforms.

Vanuit broncode (vereist Go 1.25+)

go install github.com/lajosdeme/mole/cmd/mole@latest
go install github.com/lajosdeme/mole/cmd/mole-mcp@latest

Alternatief kan men clonen en make install gebruiken, zodat de versie correct wordt gerapporteerd als een tag in plaats van 'dev'.

Technische details: Alle installatiemethoden resulteren in twee statische binaries zonder runtime-afhankelijkheden (CGO_ENABLED=0). De database is SQLite en wordt bij eerste gebruik aangemaakt in de XDG-datamap.

Configuratie

Voor het gebruik is een zoekprovider en een modelprovider nodig. API-sleutels worden opgeslagen in ~/.config/mole/config.json (modus 0600) om lekken via proceslijsten of .mcp.json te voorkomen.

Voorbeelden van configuratiecommando's:

mole config set search.provider tavily          # Of: brave
mole config set search.tavily-key tvly-...
mole config set llm.provider anthropic          # Of: openai-compatible
mole config set llm.api-key sk-...
mole config set llm.model claude-sonnet-5
mole config set llm.cheap-model claude-haiku-4-5
mole doctor                                     # Verifieer de configuratie

OpenAI-compatibele endpoints (zoals DeepSeek, Ollama, llama.cpp, vLLM):

mole config set llm.provider openai-compatible
mole config set llm.base-url https://api.deepseek.com/v1
mole config set llm.model deepseek-chat

Modellen die via localhost worden geserveerd, hebben een prijs van nul, maar worden nog steeds in tokens geteld. Gebruik --tokens om een budget in te stellen voor self-hosted runs.

Gebruik

Een vraag onderzoeken

mole research "hoeveel elektriciteit verbruikt het bitcoin-netwerk?" --usd 0.50
mole research "..." --tokens 200000            # Budget in tokens in plaats van dollars
mole research "..." --max-sources 8 --max-depth 3
mole research "..." --json                      # Machine-leesbaar resultaat

Een budget is verplicht. De twee eenheden (dollars of tokens) sluiten elkaar uit. Alleen de dollar-modus kan zoekaanroepen beprijzen; alleen de token-modus kan modellen begrenzen waarvan Mole de tarieven niet kent.

Vervolgvragen stellen

mole ask <session-id> "wat zei de schatting van Cambridge?"

Antwoorden worden gegenereerd op basis van de beweringen die in die sessie al zijn verzameld. Er wordt niet opnieuw gezocht en er zijn geen extra kosten, behalve voor de aanroep om het antwoord te formuleren.

Datasets bouwen (in plaats van proza)

mole research "largest UK supermarket chains and their revenue" \
--mode dataset \
--schema 'company:text!,revenue:number=annual revenue in GBP,employees:number' \
--usd 0.50

mole dataset <session-id> --format csv > chains.csv
mole dataset <session-id> --format json          # Alle waarden per bron

Het uitroepteken (!) markeert het veld dat een rij identificeert. Rij-fusies gebeuren via een 'fuzzy key'. CSV bevat één waarde per cel en geeft aan of er onenigheid is tussen bronnen; JSON bevat alle afwijkende waarden met de bijbehorende bronnen.

Lokale data analyseren

mole connect add sales ./exports/sales.csv       # Eén bestand
mole connect add exports ./exports               # Hele map
mole research "hoe verschilt de besteding tussen regio's?" \
--actors local_compute --usd 0.30

mole crossings <session-id>                      # Inzien wat de machine heeft verlaten

Ondersteunde formaten zijn CSV, TSV, JSON en JSONL (Parquet wordt niet ondersteund). Het model ziet nooit een individuele rij en schrijft zelf geen SQL; het kiest een sjabloon en kolomnamen, waarna Mole de statement rendert.

MCP-clients bedienen

mole serve

Mole luistert op een unix-socket in een private directory (modus 0600) en weigert verbindingen van andere gebruikers. Configureer de client als volgt:

{
  "mcpServers": {
    "mole": { "command": "mole-mcp" }
  }
}

Gevoelige gegevens staan niet in dit bestand; de shim stuurt aanvragen door naar de daemon die de credentials beheert.

Toolkit-modus (gebruik van eigen abonnement)

mole serve --toolkit

In de standaardmodus beheert Mole het model (planning, mining en schrijven). In toolkit-modus wordt dit omgedraaid: het model van de agent doet de redenering, en Mole levert het deterministische deel (zoals citaatcontrole en SQL-rendering). Dit is ideaal voor gebruikers van Claude Code of Qwen Code, waarbij tokens al zijn betaald via een abonnement.

Beschikbare tools (mole.<tool>):

  • Session: sessionopen, sessionclose
  • Retrieval: search, fetch (inclusief SSRF-beveiliging, robots.txt handling en rate limiter)
  • Evidence: verifyquote, claimadd, claims_list, citations
  • Local data: connect_list, aggregate (de privacy-boundary)
  • Graph: pairscandidates, edgeadd
  • Dataset: rows_add, dataset

Een run inspecteren

mole sessions                # Recente sessies en kosten
mole trace <session-id>      # Kosten per aanroep en timing breakdown
mole stats --fetch           # Analyse van mislukte fetches over sessies

Hoe het werkt

Het proces verloopt als volgt: Vraag → Planner (splitsen in sub-vragen, replannen op basis van bewijs) → Executor (één lead per worker, reserveren en afrekenen) → Actor (zoeken → ophalen → extraheren → beweringen minen; elke bewering wordt gecontroleerd tegen de bron) → Verifier (gerelateerde beweringen koppelen, beoordelen, claim-graph bouwen; steekproefsgewijze controle tegen bronnen) → Output (synthese van overgebleven beweringen met citaten) → Antwoord.

Er zijn drie typen actors:

  1. Web searches: Zoekt en leest webpagina's.
  2. Academic queries: Doorzoekt Crossref, OpenAlex, arXiv en PubMed; dedupliceert via DOI en geeft prioriteit aan open-access full-text.
  3. Local_compute: Voert deterministische SQL uit op geregistreerde data zonder dat rijen het model bereiken.

In toolkit-modus is deze pijplijn omgekeerd: de agent beslist wat er gezocht en gelezen wordt, en Mole voert de verificatie, koppeling, merging en SQL-rendering uit.

Eerlijke cijfers (Evaluaties)

Mole evalueert zijn eigen runs via mole eval <session-id>.

MetriekResultaatToelichting
Budget overschrijding0%Geen enkele run is over het plafond gegaan
Claim integriteit100%Elke opgeslagen claim heeft een bron en een verbatim citaat
Citaat accuratesse100%Elk citaat is teruggevonden in de geciteerde bron
Grounding rate80%Van de claims die opnieuw zijn gelezen, is 80% bevestigd
Contradictie precisie70% / 51%70% met 'confirm pass', 51% zonder
Merge precisie / recall1.000 / 1.000Getest op geconstrueerde ground truth

Bijdragen

Bugrapporten en issues zijn welkom. Code-bijdragen verlopen via een CLA (zie CONTRIBUTING.md).

Specifieke richtlijn: Project-bijdragers worden gevraagd hun eigen fix te falsificeren. Na een wijziging moet men de mechanismen terugdraaien om te bevestigen dat de test inderdaad faalt. Een test die slaagt zonder de fix bewijst niets.

Ontwikkelcommando's:

gofmt -l .      # Mag niets printen
go build ./...
go test ./...   # Moet schoon zijn, geen nieuwe skips

Licentie

Apache-2.0. Zie LICENSE en NOTICE.