README.md

---
tags:
- bloom-filters
- hebbian-learning
- associative-memory
- classics-revival
- experimental
license: apache-2.0
library_name: pytorch
---

# Hebbian Bloom Filter - The Classics Revival

**Self-Organizing Probabilistic Memory with Associative Learning**

**Experimental Research Code** - Functional but unoptimized, expect rough edges

## What Is This?

Hebbian Bloom Filter combines probabilistic membership testing with Hebbian-style associative learning. Instead of static hash functions, the filter learns associations between items and adapts its hash patterns based on co-occurrence, creating a self-organizing memory system.

**Core Innovation**: Hash functions that strengthen based on item associations using Hebbian "fire together, wire together" principles, enabling similarity-based retrieval beyond simple membership testing.

## Architecture Highlights

- **Learnable Hash Functions**: Neural networks that adapt based on item co-occurrence
- **Hebbian Plasticity**: Hash weights strengthen when items appear together
- **Associative Retrieval**: Find similar items through learned co-activation patterns
- **Confidence Estimation**: Probabilistic membership with uncertainty quantification
- **Temporal Decay**: Forgetting mechanisms prevent overfitting to old patterns
- **Ensemble Filtering**: Multiple filters vote for robust membership decisions

## Quick Start
```python
from hebbian_bloom import AssociativeHebbianBloomSystem

# Create self-organizing memory system
system = AssociativeHebbianBloomSystem(
    capacity=10000,
    vector_dim=64,
    num_filters=3
)

# Add items with associations
system.add_item("apple", associated_items=["red", "fruit", "healthy"])
system.add_item("banana", associated_items=["yellow", "fruit", "potassium"])

# Query membership with confidence
is_member = system.query_item("apple")

# Find associative memories
similar = system.find_associations("fruit", top_k=5)
```

## Current Status
- **Working**: Hebbian learning, associative retrieval, confidence estimation, ensemble voting, temporal decay
- **Rough Edges**: No benchmarking against standard Bloom filters, hash collision handling could be improved
- **Still Missing**: Advanced forgetting policies, distributed storage, memory compression techniques
- **Performance**: Functional on medium datasets, needs optimization for large-scale deployment
- **Memory Usage**: Higher than standard Bloom filters due to learning components
- **Speed**: Competitive for retrieval, slower for complex association queries

## Mathematical Foundation
The Hebbian learning rule updates hash function weights based on co-activation:
```
Δw_ij = η × h_i(x) × h_j(y) × similarity(x, y)
```
Where `h_i(x)` and `h_j(y)` are hash activations for co-occurring items `x` and `y`.

Confidence estimation combines:
- **Bit confidence**: `C_bit = mean(confidence_array[indices])`
- **Hash confidence**: `C_hash = mean(hash_activation_strengths)`  
- **Access confidence**: `C_access = normalized_access_frequency`

Final confidence: `C_total = α×C_bit + β×C_hash + γ×C_access`

## Research Applications
- **Large-scale similarity search systems**
- **Adaptive caching with learned associations**
- **Memory-augmented recommendation systems**
- **Biologically-inspired information retrieval**
- **Self-organizing knowledge bases**

## Installation 
```bash
pip install torch numpy
# Download hebbian_bloom.py from this repo
```

## The Classics Revival Collection

Hebbian Bloom Filter is part of a larger exploration of foundational algorithms enhanced with modern neural techniques:

-  Evolutionary Turing Machine
- **Hebbian Bloom Filter** ← You are here
-  Hopfield Decision Graph
-  Liquid Bayes Chain
-  Liquid State Space Model
-  Möbius Markov Chain
-  Memory Forest

## Citation
```bibtex
@misc{hebbianbloom2025,
  title={Hebbian Bloom Filter: Self-Organizing Probabilistic Memory},
  author={Jae Parker 𓅸 1990two},
  year={2025},
  note={Part of The Classics Revival Collection}
}
```