Smoltbot Overview

Transparent AI agent tracing gateway with AAP and AIP compliance

Smoltbot Overview

Smoltbot is a transparent AI agent tracing gateway. It 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.

Smoltbot is AAP-compliant and AIP-compliant. It produces structured AP-Traces and runs real-time AIP integrity checks on every agent interaction.

Architecture

smoltbot/
├── cli/          # CLI tool (npm package)
├── gateway/      # Cloudflare Worker — API proxy + tracing
├── observer/     # Cloudflare Worker — trace builder + AAP verification
├── api/          # Cloudflare Worker — REST API
├── dashboard/    # React frontend (legacy, see mnemom-website)
└── database/     # Supabase schema (Postgres)

Request Flow

                    ┌─── /anthropic/* ──→ Anthropic (Claude)
Your App → smoltbot ├─── /openai/*    ──→ OpenAI (GPT-5)
           gateway  └─── /gemini/*    ──→ Google (Gemini)
                ↓               ↑
           CF AI Gateway ← SSE stream
                ↓           |
         Response tee()     |
           /       \        |
    to client    to background analysis
   (immediate)   (ctx.waitUntil)
                    |
              Parse SSE → extract thinking
                    |
              AIP analysis (Haiku, ~3s)
                    |
           checkpoint + attestation → Supabase
                    |
           Policy evaluation (if policy active)
                    |
           Observer (cron) → AP-Trace → Supabase
                    |
           Dashboard (mnemom.ai)

Named agents use URL prefix /agent/{name}/ before the provider path (e.g., /agent/my-coder/anthropic/*), giving each agent a distinct identity even when sharing the same API key.

The system consists of five components:

1. 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, and injects thinking/reasoning per provider. For streaming responses (99%+ of traffic), the gateway uses tee() to fork the response stream — one fork goes to the client immediately (zero added latency), while the other fork is analyzed in background via ctx.waitUntil(). The background analysis parses SSE events, extracts thinking blocks, runs AIP integrity analysis with Claude Haiku (~3s), creates cryptographically attested checkpoints (Ed25519 + hash chain + Merkle tree), and creates nudges for boundary violations. Non-streaming responses are analyzed inline before returning.

2. Observer — A scheduled Cloudflare Worker (1-minute cron) that processes AI Gateway logs to build AAP-compliant AP-Traces. It extracts thinking blocks from logged responses, analyzes decisions with Claude Haiku, builds AP-Traces, and verifies them against alignment cards using the AAP SDK. The observer links its traces to gateway-created AIP checkpoints via linkCheckpointToTrace(). AIP integrity analysis is handled entirely by the gateway.

3. API — Serves agent data, traces, integrity scores, drift alerts, enforcement status, and a unified conscience timeline. Powers both the CLI and the web dashboard.

4. CLI — The smoltbot command. Configures your local environment and queries your agent’s transparency data. See the CLI Reference for details.

5. Dashboard — Web UI at mnemom.ai where you can view the conscience timeline, claim your agent, and monitor alignment.

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

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)
• Policy — Policy evaluation results including verdict (pass/warn/fail), violations, warnings, and coverage report. The X-Policy-Verdict response header indicates the result.

What is NOT Stored

Your prompts, responses, and API keys are never stored. Only SHA-256 hashes of API keys are used for agent identification.

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

Claiming Your Agent

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

1. Run smoltbot status to get your agent ID
2. Go to mnemom.ai/claim
3. 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.

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.
• Multi-agent support — Multiple named agents can share a single API key with distinct identities using the /agent/{name}/ URL prefix. See the CLI Reference for setup.
• 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)

Next Steps

CLI Reference

Learn about all CLI commands and usage

Enforcement Modes

Configure how smoltbot responds to violations

Observability

Export traces to your observability platform via OpenTelemetry

EU Compliance

Map AAP/AIP to EU AI Act Article 50 obligations