Quick Start

Get Botmem running locally in under five minutes.

Prerequisites

Docker and Docker Compose
Ollama with models pulled — required for data processing. Without it, syncs will complete but memories won't be searchable. Alternatively, use OpenRouter as a cloud backend (no local GPU needed).

Minimum hardware

Without local Ollama: 2 GB RAM, 1 CPU core, 10 GB disk (runs PostgreSQL + pgvector, Redis, and the API)
With local Ollama: 8 GB RAM, 4 CPU cores recommended (embedding models need 2-4 GB)
Disk: grows with data volume — roughly 1 GB per 100k memories

Option A: Docker (recommended for self-hosting)

bash

git clone https://github.com/botmem/botmem.git
cd botmem
cp .env.example .env    # Edit as needed (see step 3 below)
docker compose pull     # Ensure you have the latest API + app images
docker compose up -d    # Starts all services

This pulls and starts everything: the Botmem API, Botmem app, PostgreSQL + pgvector, and Redis. The WebUI is at http://localhost:12412.

Clean start

If you've previously built a local image (docker compose build), Docker may use the cached local image instead of the published one. Always run docker compose pull first to get the latest release.

Ollama connectivity

The .env.example sets OLLAMA_BASE_URL=http://localhost:11434 — this is the host-side value. Inside Docker, the compose file overrides this to http://host.docker.internal:11434 so the container can reach Ollama on your host machine.

macOS / Windows: Works out of the box.
Linux: The compose file includes extra_hosts: host.docker.internal:host-gateway which handles this automatically. If you still have issues, set OLLAMA_BASE_URL to your machine's LAN IP in .env.

No Ollama installed?

Run docker compose --profile ollama up -d to include a bundled Ollama container. Then pull models inside it:

bash

docker compose exec ollama ollama pull nomic-embed-text
docker compose exec ollama ollama pull qwen3:0.6b
docker compose exec ollama ollama pull qwen3-vl:2b

When using the bundled container, set OLLAMA_BASE_URL=http://ollama:11434 in your .env.

Skip to Step 3: Configure AI Backend.

Option B: Development mode (for contributors)

Requires Node.js 20+ and pnpm 9.15+ in addition to Docker.

1. Clone and Install

bash

git clone https://github.com/botmem/botmem.git
cd botmem
pnpm install

2. Start Infrastructure

bash

docker compose up -d postgres redis

This starts only the backing services:

PostgreSQL 17 on port 5432
Redis 7 on port 6379
PostgreSQL search index on port 8108

Configure Environment

bash

cp .env.example .env

The defaults work out of the box for local development. See Configuration for the full list.

Start the Dev Servers

bash

pnpm dev

This automatically builds shared packages first (@botmem/shared, @botmem/connector-sdk, etc.), then starts:

API on http://localhost:12412
Web UI on http://localhost:12412

3. Configure AI Backend

Option A: Ollama (default, local)

Make sure you have these models pulled on your Ollama host:

bash

ollama pull nomic-embed-text      # 768-dim embeddings (default in .env.example)
ollama pull qwen3:0.6b            # Text enrichment + entity extraction
ollama pull qwen3-vl:2b           # Vision-language for photos

If Ollama runs on a different machine, set OLLAMA_BASE_URL in your .env:

bash

OLLAMA_BASE_URL=http://192.168.1.100:11434

The embedding dimension is auto-detected from the model name — no manual configuration needed.

Larger models for better quality

The .env.example defaults use small models for quick setup. For better results:

bash

OLLAMA_EMBED_MODEL=mxbai-embed-large    # 1024-dim, higher quality
OLLAMA_TEXT_MODEL=qwen3:8b              # More capable text model
OLLAMA_VL_MODEL=qwen3-vl:4b            # Better vision model

Option B: OpenRouter (cloud, no GPU needed)

Add to your .env:

bash

AI_BACKEND=openrouter
OPENROUTER_API_KEY=sk-or-your-key-here

4. Create an Account

Open the web UI at http://localhost:12412 and sign up with an email and password.

After signup, you'll be shown a recovery key — save it somewhere safe. This key is used to decrypt your data if the server cache is cleared. It is shown only once.

5. Verify the Installation

Check that the API is running:

bash

curl http://localhost:12412/api/version

You should see a JSON response with the version number.

6. Connect Your First Data Source

Navigate to the Connectors page in the web UI. Each connector has its own setup flow:

Connector	Auth Type	What You Need
Gmail / Google	OAuth 2.0	Google Cloud OAuth credentials
Slack	API Token	Slack user token (`xoxp-...`)
WhatsApp	QR Code	WhatsApp mobile app
iMessage	Local Tool	macOS with iMessage database
Photos / Immich	API Key	Immich server URL + API key
Telegram	Phone Code	Telegram phone number + verification code
OwnTracks	API Key	OwnTracks recorder URL + HTTP auth

See the Connectors section for detailed setup instructions for each source.

7. Trigger a Sync

Once a connector is authenticated, trigger a sync from the web UI or via the API:

bash

# Get your auth token (or use the web UI)
TOKEN=$(curl -s -X POST http://localhost:12412/api/user-auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"your-password"}' | jq -r '.accessToken')

# List accounts
curl -H "Authorization: Bearer $TOKEN" http://localhost:12412/api/accounts

# Trigger sync for an account
curl -X POST -H "Authorization: Bearer $TOKEN" \
  http://localhost:12412/api/jobs/sync/<account-id>

The sync pipeline will:

Pull data from the source
Create raw events in the database
Generate embeddings via your AI backend
Resolve participants into contacts
Enrich memories with entities and factuality labels
Index everything in PostgreSQL search index for semantic search

8. Search Your Memories

bash

curl -X POST http://localhost:12412/api/memories/search \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"query": "coffee meeting last week", "limit": 5}'

Troubleshooting

"Email already registered" or stale data after upgrade

If you've run Botmem before, the PostgreSQL volume still has your old data. This can also cause issues when switching between image versions. For a truly clean start:

bash

docker compose down -v   # Removes all volumes (PostgreSQL + pgvector, Redis data)
docker compose pull      # Ensure latest image
docker compose up -d     # Fresh start

Normal upgrade (preserves data)

For most upgrades: docker compose pull && docker compose up -d. Only use down -v if you encounter persistent issues after a major version change — it deletes all data.

API curl examples with special characters

When testing via curl, make sure to properly quote JSON values. Special characters like ! in passwords can cause JSON parse errors if not properly escaped in your shell:

bash

# Use single quotes around the -d argument to avoid shell interpretation
curl -X POST http://localhost:12412/api/user-auth/register \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"MyPassword123"}'

Bash/Zsh escaping

In bash and zsh, ! inside double quotes triggers history expansion. Always use single quotes around your -d JSON body, or escape with \!.

"Failed to pre-warm embedding model" warning

On startup you may see this warning in the API logs. This is normal — it means the API started before Ollama finished loading the model. The model will be loaded automatically on first use (first search or sync). No action needed.

"Using default dev secrets" log message

You'll see Using default dev secrets (OK for local/self-hosted dev) in the API logs when running with the default .env.example values. This is expected for local development. In production (NODE_ENV=production), you must set custom secrets — see Configuration.

Upgrading

Docker images are tagged with version numbers (for example, ghcr.io/botmem/botmem:api-v1.2.3 and ghcr.io/botmem/botmem:app-v1.2.3). To pin a version, change the image: lines in docker-compose.yml.

For most upgrades, pull the latest image and restart:

bash

docker compose pull
docker compose up -d

A full reset (wipes all data) is only needed if you encounter persistent issues after a major version change:

bash

docker compose down -v   # WARNING: deletes all data
docker compose pull
docker compose up -d

What Next?

Install the CLI to query your memory from the terminal
Set up authentication to understand tokens, recovery keys, and API keys
Configure all environment variables for production
Understand the pipeline to know how data flows through the system
Deploy to production for a self-hosted setup

Quick Start ​

Prerequisites ​

Option A: Docker (recommended for self-hosting) ​

Option B: Development mode (for contributors) ​

1. Clone and Install ​

2. Start Infrastructure ​

Configure Environment ​

Start the Dev Servers ​

3. Configure AI Backend ​

Option A: Ollama (default, local) ​

Option B: OpenRouter (cloud, no GPU needed) ​

4. Create an Account ​

5. Verify the Installation ​

6. Connect Your First Data Source ​

7. Trigger a Sync ​

8. Search Your Memories ​

Troubleshooting ​

"Email already registered" or stale data after upgrade ​

API curl examples with special characters ​

"Failed to pre-warm embedding model" warning ​

"Using default dev secrets" log message ​

Upgrading ​

What Next? ​

Quick Start

Prerequisites

Option A: Docker (recommended for self-hosting)

Option B: Development mode (for contributors)

1. Clone and Install

2. Start Infrastructure

Configure Environment

Start the Dev Servers

3. Configure AI Backend

Option A: Ollama (default, local)

Option B: OpenRouter (cloud, no GPU needed)

4. Create an Account

5. Verify the Installation

6. Connect Your First Data Source

7. Trigger a Sync

8. Search Your Memories

Troubleshooting

"Email already registered" or stale data after upgrade

API curl examples with special characters

"Failed to pre-warm embedding model" warning

"Using default dev secrets" log message

Upgrading

What Next?