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.

Quick Start

Try in ~60 seconds — no API key needed

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 ensurepath

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

Use Agent Sync in the Web Console to make Hebb Mind the shared memory hub for Claude Code and Codex. It collects local session history from both tools, shows synced vs pending turns, and imports pending turns into the Hebb Mind database. The same workflow is available from the CLI:

hebb agent-sync list --host codex
hebb agent-sync sync --host codex --dry-run

Full experience (5 min) — enable LLM consolidation

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/v1

Trigger consolidation manually, or wait for the daily 18:00 job:

curl -X POST http://localhost:8321/api/v1/admin/consolidate

Installation Paths

pipx 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                     # Codex: project MCP + automatic memory hooks
hebb agent-sync list                   # Audit Claude Code / Codex session sync status
hebb agent-sync sync --dry-run         # Preview historical session import

Docker, one-line install, and source build: Installation Guide.

30-second Python SDK

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 memory loop

The same four stages, every day, in roughly the same order the brain runs them:

Walkthroughs: Memory Lifecycle · Hybrid Search · Architecture diagram

Comparison

Honest summary; full table on the docs site.

Configuration

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/hebb

Full reference: Configuration Guide.

API

REST docs at http://localhost:8321/docs once the server is running. Key endpoints:

Benchmarks

LoCoMo (1,986 questions across 10 multi-session conversations; 1,978 scorable), session-level Recall@10 — the same metric MemPalace publishes.

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

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%).

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.

Why "Hebb Mind"?

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.

Contributing

Setup: pip install -e ".[dev]" && pytest tests/ -v. See CONTRIBUTING.md.

Acknowledgments

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.

License

MIT