{ "markdown": "# BrainBox\n\n

\n \"BrainBox\n

\n\n

\n \"npm\n \"GitHub\n \"License\"\n

\n\nHebbian memory for AI coding agents. Learns which files you access together, which errors lead to which fixes, and which tool chains you use most — then recalls them instantly.\n\n**Not a vector database. Not RAG. Procedural memory.**\n\n> If BrainBox saved you tokens, [give it a star](https://github.com/thebasedcapital/brainbox) — it helps others find it.\n> Built by [@thebasedcapital](https://x.com/thebasedcapital)\n\n```\nSession 1: agent greps for auth.ts, reads it, edits it (2000 tokens)\nSession 5: agent recalls auth.ts directly, skips search (500 tokens saved)\nSession 20: auth.ts is a superhighway — instant recall, zero search cost\n```\n\n## Install\n\n```bash\nnpm install brainbox-hebbian\n```\n\nThat's it. The postinstall script automatically:\n1. Adds `PostToolUse` hook to `~/.claude/settings.json` (learns from every file read/edit/search)\n2. Adds `UserPromptSubmit` hook (injects neural recall into prompts automatically)\n3. Registers the MCP server via `claude mcp add` (6 tools for manual recall/recording)\n4. Creates `~/.brainbox/` database directory\n\nBrainBox learns passively from your next Claude Code session. No configuration needed.\n\n### What does NOT happen automatically\n\nThe **macOS daemon** (system-wide FSEvents file watcher) is completely separate and opt-in:\n\n```bash\n# Only if you want BrainBox to learn from VS Code, Xcode, vim, shell, etc.\nbrainbox daemon install # installs LaunchAgent, starts watching\nbrainbox daemon status # check if running\nbrainbox daemon uninstall # remove completely\n```\n\nThe daemon watches file changes across all your editors — not just Claude Code. It requires explicit opt-in because it registers a LaunchAgent and monitors your configured project directories.\n\n### Uninstall\n\n```bash\nbrainbox uninstall # removes hooks + MCP server, preserves database\n```\n\n### Seed from git history (recommended)\n\nKill cold start by bootstrapping from your existing git history:\n\n```bash\nbrainbox bootstrap --repo /path/to/project --imports\n```\n\nThis seeds the neural network from git commit co-changes and import graphs so BrainBox starts with knowledge instead of from zero.\n\n## How It Works\n\nBrainBox implements neuroscience-inspired learning:\n\n- **Neurons** — files, tools, and errors you interact with\n- **Synapses** — connections formed when things are accessed together (\"neurons that fire together wire together\")\n- **Myelination** — frequently-used paths get faster (like muscle memory)\n- **Spreading activation** — recalling one file activates related files\n- **Decay** — unused connections weaken naturally, keeping the network clean\n\n
\nHebbian Learning in Action (click to play)\n\nhttps://github.com/thebasedcapital/brainbox/raw/main/assets/brainbox-animation.mp4\n\n
\n\n
\nSpreading Activation — recalling one file activates related files through synaptic connections\n\nhttps://github.com/thebasedcapital/brainbox/raw/main/assets/brainbox-spreading.mp4\n\n
\n\n
\nSuperhighway Formation — frequently-used pathways become instant-recall superhighways\n\nhttps://github.com/thebasedcapital/brainbox/raw/main/assets/brainbox-superhighway.mp4\n\n
\n\n
\nError-Fix Immune System — remembers which files fixed which errors\n\nhttps://github.com/thebasedcapital/brainbox/raw/main/assets/brainbox-immune.mp4\n\n
\n\n## Other Integrations\n\n### MCP Server (any agent)\n\nIf you're not using Claude Code, you can run the MCP server standalone:\n\n```bash\n# 6 tools: record, recall, error, predict_next, stats, decay\nnpx tsx node_modules/brainbox-hebbian/src/mcp.ts\n```\n\n### Kilo / OpenCode (native plugin)\n\nAdd to `~/.config/kilo/config.json`:\n\n```json\n{\n \"plugin\": [\"node_modules/brainbox-hebbian/src/kilo-plugin.ts\"]\n}\n```\n\n### OpenClaw (NeuroVault)\n\nBrainBox can be deployed as an OpenClaw memory slot plugin. See [NeuroVault](https://github.com/thebasedcapital/neurovault) for the reference implementation.\n\n| Aspect | Claude Code | OpenClaw |\n|---|---|---|\n| Tool names | PascalCase (`Read`) | Lowercase (`read`) |\n| Context injection | `UserPromptSubmit` hook | `before_agent_start` lifecycle |\n| Learning trigger | `PostToolUse` hook | `after_tool_call` lifecycle |\n| Embeddings | all-MiniLM-L6-v2 | Keyword-only (lower confidence gate) |\n\n## CLI\n\n```bash\nbrainbox recall \"authentication login\"\nbrainbox record src/auth.ts --context \"authentication\"\nbrainbox stats\nbrainbox error \"TypeError: cannot read 'token'\"\nbrainbox predict Read\nbrainbox embed # add vector embeddings for semantic recall\nbrainbox hubs # most connected neurons\nbrainbox stale # decaying superhighways\nbrainbox projects # list project tags\nbrainbox sessions # recent sessions with intents\nbrainbox streaks # anti-recall ignore streaks\nbrainbox graph # ASCII neural network\nbrainbox highways # show superhighways\nbrainbox decay # weaken unused connections\n```\n\n## Key Features\n\n### Hebbian Learning\nFiles accessed together form synapses. Access `auth.ts` then `session.ts` 10 times and BrainBox learns they're related — recalling one activates the other.\n\n### Error-Fix Immune System\nWhen you fix a bug, BrainBox remembers which files fixed which errors. Next time a similar error appears, it suggests the fix files immediately.\n\n### Tool Sequence Prediction\nAfter 20 Grep-Read-Edit chains, BrainBox predicts you'll Read after Grep and pre-loads likely files.\n\n### SNAP Plasticity\nStrong synapses resist further strengthening (like real neural synapses). Prevents any single connection from dominating the network.\n\n### Anti-Recall Escalation\nFiles recalled but never opened get progressively stronger decay. Consecutive ignores escalate: 1st = 10%, 2nd = 19%, 3rd = 27%. Opening the file resets the streak.\n\n### Hub Detection & Staleness Alerts\nIdentify the most-connected neurons in your network and detect decaying superhighways before they fade.\n\n### Project Tagging\nAuto-tag file neurons by project. Recall scoped to current project reduces cross-project noise.\n\n## Architecture\n\n```\nsrc/\n hebbian.ts # Core engine: record, recall, decay, SNAP, BCM, spreading activation\n db.ts # SQLite schema: neurons, synapses, access_log, sessions\n embeddings.ts # Optional vector embeddings (all-MiniLM-L6-v2, 384 dims)\n installer.ts # Auto-installer: adds hooks + MCP to ~/.claude/settings.json\n mcp.ts # MCP server (6 tools)\n hook.ts # Claude Code PostToolUse hook\n prompt-hook.ts # Claude Code UserPromptSubmit hook\n kilo-plugin.ts # Kilo/OpenCode native plugin\n bootstrap.ts # Git/vault/import seeder\n daemon.ts # FSEvents file watcher (macOS, opt-in)\n cli.ts # CLI interface\n test.ts # 59 tests, all passing\n```\n\n## Algorithm Details\n\n| Component | Mechanism |\n|-----------|-----------|\n| Synapse formation | Sequential window (25 items), positional decay |\n| Strengthening | SNAP sigmoid plasticity (midpoint 0.5, steepness 8) |\n| Myelination | BCM sliding threshold + diminishing returns, 0.95 ceiling |\n| Confidence | Multiplicative: contextScore * (1 + myelin + recency + path) |\n| Spreading | 2-hop BFS, fan-out cap 10, fan effect 1/sqrt(degree) |\n| Decay | Activation -15%, synapses -2%, myelination -0.5% per cycle |\n| Error learning | 2x boosted learning rate for error neurons |\n| Anti-recall | Compound decay: `1 - (1 - 0.1)^streak`, floor at 0.1 |\n\nFull details in [WHITEPAPER.md](./WHITEPAPER.md).\n\n## Tests\n\n```bash\nnpm test # 59 tests, ~2s\n```\n\n## Requirements\n\n- Node.js 18+\n- macOS or Linux (FSEvents daemon is macOS-only, everything else is cross-platform)\n\n## License\n\nMIT\n", "bytes": 8369, "sha": "92ff804d2c0054f3de8f93910d27e2cbf19c293ca83d304be7326dc5c224cd83", "repo_slug": "thebasedcapital/brainbox", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_thebasedcapital_brainbox_db78bac0/readme" }