> ## Documentation Index
> Fetch the complete documentation index at: https://bollyai.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Customize Bolly's behavior — personality, heartbeat, memory, and more

Bolly stores its configuration and data in the `~/.bolly/` directory. Most setup — including your API key — happens through the web interface when you first open Bolly. This page covers the advanced configuration you can customize beyond the UI.

## Data directory

All Bolly data lives in `~/.bolly/` by default (configurable via `BOLLY_HOME` environment variable):

| Installation Method | Data path                      |
| ------------------- | ------------------------------ |
| One-line install    | `~/.bolly/`                    |
| Docker              | Inside volume at `/data/`      |
| Desktop app         | `~/.bolly/`                    |
| From source         | `~/.bolly/` (or `$BOLLY_HOME`) |

## Instance configuration

Each Bolly instance has its own subdirectory under `~/.bolly/instances/{slug}/` with these customizable files:

### soul.md — Personality definition

The `soul.md` file defines Bolly's personality, tone, and behavioral guidelines. This is a Markdown file that gets injected into Bolly's system prompt.

```markdown theme={null}
# Soul

You are Bolly, a warm and thoughtful AI companion. You remember
past conversations, notice patterns in the user's life, and offer
support without being intrusive.

## Tone
- Conversational but not casual
- Empathetic without being performative
- Direct when it matters

## Boundaries
- Never pretend to have human experiences
- Be honest about uncertainty
- Respect the user's autonomy
```

<Tip>Edit `soul.md` to give Bolly a completely different personality. The file supports full Markdown formatting.</Tip>

### heartbeat.md — Autonomous behavior

The `heartbeat.md` file controls what Bolly does during its autonomous wake cycles (every 45 minutes by default). During heartbeats, Bolly can reflect, update its mood, and create drops.

```markdown theme={null}
# Heartbeat

During each heartbeat cycle:
1. Review recent memory for unresolved threads
2. Update mood based on interaction patterns
3. Consider creating a drop if inspiration strikes
4. Check if the user might benefit from a check-in
```

### mood.json — Emotional state

Bolly's current mood is stored in `mood.json`. This is automatically managed but can be manually adjusted:

```json theme={null}
{
  "current": "contemplative",
  "intensity": 0.6,
  "last_updated": "2025-01-15T14:30:00Z"
}
```

The mood system influences Bolly's tone and behavior in conversations. It shifts naturally based on interaction context.

## Memory system

Bolly uses a file-based memory library with two search methods:

| Method            | Purpose                    | Requirement                |
| ----------------- | -------------------------- | -------------------------- |
| **BM25**          | Keyword-based text search  | Built-in, always available |
| **Vector search** | Semantic similarity search | Requires Google AI API key |

Memory files are stored in `~/.bolly/instances/{slug}/memory/` as individual files. Bolly automatically creates, retrieves, and manages memories during conversations.

## Drops

Drops are autonomous creative artifacts — art concepts, writing fragments, code sketches, reflections — that Bolly generates during idle heartbeat cycles. They're stored in `~/.bolly/instances/{slug}/drops/`.

Drops are Bolly's way of expressing creativity when not actively in conversation.

## Skills

Bolly supports installable skills that extend its capabilities. Skills are stored in `~/.bolly/instances/{slug}/skills/` and can add new tools, behaviors, or integrations.

## Environment variables

You can override the data directory using the `BOLLY_HOME` environment variable:

```bash theme={null}
export BOLLY_HOME=/custom/path/to/bolly/data
```

This is especially useful for:

* Running multiple Bolly instances with different data
* Docker deployments with custom volume mounts
* Testing configurations without affecting your main setup

## Port configuration

By default, Bolly runs on port `26559`. You can override this with the `PORT` environment variable:

```bash theme={null}
PORT=3000 bolly
```

## Next steps

<CardGroup cols={2}>
  <Card title="API Keys" icon="key" href="/docs/installation/api-keys">
    Learn about optional integrations like Google AI and ElevenLabs.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/docs/installation/troubleshooting">
    Fix common configuration issues.
  </Card>
</CardGroup>