Quick Start
The fastest way to set up Memory Swarm is the interactive onboard wizard:
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:
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
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 |
brv swarm status after any config change to verify all providers are healthy.
