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

# Memory Swarm

> Search and store knowledge across multiple memory providers simultaneously

## The Problem

ByteRover's context tree is powerful — but your knowledge lives in many places. Obsidian vaults, markdown folders, GBrain databases, OpenClaw wikis. Without a unified search layer, you have to query each system separately, mentally merge the results, and decide where to store new knowledge.

Memory Swarm solves this by federating all your knowledge sources into a single query and curation interface.

## How It Works

Memory Swarm connects up to 5 memory providers into a coordinated search and write system. When you query, all active providers are searched in parallel. Results are merged using Reciprocal Rank Fusion (RRF) — a ranking algorithm that combines results from heterogeneous sources without requiring comparable score scales.

```
                        ┌─────────────┐
          brv swarm     │   Classify  │
         query "JWT"───▶│   Query     │
                        └──────┬──────┘
                               │
              ┌────────────────┼────────────────┐
              ▼                ▼                ▼
        ┌──────────┐   ┌──────────┐     ┌──────────┐
        │ByteRover │   │ Obsidian │     │  GBrain  │  ... more providers
        │Context   │   │  Vault   │     │ Database │
        └────┬─────┘   └────┬─────┘     └────┬─────┘
             │              │                 │
             └──────────────┼─────────────────┘
                            ▼
                     ┌──────────────┐
                     │  RRF Fusion  │
                     │  + Filtering │
                     └──────┬───────┘
                            ▼
                      Ranked Results
```

No LLM call is involved — Memory Swarm is pure algorithmic search and ranking. Queries typically complete in under 500ms across all providers.

## Key Concepts

### Query Classification

Every query is automatically classified into one of four types using lightweight regex rules:

| Type           | Trigger Signals                               | Providers Activated  |
| -------------- | --------------------------------------------- | -------------------- |
| **Factual**    | Default (no special signals)                  | All providers        |
| **Temporal**   | "yesterday", "last week", "since", "when did" | All providers        |
| **Relational** | "related to", "depends on", "connected"       | All providers        |
| **Personal**   | "I prefer", "how do I usually", "my style"    | Local providers only |

Personal queries are routed only to local providers (ByteRover, Obsidian, Local Markdown, Memory Wiki) — cloud providers like GBrain are excluded for privacy.

### Reciprocal Rank Fusion (RRF)

Results from different providers use different scoring systems — BM25 scores, cosine similarity, ts\_rank. RRF sidesteps this by ranking based on position rather than raw score:

```
score = Σ (provider_weight / (K + rank))
```

Where `K=60` (configurable) and provider weights range from 0.7 to 1.0. This produces a unified ranking without requiring score normalization across providers.

### Enrichment

Optionally, providers can be chained so that results from one feed into another. For example, ByteRover context tree results can be used to expand Obsidian searches with additional keywords. Enrichment edges form a directed acyclic graph (DAG) — cycles are rejected at config validation time.

### Graceful Degradation

If a provider is unhealthy (missing path, bad credentials, unreachable service), it is skipped. The swarm continues with remaining providers and reports the issue in `--explain` mode. No single provider failure blocks the entire query.

## Supported Providers

| Provider           | Type  | Search                | Write | Requires                       |
| ------------------ | ----- | --------------------- | ----- | ------------------------------ |
| **ByteRover**      | Local | Keyword (BM25)        | No    | Always available               |
| **Obsidian**       | Local | Keyword (BM25)        | No    | Vault path                     |
| **Memory Wiki**    | Local | Keyword (BM25)        | Yes   | OpenClaw wiki vault            |
| **GBrain**         | Cloud | Hybrid/Keyword/Vector | Yes   | GBrain repo + optional API key |
| **Local Markdown** | Local | Keyword (BM25)        | Yes   | Folder path(s)                 |

## Commands

| Command             | Purpose                                                     |
| ------------------- | ----------------------------------------------------------- |
| `brv swarm onboard` | Interactive setup wizard — detects and configures providers |
| `brv swarm status`  | Check provider health and write targets                     |
| `brv swarm query`   | Search across all active providers                          |
| `brv swarm curate`  | Store knowledge in the best available provider              |

## Next Steps

<CardGroup cols={2}>
  <Card title="Setup" icon="settings" href="/memory-swarm/setup">
    Configure providers with the onboard wizard or manual YAML
  </Card>

  <Card title="Query" icon="search" href="/memory-swarm/query">
    Search across all providers with RRF fusion
  </Card>

  <Card title="Curate" icon="pen" href="/memory-swarm/curate">
    Store knowledge in external memory providers
  </Card>

  <Card title="Providers" icon="database" href="/memory-swarm/providers">
    Detailed reference for each provider type
  </Card>
</CardGroup>