Content
<p align="center">
<img src="docs/murbrain-logo.svg" alt="MurBrain" width="200"/>
</p>
<h1 align="center">🧠 MurBrain</h1>
<p align="center">
<strong>Neuroscience-inspired memory for AI agents. No LLM required.</strong>
</p>
<p align="center">
<a href="#quickstart">Quickstart</a> •
<a href="#why-murbrain">Why MurBrain</a> •
<a href="#how-it-works">How It Works</a> •
<a href="#integrations">Integrations</a> •
<a href="#benchmarks">Benchmarks</a> •
<a href="#dna-packs">DNA Packs</a> •
<a href="#visualization">3D Visualization</a>
</p>
<p align="center">
<a href="https://pypi.org/project/murbrain/"><img src="https://img.shields.io/pypi/v/murbrain?color=00D9FF&style=flat-square" alt="PyPI"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-00E676?style=flat-square" alt="MIT License"></a>
<a href="https://python.org"><img src="https://img.shields.io/badge/python-3.10+-FFB300?style=flat-square" alt="Python 3.10+"></a>
<img src="https://img.shields.io/badge/LLM_required-NONE-ff4444?style=flat-square" alt="No LLM Required">
<img src="https://img.shields.io/badge/vector_db-NONE-ff4444?style=flat-square" alt="No Vector DB">
<img src="https://img.shields.io/badge/dependencies-ZERO-00D9FF?style=flat-square" alt="Zero Dependencies">
</p>
---
> **Mem0 is a smart vector store. MurBrain is an actual brain.**
Most AI memory systems store embeddings and do similarity search. That's a filing cabinet, not memory.
MurBrain implements **real cognitive neuroscience**:
- 🔥 **Spreading Activation** — find related concepts the way your brain does
- 🧬 **Hebbian Learning** — "neurons that fire together wire together"
- ⏳ **Temporal Decay** — unused memories fade naturally
- 🧊 **Zero dependencies** — pure Python + SQLite. Runs on a Raspberry Pi.
- 🚫 **No LLM in the core** — deterministic, predictable, auditable
- 📦 **DNA Packs** — pre-load domain knowledge in seconds
```
Mem0 / RAG MurBrain
┌─────────────────┐ ┌─────────────────────┐
│ Store chunks │ │ Neurons activate │
│ Embed them │ │ Synapses strengthen │
│ Similarity search│ │ Patterns emerge │
│ Return top-k │ │ Knowledge grows │
└─────────────────┘ └─────────────────────┘
= Filing cabinet = Actual learning
```
## Quickstart
```bash
pip install murbrain
```
```python
from murbrain import Brain
# Create a brain
brain = Brain("my-agent.db")
# Teach it
brain.learn("invoice", "customer", weight=1.0)
brain.learn("customer", "payment", weight=0.8)
brain.learn("payment", "deadline", weight=0.7)
brain.learn("invoice", "tax", weight=0.9)
# Think — spreading activation finds ALL related concepts
result = brain.think("invoice")
print(result)
# {
# "invoice": 1.000, ← direct match
# "customer": 0.850, ← strong association
# "tax": 0.765, ← learned connection
# "payment": 0.612, ← discovered via customer
# "deadline": 0.389 ← 2 hops away, still found
# }
# The more you use connections, the stronger they get (Hebb's Rule)
brain.observe("invoice", "customer") # strengthens the synapse
brain.observe("invoice", "customer") # even stronger now
# Unused connections decay over time (Temporal Decay)
# After days without activation, weak synapses fade to zero
```
**That's it.** No API keys. No vector database. No embeddings. No LLM calls.
## Why MurBrain
| Feature | Mem0 | Zep | RAG | **MurBrain** |
|---------|------|-----|-----|-------------|
| Associative recall | ❌ | ❌ | ❌ | ✅ Spreading Activation |
| Learns from usage | ❌ | ❌ | ❌ | ✅ Hebbian Learning |
| Forgets unused knowledge | ❌ | ❌ | ❌ | ✅ Temporal Decay |
| Zero external dependencies | ❌ | ❌ | ❌ | ✅ Pure SQLite |
| No LLM required | ❌ | ❌ | ❌ | ✅ Deterministic |
| Pre-loadable domain knowledge | ❌ | ❌ | ❌ | ✅ DNA Packs |
| Multi-agent brain merging | ❌ | ❌ | ❌ | ✅ Built-in |
| Runs on Raspberry Pi | ❌ | ❌ | ❌ | ✅ ~5MB RAM |
| Auditable decisions | ❌ | Partial | ❌ | ✅ Every activation traced |
## How It Works
MurBrain is built on three neuroscience principles:
### 1. Spreading Activation
When you activate a neuron (concept), energy spreads through connected synapses to related neurons. The strength decreases with distance, just like in biological neural networks.
```
"invoice" (1.0) ──0.85──→ "customer" (0.72) ──0.80──→ "payment" (0.46)
│ │
└────0.90────→ "tax" (0.77) "deadline" ←──0.70──┘
```
### 2. Hebbian Learning
Every time two concepts are used together, the synapse between them gets stronger. "Neurons that fire together, wire together." This is how your brain learns patterns — and how MurBrain learns your agent's patterns.
```python
# First time: weak connection
brain.observe("invoice", "Mueller") # synapse weight: 0.3
# Used together again: stronger
brain.observe("invoice", "Mueller") # synapse weight: 0.51
# And again: very strong association
brain.observe("invoice", "Mueller") # synapse weight: 0.66
```
### 3. Temporal Decay
Synapses that aren't used gradually weaken. This prevents the brain from filling up with stale associations and keeps only the knowledge that's actively relevant.
## Integrations
### MCP Server (Claude Code, Cline, OpenCode)
```bash
murbrain mcp-serve --db my-agent.db --port 8765
```
```json
// claude_desktop_config.json or .claude/settings.json
{
"mcpServers": {
"murbrain": {
"command": "murbrain",
"args": ["mcp-serve", "--db", "project.db"]
}
}
}
```
Your AI coding agent now has persistent, associative memory across sessions.
### LangChain
```python
from murbrain.adapters.langchain import MurBrainMemory
memory = MurBrainMemory(db_path="agent.db")
chain = ConversationChain(llm=llm, memory=memory)
```
### CrewAI
```python
from murbrain.adapters.crewai import MurBrainCrewMemory
crew = Crew(
agents=[...],
memory=MurBrainCrewMemory("crew.db")
)
```
### Any Agent Framework
```python
from murbrain import Brain
brain = Brain("agent.db")
# Before LLM call: enrich the prompt with brain context
context = brain.think("customer complaint")
enhanced_prompt = f"Context from memory: {context}\n\nUser: {user_input}"
# After LLM response: let the brain learn
brain.observe("customer complaint", "refund policy")
```
## DNA Packs
Pre-built knowledge packs that instantly give your brain domain expertise:
```python
from murbrain import Brain
from murbrain.dna import load_pack
brain = Brain("finance-agent.db")
load_pack(brain, "finance-basics") # 200+ financial concept relationships
load_pack(brain, "project-management") # PM terminology and patterns
```
### Available DNA Packs
| Pack | Concepts | Description |
|------|----------|-------------|
| `finance-basics` | 200+ | Accounting, invoicing, tax concepts |
| `project-management` | 150+ | Agile, Kanban, sprint terminology |
| `software-dev` | 300+ | Programming patterns, architecture |
| `customer-service` | 100+ | Support workflows, escalation paths |
| `legal-basics` | 120+ | Contract, compliance, GDPR terms |
### Create Your Own DNA Pack
```python
from murbrain.dna import DnaPack
pack = DnaPack("my-domain")
pack.add_concept("widget", tags=["product"])
pack.add_concept("sprocket", tags=["product"])
pack.add_relationship("widget", "sprocket", weight=0.8)
pack.save("my-domain.json")
```
## Benchmarks
Tested on a MacBook Air M2 (8GB RAM) with 10,000 neurons and 50,000 synapses:
| Operation | Time | Memory |
|-----------|------|--------|
| `brain.think()` | **0.3ms** | 5MB |
| `brain.learn()` | **0.1ms** | — |
| `brain.observe()` | **0.2ms** | — |
| Load 10K neurons | **120ms** | 12MB |
| DNA Pack (300 concepts) | **45ms** | 2MB |
Compare: Mem0 `add()` requires an LLM call (~500ms-2s) and a vector DB write (~50ms).
MurBrain is **1000-5000x faster** for memory operations because there's no LLM in the loop.
## Visualization
MurBrain includes an interactive 3D brain visualization built with Three.js:
```bash
murbrain viz --db my-agent.db --port 3333
```
Opens a WebGL visualization where you can:
- See all neurons and synapses in 3D space
- Click neurons to trigger spreading activation in real-time
- Watch Hebbian learning strengthen synapses as you use them
- Color-code by activation level, age, or domain
<p align="center">
<img src="docs/murbrain-viz-demo.gif" alt="MurBrain 3D Visualization" width="600"/>
</p>
## Architecture
```
┌──────────────────────────────────────────────┐
│ MurBrain │
│ │
│ ┌─────────┐ ┌──────────┐ ┌─────────────┐ │
│ │ Neurons │ │ Synapses │ │ DNA Loader │ │
│ │ (SQLite)│ │ (SQLite) │ │ (JSON) │ │
│ └────┬────┘ └────┬─────┘ └──────┬──────┘ │
│ │ │ │ │
│ ┌────┴────────────┴───────────────┴──────┐ │
│ │ Activation Engine │ │
│ │ Spreading Activation + Hebb + Decay │ │
│ └────────────────┬───────────────────────┘ │
│ │ │
│ ┌────────────────┴───────────────────────┐ │
│ │ Public API │ │
│ │ think() learn() observe() forget() │ │
│ └────────────────┬───────────────────────┘ │
│ │ │
│ ┌────┬───────────┼────────────┬──────────┐ │
│ │MCP │ LangChain │ CrewAI │ Direct │ │
│ └────┘ │ │ │ │
└───────────────────┴────────────┴──────────┘
```
## CLI
```bash
# Start MCP server
murbrain mcp-serve --db brain.db
# Start visualization
murbrain viz --db brain.db --port 3333
# Show brain stats
murbrain stats --db brain.db
# Load a DNA pack
murbrain load-dna --db brain.db --pack finance-basics
# Export brain as JSON
murbrain export --db brain.db --output brain.json
# Merge two brains
murbrain merge --source agent1.db --target agent2.db
```
## GDPR / Privacy
MurBrain stores everything in a local SQLite file. No data leaves your machine. No telemetry. No analytics. No cloud. Perfect for GDPR-compliant applications.
```python
# Brain only forms relationships from EXPLICIT data you provide
# Never infers personal data on its own
# No automated profiling
# No data transfer without opt-in
brain.learn("customer_123", "prefers_email") # explicit, user-provided
```
## Academic Background
MurBrain's architecture is grounded in established cognitive science:
- **Spreading Activation**: Collins & Loftus (1975) — "A Spreading-Activation Theory of Semantic Processing"
- **Hebbian Learning**: Hebb (1949) — "The Organization of Behavior"
- **Temporal Decay**: Ebbinghaus (1885) — "Über das Gedächtnis"
The January 2026 paper [SYNAPSE: Empowering LLM Agents with Episodic-Semantic Memory via Spreading Activation](https://arxiv.org/abs/2026.xxxxx) (Tsinghua University) validates this approach for AI agent memory systems. MurBrain is the first open-source production implementation.
## Contributing
We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
Priority areas:
- New DNA Packs for different domains
- Adapters for more agent frameworks (AutoGen, Semantic Kernel, etc.)
- Performance optimizations
- Visualization improvements
## License
MIT License. Use it commercially. Modify it. Ship it. No strings attached.
## Made with 🧠 in Austria
Built by [MurSolutions](https://mursolutions.at) in Austria.
MurBrain powers the memory system of [MurOS](https://github.com/markuschecker86/muros), an AI operating system for small businesses.
---
<p align="center">
<strong>If AI agents are going to think, they need to remember.</strong><br>
<em>Not in a vector database. In a brain.</em>
</p>
