Getting Started

Installation

From Source (Recommended)

go install github.com/rainmana/tinybrain/v3/cmd/tinybrain@latest

Note the /v3 in the module path — it’s required for v3.x releases.

Claude Code Plugin

If you use Claude Code, the Claude Code Plugin registers the MCP server and installs skills that teach Claude how to use TinyBrain — in one install.

Docker

docker pull rainmana/tinybrain:latest
docker run -p 8090:8090 rainmana/tinybrain

Pre-built Binaries

Download from Releases

Architecture

TinyBrain is a single, self-contained Go binary:

• Single Binary: MCP server, REST API, and dashboard in one executable — zero configuration
• Embedded SQLite: A pure-Go SQLite engine (no cgo, no external database) with FTS5 full-text search; cross-compiles cleanly to every platform
• MCP over stdio: JSON-RPC 2.0 for AI assistant integration (run tinybrain with no args)
• REST API + Dashboard (in serve mode): full REST API at http://127.0.0.1:8090/api/ and a status dashboard at http://127.0.0.1:8090/_/
• Data Persistence: everything persists in a SQLite database at ~/.tinybrain/memory.db by default (override with TINYBRAIN_DB_PATH)

Basic Usage

1. Start the Server

# Start with default data directory
tinybrain serve --dir ~/.tinybrain

# Or with custom data directory
tinybrain serve --dir /path/to/your/data

2. Access Admin Dashboard

# Open admin dashboard in browser
open http://127.0.0.1:8090/_/

# Or access REST API
curl http://127.0.0.1:8090/api/

3. MCP Integration

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "tinybrain": {
      "command": "tinybrain",
      "args": ["serve", "--dir", "~/.tinybrain"],
      "env": {
        "TINYBRAIN_DB_PATH": "~/.tinybrain/memory.db"
      }
    }
  }
}

4. Create a Session (MCP)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "mcp_tinybrain-mcp-server_create_session",
    "arguments": {
      "name": "Security Assessment",
      "task_type": "penetration_test",
      "intelligence_type": "osint"
    }
  }
}

5. Store Memory (MCP)

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "mcp_tinybrain-mcp-server_store_memory",
    "arguments": {
      "session_id": "session-id",
      "title": "OSINT Finding",
      "content": "Social media analysis reveals...",
      "category": "intelligence",
      "priority": 7,
      "confidence": 0.8,
      "tags": "[\"osint\", \"social-media\", \"reconnaissance\"]"
    }
  }
}

Configuration

PocketBase Configuration

TinyBrain uses PocketBase with zero configuration by default:

# Default configuration
tinybrain serve --dir ~/.tinybrain

# Custom data directory
tinybrain serve --dir /path/to/your/data

# Custom port (if needed)
tinybrain serve --dir ~/.tinybrain --port 8090

Environment Variables

export TINYBRAIN_DB_PATH="~/.tinybrain/memory.db"
export TINYBRAIN_HOST="localhost"
export TINYBRAIN_PORT="8090"

Admin Dashboard Configuration

Access the admin dashboard at http://127.0.0.1:8090/_/ to:

• View and manage collections
• Monitor system performance
• Configure user access (future feature)
• View real-time logs and metrics

REST API Configuration

The REST API is automatically available at http://127.0.0.1:8090/api/ with:

• Full CRUD operations for all collections
• Real-time subscriptions
• Authentication support (future feature)
• Rate limiting and security controls

Next Steps

• Core Features - Learn about memory management and sessions
• Intelligence & Reconnaissance - Explore intelligence gathering capabilities
• API Reference - Complete API documentation