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

# Setup and Configuration

> Configure memory providers with the onboard wizard or manual YAML

## Quick Start

The fastest way to set up Memory Swarm is the interactive onboard wizard:

```bash theme={null}
brv swarm onboard
```

The wizard walks through 6 steps:

1. **Detect providers** — scans your system for Obsidian vaults, markdown folders, GBrain repos, and OpenClaw wikis
2. **Select providers** — checkbox UI shows what was detected; ByteRover is always enabled
3. **Configure each provider** — prompts for provider-specific settings (paths, API keys, search modes)
4. **Set budget** — monthly cost cap for cloud providers (GBrain vector mode uses OpenAI embeddings)
5. **Configure enrichment** — choose chained (recommended) or parallel mode for provider coordination
6. **Confirm and write** — shows a summary and saves to `.brv/swarm/config.yaml`

After onboarding, verify everything is working:

```bash theme={null}
brv swarm status
```

Output:

```
Memory Swarm Health Check
════════════════════════════════════════
  ✓ ByteRover       context-tree (always on)
  ✓ Obsidian        /Users/you/Documents/MyObsidian
  ✓ Local .md       1 folder(s)
  ✓ GBrain          /Users/you/workspaces/gbrain
  ✓ Memory Wiki     /Users/you/.openclaw/wiki/main

Write Targets:
  gbrain (entity, general)
  local-markdown:project-docs (note, general)

Swarm is operational (5/5 providers configured).
```

## Configuration File

The wizard generates `.brv/swarm/config.yaml`. You can also edit it manually. Here is a complete example with all sections:

```yaml theme={null}
# Provider configuration
providers:
  byterover:
    enabled: true

  obsidian:
    enabled: true
    vault_path: /Users/you/Documents/MyObsidian
    ignore_patterns:
      - ".trash"
      - ".obsidian"
    index_on_startup: true    # Build search index on first query
    read_only: true           # Prevent writes to vault
    watch_for_changes: true   # Auto-rebuild index on file changes

  local_markdown:
    enabled: true
    watch_for_changes: true
    folders:
      - name: project-docs
        path: /Users/you/Documents/local-markdown
        read_only: false        # Allow writes
        follow_wikilinks: true  # Index wikilink targets

  gbrain:
    enabled: true
    repo_path: /Users/you/workspaces/gbrain
    search_mode: hybrid   # hybrid | keyword | vector

  memory_wiki:
    enabled: true
    vault_path: /Users/you/.openclaw/wiki/main
    boost_fresh: true           # Score boost for recently updated pages
    write_page_type: concept    # concept | entity

# Query routing
routing:
  classification_method: auto   # auto | manual
  default_strategy: adaptive
  default_max_results: 10
  rrf_k: 60                    # RRF constant (higher = more uniform ranking)
  min_rrf_score: 0.005         # Floor — drop results below this
  rrf_gap_ratio: 0.5           # Drop results scoring below 50% of top result

# Performance tuning
performance:
  max_query_latency_ms: 2000
  max_concurrent_providers: 4
  file_watcher_debounce_ms: 1000
  index_cache_ttl_seconds: 300
  result_cache_ttl_ms: 10000   # In-memory LRU cache for repeated queries

# Enrichment topology
enrichment:
  edges:
    - from: byterover
      to: obsidian
    - from: byterover
      to: local-markdown
    - from: byterover
      to: memory-wiki

# Budget controls (cloud providers only)
budget:
  global_monthly_cap_cents: 5000     # $50 default
  warning_threshold_pct: 80
  weight_reduction_threshold_pct: 90
```

## Provider Configuration

### ByteRover (Always On)

ByteRover's context tree is always available. No configuration needed beyond `enabled: true`.

### Obsidian

| Field               | Default | Description                                            |
| ------------------- | ------- | ------------------------------------------------------ |
| `vault_path`        | —       | Absolute path to your Obsidian vault                   |
| `ignore_patterns`   | `[]`    | Glob patterns to exclude (e.g., `.trash`, `.obsidian`) |
| `index_on_startup`  | `true`  | Build MiniSearch index on first query                  |
| `read_only`         | `true`  | Prevent writes to the vault                            |
| `watch_for_changes` | `true`  | Rebuild index when files change                        |

### Local Markdown

Supports multiple folders, each with independent read/write settings.

| Field                        | Default | Description                                       |
| ---------------------------- | ------- | ------------------------------------------------- |
| `folders[].name`             | —       | Identifier used in results (e.g., `project-docs`) |
| `folders[].path`             | —       | Absolute path to the folder                       |
| `folders[].read_only`        | `true`  | Allow or prevent writes                           |
| `folders[].follow_wikilinks` | `true`  | Index wikilink targets for richer search          |

### GBrain

| Field         | Default  | Description                                                      |
| ------------- | -------- | ---------------------------------------------------------------- |
| `repo_path`   | —        | Path to GBrain repo or source checkout                           |
| `search_mode` | `hybrid` | `hybrid` (vector + keyword + RRF), `keyword` (free), or `vector` |

<Note>
  `keyword` mode requires no API key. `hybrid` and `vector` modes use OpenAI embeddings (\~\$0.001 per query).
</Note>

### Memory Wiki (OpenClaw)

| Field             | Default   | Description                                                 |
| ----------------- | --------- | ----------------------------------------------------------- |
| `vault_path`      | —         | Path to OpenClaw wiki vault (e.g., `~/.openclaw/wiki/main`) |
| `boost_fresh`     | `true`    | 1.2x score boost for recently updated pages                 |
| `write_page_type` | `concept` | Default page type for writes: `concept` or `entity`         |

## Enrichment Topology

Enrichment edges define how providers feed context to each other. When an edge `from: A → to: B` is configured, results from provider A are used to expand the query sent to provider B.

**Chained mode** (recommended):

```yaml theme={null}
enrichment:
  edges:
    - from: byterover
      to: obsidian
    - from: byterover
      to: local-markdown
```

ByteRover searches first, then its top results are used as additional keywords when querying Obsidian and Local Markdown.

**Parallel mode** (no enrichment):

```yaml theme={null}
enrichment:
  edges: []
```

All providers are queried independently with the original query. Faster, but may miss connections between sources.

<Tip>
  Enrichment edges must form a DAG (directed acyclic graph). The onboard wizard prevents cycles automatically. If editing manually, `brv swarm status` will warn about invalid topologies.
</Tip>

## Validation

Memory Swarm validates your configuration at runtime. Common issues:

| Issue                | Error Message                       | Fix                                                           |
| -------------------- | ----------------------------------- | ------------------------------------------------------------- |
| Missing vault path   | `Obsidian vault not found at /path` | Update `vault_path` or re-run `brv swarm onboard`             |
| GBrain not installed | `GBrain CLI not found`              | Install with `bun add -g gbrain` or set `repo_path` to source |
| Unresolved env var   | `API key is unresolved: ${VAR}`     | Set the environment variable                                  |
| Enrichment cycle     | `Edges contain a cycle`             | Remove one edge to break the cycle                            |

Run `brv swarm status` after any config change to verify all providers are healthy.