hebb-mind 0.1.1

Hebb Mind — neuroscience-inspired long-term memory framework for AI agents (neurons that fire together, wire together)

Hebb Mind

A memory framework for AI agents — named for Donald Hebb, built on the rule his work gave us: neurons that fire together, wire together.

Encode. Replay. Consolidate. Forget. The way brains do.

Documentation · English | 中文

---

In 1957, neurosurgeons removed both hippocampi from a patient known as H.M. to treat his epilepsy. He survived — but lost the ability to form new long-term memories. Each day, every meal, every face was forever new. The hippocampus, it turned out, was the bridge between what just happened and what we know. Half a century of research (Squire, 1992; Tulving, 2002) has shown how it does this: it encodes fragments of experience, replays them during quiet rest (Wilson & McNaughton, 1994), consolidates the important ones into long-term knowledge, and lets the rest fade (Ebbinghaus, 1885).

Today's AI agents are H.M. They start every conversation new.

Hebb Mind is a memory framework that gives your agent that missing bridge. pip install, one command, and you have a local REST + MCP endpoint that runs the same four-stage loop: encode → replay → consolidate → forget. SQLite for storage, sentence-transformers for the embedding cortex, NetworkX for the tag graph. Zero external services. Bring an LLM key only when you want consolidation to do its work.

Where peers diverge: mem0 is cloud-first and append-only; letta needs an external DB and a separate sleeptime agent; zep needs Postgres + Neo4j. Hebb Mind runs on a single binary, with one biological loop.

Quick Start

Try in 60 seconds — no API key needed

Ingest and hybrid search work fully offline with the bundled local embedding.

pip install --user -U hebb-mind
hebb setup              # picks an embedding model based on your OS locale
hebb service install    # registers a background service (launchd / systemd / Task Scheduler)

If hebb is not found after pip install --user, your Python user-script directory is not on PATH. This is the macOS default. Add it once and you're done — run the one line that matches your shell:

# zsh (macOS default)
echo 'export PATH="$(python3 -m site --user-base)/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

# bash
echo 'export PATH="$(python3 -m site --user-base)/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

# fish
fish_add_path (python3 -m site --user-base)/bin

Installing in a virtualenv (python -m venv .venv && source .venv/bin/activate && pip install hebb-mind) sidesteps this entirely; system-wide sudo pip install hebb-mind does too.

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.

Full experience (5 min) — with LLM consolidation

Consolidation, conflict resolution, and tag extraction need an LLM. Without a key, those endpoints are a no-op (this is a known v0.1.1 gap — see #consolidation-no-op).

hebb config set llm_api_key sk-...
hebb config set llm_model openai/gpt-4o-mini
# For Qwen / GLM / Kimi via LiteLLM:
hebb config set llm_base_url https://dashscope.aliyuncs.com/compatible-mode/v1

Then trigger consolidation manually or wait for the daily 18:00 job:

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

Why "Hebb Mind"?

In 1949, Canadian psychologist Donald O. Hebb (1904–1985) published The Organization of Behavior and proposed the rule that became the foundation of how we understand learning in the brain. When one neuron repeatedly takes part in firing another, he argued, the connection between them strengthens. Half a century later it is still taught in four words:

Neurons that fire together, wire together.

Hebb's insight was that 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 — is the ancestor of every artificial neural network and every associative-memory system since.

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. The name fits the job: in the brain, the hippocampus is the gateway that holds new experience until it is wired into long-term cortical memory. The partition does exactly that.

Inspired by the brain (not just the name)

Each piece of the system maps to a mechanism cognitive neuroscience has spent fifty years describing. The point isn't fidelity to biology — it's that the brain has already solved the problem of which memories to keep, when to consolidate them, and how to recall them from a partial cue. We borrow the answers.

Brain mechanism	What the brain does	What Hebb Mind does
Sharp-wave ripples & replay (Wilson & McNaughton, 1994; Buzsáki, 2015)	During slow-wave sleep the hippocampus replays the day's experiences, transferring them to neocortex.	A daily 18:00 consolidation job replays the working-memory inbox, classifies each item into a partition, resolves conflicts, and writes tags into the knowledge graph.
Multiple memory systems (Tulving, 1972; Squire, 1992)	Episodic, semantic, procedural memory live in distinct sub-systems.	Five named partitions — episodic, semantic, preference, procedural, custom — modeled on the CoALA cognitive architecture.
Forgetting curve (Ebbinghaus, 1885)	Unrehearsed memories decay exponentially; rehearsal flattens the curve.	TTL = base × (1 + log(access)) × importance × exp(-decay × days). Frequently used memories survive; neglected ones fade.
Pattern separation + completion (O'Reilly & McClelland, 1994)	DG distinguishes similar memories; CA3 reconstructs whole memories from partial cues.	Hybrid retrieval combines vector similarity (separation), keyword match, and tag-graph walk (completion) — three paths, one composite score.

Why this matters in practice: a system that only appends never resolves contradictions, and a system that never forgets drowns its own retrieval in noise. The brain solved both. So do we.

Why Hebb Mind? (the engineering view)

• Zero external services — sqlite-vec for vectors, NetworkX for the tag graph, sentence-transformers for embedding. No Postgres, no Neo4j, no Redis. See Storage Backends.
• Honest forgetting — the Ebbinghaus formula above, applied as a periodic job. See Forgetting.
• Conflict-resolving consolidation — the agent doesn't just append; it merges duplicates and overwrites stale facts. See Consolidation.
• Drop-in for Claude Code — three-line install gives Claude Code cross-session memory via hooks; one command adds the same as MCP tools to Codex. See Claude Code Integration.

Benchmarks

v0.1.1, single run on the LoCoMo long-conversation benchmark:

Metric	Value
Accuracy	37.6% (187 / 497)
Avg latency	102 ms / query
Best category	Adversarial 66.1%
Weakest category	Multi-hop 5.6%

Multi-hop reasoning over the tag graph is a known weak spot. Full numbers, methodology, and per-category breakdown: Benchmarks. This is a work in progress — comparison runs against mem0 and zep are tracked in [#TBD].

30-second Python SDK

from hebb import HebbMind

mem = HebbMind()  # uses ~/.hebb/hebb.json

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

The HebbMind() facade wraps the same REST endpoints used above; it also boots an in-process server when no daemon is running.

Installation Paths

pip install -U hebb-mind               # pip
pip install -U hebb-mind[pg]           # + PostgreSQL/pgvector
hebb claude-code install --scope user          # Claude Code: hooks-based auto memory
hebb codex install --scope user       # Codex: MCP memory tools

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

The memory loop

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, extracts tags	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

Comparison

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

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:

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_api_key)
GET	/api/v1/graph/tags	List knowledge-graph tags
GET	/api/v1/graph/neighbors/{tag}?depth=2	Walk the tag graph

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