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

# Spreading Activation Retrieval

> Hystersis proprietary spreading activation search that improves multi-hop reasoning by 23% over pure vector search

# Spreading Activation Retrieval

Hystersis's proprietary spreading activation retrieval improves multi-hop reasoning by 23% over pure vector similarity search by propagating activation signals through the knowledge graph.

## How It Works

Based on the Synapse paper (arXiv:2601.02744), spreading activation combines vector search with graph traversal:

```
Query → Vector Embedding → Initial Nodes → Graph Propagation → Activation Ranking → Results
```

### Algorithm Steps

1. **Initial Activation** — Convert query to embedding and find top-K similar nodes via Qdrant vector search
2. **Graph Propagation** — Propagate activation through Neo4j graph with per-hop decay
3. **Threshold Filtering** — Keep nodes above activation threshold
4. **Hybrid Ranking** — Score results by combining activation level with vector similarity

### Propagation Parameters

| Parameter        | Default | Description                          |
| ---------------- | ------- | ------------------------------------ |
| `initial_budget` | 1.0     | Initial activation energy            |
| `decay_factor`   | 0.85    | Per-hop decay (15% loss per hop)     |
| `threshold`      | 0.1     | Minimum activation to include result |
| `max_hops`       | 3       | Maximum propagation depth            |
| `top_k`          | 50      | Initial nodes from vector search     |

### Example

```
Query: "What programming languages does Alice know?"

1. Vector search finds: [Alice:developer, Python:language, Alice:works_at_techcorp]
   Initial activation: Alice(1.0), Python(0.9), TechCorp(0.7)

2. Hop 1 (decay=0.85):
   Alice → knows → Python(0.85)
   Alice → knows → JavaScript(0.85)
   Alice → works_at → TechCorp(0.85)

3. Hop 2 (decay=0.72):
   TechCorp → uses → Python(0.72 × 0.9 = 0.65)
   TechCorp → uses → Rust(0.72)
   JavaScript → similar_to → TypeScript(0.61)

4. Results (above threshold=0.1):
   Python (0.90 + 0.65 = 1.55)
   JavaScript (0.85)
   TypeScript (0.61)
   Rust (0.72)
```

## API Usage

```python theme={null}
from hystersis import Hystersis

client = Hystersis(api_key="your-api-key")

# Standard vector search
results = client.search(query="Alice's programming skills")

# Enhanced search with spreading activation
results = client.search_enhanced(
    query="Alice's programming skills",
    mode="spreading",           # or "hybrid" for combined
    max_hops=3,                 # propagation depth
    threshold=0.1,              # minimum activation
    decay_factor=0.85           # per-hop decay
)

for result in results:
    print(f"{result.content} (activation: {result.activation_score:.2f})")
```

### cURL

```bash theme={null}
# Spreading activation search
curl -H "X-API-Key: your-key" \
  "https://api.hystersis.com/search/enhanced?mode=spreading&query=Alice+programming&max_hops=3&threshold=0.1"
```

## Search Modes

| Mode        | Description                           | Use Case               |
| ----------- | ------------------------------------- | ---------------------- |
| `vector`    | Pure vector similarity (Qdrant)       | Simple keyword matches |
| `spreading` | Spreading activation (Neo4j + Qdrant) | Multi-hop reasoning    |
| `hybrid`    | Combined vector + spreading           | Best general-purpose   |

## Benchmark Results

| Query Type        | Vector Only | Spreading Activation | Improvement |
| ----------------- | ----------- | -------------------- | ----------- |
| Single-hop        | 87%         | 89%                  | +2%         |
| Two-hop           | 62%         | 82%                  | +20%        |
| Three-hop         | 41%         | 64%                  | +23%        |
| Complex reasoning | 55%         | 75%                  | +20%        |

## Configuration

```bash theme={null}
# Spreading activation defaults
SPREADING_INITIAL_BUDGET=1.0
SPREADING_DECAY_FACTOR=0.85
SPREADING_THRESHOLD=0.1
SPREADING_MAX_HOPS=3
SPREADING_TOP_K=50
```

## When to Use Spreading Activation

* **Multi-hop questions** — "What tools does Alice's team use?"
* **Relationship queries** — "Who works with Bob on similar projects?"
* **Exploratory search** — "Tell me about the tech stack at TechCorp"
* **Context-rich queries** — Questions that require connecting multiple facts

## See Also

* [Search Modes](/concepts/search-modes) for search architecture
* [Compression](/features/compression) for memory compression
* [Search API](/api-reference/search) for API endpoints