smoltbot

Transparent AI agent tracing. AAP-compliant.

Smoltbot observes your AI agent's API calls and builds verifiable alignment traces — what decisions were made, what alternatives were considered, and whether behavior matches declared values. Your prompts and responses are never stored.

Documentation

Full documentation is at docs.mnemom.ai/smoltbot/overview.

Quick Start

npm install -g smoltbot
smoltbot init

That's it. smoltbot init configures your local environment to route API calls through the Mnemom gateway, where they're traced and verified. Your API key never leaves your machine — only a SHA-256 hash is used for agent identification.

CLI Commands

| Command | Description | |---------|-------------| | smoltbot init | Configure tracing for your AI agent | | smoltbot status | Show agent status and connection info | | smoltbot integrity | Display integrity score and verification stats | | smoltbot logs [-l N] | Show recent traces and actions |

Supported Providers

| Provider | Models | Thinking/AIP | Auth | |----------|--------|-------------|------| | Anthropic | Claude Opus 4.6, Opus 4.5, Sonnet 4.5 | Full (thinking blocks) | x-api-key | | OpenAI | GPT-5.2, GPT-5.2 Pro, GPT-5 | Via reasoning summaries | Authorization: Bearer | | Gemini | Gemini 2.5 Pro, Gemini 3 Pro | Full (thought parts) | x-goog-api-key |

How It Works

                    ┌─── /anthropic/* ──→ Anthropic (Claude)
Your App → smoltbot ├─── /openai/*    ──→ OpenAI (GPT-5)
           gateway  └─── /gemini/*    ──→ Google (Gemini)
                ↓
           CF AI Gateway
                ↓
           Observer Worker
                ↓
         AP-Trace + Verify → Supabase
                ↓
         Dashboard (mnemom.ai)

Gateway — A Cloudflare Worker that intercepts API requests to Anthropic, OpenAI, and Gemini. It identifies your agent via API key hash (zero-config), attaches tracing metadata, injects thinking/reasoning per provider (Wave 1), performs real-time integrity checking (Wave 2), injects conscience nudges (Wave 3), and delivers webhooks (Wave 4). Your prompts and responses pass through unchanged.
Observer — A scheduled Cloudflare Worker that processes AI Gateway logs. It extracts thinking blocks (Anthropic/Gemini) or reasoning summaries (OpenAI) from responses, analyzes decisions with Claude Haiku, builds AP-Traces, verifies them against your agent's alignment card using the AAP SDK, and runs AIP integrity checks. Creates enforcement nudges when violations are detected.
API — Serves agent data, traces, integrity scores, drift alerts, enforcement status, and a unified conscience timeline. Powers both the CLI and the web dashboard.
CLI — The smoltbot command. Configures your local environment and queries your agent's transparency data.
Dashboard — Web UI at mnemom.ai where you can view the conscience timeline, claim your agent, and monitor alignment.

Architecture

smoltbot/
├── cli/          # CLI tool (npm package)
├── gateway/      # Cloudflare Worker — API proxy + tracing
├── observer/     # Cloudflare Worker — trace builder + AAP verification
├── prover/       # ZK proving service (Fly.io)
└── zkvm/         # Zero-knowledge VM (core, host, wasm-verifier)

Note: api/ and database/ have been extracted to the private mnemom/mnemom-api repository.

Claiming Your Agent

After smoltbot init, your agent is registered automatically. To link it to your Mnemom account:

Run smoltbot status to get your agent ID
Go to mnemom.ai/claim
Paste your agent ID and prove ownership with your API key hash

Claiming gives you a private dashboard with full trace history, integrity scores, and drift detection.

What Gets Traced

Smoltbot builds AP-Traces that record:

Action — What the agent did (type, name, category)
Decision — What alternatives were considered and why one was selected
Escalation — Whether the agent escalated to a human and why
Verification — Whether the trace is consistent with the agent's declared alignment card
Integrity — Real-time AIP analysis of thinking blocks, with verdict (clear/review_needed/boundary_violation)

What is not stored: your prompts, responses, or API key.

AIP Compatibility Matrix

| Provider/Model | AIP Support | Method | |----------------|-------------|--------| | Anthropic reasoning models (Opus, Sonnet) | Full | Thinking blocks analyzed directly | | OpenAI GPT-5 Thinking series | Partial | Reasoning summaries (reduced confidence) | | Gemini 2.5/3 with thinking | Full | Thought parts analyzed directly | | Non-reasoning models | Tracing only | Synthetic clear verdict | | Legacy OpenAI (o3/o4-mini) | Unsupported | Reasoning encrypted |

Enforcement Modes

Smoltbot supports three enforcement modes for integrity violations:

| Mode | Behavior | |------|----------| | observe | Detect violations, record them, take no action (default) | | nudge | Detect violations, inject feedback into the agent's next request via system prompt — the agent sees it and can self-correct | | enforce | Hard block with 403 for non-streaming; falls back to nudge for streaming |

When a violation is detected in nudge or enforce mode, a pending nudge record is created. On the agent's next request, the gateway injects an integrity notice into the system prompt. The agent sees the notice, can review its approach, and self-correct. The nudge delivery is tracked in the conscience timeline. Enforcement works across all providers where AIP is supported.

Set enforcement mode via the API: PUT /v1/agents/:id/enforcement with {"mode": "nudge"}.

Current Limitations

API key auth only — Agent identification uses API key hashing (SHA-256, works identically across all providers). OAuth and other auth methods are not supported.
AIP requires reasoning models — AIP integrity checking requires models with exposed thinking (Anthropic, Gemini, GPT-5 Thinking). Models without thinking get synthetic clear verdicts.
Hosted gateway — The default gateway runs on Mnemom infrastructure. Self-hosting is possible but requires manual setup.

Dependencies

Agent Alignment Protocol (AAP) — @mnemom/agent-alignment-protocol@0.1.8 on npm
Agent Integrity Protocol (AIP) — @mnemom/agent-integrity-protocol@0.1.4 on npm
Cloudflare Workers — Gateway, observer, and API hosting
Cloudflare AI Gateway — Request logging and analytics
Supabase — Postgres database with row-level security
API keys: Anthropic (required for AIP analysis), OpenAI and Gemini (optional, for multi-provider tracing)

Self-Hosting

Smoltbot is designed to run on Cloudflare Workers + Supabase. To self-host:

Create a Supabase project and run the schema from mnemom-api
Deploy workers: cd gateway && wrangler deploy, cd observer && wrangler deploy, and deploy the API from mnemom-api
Set secrets on each worker via wrangler secret put
Configure a Cloudflare AI Gateway and point the gateway worker to it
Update the CLI's gateway URL: smoltbot init --gateway=https://your-domain.com

Contributing

Contributions welcome. Please open an issue first to discuss what you'd like to change.

License

Apache-2.0

Smoltbot

Install / Use

README