The Intuition Database

Teach your AI which decisions work within budget

BanditDB is the decision layer for AI agents and adaptive applications.
It stores every decision, learns from the outcome, and stays within budget.

Start free →Set up your first decision free →

$60 free credits$60 free credits

★ GitHub Docker Hub PyPI npm Apache-2.0

Is it right for you?

When to reach for it, and when not to.

Good fit

A choice from a fixed set of options
Repeated often
A reward you can measure
A cost per action optional

Bad fit

One-off decisions
Open-ended choices, no fixed options
Outcomes you can’t measure

Domainwhere it’s used	Decisionwhat it decides	Contextwhat it knows	Rewardhow it’s scored
Checkout	discount, free shipping, or gift	cart value, returning visitor, device	completed purchasepromo budget of $10,000 a month
LLM routing	which model handles the request	prompt embedding, task type	task successtoken spend capped at $200 a day
Ad tech	which creative variant to serve	device, time of day, audience segment	click or conversion$5,000 a day across creatives
Support	AI agent, human agent, or callback	ticket topic, customer tier, sentiment	resolved on first contacthuman agent hours capped per shift
Retail pricing	hold the price or mark down 10%, 20% or 30%	sell-through rate, days to holiday, competitor price	margin on units sold
Collections	reminder, payment plan, or settlement offer	balance, days past due, payment history	amount recoveredsettlement discounts capped at $50,000 a month
Telecom	retention credit, upgrade offer, or no offer	tenure, drop in usage, plan type	customer renewsretention credits of $20,000 a month
Travel	room upgrade, late checkout, or bonus points	booking window, trip purpose, loyalty tier	booking completedupgrade budget of $3,000 a week
Banking	credit line offer to extend	credit utilization, income, repayment history	repaid without defaulttotal credit exposure capped
Insurance	route to fast-track, adjuster, or SIU review	claim complexity, prior history, policy tier	time to resolution
Logistics	pick path or packing station	order size, zone congestion, SKU mix	fulfillment time
Healthcare	which protocol to recommend	symptoms, vitals, treatment history	patient outcome improved
Legal	consult, intake form, refer, or decline	matter type, client profile, urgency	matter value won
Media	which title to feature on the home screen	viewing history, device, time of day	watched to the end
Edtech	which exercise or hint to serve next	skill level, past attempts, learning pace	concept mastered

Try it on your own decision → More use cases

Where it sits in your stack

Different databases answer different questions.

Postgres / OLTP What is true?

Stores facts and transactions as rows.

Vector database What is similar?

Retrieves related information by nearest neighbour.

BanditDB What should I do?

Learns from decisions and their outcomes, one prediction-action-reward tuple at a time.

your app / agents
   │
   ├── SQL ─────────────►  postgres       "what is true?"
   ├── embed + ANN ─────►  vector store   "what is similar?"
   └── predict/reward ──►  banditdb     "what should I do?"

The whole API, nearly

Three calls. One loop.

create
Name the decision and its options.
predict
Send the context, get the best action.
reward
Report the outcome, even days later.

Run this loop in the cloud → Quick start guide

from banditdb import Client, PacingConfig, ResourceConstraint

db = Client("http://localhost:8080", api_key="your-secret-key")

db.create_campaign(
    "checkout",
    # arms: the offers BanditDB can choose between at checkout
    arms=["discount", "free_shipping", "gift"],
    feature_dim=4,
    pacing=PacingConfig(resources=[ResourceConstraint(
        name="discount_spend", budget=5_000, horizon=50_000,
        arm_costs={"discount": 5.0},
    )]),
)

# context: cart value, pages viewed, returning visitor, time of day
context = [0.8, 0.2, 1.0, 0.4]
arm, iid = db.predict("checkout", context)
db.reward(iid, 1.0)

import { BanditDBClient } from "banditdb-js";

const db = new BanditDBClient({ url: "http://localhost:8080", apiKey: "your-secret-key" });

await db.createCampaign("checkout", {
  // arms: the offers BanditDB can choose between at checkout
  arms: ["discount", "free_shipping", "gift"],
  feature_dim: 4,
  pacing: {
    resources: [{ name: "discount_spend", budget: 5_000, horizon: 50_000,
                 arm_costs: { discount: 5.0 } }],
  },
});

// context: cart value, pages viewed, returning visitor, time of day
const context = [0.8, 0.2, 1.0, 0.4];
const { arm_id, interaction_id } = await db.predict("checkout", context);
await db.reward(interaction_id, 1.0);

# arms: the offers BanditDB can choose between at checkout
curl -X POST http://localhost:8080/campaign \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "checkout_offer",
    "arms": ["discount", "free_shipping", "gift"],
    "feature_dim": 4,
    "pacing": { "resources": [{
      "name": "discount_spend", "budget": 5000, "horizon": 50000,
      "arm_costs": { "discount": 5.0 }
    }] }
  }'

# make BanditDB a native tool in Claude, Cursor, or any MCP host
claude mcp add banditdb banditdb-mcp \
  --env BANDITDB_URL=http://localhost:8080

# your agent can now define its own decisions:
#   create_campaign("checkout_offer",
#                   arms=["discount", "free_shipping", "gift"],
#                   feature_dim=4)

Budgets and costs

Spend your budget where it pays back most.

Tell BanditDB what each option costs and how much you can spend. It spreads the budget across the whole period and puts each dollar where it brings the most return.

1
Give each option a cost
A search click costs $1.20, a social click $0.60, an AI ad $2.50.
2
Set a budget
For example, $5,000 a day. You can set several budgets at once, like total spend plus a cap for one channel.
3
BanditDB sets the bar
Each dollar gets a price that rises when spend runs fast. A channel wins only if its return beats that price.

For developers

"pacing": {
  "resources": [{
    "name": "ad_spend",
    "budget": 5000,
    "horizon": 20000,
    "arm_costs": {
      "search": 1.20,
      "social": 0.60,
      "ai_ads": 2.50
    }
  }]
}

Splitting a $5,000 daily ad budget between Search, Social and AI ads

Example figures

Fixed split, no pacing: budget gone by 13:00BanditDB: spread across the day

MomentCostChannel picked

Morning · bargain hunters$0.60Social

Afternoon · comparing products$1.20Search

Evening · asking AI what to buy$2.50AI ads

The pricier AI ad is bought only where its expected return clears the bar. Each dollar goes to the channel that earns most for that audience, and the budget lasts until midnight.

Try a budgeted campaign free → How budgets work

The BanditDB key visual: a head drawn as intersecting teal ellipses with orange points inside, sending a stream of dots and dashes into the B mark — context inbelief updatedaction out

Storage model · constant memory

It doesn’t store ~~records~~. It stores beliefs.

Every interaction shrinks the uncertainty around what works. The model updates in place, so memory stays flat no matter how much traffic the database has seen.

.91.12.04.08 .12.74.09.03 .04.09.66.14 .08.03.14.81

.42.17.63.09

For data scientists

Old evidence fades. Every decision is on file.

Decision half-life

Markets drift and audiences change. Set a half-life and the model’s confidence halves on that clock, so it tests again instead of trusting stale wins. Its best guesses are kept.

decay_half_life_hours: 24 · 168 weekly · 720 monthly

Parquet export

At every checkpoint, each completed decision is written to Parquet per campaign: what it saw, what it chose, what happened, and the probability it had of choosing it.

interaction_idarm_idrewardpredicted_atrewarded_atpropensityfeature_0 … feature_n

Logged propensities make off-policy evaluation (IPS, SNIPS) possible. List files with GET /export.

Causal effects (CATE)

A bandit’s own scores are biased by who it chose to show each option to. Run the bundled causal-forest analysis on the export to separate real effect from selection.

Which option actually works?
Which works best for which customers?
Which signals drive the difference?
Is the bandit routing traffic well?

python causal_analysis.py --parquet exports/checkout.parquet

Small binary, fast loop

Built to sit in the hot path.

~11MB

Single binary

μs

Per update

~10K

Predictions / sec

+16.7%

Lift on MovieLens

See benchmark →

5

Algorithms

Monitoring · backup · restore

Never lose what it learned.

Observable

Prometheus metrics and per-campaign health. It warns you when a campaign stops exploring.

exploration entropy

criticalwarningok

banditdb_arm_predictions_totalbanditdb_wal_healthy

Durable

Every reward is on disk before the API answers. If the server dies a moment later, the reward is still there.

POST /rewardWAL fsync200 OK

Recoverable

After a crash it rebuilds itself from disk. Nothing it confirmed is lost.

~0.6 s

to replay 100,000 events on boot

Secure by default

Role-based access (RBAC)
Constant-time key checks
Per-key rate limiting
Input validation
JSONL audit log
Self-healing WAL

Model Context Protocol

Shared policy state for agent fleets.

The MCP server exposes campaigns as tools, so every agent in the fleet reads and writes one shared, persistent policy. Every recorded outcome sharpens the policy the whole fleet reads from.

claude mcp add banditdb banditdb-mcp --env BANDITDB_URL=http://localhost:8080

Connect your agents to Cloud → MCP setup guide

create_campaignDefine a new decision
get_intuitionAsk which action to take
record_outcomeReport success or failure
campaign_diagnosticsInspect learning state

Runnable examples

Start simple. Go deep.

Cloud or self-host

Run it your way.

Start in BanditDB Cloud, now in beta. Or self-host with one command.

curl -fsSL https://raw.githubusercontent.com/dynamicpricing-ai/banditdb/main/scripts/install.sh | sh

docker run -d -p 8080:8080 simeonlukov/banditdb:latest

Try BanditDB Cloud (beta) →