brainbox

安装 · 工作原理 · 效果 · 研究 · 集成 · 白皮书

BrainBox 是面向 AI 编码 Agent 的程序性记忆。它会观察 Agent 的实际操作并将其记住：

• 哪些文件会被一起读取和编辑
• 哪些编辑修复了哪些错误
• Agent 会重复使用哪些工具链

下次执行任务时，它会在 Agent 开始搜索之前，将合适的文件呈现在它面前。

不是向量数据库，也不是 RAG。 基于本地 SQLite 图谱的赫布学习。零 API 成本，无需 GPU，数据不会离开你的设备。

Session 1   agent greps for auth.ts, reads it, edits it            ~2,000 tokens of searching
Session 5   BrainBox recalls auth.ts + session.ts up front         search skipped
Session 20  auth.ts → session.ts → token.ts is a superhighway      instant recall

论文

BrainBox：面向编码 Agent 的本地行为记忆（Bhavesh B，2026）。上方 DOI 涵盖所有版本，并会解析到最新版本。最新版本：v0.2，doi:10.5281/zenodo.23250505。

@misc{b2026brainbox,
  author    = {B, Bhavesh},
  title     = {BrainBox: Local Behavioral Memory for Coding Agents},
  year      = {2026},
  publisher = {Zenodo},
  version   = {v0.2},
  doi       = {10.5281/zenodo.23250505},
  url       = {https://doi.org/10.5281/zenodo.23250505}
}

安装

npm install brainbox-hebbian

就这么简单。安装后脚本会：

1. 在 ~/.claude/settings.json 中添加 PostToolUse 钩子。它会从每次文件读取、编辑、搜索和命令执行中学习。
2. 添加 UserPromptSubmit 钩子。它会将精简的回忆注入提示词；一旦发现你会忽略这些内容，就保持静默。
3. 添加 SessionEnd 钩子。它会评估你实际打开或编辑了哪些召回文件，并整理出操作流程。
4. 通过 claude mcp add 注册 MCP 服务，并提供 8 个工具：record、recall、explain、error、resolve、predict_next、stats、decay。
5. 创建 ~/.brainbox/，并在后台开始下载嵌入模型。

钩子不会下载模型。在模型缓存好之前（brainbox models pull），召回仅使用词法搜索。嵌入功能由可选依赖项 @huggingface/transformers 提供；如果其原生模块无法在你的设备上安装（例如，使用系统 libvips 的 sharp 且没有构建工具），BrainBox 仍会完成安装并使用关键词搜索运行。brainbox models status 会显示当前运行模式。

通过 Git 历史和代码图谱预先填充数据，告别冷启动：

brainbox bootstrap --repo /path/to/project --imports

卸载： brainbox uninstall 会移除钩子和 MCP 服务，并保留数据库。

工作原理

每次工具调用都是一个正在放电的神经元。文件、工具和错误都会成为神经元，而在相近时间访问的内容会形成突触。提示词会触发回忆，融合多个排序通道。学习得到的策略会判断注入是否值得消耗这些令牌。关于你实际打开或编辑内容的反馈会回流到图中。

一起放电，一起连接

在不同会话中先访问 auth.ts，再访问 session.ts，它们之间的突触就会增强。SNAP 可塑性会让强突触增长得更慢，因此没有任何单一连接会占据主导。连接具有方向性（STDP）：你接下来打开什么，比之前打开的内容更重要。

扩散激活

回忆一个文件会激活其邻居，最多扩散 3 跳。每一跳都会按 1/√degree 衰减，因此枢纽文件不会淹没结果。每个结果都会注明产生它的通道和边。brainbox_explain 会准确说明回忆某个文件的原因。

超级通道与衰减

常用路径会髓鞘化，成为可即时回忆的超级通道。近期性和频率遵循 ACT-R 基础水平公式 B = ln Σ tⱼ^-0.5，未使用的连接则会逐渐减弱。回忆后却被忽略的文件，只会削弱使其浮现的那条边。

错误 → 修复免疫系统

如果失败的命令之后进行了编辑，并且重新运行后通过，BrainBox 就会存储一条错误→修复流程。该流程以错误指纹为键，并跟踪有益或有害的结果。下次出现该错误时，修复文件会立即被回忆出来。流程会以引用观察结果的形式呈现给 Agent，绝不会作为指令。

结果

brainbox eval 会按时间顺序重放真实的编码 Agent 轨迹。每项任务都在全新的内存数据库上进行评分，该数据库仅使用同一仓库中更早的任务进行训练，且所有系统的候选集都相同。

v0.1 在下一文件预测上不如简单的近期性基线。 在留出的 SWE 任务上，差距为 −.207，95% 置信区间为 −.312…−.118。v0.2 在这项指标上与近期性基线在统计上持平。下一工具预测现在显著优于所有基线，文件读取召回率在两种数据源上都领先。

已知差距： 在本地会话中，仅按编辑频率排序，在已编辑文件上的表现仍优于 BrainBox（Δ −.089，置信区间 −.185…0）。

将词法和 Hebbian 通道权重拟合为零后，开发集得分更高，但召回结果会忽略查询，因此发布的权重仍保留这些通道。

npm run eval -- --source nebius --repos 5 --max-tasks-per-repo 20 --split test --embeddings off --engine new
npm run eval -- --source omp    --repos 5 --max-tasks-per-repo 20 --embeddings off --engine old   # v0.1 engine (needs a worktree, see src/eval)

每项 v0.2 变更都对应一篇近期论文，并通过回放评估进行测量：

0.2 还包括：

• 基于 Node 22–26 构建（better-sqlite3 v13）。
• 钩子采用 Claude Code 的嵌套设置格式编写。
• 钩子数据库锁定等待时间上限为 100 ms。
• 在大型历史记录上，操作流程编译速度提升 470 倍。

集成

MCP 服务（任意 Agent）

# 8 tools: record, recall (detail: compact|full), explain, error, resolve, predict_next, stats, decay
npx tsx node_modules/brainbox-hebbian/src/mcp.ts

Kilo / OpenCode（原生插件）

添加到 ~/.config/kilo/config.json：

{
  "plugin": ["node_modules/brainbox-hebbian/src/kilo-plugin.ts"]
}

OpenClaw（NeuroVault）

BrainBox 可作为 OpenClaw 记忆槽插件运行。参考实现请参阅 NeuroVault。

macOS 守护进程（可选启用）

一个系统级 FSEvents 文件监视器，可从 VS Code、Xcode、vim 和 shell 中学习，而不仅限于 Agent。它会安装 LaunchAgent，因此需要明确选择启用：

brainbox daemon install   # installs LaunchAgent, starts watching
brainbox daemon status
brainbox daemon uninstall

命令行

brainbox recall "authentication login"
brainbox record src/auth.ts --query "authentication"
brainbox stats                 # includes stale-embedding counts + re-index commands
brainbox error "TypeError: cannot read 'token'"
brainbox predict Read
brainbox bootstrap --repo . --imports [--since <git-rev>]   # git history + tree-sitter code graph
brainbox extract-snippets [--force] [--no-embed]           # AST chunks → FTS5 + sqlite-vec
brainbox embed [--force]       # embed neurons with the active model
brainbox models pull|status    # fetch / inspect the embedding model
brainbox procedures [list|compile|show <id>|deprecate <id>]
brainbox sleep                 # consolidation + procedure compilation
brainbox eval --source nebius|omp [...]                   # offline replay evaluation
brainbox hubs | stale | projects | sessions | streaks | graph | highways | decay

src/
  hebbian.ts       # Engine: record, recall (rank fusion), STDP, n-gram tool prediction, decay, anti-recall
  db.ts            # SQLite schema + migrations
  policy.ts        # Recall event log + contextual UCB1 injection policy
  adapter.ts       # Shared recall/injection orchestration for all hosts
  snippets.ts      # AST chunking, FTS5 + sqlite-vec hybrid search
  embeddings.ts    # Embedding model profiles, hook-safe loading
  codegraph.ts     # Tree-sitter import/call/inherit graph
  procedures.ts    # Procedural playbook mining + matching
  bootstrap.ts     # Git history / code graph / session seeding
  installer.ts     # Hooks + MCP registration, model prefetch
  mcp.ts           # MCP server (8 tools)
  hook.ts          # PostToolUse + SessionEnd hook
  prompt-hook.ts   # UserPromptSubmit hook
  kilo-plugin.ts   # Kilo/OpenCode native plugin
  daemon.ts        # FSEvents file watcher (macOS, opt-in)
  cli.ts           # CLI
  eval/            # Offline trajectory replay evaluation
  testkit.ts       # Test harness; test.ts + tests/*.test.ts
scripts/visuals/   # JS generators for the README figures (tbcresearch.org ink style, light + dark)

开发

npm test                      # 147 tests
npx tsx src/test.ts "Ranking" # filter by suite/test name
npm run visuals               # regenerate assets/*.svg (light + dark) from scripts/visuals/scenes/*.mjs
bash scripts/visuals/social.sh  # render assets/social-preview.png for GitHub's social preview

要求：Node.js 22+，macOS 或 Linux。FSEvents 守护进程仅支持 macOS；其他所有内容均可跨平台运行。

如果 BrainBox 帮你的 Agent 少费了些搜索功夫，请给它一个 ⭐，让更多人发现它。
由 @thebasedcapital 构建 · MIT 许可证