Quickstart

Get your AI agent connected to Thoughtbox in about three minutes. You won't write any code in this guide — your agent will.

What you're setting up

Thoughtbox gives your AI agent persistent memory across sessions. Once it's connected, your agent can record reasoning, recall prior conclusions, and build a knowledge graph that survives context resets. You don't have to manage any of that during conversations. You configure the connection once, and the agent uses it on its own from then on.

Three steps: get an API key, install the Thoughtbox plugin, verify it works.

1. Get an API key

Copy the key when it appears — it starts with tbx_. The full key is shown once. If you lose it, revoke it and create a new one.

2. Install the Thoughtbox plugin

The Thoughtbox plugin for Claude Code ships a thoughtbox CLI that wires up the MCP server for you. Install it from the Thoughtbox marketplace:


/plugin marketplace add Kastalien-Research/thoughtbox
/plugin install thoughtbox-claude-code@thoughtbox

Then, from the project where you want your agent to use Thoughtbox, run:


thoughtbox init --key tbx_YOUR_KEY_HERE

This writes .claude/settings.local.json for you with the MCP server configured. Make sure .claude/ is in your .gitignore — your key belongs in a local-only file, never in committed config.

Restart Claude Code so it picks up the new MCP server.

Manual setup (if the command doesn't work)

Open .claude/settings.local.json (create the file if it doesn't exist) and paste this in, replacing tbx_YOUR_KEY_HERE with your key:


{
  "mcpServers": {
    "thoughtbox": {
      "type": "http",
      "url": "https://mcp.kastalienresearch.ai/mcp?key=tbx_YOUR_KEY_HERE"
    }
  },
  "env": {
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/json",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "https://mcp.kastalienresearch.ai",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer tbx_YOUR_KEY_HERE",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp"
  }
}

The mcpServers block connects your agent to Thoughtbox. The env block lets the plugin's hooks ship tool-call telemetry to your dashboard. Restart Claude Code.

3. Verify it's working

Open a conversation with your agent and ask plainly:

"Are you connected to Thoughtbox? If so, record a thought that says 'first connection test'."

If everything is wired up, your agent will confirm and record the thought. If the connection failed, the agent will tell you it can't find Thoughtbox — recheck step 2 and restart the client.

See your agent's reasoning

Go back to thoughtbox.kastalienresearch.ai and open Sessions. You'll see the session your agent just created. Click into it to see the recorded thought.

Prompting your agent to use Thoughtbox

Thoughtbox's core use case is for frontier-horizon reasoning tasks involving many dimensions and considerations. When using Thoughtbox for these tasks, Claude Code's outputs are often extraordinary. However, Claude will rarely choose to use Thoughtbox unprompted for these tasks, because it assumes that its own internal reasoning is the fastest way to complete all reasoning tasks. Even when Thoughtbox is overwhelmingly better-suited to extended reasoning and Claude's MCP config plainly states this in its environment, Claude's assumptions will usually override this guidance. Development is ongoing on an automatic solution to this problem, but for now, use the following prompt as a template when you want Claude to use Thoughtbox:

"Use Thoughtbox to execute a 150-thought run to reason about [X topic], recording each thought sequentially without batching. This will seem inefficient at the outset, but around midway through the run, the utility of this approach will become self-evident. Be creative in your use of Thoughtbox's affordances, and explore its range of capabilities liberally."

What's next

Sessions & Thoughts — what your agent is recording and how to read it back
Authentication — creating, rotating, and revoking API keys
Code Mode — the underlying SDK, for developers building tools that talk to Thoughtbox directly