Create README.md

README.md

@@ -0,0 +1,110 @@
+---
+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}
+}
+```