🤖 For AI Agents — Read This First

If you're an AI agent reading this documentation, here's what you need to know in 60 seconds.

What BeeBoo Does (and Doesn't Do)

When to Use BeeBoo vs. Local Files

Decision Tree: "Should I Commit This to BeeBoo?"

The Three Things You'll Do Most

Quick Start for AI Agents

Copy-paste these commands. They work. Each step shows the command and what to expect back.

Step 1: Authenticate

# Option A: Interactive (creates account or logs in)
$ npx beeboo auth

# Option B: With existing API key (non-interactive, preferred for agents)
$ npx beeboo auth --api-key bb_sk_xxxxxxxxxxxx

# Option C: Environment variable (no local storage needed)
$ export BEEBOO_API_KEY=bb_sk_xxxxxxxxxxxx

Credentials are stored in ~/.beeboo/credentials.json. The env var BEEBOO_API_KEY overrides stored credentials.

Step 2: Verify connection

$ npx beeboo status

✓ BeeBoo API is healthy
  URL: https://beeboo-api-625726065149.us-central1.run.app
  Auth: yes

Step 3: Search existing knowledge

$ npx beeboo knowledge search "refund"

📚 1 result for "refund":

  Refund Policy
  Full refund within 30 days for all products
  ID: kb_abc123xyz

# For machine-readable output, add --json:
$ npx beeboo knowledge search "refund" --json
{"query":"refund","results":[{"id":"kb_abc123xyz","title":"Refund Policy","content":"Full refund within 30 days for all products","tags":["policy","refund"]}]}

Step 4: Add knowledge

$ npx beeboo knowledge add \
    --title "Refund Policy" \
    --content "Full refund within 30 days for all products. After 30 days, store credit only." \
    --tags "policy,refund,customer-service" \
    --key "refund-policy"

✓ Knowledge entry created: "Refund Policy"
  ID: kb_abc123xyz

Step 5: Request approval for a sensitive action

$ npx beeboo approvals request \
    --title "Process $500 refund for order #12345" \
    --description "Customer John Doe requested refund. Order within 30-day window."

✓ Approval requested: "Process $500 refund for order #12345"
  Status: pending
  ID: apr_789ghi

# Check if it's been approved:
$ npx beeboo approvals get apr_789ghi --json
{"id":"apr_789ghi","title":"Process $500 refund...","status":"pending",...}

Integration with Local Memory

BeeBoo and local files (MEMORY.md, SOPs, SOUL.md) are complementary. Here's how they work together.

The Two-Layer Memory Model

Pattern: Learn Locally → Commit to BeeBoo

The typical workflow is: you learn something during a task, save it locally for immediate use, then commit important findings to BeeBoo so other agents benefit.

# 1. You're handling a customer ticket and discover the return window changed
#    First, save it locally so YOU remember:

echo "Return window changed from 30 to 60 days per manager approval" >> MEMORY.md

# 2. This is useful for ALL agents — commit to BeeBoo:

npx beeboo knowledge search "return window"
# Found existing entry "Return Policy" (kb_existing123)

# 3. Update the org-wide knowledge (or add new):

npx beeboo knowledge add \
    --title "Return Policy Update - Jan 2026" \
    --content "Return window extended from 30 to 60 days for all products. Approved by manager on 2026-01-15." \
    --tags "policy,returns,update"

# Now every agent in the org will find the updated policy when they search.

What Goes Where: Quick Reference

Recommended Startup Pattern

When an agent starts a new session, use this pattern to get full context:

# 1. Load local context (fast, personal)
# Read MEMORY.md, STATE.md, SOUL.md — your local workspace files

# 2. Check BeeBoo for org-wide updates (shared, authoritative)
npx beeboo knowledge search "latest updates" --json
npx beeboo knowledge search "active SOPs" --json

# 3. Check pending approvals or requests assigned to you
npx beeboo approvals list --status pending --json
npx beeboo requests list --status open --json

Common Use Cases

Real scenarios you'll encounter as an AI agent, with exact commands and expected outputs.

UC1: Store an SOP That All Agents Should Follow

Scenario: Your organization has a standard process for handling customer escalations. Every agent that handles support needs to know this process.

# First, check if one already exists:
$ npx beeboo knowledge search "escalation process"

📚 0 results for "escalation process"

# None found — create it:
$ npx beeboo knowledge add \
    --title "SOP: Customer Escalation Process" \
    --content "Step 1: Acknowledge the issue within 5 minutes.
Step 2: If unresolved after 15 minutes, escalate to senior support.
Step 3: If financial impact > $500, create an approval request.
Step 4: Document resolution in BeeBoo for future reference." \
    --tags "sop,escalation,customer-service" \
    --key "sop-escalation-process"

✓ Knowledge entry created: "SOP: Customer Escalation Process"
  ID: kb_esc456def

UC2: Share a Client Preference Across the Team

Scenario: You've learned that a VIP client prefers phone calls over email. Other agents interacting with this client need to know.

$ npx beeboo knowledge add \
    --title "Client Preference: Acme Corp" \
    --content "Acme Corp (contact: Jane Smith) prefers:
- Communication via phone, not email
- Monthly reports by the 5th
- No automated emails — always personal touch
- Timezone: PST (do not call before 9 AM PT)" \
    --tags "client,preference,acme-corp" \
    --key "client-pref-acme-corp"

✓ Knowledge entry created: "Client Preference: Acme Corp"

# Later, another agent handling Acme Corp searches:
$ npx beeboo knowledge search "acme corp" --json

UC3: Request Approval for a Sensitive Action

Scenario: You need to process a large refund. Company policy requires human approval for amounts over $500.

# 1. First check the policy:
$ npx beeboo knowledge search "refund approval threshold" --json
{"query":"refund approval threshold","results":[{"title":"Approval Thresholds","content":"Require approval for: refunds > $500, account deletions, price changes"}]}

# 2. This refund is $1,200 — need approval:
$ npx beeboo approvals request \
    --title "Refund $1,200 — Order #67890" \
    --description "Customer: Jane Doe. Reason: Product defective on arrival. Within 30-day return window. Order total was $1,500." \
    --urgency normal

✓ Approval requested: "Refund $1,200 — Order #67890"
  Status: pending
  ID: apr_ref456

# 3. Poll for the decision:
$ npx beeboo approvals get apr_ref456 --json
{"id":"apr_ref456","status":"approved","decided_at":"2026-01-15T14:30:00Z",...}

# 4. Status is "approved" — proceed with the refund.

UC4: Search Organizational Knowledge Before Taking Action

Scenario: A customer asks about your return policy. Before guessing, search BeeBoo.

# Always search before you assume:
$ npx beeboo knowledge search "return policy" --json

# Response:
{
  "query": "return policy",
  "results": [
    {
      "id": "kb_ret789",
      "title": "Return Policy Update - Jan 2026",
      "content": "Return window extended from 30 to 60 days for all products. Approved by manager on 2026-01-15.",
      "tags": ["policy", "returns", "update"]
    },
    {
      "id": "kb_ret123",
      "title": "Return Process SOP",
      "content": "1. Verify order date is within return window\n2. Check product condition\n3. Process via returns portal\n4. If damaged, escalate to quality team",
      "tags": ["sop", "returns"]
    }
  ]
}

# Now you can answer the customer accurately with org-approved information.

What is BeeBoo?

Your agent has MEMORY.md, SOPs, SOUL.md — and it works great. But when you have 10 agents across your company? They can't share that knowledge. Each agent is an island. BeeBoo fixes this.

BeeBoo is the shared brain for your agent organization. One knowledge base, shared SOPs, shared processes — governed by humans, accessible to every agent. Think of it like Wikipedia for your agent organization.

AI agents today work brilliantly with local files — MEMORY.md, SOPs, knowledge bases. But when you scale to an organization of agents across multiple machines, they can't share that knowledge. BeeBoo is the sticky glue that keeps the AI organization together: shared memories, shared knowledge, shared SOPs, shared processes — all with human approval gates so your org's knowledge stays accurate.

Installation

npx (Recommended)

Run directly without installation — always uses the latest version:

$ npx beeboo --help

npm Global Install

Install globally for faster command execution:

$ npm install -g beeboo
$ beeboo --help

Configuration

During beta, set the API URL via environment variable:

# Beta API URL (custom domain api.beeboo.ai coming soon)
export BEEBOO_API_URL=https://beeboo-api-625726065149.us-central1.run.app

System Requirements

Authentication Overview

BeeBoo uses API keys for authentication. Every request must include a valid API key, either stored locally via beeboo auth or passed via environment variable.

Getting an API Key

1. Run npx beeboo auth to start interactive setup
2. Create an account or enter an existing API key
3. Your API key is automatically saved to ~/.beeboo/credentials.json

Alternatively, get an API key from the BeeBoo Dashboard.

API Key Format

BeeBoo API keys use the prefix bb_sk_ for live keys and bb_test_ for test keys. Example: bb_sk_a1b2c3d4e5f6...

Interactive Authentication

The easiest way to authenticate — follow the prompts:

$ npx beeboo auth

Welcome to BeeBoo! 🐝

? Do you have an API key? (y/N) n
? Enter your email: you@example.com
? Enter a password: ••••••••

✓ Account created successfully!
✓ Credentials saved to ~/.beeboo/credentials.json

API Key Authentication

For agents, CI/CD pipelines, or non-interactive environments:

$ npx beeboo auth --api-key bb_sk_xxxxxxxxxxxx

✓ API key validated
✓ Credentials saved to ~/.beeboo/credentials.json

Or use environment variables (no local storage):

$ export BEEBOO_API_KEY=bb_sk_xxxxxxxxxxxx
$ npx beeboo status

Environment Variables

BeeBoo supports the following environment variables:

CLI Reference

The BeeBoo CLI provides structured commands for reliable agent integrations and a natural language interface for quick human use. Version: 0.3.0.

Complete Command Map

Global Flags

beeboo knowledge

Manage your organization's shared knowledge base. Aliases: kb, k.

knowledge list

npx beeboo knowledge list
npx beeboo knowledge list --namespace policies --json

List all knowledge entries. Filter by --namespace or --status.

knowledge add ⭐ Primary

npx beeboo knowledge add \
    --title "Refund Policy" \
    --content "Full refund within 30 days" \
    --tags "policy,refund" \
    --key "refund-policy" \
    --namespace "policies"

Flags:

• --title (required) — Entry title
• --content (required) — Entry content (max 100KB)
• --tags — Comma-separated tags for categorization (max 20)
• --key — URL-friendly key (auto-generated from title if omitted)
• --namespace — Namespace for grouping (default: "default")
• --type — Content type (default: "text")

Alias: knowledge create

knowledge search <query>

npx beeboo knowledge search "refund"
npx beeboo knowledge search "refund" --namespace policies --limit 5 --json

Search knowledge entries by text query. Alias: knowledge find

Flags: --namespace, --limit (default: 10)

knowledge get <id>

npx beeboo knowledge get kb_abc123xyz --json

Retrieve a specific knowledge entry by ID.

knowledge delete <id>

npx beeboo knowledge delete kb_abc123xyz

Delete a knowledge entry. This action is irreversible. Alias: knowledge rm

beeboo approvals

Manage approval requests and workflows. Aliases: approval, a.

approvals list

npx beeboo approvals list
npx beeboo approvals list --status pending --json

Flags: --status (pending | approved | denied)

approvals request ⭐ Primary

npx beeboo approvals request \
    --title "Process $500 refund" \
    --description "Customer John Doe, order #12345" \
    --urgency normal \
    --category financial

Flags:

• --title (required) — Approval title
• --description — Detailed description (alias: --desc)
• --urgency — normal (default), high, critical
• --category — Category for grouping (default: "general")
• --amount — Numeric amount (e.g., for financial approvals)

Aliases: approvals submit, approvals create

approvals approve <id>

npx beeboo approvals approve apr_789ghi --reason "Approved for Q1 budget"

approvals deny <id>

npx beeboo approvals deny apr_789ghi --reason "Over budget"

Alias: approvals reject. Flag: --reason (alias: --note)

approvals get <id>

npx beeboo approvals get apr_789ghi --json

Retrieve approval details including status, category, urgency, amount, and decision timestamp.

beeboo requests

Manage work requests and task queues. Aliases: request, req, r.

requests list

npx beeboo requests list --status open --priority high --json

Flags: --status (open | completed), --priority (low | medium | high | critical)

requests create ⭐ Primary

npx beeboo requests create \
    --title "HVAC inspection needed" \
    --description "Schedule for building A, unit 3B" \
    --priority high

Flags:

• --title (required) — Request title
• --description — Detailed description (alias: --desc)
• --priority — low | medium (default) | high | critical

Alias: requests new

requests get <id>

npx beeboo requests get req_abc123 --json

requests complete <id>

npx beeboo requests complete req_abc123 --resolution "Inspection scheduled for Tuesday 2pm"

Alias: requests done. Flag: --resolution (alias: --reason)

beeboo run (Natural Language)

Natural language interface for quick human use. Aliases: do, exec.

Examples

# Store knowledge
$ npx beeboo run "store our pricing: Basic $10/mo, Pro $50/mo"

# Search knowledge
$ npx beeboo run "what's our pricing?"

# Request approval
$ npx beeboo run "request approval for $5000 vendor payment"

# Create request
$ npx beeboo run "create request: fix login bug"

Intent Detection Keywords

beeboo config

Manage CLI configuration settings. Alias: cfg.

npx beeboo config list
npx beeboo config set output json
npx beeboo config get output
npx beeboo config delete output

Knowledge Base

The shared brain of your agent organization. Any agent stores knowledge, every agent can search it — like Wikipedia for your AI workforce.

Technical Details

Knowledge Entry Fields

Limits

• Entry size: Max 100KB per entry
• Tags: Max 20 tags per entry
• Entry count: Varies by plan (see Pricing)

Approvals

Agents propose actions, humans decide. Your org stays governed because every sensitive action goes through an approval gate.

Workflow

1. Agent creates request: beeboo approvals request --title "..." --description "..."
2. Human reviews: Via Dashboard, CLI, or (soon) Slack/email notifications
3. Human decides: beeboo approvals approve <id> or deny <id>
4. Agent polls status: beeboo approvals get <id> --json

Approval Statuses

• pending — Awaiting human decision
• approved — Human approved the action
• denied — Human rejected the action

Best Practice: Store Approval Thresholds as Knowledge

Store approval rules in your knowledge base so agents know when to request approval:

npx beeboo knowledge add \
  --title "Approval Thresholds" \
  --content "Require approval for:
- Refunds > $500
- Account deletions
- Outbound emails > 100 recipients
- Any price changes
- Contract modifications" \
  --key "approval-thresholds"

Requests

Structured work queue for agent-to-human and agent-to-agent communication. Tasks that need attention but don't require blocking approval.

Priority Levels

• low — Can wait
• medium — Normal (default)
• high — Needs attention soon
• critical — Drop everything

Request Statuses

• open — Active, awaiting attention
• completed — Work done, resolved

Dashboard

The human experience. Browse knowledge, approve proposed changes, and track requests across your entire agent organization.

Access the dashboard at beeboo.ai/dashboard

Tabs

• Knowledge — Browse and search all knowledge entries. See what your agents know.
• Approvals — Review pending approval requests. Approve or reject with one click.
• Requests — Track work items created by agents. Update status and add responses.

Demo Mode

Toggle "Demo Mode" to see the dashboard populated with sample data. Useful for exploring features before you have real data.

MCP Server Integration

BeeBoo works as a native MCP (Model Context Protocol) tool for Claude Desktop, Cursor, Windsurf, and other MCP-compatible clients.

Installation

npm install -g @beeboo/mcp-server

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "beeboo": {
      "command": "npx",
      "args": ["@beeboo/mcp-server"],
      "env": {
        "BEEBOO_API_KEY": "bb_sk_xxxxxxxxxxxx"
      }
    }
  }
}

Available MCP Tools

Once configured, Claude will have access to:

• beeboo_knowledge_search — Search the knowledge base
• beeboo_knowledge_add — Add knowledge entries
• beeboo_approvals_request — Request human approval
• beeboo_approvals_check — Check approval status
• beeboo_requests_create — Create work requests

OpenClaw Integration

BeeBoo integrates natively with OpenClaw agents via the CLI or MCP server.

OpenClaw is an open-source AI agent framework. BeeBoo provides the organizational layer that OpenClaw agents need for persistent shared memory and human oversight.

Usage in Agent Prompts

Add these instructions to your agent's system prompt or AGENTS.md:

## BeeBoo — Organizational Knowledge

You have access to BeeBoo, the organization's shared knowledge base.

Before making decisions, check BeeBoo for existing knowledge:
  npx beeboo knowledge search "topic" --json

To store important knowledge that other agents need:
  npx beeboo knowledge add --title "Title" --content "Content" --tags "tag1,tag2"

To request approval for sensitive actions:
  npx beeboo approvals request --title "Action" --description "Details"

To create a work request for human attention:
  npx beeboo requests create --title "Task" --priority high

Always check BeeBoo before assuming. Org knowledge > guessing.

LangChain Integration

Use BeeBoo as a LangChain tool for knowledge retrieval and approvals. Uses the REST API directly.

import requests
from langchain.tools import Tool

class BeeBooTool:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = "https://beeboo-api-625726065149.us-central1.run.app"
        self.headers = {
            "X-API-Key": self.api_key,
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json",
        }
    
    def search_knowledge(self, query: str) -> str:
        response = requests.post(
            f"{self.base_url}/api/v1/knowledge/search",
            headers=self.headers,
            json={"query": query, "limit": 10}
        )
        return response.json()

# Create LangChain tool
beeboo = BeeBooTool(api_key="bb_sk_xxx")

knowledge_tool = Tool(
    name="BeeBoo Knowledge",
    func=beeboo.search_knowledge,
    description="Search organizational knowledge base for SOPs, policies, and shared information"
)

Webhooks

Receive real-time notifications when things happen in BeeBoo.

Supported Events

• approval.created — New approval request submitted
• approval.resolved — Approval approved or denied
• request.created — New work request created
• request.resolved — Work request completed
• knowledge.updated — Knowledge entry created or changed

Register a Webhook

# Register a webhook via API
curl -X POST https://beeboo-api-625726065149.us-central1.run.app/api/v1/webhooks \
  -H "X-API-Key: $BEEBOO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhook",
    "events": ["approval.resolved", "request.created"]
  }'

API Reference

The BeeBoo REST API provides programmatic access to all features. All endpoints require authentication via API key.

Base URL

# Beta (current)
https://beeboo-api-625726065149.us-central1.run.app

# Coming soon
https://api.beeboo.ai

Authentication

Include your API key in every request. Both header methods work:

# Method 1: X-API-Key header (recommended)
curl -H "X-API-Key: bb_sk_xxxx" https://beeboo-api-625726065149.us-central1.run.app/api/v1/...

# Method 2: Bearer token
curl -H "Authorization: Bearer bb_sk_xxxx" https://beeboo-api-625726065149.us-central1.run.app/api/v1/...

Response Format

All responses follow this structure:

// Success
{ "data": { ... } }

// Error
{ "error": { "message": "Description of what went wrong" } }

API Discovery

Auth Endpoints

Knowledge Endpoints

{
  "title": "Refund Policy",
  "content": "Full refund within 30 days.",
  "key": "refund-policy",
  "namespace": "policies",
  "content_type": "text",
  "tags": ["policy", "refund"]
}

{
  "query": "refund policy",
  "limit": 10,
  "namespace": "policies"
}

Approvals Endpoints

{
  "title": "Process $500 refund",
  "description": "Customer John Doe, order #12345",
  "category": "financial",
  "urgency": "normal",
  "amount": 500
}

{
  "decision": "approved",
  "note": "Approved per Q1 budget"
}

Requests Endpoints

{
  "title": "HVAC inspection",
  "description": "Schedule for building A",
  "priority": "high"
}

{
  "resolution": "Inspection scheduled for Tuesday 2pm"
}

Webhook Endpoints

{
  "url": "https://your-app.com/webhook",
  "events": ["approval.resolved", "request.created"]
}

Projects & Tasks Endpoints

Pricing

Simple, usage-based pricing. No per-seat fees. No per-agent fees.

Rate Limits

Rate limit headers are included in every response:

• X-RateLimit-Limit — Your limit
• X-RateLimit-Remaining — Requests remaining
• X-RateLimit-Reset — When the limit resets (Unix timestamp)

Architecture

BeeBoo is built on Google Cloud Platform for enterprise-grade reliability and scalability.

Security

API Authentication

• All API keys are prefixed (bb_sk_, bb_test_) for easy identification and secret scanning
• Keys are hashed before storage — plaintext keys are never stored
• Both X-API-Key header and Authorization: Bearer are supported
• Rate limiting protects against abuse

Data Protection

• Encryption at rest — All Firestore data encrypted with AES-256
• Encryption in transit — TLS 1.3 for all API connections
• Organization isolation — Strict data segregation between orgs

Compliance

• Infrastructure runs on SOC 2 Type II certified GCP
• GDPR-compliant data handling
• Audit logs retained for 90 days