bloomer 0.2.0

Bloomer — brain-mimetic memory for AI. Seven biological principles, one Python library.

💰 Support This Research — Please Donate!

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

💳 DONATE VIA PAYPAL | ❤️ SPONSOR ON GITHUB

---

🧠 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

pip install bloomer

Or for development directly from source:

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.

# 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

from bloomer import Memory

mem = Memory(db_path="~/.bloomer/memory.db")

# Write
mem.remember(
    "the user prefers caveman mode by default",
    namespace="user:benedict",
    tags=["preference"],
)

# Read with state-dependent priming (the flagship feature)
result = mem.recall(
    "how should I respond to benedict",
    namespace="user:benedict",
    recent_context=[...],  # last few messages → primes WM → biases retrieval
    top_k=5,
)
for chunk, score in zip(result.chunks, result.scores):
    print(f"[{score:.3f}] {chunk.text[:80]}")

# Time-window read for "what did we say in the last 30 min"
recent = mem.recall_recent(window_minutes=30, namespace="user:benedict")

# Maintenance
mem.forget(pattern_id=...)
mem.forget(namespace="session:expired", before_days=7)
stats = mem.stats()

MCP server (v0.2.0 and up)

Any MCP-compatible client (Claude Code, Cursor, Windsurf, Continue, custom agents) can use bloomer as a persistent memory layer.

pip install 'bloomer[mcp]'

Then add it to your Claude Code MCP config:

{
  "mcpServers": {
    "bloomer": {
      "command": "bloomer-mcp",
      "args":    ["--db", "~/.bloomer/memory.db"]
    }
  }
}

Five tools become available to the agent:

tool	what it does
bloomer_remember	store text + optional namespace / tags / TTL
bloomer_recall	Hopfield retrieval with recent_context priming
bloomer_recall_recent	time-window query (no LLM, no Hopfield, just fast)
bloomer_forget	delete by id or selector
bloomer_stats	snapshot of what's in memory

The killer feature is recent_context on bloomer_recall — pass the last few messages from the agent's thread, and bloomer's working-memory buffer (P4) primes retrieval toward that context. Same query, different recent chat → different chunks come back. No other memory system in the May 2026 landscape (mem0, Zep, Letta, Cognee, Supermemory, Anthropic memory-tool) does this natively.

---

🧬 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:

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

./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:

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

Free for academic, research, and personal use. Commercial use requires a separate license — contact [e-mail].

---

🎓 About

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

📧 Contact: [e-mail] 🐙 GitHub: @benedictchen 🪣 Bitbucket: 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 | ❤️ GitHub Monthly

🍕 $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 | ❤️ GitHub Monthly

🎧 $100 — Better Headphones for Deep Work "My working memory buffer (P4) decays at exp(-t / 30s). Noise cancellation extends the time constant." 💳 PayPal | ❤️ GitHub Sponsors

🖥️ $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 | ❤️ GitHub Sponsors

🏎️ $200,000 — Lambo Fund "For testing retrieval latency at 200mph. Does the Hopfield softmax converge faster under acceleration?" 💳 PayPal Supercar | ❤️ GitHub Lifetime

🏠 $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 | ❤️ GitHub Lifetime

✈️ $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 | ❤️ GitHub Aviation

🏝️ $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 | ❤️ GitHub Tropical

🎪 Monthly Subscription Tiers (GitHub Sponsors)

🧠 Engram Sponsor ($10/month) — "Keeps the salience on this project above the Ebbinghaus floor." ❤️ Subscribe on GitHub

⚡ Hopfield Patron ($25/month) — "Funds the next attractor basin in the Bloomer roadmap." ❤️ Subscribe on GitHub

🏆 Reconsolidation Royalty ($100/month) — "Every retrieval reconsolidates. Every sponsorship strengthens the trace." ❤️ Subscribe on GitHub

One-time donation? 💳 DONATE VIA PAYPAL

Ongoing support? ❤️ SPONSOR ON GITHUB

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

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.

---

🌟 What the Community is Saying

---

@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 😭

---

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

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