{"id":51041893,"url":"https://github.com/afx-team/hebb-mind","last_synced_at":"2026-06-22T11:02:22.329Z","repository":{"id":352589992,"uuid":"1213232466","full_name":"afx-team/hebb-mind","owner":"afx-team","description":"Neuroscience-inspired memory framework for AI agents","archived":false,"fork":false,"pushed_at":"2026-06-11T03:06:59.000Z","size":20358,"stargazers_count":9,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-11T05:07:28.289Z","etag":null,"topics":["agent","agentmemory","claude-code","codex","llm","memory","neuroscience"],"latest_commit_sha":null,"homepage":"https://afx-team.github.io/hebb-mind/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/afx-team.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-17T07:07:20.000Z","updated_at":"2026-06-10T07:19:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/afx-team/hebb-mind","commit_stats":null,"previous_names":["afx-team/hippocampus","afx-team/hebb-mind"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/afx-team/hebb-mind","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afx-team%2Fhebb-mind","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afx-team%2Fhebb-mind/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afx-team%2Fhebb-mind/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afx-team%2Fhebb-mind/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/afx-team","download_url":"https://codeload.github.com/afx-team/hebb-mind/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/afx-team%2Fhebb-mind/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34645688,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-22T02:00:06.391Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","agentmemory","claude-code","codex","llm","memory","neuroscience"],"created_at":"2026-06-22T11:02:21.504Z","updated_at":"2026-06-22T11:02:22.321Z","avatar_url":"https://github.com/afx-team.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ch1 align=\"center\"\u003e\u003ca href=\"https://afx-team.github.io/hebb-mind/\"\u003e\u003cimg src=\"logo.svg\" width=\"40\" height=\"40\" alt=\"Hebb Mind logo\" valign=\"middle\"/\u003e Hebb Mind\u003c/a\u003e\u003c/h1\u003e\n  \u003cp align=\"center\"\u003e\u003cstrong\u003eA neuroscience-inspired memory framework for AI agents\u003c/strong\u003e\u003c/p\u003e\n  \u003cp align=\"center\"\u003e\u003cem\u003eEncode. Consolidate. Activate. Forget.\u003c/em\u003e\u003c/p\u003e\n  \u003cp align=\"center\"\u003e\u003ca href=\"https://afx-team.github.io/hebb-mind/\"\u003eDocumentation\u003c/a\u003e · \u003ca href=\"README.md\"\u003eEnglish\u003c/a\u003e | \u003ca href=\"README_ZH.md\"\u003e中文\u003c/a\u003e\u003c/p\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://afx-team.github.io/hebb-mind/\"\u003e\u003cimg src=\"https://img.shields.io/badge/docs-afx--team.github.io-blue\" alt=\"Documentation\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/afx-team/hebb-mind/actions\"\u003e\u003cimg src=\"https://github.com/afx-team/hebb-mind/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/hebb-mind/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/hebb-mind\" alt=\"PyPI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/afx-team/hebb-mind/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-blue\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/pypi/pyversions/hebb-mind\" alt=\"Python\"\u003e\n\u003c/p\u003e\n\n---\n\nHebb 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.\n\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"repo_pages/public/architecture-en.jpg\" alt=\"Hebb Mind architecture — agent integrations · hebb CLI · 4-stage memory loop with LLM-driven 7-step consolidation agent · SQLite + pgvector\" width=\"900\"\u003e\n\u003c/p\u003e\n\n## Quick Start\n\n### Try in ~60 seconds — no API key needed\n\nIngest and hybrid search work fully offline with a local embedding model.\n\n```bash\npipx install hebb-mind\nhebb setup              # downloads a small embedding model based on your OS locale\nhebb service install    # registers a background service (launchd / systemd / Task Scheduler)\n```\n\n`hebb setup` downloads a small embedding model only if it isn't already cached —\n~90MB for English (`all-MiniLM-L6-v2`), ~470MB for multilingual\n(`intfloat/multilingual-e5-small`). The ~60-second figure is for the English /\n`--profile fast` small-model path; the multilingual model is a larger download.\nWant the high-quality models? `hebb setup --profile best` pulls the BAAI `bge`\nfamily instead (1–2GB+) — opt-in, never downloaded by default.\n\n**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:\n\n```bash\n# macOS (Homebrew)\nbrew install pipx \u0026\u0026 pipx ensurepath\n\n# Linux — Debian / Ubuntu 23.04+\nsudo apt install pipx \u0026\u0026 pipx ensurepath\n\n# Linux — Fedora\nsudo dnf install pipx \u0026\u0026 pipx ensurepath\n\n# Windows / any platform with Python 3.10+\npython -m pip install --user pipx \u0026\u0026 python -m pipx ensurepath\n```\n\nThen **open a new terminal** so the updated `PATH` takes effect, and re-run `pipx install hebb-mind`.\n\nPrefer plain `pip` instead? `python -m venv .venv \u0026\u0026 source .venv/bin/activate \u0026\u0026 pip install -U hebb-mind` works fine — `hebb` lives on the venv's `PATH` automatically.\n\nHebb 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`.\n\nIn another shell:\n\n```bash\ncurl -X POST http://localhost:8321/api/v1/memories \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"content\": \"User prefers dark mode and compact layout\", \"tags\": [\"preference\", \"ui\"]}'\n\ncurl -X POST http://localhost:8321/api/v1/search \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"query\": \"UI preferences\", \"top_k\": 5}'\n```\n\nOpen \u003chttp://localhost:8321/\u003e for the Web Console.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"repo_pages/public/web-console-hero.jpg\" alt=\"Hebb Mind Web Console — partitioned memories and tag graph\" width=\"760\"\u003e\n\u003c/p\u003e\n\n### Full experience (5 min) — enable LLM consolidation\n\nConsolidation, 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](https://afx-team.github.io/hebb-mind/troubleshooting.html)). A hosted provider also needs `llm_api_key`; a local model (e.g. Ollama via `llm_base_url`) does not.\n\n```bash\nhebb config set llm_model openai/gpt-4o-mini   # required — enables consolidation\nhebb config set llm_api_key sk-...             # for hosted providers\n# For Qwen / GLM / Kimi via LiteLLM:\nhebb config set llm_base_url https://dashscope.aliyuncs.com/compatible-mode/v1\n```\n\nTrigger consolidation manually, or wait for the daily 18:00 job:\n\n```bash\ncurl -X POST http://localhost:8321/api/v1/admin/consolidate\n```\n\n## Installation Paths\n\n```bash\npipx install hebb-mind                 # recommended (isolated CLI install)\npipx install 'hebb-mind[pg]'           # + PostgreSQL/pgvector\npipx upgrade hebb-mind                 # upgrade later\nhebb claude-code install --scope user  # Claude Code: hooks-based recall + turn capture\nhebb codex install --scope user        # Codex: MCP memory tools\n```\n\nDocker, one-line install, and source build: [Installation Guide](https://afx-team.github.io/hebb-mind/guide/installation.html).\n\n## 30-second Python SDK\n\n```python\nfrom hebb import HebbMind\n\nmem = HebbMind()  # resolves hebb.json from cwd → $HEBB_HOME → ~/.hebb\n\nmem.add(\"User prefers dark mode\", tags=[\"preference\", \"ui\"], importance=7.5)\nmem.add(\"User uses VS Code with the One Dark theme\", tags=[\"preference\", \"tools\"])\n\nfor hit in mem.search(\"UI preferences\", top_k=5):\n    print(hit.score, hit.memory.content)\n```\n\nThe `HebbMind()` facade runs the memory engine in-process (storage + embedder +\ngraph + hybrid search) — no HTTP server, no daemon required. It uses the same\ncomponents the REST server builds, minus the network layer.\n\n## The memory loop\n\nThe same four stages, every day, in roughly the same order the brain runs them:\n\n| Stage | Brain analogue | What happens here | Trigger |\n|-------|----------------|-------------------|---------|\n| **Encoding** | Hippocampal CA1 captures the moment | New memories land in the working-memory inbox (`mem_hippocampus`) | API write |\n| **Replay \u0026 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 |\n| **Retrieval** | Pattern completion in CA3 | Three-path hybrid search (vector + keyword + graph), scored on recency / importance / relevance | API search |\n| **Forgetting** | Synaptic pruning + the Ebbinghaus curve | Dynamic TTL on access count and importance — neglected memories fade | Periodic |\n\nWalkthroughs: [Memory Lifecycle](https://afx-team.github.io/hebb-mind/concepts/memory-lifecycle.html) · [Hybrid Search](https://afx-team.github.io/hebb-mind/concepts/hybrid-search.html) · [Architecture diagram](https://afx-team.github.io/hebb-mind/#architecture)\n\n## Comparison\n\nHonest summary; full table on the [docs site](https://afx-team.github.io/hebb-mind/#why-hebb-mind).\n\n| Feature | Mem0 | Letta | Zep | **Hebb Mind** |\n|---|---|---|---|---|\n| Self-hosted Web UI | Cloud only ([discussion](https://github.com/mem0ai/mem0/discussions/3599)) | Cloud only | Cloud only | **Built-in SPA** |\n| Knowledge graph | Pluggable ([removed in v3](https://docs.mem0.ai/migration/oss-v2-to-v3)) | No | Yes (Graphiti) | Tag-based (NetworkX) |\n| Memory consolidation | Append-only | Sleeptime Agent | Contradiction resolve | **Auto + conflict resolve** |\n| Forgetting / decay | No | No | Temporal invalidation | **Dynamic TTL** |\n| Zero-config local deploy | Needs API key | Needs API key + DB | Needs Postgres + Neo4j | **SQLite + local embed** |\n\n## Configuration\n\nAll config lives in `hebb.json`. Common settings:\n\n```bash\nhebb config list\nhebb config set llm_model openai/gpt-4o-mini\nhebb config set storage_type postgresql\nhebb config set pg_url postgresql://user:pass@localhost/hebb\n```\n\nFull reference: [Configuration Guide](https://afx-team.github.io/hebb-mind/guide/configuration.html).\n\n## API\n\nREST docs at `http://localhost:8321/docs` once the server is running. Key endpoints:\n\n| Method | Endpoint | Purpose |\n|--------|----------|---------|\n| `POST` | `/api/v1/memories` | Store a memory |\n| `POST` | `/api/v1/search` | Hybrid search |\n| `POST` | `/api/v1/admin/consolidate` | Run consolidation now (requires `llm_model`) |\n| `GET`  | `/api/v1/graph/tags` | List knowledge-graph tags |\n| `GET`  | `/api/v1/graph/neighbors/{tag}?depth=2` | Walk the tag graph |\n\n## Benchmarks\n\n**LoCoMo** (1,986 questions across 10 multi-session conversations; 1,978 scorable), session-level Recall@10 — the same metric MemPalace publishes.\n\n| System | Embedding | Rerank | R@10 |\n|---|---|---|---|\n| **Hebb Mind v0.1.6** | bge-large-1024 | bge-reranker-base | **95.75%** |\n| **Hebb Mind v0.1.6** | bge-large-1024 | — | **94.14%** |\n| MemPalace hybrid | bge-large-1024 | — | 92.40% |\n| **Hebb Mind v0.1.6** | MiniLM-384 | bge-reranker-base | **94.69%** |\n| MemPalace hybrid | MiniLM-384 | — | 92.63% |\n| **Hebb Mind v0.1.6** | MiniLM-384 | — | 91.41% |\n\nSame-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%**.\n\n**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).\n\n| System | Retrieval recall@10 | End-to-end QA | Reader LLM |\n|---|---|---|---|\n| **Hebb Mind v0.1.6** | **99.4%** | **79.0%** | DeepSeek-V4-Pro (neutral official prompt) |\n| Zep | 95.5% | 71.2% | gpt-4o |\n| Mem0 | not reported | ~85–94%¹ | gpt-4o (heavily-tuned prompt) |\n\nRetrieval 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. \u003csup\u003e¹ varies by source/setup.\u003c/sup\u003e\n\n**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%).\n\n| Category | Hebb Mind v0.1.6 Hit@5 | MemPalace Hit@5 | Δ |\n|---|---|---|---|\n| noisy | **79.4%** | 43.4% | +36.0 pp |\n| post_processing | **90.3%** | 56.6% | +33.7 pp |\n| conditional | **86.0%** | 57.3% | +28.7 pp |\n| highlevel_rec | **89.6%** | 76.2% | +13.4 pp |\n| **Overall (11 categories)** | **94.6%** | 80.3% | **+14.3 pp** |\n\nMiniLM-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.\n\nHebb 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](https://afx-team.github.io/hebb-mind/benchmarks/).\n\n## Why \"Hebb Mind\"?\n\nIn 1949, psychologist **Donald O. Hebb** proposed a rule that later got distilled into four words:\n\n\u003e **Neurons that fire together, wire together.**\n\nA 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.\n\n**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.*\n\nThe **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)](#acknowledgments). Today's AI agents are H.M. — every conversation starts from zero. Hebb Mind gives your agent that missing loop.\n\n## Contributing\n\nSetup: `pip install -e \".[dev]\" \u0026\u0026 pytest tests/ -v`. See [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Acknowledgments\n\n**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., \u0026 McClelland, J. L. (1994). Hippocampal conjunctive encoding, storage, and recall. *Hippocampus*, 4(6). · Wilson, M. A., \u0026 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).\n\n**AI memory systems.** [Generative Agents](https://arxiv.org/abs/2304.03442) (scoring) · [MemGPT / Letta](https://arxiv.org/abs/2310.08560) (agent-driven memory) · [CoALA](https://arxiv.org/abs/2309.02427) (partition taxonomy) · [Graphiti](https://github.com/getzep/graphiti) (temporal KG). Survey notes in [`reports/papers/`](reports/papers/).\n\n\u003e *\"Memory is the scribe of the soul.\" — Aristotle*\n\u003e The brain solved this in deep time. We're just porting the loop.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fafx-team%2Fhebb-mind","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fafx-team%2Fhebb-mind","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fafx-team%2Fhebb-mind/lists"}