Setup and Configuration

Quick Start

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

brv swarm onboard

The wizard walks through 6 steps:

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

After onboarding, verify everything is working:

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:

# 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`

keyword mode requires no API key. hybrid and vector modes use OpenAI embeddings (~$0.001 per query).

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):

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):

enrichment:
  edges: []

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

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.

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.

Getting Started

LLM Providers

Agent Connectors

Context Tree

Knowledge Sharing

Memory Swarm

Git-Semantic Version Control

Review Changes

BRV Hub

Headless Mode

Daemon-First Architecture

Local Web UI

Reference

FAQs

Security

ByteRover Cookbook

Setup and Configuration

Quick Start

Configuration File

Provider Configuration

ByteRover (Always On)

Obsidian

Local Markdown

GBrain

Memory Wiki (OpenClaw)

Enrichment Topology

Validation

​Quick Start

​Configuration File

​Provider Configuration

​ByteRover (Always On)

​Obsidian

​Local Markdown

​GBrain

​Memory Wiki (OpenClaw)

​Enrichment Topology

​Validation

Quick Start

Configuration File

Provider Configuration

ByteRover (Always On)

Obsidian

Local Markdown

GBrain

Memory Wiki (OpenClaw)

Enrichment Topology

Validation