Hebb Mind
A neuroscience-inspired memory framework for AI agents
Encode. Consolidate. Activate. Forget.
Documentation · English | 中文
Hebb Mind gives AI agents a neuroscience-inspired memory loop — encode → replay → consolidate → forget. A pipx install and one command stand up a local REST + MCP endpoint: SQLite for storage, sentence-transformers for embedding, NetworkX for the tag graph. Zero external services — bring an LLM key only when you want consolidation to do its work.
Ingest and hybrid search work fully offline with a local embedding model.
pipx install hebb-mind
hebb setup # downloads a small embedding model based on your OS locale
hebb service install # registers a background service (launchd / systemd / Task Scheduler)hebb setup downloads a small embedding model only if it isn't already cached —
~90MB for English (all-MiniLM-L6-v2), ~470MB for multilingual
(intfloat/multilingual-e5-small). The ~60-second figure is for the English /
--profile fast small-model path; the multilingual model is a larger download.
Want the high-quality models? hebb setup --profile best pulls the BAAI bge
family instead (1–2GB+) — opt-in, never downloaded by default.
Don't have pipx? It's the recommended installer for Python CLI tools — isolated venv, automatic PATH, plays nice with PEP 668. Install it once:
# macOS (Homebrew)
brew install pipx && pipx ensurepath
# Linux — Debian / Ubuntu 23.04+
sudo apt install pipx && pipx ensurepath
# Linux — Fedora
sudo dnf install pipx && pipx ensurepath
# Windows / any platform with Python 3.10+
python -m pip install --user pipx && python -m pipx ensurepathThen open a new terminal so the updated PATH takes effect, and re-run pipx install hebb-mind.
Prefer plain pip instead? python -m venv .venv && source .venv/bin/activate && pip install -U hebb-mind works fine — hebb lives on the venv's PATH automatically.
Hebb Mind runs as an OS-managed background service — no foreground process to keep alive, no start/stop shells to remember. The service is per-user by default and needs no admin/sudo. Use --scope system for a system-wide install. See hebb service --help.
In another shell:
curl -X POST http://localhost:8321/api/v1/memories \
-H 'Content-Type: application/json' \
-d '{"content": "User prefers dark mode and compact layout", "tags": ["preference", "ui"]}'
curl -X POST http://localhost:8321/api/v1/search \
-H 'Content-Type: application/json' \
-d '{"query": "UI preferences", "top_k": 5}'Open http://localhost:8321/ for the Web Console.
Consolidation, conflict resolution, and tag extraction need an LLM backend. The gate is llm_model — until it's set, those endpoints are a no-op (see #consolidation-no-op). A hosted provider also needs llm_api_key; a local model (e.g. Ollama via llm_base_url) does not.
hebb config set llm_model openai/gpt-4o-mini # required — enables consolidation
hebb config set llm_api_key sk-... # for hosted providers
# For Qwen / GLM / Kimi via LiteLLM:
hebb config set llm_base_url https://dashscope.aliyuncs.com/compatible-mode/v1Trigger consolidation manually, or wait for the daily 18:00 job:
curl -X POST http://localhost:8321/api/v1/admin/consolidatepipx install hebb-mind # recommended (isolated CLI install)
pipx install 'hebb-mind[pg]' # + PostgreSQL/pgvector
pipx upgrade hebb-mind # upgrade later
hebb claude-code install --scope user # Claude Code: hooks-based recall + turn capture
hebb codex install --scope user # Codex: MCP memory toolsDocker, one-line install, and source build: Installation Guide.
from hebb import HebbMind
mem = HebbMind() # resolves hebb.json from cwd → $HEBB_HOME → ~/.hebb
mem.add("User prefers dark mode", tags=["preference", "ui"], importance=7.5)
mem.add("User uses VS Code with the One Dark theme", tags=["preference", "tools"])
for hit in mem.search("UI preferences", top_k=5):
print(hit.score, hit.memory.content)The HebbMind() facade runs the memory engine in-process (storage + embedder +
graph + hybrid search) — no HTTP server, no daemon required. It uses the same
components the REST server builds, minus the network layer.
The same four stages, every day, in roughly the same order the brain runs them:
| Stage | Brain analogue | What happens here | Trigger |
|---|---|---|---|
| Encoding | Hippocampal CA1 captures the moment | New memories land in the working-memory inbox (mem_hippocampus) |
API write |
| Replay & consolidation | Sharp-wave ripples during slow-wave sleep | Agent classifies into a partition, resolves conflicts, writes tags into the knowledge graph | Daily 18:00 / manual |
| Retrieval | Pattern completion in CA3 | Three-path hybrid search (vector + keyword + graph), scored on recency / importance / relevance | API search |
| Forgetting | Synaptic pruning + the Ebbinghaus curve | Dynamic TTL on access count and importance — neglected memories fade | Periodic |
Walkthroughs: Memory Lifecycle · Hybrid Search · Architecture diagram
Honest summary; full table on the docs site.
| Feature | Mem0 | Letta | Zep | Hebb Mind |
|---|---|---|---|---|
| Self-hosted Web UI | Cloud only (discussion) | Cloud only | Cloud only | Built-in SPA |
| Knowledge graph | Pluggable (removed in v3) | No | Yes (Graphiti) | Tag-based (NetworkX) |
| Memory consolidation | Append-only | Sleeptime Agent | Contradiction resolve | Auto + conflict resolve |
| Forgetting / decay | No | No | Temporal invalidation | Dynamic TTL |
| Zero-config local deploy | Needs API key | Needs API key + DB | Needs Postgres + Neo4j | SQLite + local embed |
All config lives in hebb.json. Common settings:
hebb config list
hebb config set llm_model openai/gpt-4o-mini
hebb config set storage_type postgresql
hebb config set pg_url postgresql://user:pass@localhost/hebbFull reference: Configuration Guide.
REST docs at http://localhost:8321/docs once the server is running. Key endpoints:
| Method | Endpoint | Purpose |
|---|---|---|
POST |
/api/v1/memories |
Store a memory |
POST |
/api/v1/search |
Hybrid search |
POST |
/api/v1/admin/consolidate |
Run consolidation now (requires llm_model) |
GET |
/api/v1/graph/tags |
List knowledge-graph tags |
GET |
/api/v1/graph/neighbors/{tag}?depth=2 |
Walk the tag graph |
LoCoMo (1,986 questions across 10 multi-session conversations; 1,978 scorable), session-level Recall@10 — the same metric MemPalace publishes.
| System | Embedding | Rerank | R@10 |
|---|---|---|---|
| Hebb Mind v0.1.6 | bge-large-1024 | bge-reranker-base | 95.75% |
| Hebb Mind v0.1.6 | bge-large-1024 | — | 94.14% |
| MemPalace hybrid | bge-large-1024 | — | 92.40% |
| Hebb Mind v0.1.6 | MiniLM-384 | bge-reranker-base | 94.69% |
| MemPalace hybrid | MiniLM-384 | — | 92.63% |
| Hebb Mind v0.1.6 | MiniLM-384 | — | 91.41% |
Same-embedding lead: +1.74 pp at bge-large with no rerank, +3.35 pp with rerank; the local cross-encoder even lifts the cheap MiniLM-384 to 94.69%, past MemPalace's tuned hybrid. End-to-end QA (same retrieval + DeepSeek-V4-Pro judge, full 1,978q): 77.1%.
LongMemEval (500 questions, LongMemEval-S) — session-level Recall@k (retrieval, apples-to-apples with MemPalace) and end-to-end QA (official reader + get_anscheck_prompt judge, comparable to Zep / Mem0).
| System | Retrieval recall@10 | End-to-end QA | Reader LLM |
|---|---|---|---|
| Hebb Mind v0.1.6 | 99.4% | 79.0% | DeepSeek-V4-Pro (neutral official prompt) |
| Zep | 95.5% | 71.2% | gpt-4o |
| Mem0 | not reported | ~85–94%¹ | gpt-4o (heavily-tuned prompt) |
Retrieval R@5 = 99.0%, tying MemPalace's best hybrid+rerank config (99.4%) and well above its raw 96.6% — on the same MiniLM-384 embedding. Hebb beats Zep at every retrieval depth (R@1 93.4% vs 75.9%) and leads its QA (79.0% vs 71.2%) with an untuned reader prompt; the gap to Mem0 is reader-prompt engineering, not memory — Hebb's retrieval is the stronger layer. ¹ varies by source/setup.
MemBench (ACL 2025; 11 categories, all topics, 11,996 questions) — turn-level Hit@5 against the dataset's target_step_id pointer, the metric MemPalace publishes. MCQ ground truth, so no LLM judge (random guessing alone scores 25%).
| Category | Hebb Mind v0.1.6 Hit@5 | MemPalace Hit@5 | Δ |
|---|---|---|---|
| noisy | 79.4% | 43.4% | +36.0 pp |
| post_processing | 90.3% | 56.6% | +33.7 pp |
| conditional | 86.0% | 57.3% | +28.7 pp |
| highlevel_rec | 89.6% | 76.2% | +13.4 pp |
| Overall (11 categories) | 94.6% | 80.3% | +14.3 pp |
MiniLM-384 + bge-reranker-base. Hebb matches MemPalace on the easy categories (within ±4 pp) and wins decisively on all four hard ones — distractors, conditional reasoning, post-processing — exactly where verbatim-embedding retrieval collapses; the lever is the local cross-encoder rerank. Per-category k-curves on the docs site.
Hebb Mind's eval calls the same Claude Code hook code paths (integrations/claude_code/{recall,stop}.py) and /api/v1/search endpoint that the shipped product uses — the numbers above are what a user actually gets in production. Full methodology, per-category breakdowns, and prod-vs-eval-pipeline caveats: hebb-mind.github.io/benchmarks.
In 1949, psychologist Donald O. Hebb proposed a rule that later got distilled into four words:
Neurons that fire together, wire together.
A memory is not a place you look something up — it is a pattern of connection. Concepts that co-occur get physically linked into cell assemblies, and lighting up part of an assembly recalls the rest. Repetition strengthens the wiring; disuse lets it fade. That single rule — Hebbian learning — has shaped most of what came after in memory research and artificial neural networks.
Hebb Mind runs on that rule. Its tag knowledge graph is a cell assembly: tags that appear together gain an edge, and every time they co-occur that edge grows stronger. Retrieval walks those edges, so a partial cue completes the whole pattern. Consolidation keeps what gets reinforced; forgetting prunes what does not — fire together, wire together; neglect it, lose it.
The hippocampus has a place here too — it names the working-memory partition (mem_hippocampus), the inbox where every new memory lands before consolidation. In the brain, the hippocampus is the gateway that holds new experience until it is wired into long-term cortical memory; in 1957, the patient known as H.M. lost both of his and could never form a new long-term memory again (Squire, 1992; Tulving, 2002). Today's AI agents are H.M. — every conversation starts from zero. Hebb Mind gives your agent that missing loop.
Setup: pip install -e ".[dev]" && pytest tests/ -v. See CONTRIBUTING.md.
Cognitive neuroscience. Ebbinghaus, H. (1885). Über das Gedächtnis. · Hebb, D. O. (1949). The Organization of Behavior. Wiley — the namesake; the postulate behind "fire together, wire together." · Tulving, E. (1972). Episodic and semantic memory. · Squire, L. R. (1992). Memory and the hippocampus: a synthesis from findings with rats, monkeys, and humans. Psychological Review, 99(2). · O'Reilly, R. C., & McClelland, J. L. (1994). Hippocampal conjunctive encoding, storage, and recall. Hippocampus, 4(6). · Wilson, M. A., & McNaughton, B. L. (1994). Reactivation of hippocampal ensemble memories during sleep. Science, 265(5172). · Tulving, E. (2002). Episodic memory: from mind to brain. Annual Review of Psychology, 53. · Buzsáki, G. (2015). Hippocampal sharp wave-ripple. Hippocampus, 25(10).
AI memory systems. Generative Agents (scoring) · MemGPT / Letta (agent-driven memory) · CoALA (partition taxonomy) · Graphiti (temporal KG). Survey notes in reports/papers/.
"Memory is the scribe of the soul." — Aristotle The brain solved this in deep time. We're just porting the loop.