Airbok Think

Self-hosted memory infrastructure for AI applications.

Airbok Think extends LLM context memory. It sits between your app/model and your storage to index, retrieve, and govern long-term context.

Minimum Requirements

• Docker Engine / Docker Desktop with Docker Compose (docker compose)
• A backend project directory where you run airbok-think
• Outbound network access to ghcr.io for pulling the runtime image
• One Airbok Think license key + tenant id
• BYOB storage credentials (S3-compatible or Azure Blob)

Getting Access (Required)

Airbok Think requires a license/API key.

1. Register at https://airbok.com
2. Generate/purchase a Think API key and copy the associated tenant id
3. In /creator/think-api, generate a connector key for Think-to-control-plane sync
4. Set AIRBOK_CONTROL_PLANE_CONNECTOR_KEY in Think .env
5. Activate on your machine (CLI writes .env and validates setup)

Backend-Local BYOB Model

• Run airbok-think from your backend project directory.
• CLI state is backend-local (./.env, ./.airbok_think_machine_id) so deployment is tied to your backend.
• If an older ~/.airbok-think/.env exists, CLI imports it once into the backend directory.
• You connect your own storage in /creator/manage-think; Think uses that BYOB configuration.

Quick Start (Self-Hosted)

• npm install -g airbok-think
• cd /path/to/your/backend
• airbok-think up

If AIRBOK_LICENSE_KEY is missing, activation prompts for account login, Think API key, and tenant id.

Default API host port is 8000 (container listens on 8080). Override with AIRBOK_API_PORT in backend .env.

Control plane base URL should be https://api.airbok.com.

For control-plane defaults sync and verify-on-requests, Think must also have AIRBOK_CONTROL_PLANE_CONNECTOR_KEY set from the key you generated in /creator/think-api.

Activation privacy flow

• CLI shows Think Privacy Policy URL: https://www.airbok.com/docs/privacy
• CLI asks explicit country telemetry consent (yes/no, default no)
• CLI asks explicit privacy policy acceptance (yes/no, default no)
• Activation stops if privacy policy acceptance is declined

CLI Commands (User)

• airbok-think up
• airbok-think down
• airbok-think doctor
• airbok-think storage-check
• airbok-think test storage --user-id=<user_id>
• airbok-think activate
• airbok-think deactivate
• airbok-think logs
• airbok-think logs view
• airbok-think logs tail-20
• airbok-think logs view tail-20
• airbok-think logs clear

airbok-think test storage runs API method probes after startup (GET, PUT, POST) and reports DELETE capability status for the current public contract.

airbok-think logs reads all runtime Think API logs (including request receipts and error events).

airbok-think logs view reads recent Think API logs.

airbok-think logs view tail-20 shows the last 20 log lines.

airbok-think logs tail-20 is a shortcut for the same last-20-lines view.

airbok-think logs clear clears Think API logs by recreating the API container.

App Integration (LLM)

Use Airbok Think as retrieval middleware in your app:

1. Write memory/events to POST /v1/ingest.
2. For each user query, call POST /v1/context and use returned snippets as grounding context for your model prompt.
3. If a snippet provenance includes media pointer metadata, request a short-lived token from POST /v1/storage/retrieval/sign and fetch bytes through GET /v1/storage/retrieval/proxy?token=....

Save/edit API surface (public):

• POST /v1/ingest for new memory records.
• PUT /v1/settings for user memory policy updates.
• PUT /v1/storage/providers for BYOB provider configuration updates.

This documents API usage only. Retrieval ranking/fusion internals are intentionally not exposed in user docs.

Endpoint matrix (public integration)

| Method | Endpoint | Purpose | |---|---|---| | POST | /v1/ingest | Create/write memory events | | POST | /v1/context | Retrieve grounded snippets for LLM prompts | | PUT | /v1/settings | Save/update user memory policy settings | | GET | /v1/storage/providers | Read masked BYOB provider configuration | | PUT | /v1/storage/providers | Save/update BYOB provider configuration | | POST | /v1/storage/retrieval/sign | Mint short-lived retrieval token | | GET | /v1/storage/retrieval/proxy?token=... | Fetch media via signed proxy |

Documentation

User docs

• Getting started and product flow: [Additional Documentation/USER_FLOW.md](Additional Documentation/USER_FLOW.md)
• User settings reference: [Additional Documentation/AIRBOK_THINK_SETTINGS.md](Additional Documentation/AIRBOK_THINK_SETTINGS.md)
• Product specification: [Additional Documentation/PRODUCT.md](Additional Documentation/PRODUCT.md)
• Privacy policy: [Additional Documentation/THINK_PRIVACY_POLICY.md](Additional Documentation/THINK_PRIVACY_POLICY.md)
• Troubleshooting KB: [Additional Documentation/SUPPORT_KB_TROUBLESHOOTING.md](Additional Documentation/SUPPORT_KB_TROUBLESHOOTING.md)
• JavaScript SDK usage: packages/think-client/README.md