Metadata-Version: 2.4
Name: bloomer
Version: 0.1.1
Summary: Bloomer — brain-mimetic memory for AI. Seven biological principles, one Python library.
Author-email: Benedict Chen <benedict@benedictchen.com>
Maintainer-email: Benedict Chen <benedict@benedictchen.com>
License: Custom Non-Commercial License with Donation Requirements
Project-URL: Homepage, https://bitbucket.org/brainbloomer/bloomer
Project-URL: Source, https://bitbucket.org/brainbloomer/bloomer
Project-URL: Documentation, https://bitbucket.org/brainbloomer/bloomer/src/main/README.md
Project-URL: Funding, https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=WXQKYYKPHWXHS
Project-URL: Sponsor, https://github.com/sponsors/benedictchen
Project-URL: Issues, https://bitbucket.org/brainbloomer/bloomer/issues
Keywords: ai-memory,biological-memory,hopfield,sparse-distributed-representation,predictive-coding,reconsolidation,schema-emergence,rag-alternative,neuroscience,engram
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Requires-Dist: torch>=2.2
Requires-Dist: sentence-transformers>=2.7
Requires-Dist: networkx>=3.2
Requires-Dist: python-louvain>=0.16
Requires-Dist: apscheduler>=3.10
Requires-Dist: pydantic>=2.6
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-mock>=3.12; extra == "dev"
Requires-Dist: ruff>=0.3; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Provides-Extra: server
Requires-Dist: fastapi>=0.110; extra == "server"
Requires-Dist: uvicorn>=0.27; extra == "server"
Provides-Extra: ollama
Requires-Dist: ollama>=0.1.7; extra == "ollama"
Dynamic: license-file

# 💰 Support This Research — Please Donate!

**🙏 If Bloomer helps your research, agent, or project, please consider donating to keep this work alive:**

<div align="center">

**[💳 DONATE VIA PAYPAL](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=WXQKYYKPHWXHS)** | **[❤️ SPONSOR ON GITHUB](https://github.com/sponsors/benedictchen)**

</div>

[![PyPI version](https://img.shields.io/pypi/v/bloomer.svg)](https://pypi.org/project/bloomer/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-Custom%20Non--Commercial-red.svg)](LICENSE)
[![Research Accurate](https://img.shields.io/badge/research-7%20principles-brightgreen.svg)](#-research-foundation)

---

# 🧠 Bloomer

> **Brain-mimetic memory for AI — seven biological principles, one Python library.**

Bloomer is not RAG. It is not vector search.

Bloomer is a memory system that behaves like a brain: it stores patterns the way the cortex stores them, retrieves them the way the hippocampus retrieves them, decays them the way unused memories decay, and reconsolidates them every time you remember. It is built directly from **seven biological principles** spanning 70 years of neuroscience research, and it runs locally on a free stack.

**Research foundation in one line:** Kanerva (SDR) + Ramsauer (Modern Hopfield) + Friston (Predictive Coding) + Baddeley (Working Memory) + Bartlett (Schemas) + Ebbinghaus (Forgetting Curve) + Nader (Reconsolidation).

---

## ⚡ 30-Second Pitch

```
   ┌─ what existing RAG does ─────────────────────────────┐
   │                                                       │
   │   text ──► embed ──► cosine top-k ──► stuff into LLM  │
   │                                                       │
   │   ✗  no salience    ✗  no working memory               │
   │   ✗  no schemas     ✗  no reconsolidation              │
   │   ✗  no surprise    ✗  no state-dependence             │
   │                                                       │
   └──────────────────────────────────────────────────────┘

   ┌─ what Bloomer does ─────────────────────────────────────┐
   │                                                          │
   │   text ──► dense ──► SDR ──► Hopfield ──► answer         │
   │           (Kanerva) (CA3-style pattern completion)       │
   │                                                          │
   │   + working memory primes current context (Baddeley)     │
   │   + predictor reports surprise (Friston)                 │
   │   + co-firing patterns merge into schemas (Bartlett)     │
   │   + salience gates what gets remembered (Ebbinghaus)     │
   │   + every retrieval reconsolidates (Nader)               │
   │                                                          │
   │   → state-dependent  → drift-bounded  → no human ontology│
   │                                                          │
   └─────────────────────────────────────────────────────────┘
```

---

## 🚀 Quick Start

### Install

```bash
pip install bloomer
```

Or for development directly from source:

```bash
git clone https://bitbucket.org/brainbloomer/bloomer.git
cd bloomer
pip install -e ".[dev]"
```

**Requirements**: Python 3.11+ · NumPy · PyTorch · sentence-transformers · NetworkX · python-louvain

### Zero-config CLI

The `bin/bm` wrapper auto-creates a venv and installs deps on first invocation. No `source activate` ever.

```bash
# 1. Ingest a directory of markdown files
./bin/bm ingest docs/

# 2. Query (uses Claude Code subscription by default — zero marginal cost)
./bin/bm query "what is reconsolidation" --top-k 5

# 3. Check store stats
./bin/bm stats

# 4. Benchmark vs baseline cosine RAG
./bin/bm bench

# 5. Run the test suite
./bin/bm test

# 6. Background jobs
./bin/bm jobs daily      # salience decay on unused patterns
./bin/bm jobs weekly     # schema emergence
```

### Python API

```python
from bloomer import Memory

mem = Memory(db_path="memory.db")

# Ingest
mem.ingest_directory("docs/")

# Query — returns full retrieval result with surprise + scores
result = mem.query("how do I build smash power", top_k=5)
print(result.answer)
for chunk, score in zip(result.chunks, result.scores):
    print(f"[{score:.3f}] {chunk.source}")
```

---

## 🧬 The Seven Principles

| # | Principle                    | Module                       | Research Anchor          |
|---|------------------------------|------------------------------|--------------------------|
| 1 | Sparse Distributed Reps      | `core/sdr.py`                | Kanerva 1988             |
| 2 | Modern Hopfield Retrieval    | `core/hopfield.py`           | Ramsauer 2020            |
| 3 | Predictive Coding            | `core/predictor.py`          | Friston 2010             |
| 4 | Decaying Working Memory      | `core/working_memory.py`     | Baddeley 1974            |
| 5 | Schema Emergence             | `core/schemas.py`            | Bartlett 1932            |
| 6 | Salience Gating              | `core/salience.py`           | Ebbinghaus 1885          |
| 7 | Reconsolidation              | `core/reconsolidation.py`    | Nader 2000               |

Each principle has a dedicated test suite in `tests/test_p{1..7}_*.py`. See `docs/sport-science/26_BIOLOGY_DRIVEN_MEMORY_ARCHITECTURE_*.md` for the full unified design document.

---

## 🏗️ Architecture

```
   ┌────────────────────────────────────────────────────────┐
   │                       INGEST                            │
   │  markdown ──► chunk ──► embed (BGE-M3) ──► SDR (P1)    │
   │                          1024-d dense    16384-d sparse │
   │                                ↓                        │
   │                          SQLite Store                   │
   └────────────────────────────────────────────────────────┘
                              │
                              ▼
   ┌────────────────────────────────────────────────────────┐
   │                        QUERY                            │
   │                                                         │
   │  question ──► embed ──► WM prime (P4) ──► predict (P3) │
   │                                ↓               ↓        │
   │                          Hopfield retrieve (P2)         │
   │                          + salience gate (P6)           │
   │                                ↓                        │
   │                          top-k chunks                   │
   │                                ↓                        │
   │                          reconsolidate (P7)             │
   │                                ↓                        │
   │                          LLM compose                    │
   │                                ↓                        │
   │                          answer                         │
   └────────────────────────────────────────────────────────┘
                              │
                              ▼
   ┌────────────────────────────────────────────────────────┐
   │                     BACKGROUND                          │
   │  daily:  salience decay (P6) — Ebbinghaus curve         │
   │  weekly: schema emergence (P5) — Louvain co-firing      │
   └────────────────────────────────────────────────────────┘
```

---

## 🆚 Bloomer vs. Plain RAG

```
                        Plain RAG       Bloomer
                        ─────────       ───────
  retrieval geometry    cosine top-k    SDR + Hopfield
  state-dependence      ✗               ✓ (working memory primes)
  surprise / novelty    ✗               ✓ (predictor reports it)
  salience / forgetting ✗               ✓ (Ebbinghaus-shaped)
  schema emergence      ✗               ✓ (Louvain on co-firing)
  drift bounds          ✗               ✓ (reconsolidation w/ floor)
  human ontology req'd  often           none — emerges from data
  LLM cost              per-token API   $0 via Claude Code subscription
```

Run `./bin/bm bench` to measure on your own corpus. Reports Recall@3, Recall@5, latency, and the Jaccard distance gained from state-dependence (working memory priming).

---

## 🔌 LLM Composer Configuration

Default composer: **Claude Code CLI** — uses your existing subscription, $0 marginal.

Bloomer strips `ANTHROPIC_API_KEY` from the subprocess env before invoking `claude` so the CLI uses keychain OAuth instead of pay-per-token billing. If you actually want API-key billing, set `BM_CLAUDE_USE_API_KEY=1`.

Switch backends by env var:

```bash
# Default — Claude Code CLI (subscription)
unset BM_LLM   # or: export BM_LLM=claude_code

# Ollama (fully local)
export BM_LLM=ollama
export BM_OLLAMA_MODEL=gemma3:12b

# OpenAI (paid)
export BM_LLM=openai
export OPENAI_API_KEY=sk-...
```

The router is in `llm/router.py`. Drop in your own composer by implementing `compose(question, chunks) -> str` and registering it.

---

## 📐 Why "state-dependent"

Words mean different things in different contexts. "That's the bomb" in the 90s was praise. "That's the bomb" at TSA is a felony. Plain RAG returns the same top-k regardless of context. Bloomer's working memory buffer keeps a decaying trace of recent activity (Baddeley 7±2, exponential decay over ~30s), which **primes retrieval** toward semantically nearby memories. Same query, different recent context → different retrieval. That is what biological memory does.

Empirically, Bloomer's retrieved chunks shift by ~17% Jaccard distance when the working memory buffer is primed with different topics. Plain RAG shifts 0%.

---

## 🔬 Research Foundation

### Original Papers

- **Kanerva, P. (1988).** *Sparse Distributed Memory.* MIT Press.
- **Ramsauer, H., et al. (2020).** "Hopfield Networks is All You Need." *arXiv:2008.02217.*
- **Friston, K. (2010).** "The free-energy principle: a unified brain theory?" *Nature Reviews Neuroscience*, 11(2), 127–138.
- **Baddeley, A., & Hitch, G. (1974).** "Working Memory." *Psychology of Learning and Motivation*, 8, 47–89.
- **Bartlett, F. C. (1932).** *Remembering: A Study in Experimental and Social Psychology.* Cambridge University Press.
- **Ebbinghaus, H. (1885).** *Über das Gedächtnis* [On Memory].
- **Nader, K., Schafe, G. E., & LeDoux, J. E. (2000).** "Fear memories require protein synthesis in the amygdala for reconsolidation after retrieval." *Nature*, 406(6797), 722–726.
- **Tonegawa, S., et al. (2015).** "Memory engram cells have come of age." *Neuron*, 87(5), 918–931.

### Scientific Accuracy

Bloomer is a **research-accurate** composition of the seven principles, not a vague "brain-inspired" wrapper:

- **Mathematical Fidelity** — SDR sparsity, Hopfield softmax retrieval, and Friston-style prediction error follow the published math.
- **Drift Bounds** — Every reconsolidation step is cosine-distance bounded so memories cannot silently warp past a configurable floor (default 0.7).
- **Schema Emergence** — Schemas are discovered by Louvain community detection over a co-firing matrix; **no human ontology is required.**
- **Salience Curve** — Pattern salience updates blend prediction error (30%), feedback (40%), novelty (10%), and co-firing (20%) at a 10% rate, bounded `[0.1, 5.0]`.

See `docs/sport-science/22_…` through `26_…` for the literature deep-dive that motivates each design choice.

---

## 📊 What's In The Box

```
   bloomer/
     ├─ core/
     │   ├─ sdr.py              # P1 sparse distributed reps
     │   ├─ hopfield.py         # P2 modern Hopfield retrieval
     │   ├─ predictor.py        # P3 predict-then-correct loop
     │   ├─ working_memory.py   # P4 Baddeley 7±2 buffer
     │   ├─ schemas.py          # P5 co-firing → Louvain schemas
     │   ├─ salience.py         # P6 Ebbinghaus + dopamine analog
     │   ├─ reconsolidation.py  # P7 drift-bounded update
     │   ├─ store.py            # SQLite WAL store
     │   ├─ embedder.py         # BGE-M3 wrapper (auto MPS/CUDA/CPU)
     │   ├─ ingest.py           # markdown chunker
     │   └─ query.py            # the full retrieval pipeline
     ├─ llm/
     │   ├─ router.py           # BM_LLM env var → composer
     │   ├─ claude_code.py      # Claude Code CLI composer
     │   ├─ ollama_composer.py  # Ollama / Gemma 3
     │   └─ openai_composer.py  # OpenAI (paid)
     ├─ tests/                  # 137 tests across 11 suites
     ├─ scripts/bench.py        # Bloomer vs cosine RAG benchmark
     ├─ bin/bm                  # zero-config CLI wrapper
     ├─ cli.py                  # argparse entry point
     └─ pyproject.toml
```

---

## 🧪 Tests

Bloomer ships with 137 tests covering every principle, the store, the router, ingest, and end-to-end integration:

```bash
./bin/bm test                             # whole suite
./bin/bm test tests/test_p2_hopfield.py   # one module
./bin/bm test -k reconsolidation          # by keyword
```

Tests use real `numpy` ops where the math matters (P1, P2, P7) and fakes the LLM only at the composer boundary so the rest of the stack is exercised end-to-end.

---

## 📜 Citation

If you use Bloomer in academic work, please cite:

```bibtex
@software{bloomer_benedictchen,
  title   = {Bloomer: Brain-Mimetic Memory for AI},
  author  = {Benedict Chen},
  year    = {2026},
  url     = {https://bitbucket.org/brainbloomer/bloomer},
  version = {0.1.0}
}

@article{ramsauer2020hopfield,
  title   = {Hopfield Networks is All You Need},
  author  = {Ramsauer, Hubert and others},
  year    = {2020},
  journal = {arXiv preprint arXiv:2008.02217}
}

@article{nader2000fear,
  title   = {Fear memories require protein synthesis in the amygdala for reconsolidation after retrieval},
  author  = {Nader, Karim and Schafe, Glenn E. and LeDoux, Joseph E.},
  year    = {2000},
  journal = {Nature},
  volume  = {406},
  number  = {6797},
  pages   = {722--726}
}
```

A machine-readable `CITATION.cff` is included at the repository root.

---

## 📋 License

**Custom Non-Commercial License with Donation Requirements** — see [LICENSE](LICENSE).

Free for academic, research, and personal use. Commercial use requires a separate license — contact **benedict@benedictchen.com**.

---

## 🎓 About

**Implemented by Benedict Chen** — bringing 70 years of memory neuroscience into a single Python package.

📧 **Contact**: benedict@benedictchen.com
🐙 **GitHub**: [@benedictchen](https://github.com/benedictchen)
🪣 **Bitbucket**: [brainbloomer](https://bitbucket.org/brainbloomer)

---

## 💰 Support This Work — Choose Your Adventure!

**Bloomer represents hundreds of hours of literature review, design, and implementation. If you find it valuable, please consider donating:**

### 🎯 Donation Tier Goals (With Bloomer Humor)

**☕ $5 — Buy Benedict Coffee**
*"Caffeine fires the locus coeruleus, which gates salience updates in my prefrontal cortex. In other words: coffee turns up the dopamine on my code-writing patterns."*
💳 [PayPal One-time](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=WXQKYYKPHWXHS) | ❤️ [GitHub Monthly](https://github.com/sponsors/benedictchen)

**🍕 $25 — Pizza Fund**
*"Each slice consolidates into long-term memory via the hippocampus during the post-prandial nap. Bloomer's `jobs daily` runs while I dream."*
💳 [PayPal One-time](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=WXQKYYKPHWXHS) | ❤️ [GitHub Monthly](https://github.com/sponsors/benedictchen)

**🎧 $100 — Better Headphones for Deep Work**
*"My working memory buffer (P4) decays at exp(-t / 30s). Noise cancellation extends the time constant."*
💳 [PayPal](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=WXQKYYKPHWXHS) | ❤️ [GitHub Sponsors](https://github.com/sponsors/benedictchen)

**🖥️ $2,000 — Workstation Upgrade**
*"BGE-M3 embeddings on MPS are nice. BGE-M3 on a fresh M-series with 64GB unified memory is a religious experience."*
💳 [PayPal](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=WXQKYYKPHWXHS) | ❤️ [GitHub Sponsors](https://github.com/sponsors/benedictchen)

**🏎️ $200,000 — Lambo Fund**
*"For testing retrieval latency at 200mph. Does the Hopfield softmax converge faster under acceleration?"*
💳 [PayPal Supercar](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=WXQKYYKPHWXHS) | ❤️ [GitHub Lifetime](https://github.com/sponsors/benedictchen)

**🏠 $500,000 — Memory Palace IRL**
*"A real house with one room per principle. The hippocampus room has the bed (for consolidation). The cortex room has the desk. The amygdala room is just locked."*
💳 [PayPal Challenge](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=WXQKYYKPHWXHS) | ❤️ [GitHub Lifetime](https://github.com/sponsors/benedictchen)

**✈️ $50,000,000 — Private Jet**
*"To test reconsolidation across time zones. Does crossing the date line drift-bound your memories below the cosine floor?"*
💳 [PayPal Aerospace](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=WXQKYYKPHWXHS) | ❤️ [GitHub Aviation](https://github.com/sponsors/benedictchen)

**🏝️ $100,000,000 — Private Island**
*"Where I'll build the world's largest biological memory: 8 billion human brains running Bloomer in parallel, all reconsolidating each other's memories. Civilization 2.0."*
💳 [PayPal Paradise](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=WXQKYYKPHWXHS) | ❤️ [GitHub Tropical](https://github.com/sponsors/benedictchen)

### 🎪 Monthly Subscription Tiers (GitHub Sponsors)

**🧠 Engram Sponsor ($10/month)** — *"Keeps the salience on this project above the Ebbinghaus floor."*
❤️ [Subscribe on GitHub](https://github.com/sponsors/benedictchen)

**⚡ Hopfield Patron ($25/month)** — *"Funds the next attractor basin in the Bloomer roadmap."*
❤️ [Subscribe on GitHub](https://github.com/sponsors/benedictchen)

**🏆 Reconsolidation Royalty ($100/month)** — *"Every retrieval reconsolidates. Every sponsorship strengthens the trace."*
❤️ [Subscribe on GitHub](https://github.com/sponsors/benedictchen)

<div align="center">

**One-time donation?**
**[💳 DONATE VIA PAYPAL](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=WXQKYYKPHWXHS)**

**Ongoing support?**
**[❤️ SPONSOR ON GITHUB](https://github.com/sponsors/benedictchen)**

**Can't decide?**
**Why not both?** 🤷‍♂️

</div>

**Every donation gets reconsolidated into my long-term memory. Your contribution literally rewires my engrams of gratitude.**

*P.S. — If you fund the private island, the eight billion brains will all be named after their assigned schema community.*

---

<div align="center">

## 🌟 What the Community is Saying

</div>

---

> **@NeuroCoderQueen** (412K followers) • *3 hours ago* • *(parody)*
>
> *"okay but bloomer is actually unhinged in the best way 🧠 it's like someone read every neuroscience paper from 1885 to 2026 and was like 'what if we just IMPLEMENTED all of it' and now my AI remembers things STATE-DEPENDENTLY like a human?? the working memory buffer literally primes retrieval based on what you talked about 30 seconds ago. RAG could NEVER. also the reconsolidation thing where every retrieval slightly updates the memory is so brain-coded i cannot. 10/10 would let it remember me. ⚡🧬"*
>
> **87.2K ❤️ • 19.4K 🔄 • 6.1K 🤯**

> **@HippocampalChaos** (1.1M followers) • *yesterday* • *(parody)*
>
> *"installed bloomer at 3am. by 4am it had emerged a schema from my notes that i didn't know existed. by 5am i was crying. by 6am i was paypal-ing benedict. this is the most cracked memory library i've used and i don't even know what to do with this energy. the seven principles thing is sending me. why does an open source library have a private island fundraising tier 😭 anyway. 1024-dim engrams forever."*
>
> **142.6K ❤️ • 28.1K 🔄 • 11.3K 😭**

---

<div align="center">

**Bloomer — your AI's hippocampus, by the book.**

🧠 Made with caffeine, dopamine, and an embarrassing amount of literature review.

</div>
