brainbox

インストール · 仕組み · 成果 · 研究 · 連携 · ホワイトペーパー

BrainBox はAI コーディングエージェントのための手続き記憶です。エージェントが実際に行う操作を監視して記憶します。

• どのファイルが一緒に読み込まれ、編集されるか
• どの編集によってどのエラーが修正されたか
• エージェントが繰り返すツールの組み合わせ

次のタスクでは、エージェントが検索を始める前に、適切なファイルを提示します。

ベクトルデータベースではありません。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：コーディングエージェントのためのローカル行動記憶（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

これで完了です。postinstall スクリプトは次の処理を行います。

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）、それ以前に何を開いたかよりも、次に何を開くかが重要です。

活性の伝播

1つのファイルを想起すると、最大3ホップ先まで近隣のファイルが活性化されます。各ホップは 1/√degree で減衰するため、ハブとなるファイルが結果を埋め尽くすことはありません。各結果には、それを生成したチャネルとエッジが付随します。brainbox_explain を使うと、ファイルが想起された理由を正確に確認できます。

主要経路と減衰

よく使う経路は髄鞘化され、即座に想起できる超高速道路になります。新しさと頻度は ACT-R の基準レベル方程式 B = ln Σ tⱼ^-0.5 に従い、使われないつながりは弱まります。想起されたものの無視されたファイルは、そのファイルを表面化させたエッジのみが弱まります。

エラー → 修正の免疫システム

失敗したコマンドの後に編集が行われ、再実行が成功すると、BrainBox はエラーから修正に至る手順を保存します。この手順はエラーのフィンガープリントをキーとし、有益または有害だった結果を追跡します。同じエラーが次に発生すると、修正に使われたファイルがすぐに想起されます。手順は指示ではなく、引用された観察事項としてエージェントに提示されます。

結果

brainbox eval は、実際のコーディングエージェントの軌跡を時間順に再生します。各タスクは、同じリポジトリ内のそれより前のタスクのみで学習した新しいインメモリ DB で評価され、すべてのシステムが同じ候補セットを順位付けします。

v0.1 は次のファイルの予測で、単純な新しさベースの方式に負けました。 ホールドアウトされた SWE タスクでは差は −.207、95% 信頼区間は −.312…−.118 でした。v0.2 はこの指標で新しさベースの方式と統計的に同等です。次のツールの予測では、すべてのベースラインを有意に上回り、読み込んだファイルの再現率は両方のデータソースで最高です。

既知の課題： ローカルセッションでは、編集頻度のみで順位付けすると、編集されたファイルについては依然として BrainBox を上回ります（Δ −.089、信頼区間 −.185…0）。

語彙チャネルとヘブ則チャネルの重みをゼロに調整すると dev で高いスコアになりましたが、その場合、再現率はクエリを無視してしまうため、リリース版ではこれらの重みを維持しています。

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のネストされた設定形式で記述されています。
• フックのDBロック待機時間は最大100 msです。
• 手順のコンパイルは、大規模な履歴で470倍高速です。

インテグレーション

MCP サーバー（任意のエージェント）

# 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、シェルからも学習します。LaunchAgentをインストールするため、明示的なオプトインが必要です。

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

CLI

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

要件：macOS または Linux 上の Node.js 22 以降。FSEvents デーモンは macOS 専用ですが、それ以外はすべてクロスプラットフォームです。

BrainBox がエージェントの検索の手間を省いたなら、他の人にも見つけてもらえるよう⭐ を付けてください。
@thebasedcapital が開発 · MIT License