BrainBox

BrainBox

Memória hebbiana para agentes de codificação com IA. Aprende quais arquivos você acessa em conjunto, quais erros levam a quais correções e quais cadeias de ferramentas você mais usa — e os recupera instantaneamente.

Não é um banco de dados vetorial. Não é RAG. É memória procedural.

Se o BrainBox economizou tokens para você, dê uma estrela — isso ajuda outras pessoas a encontrá-lo. Construído por @thebasedcapital

Session 1:  agent greps for auth.ts, reads it, edits it (2000 tokens)
Session 5:  agent recalls auth.ts directly, skips search (500 tokens saved)
Session 20: auth.ts is a superhighway — instant recall, zero search cost

Instalação

npm install brainbox-hebbian

É só isso. O script de pós-instalação automaticamente:

1. Adiciona o hook PostToolUse ao ~/.claude/settings.json (aprende com cada leitura/edição/busca de arquivo)
2. Adiciona o hook UserPromptSubmit (injeta recall neural nos prompts automaticamente)
3. Registra o servidor MCP via claude mcp add (6 ferramentas para recall/gravação manual)
4. Cria o diretório do banco de dados ~/.brainbox/

O BrainBox aprende passivamente na sua próxima sessão do Claude Code. Nenhuma configuração necessária.

O que NÃO acontece automaticamente

O daemon do macOS (observador de arquivos FSEvents em todo o sistema) é completamente separado e opcional:

# Only if you want BrainBox to learn from VS Code, Xcode, vim, shell, etc.
brainbox daemon install   # installs LaunchAgent, starts watching
brainbox daemon status    # check if running
brainbox daemon uninstall # remove completely

O daemon observa mudanças de arquivos em todos os seus editores — não apenas no Claude Code. Ele exige aceitação explícita porque registra um LaunchAgent e monitora seus diretórios de projeto configurados.

Desinstalação

brainbox uninstall  # removes hooks + MCP server, preserves database

Semear a partir do histórico do git (recomendado)

Elimine o início frio inicializando a partir do seu histórico git existente:

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

Isso semeia a rede neural a partir de co-mudanças de commits git e grafos de importação, para que o BrainBox comece com conhecimento em vez de do zero.

Como Funciona

O BrainBox implementa aprendizado inspirado em neurociência:

• Neurônios — arquivos, ferramentas e erros com os quais você interage
• Sinapses — conexões formadas quando coisas são acessadas juntas ("neurônios que disparam juntos se conectam")
• Mielinização — caminhos usados com frequência ficam mais rápidos (como memória muscular)
• Ativação por propagação — recuperar um arquivo ativa arquivos relacionados
• Decaimento — conexões não utilizadas enfraquecem naturalmente, mantendo a rede limpa

Aprendizado Hebbiano em Ação (clique para reproduzir)

https://github.com/thebasedcapital/brainbox/raw/main/assets/brainbox-animation.mp4

Ativação por Propagação — recuperar um arquivo ativa arquivos relacionados através de conexões sinápticas

https://github.com/thebasedcapital/brainbox/raw/main/assets/brainbox-spreading.mp4

Formação de Superestradas — caminhos usados com frequência se tornam superestradas de recall instantâneo

https://github.com/thebasedcapital/brainbox/raw/main/assets/brainbox-superhighway.mp4

Sistema Imunológico de Correção de Erros — lembra quais arquivos corrigiram quais erros

https://github.com/thebasedcapital/brainbox/raw/main/assets/brainbox-immune.mp4

Outras Integrações

Servidor MCP (qualquer agente)

Se você não está usando o Claude Code, pode executar o servidor MCP de forma independente:

# 6 tools: record, recall, error, predict_next, stats, decay
npx tsx node_modules/brainbox-hebbian/src/mcp.ts

Kilo / OpenCode (plugin nativo)

Adicione ao ~/.config/kilo/config.json:

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

OpenClaw (NeuroVault)

O BrainBox pode ser implantado como um plugin de slot de memória do OpenClaw. Veja NeuroVault para a implementação de referência.

Aspecto	Claude Code	OpenClaw
Nomes das ferramentas	PascalCase (Read)	minúsculas (read)
Injeção de contexto	hook UserPromptSubmit	ciclo de vida before_agent_start
Gatilho de aprendizado	hook PostToolUse	ciclo de vida after_tool_call
Embeddings	all-MiniLM-L6-v2	Somente palavras-chave (limiar de confiança mais baixo)

CLI

brainbox recall "authentication login"
brainbox record src/auth.ts --context "authentication"
brainbox stats
brainbox error "TypeError: cannot read 'token'"
brainbox predict Read
brainbox embed          # add vector embeddings for semantic recall
brainbox hubs           # most connected neurons
brainbox stale          # decaying superhighways
brainbox projects       # list project tags
brainbox sessions       # recent sessions with intents
brainbox streaks        # anti-recall ignore streaks
brainbox graph          # ASCII neural network
brainbox highways       # show superhighways
brainbox decay          # weaken unused connections

Principais Recursos

Aprendizado Hebbiano

Arquivos acessados juntos formam sinapses. Acesse auth.ts e depois session.ts 10 vezes e o BrainBox aprende que eles estão relacionados — recuperar um ativa o outro.

Sistema Imunológico de Correção de Erros

Quando você corrige um bug, o BrainBox lembra quais arquivos corrigiram quais erros. Na próxima vez que um erro semelhante aparecer, ele sugere os arquivos de correção imediatamente.

Predição de Sequência de Ferramentas

Após 20 cadeias Grep-Read-Edit, o BrainBox prevê que você fará Read após Grep e pré-carrega os arquivos prováveis.

Plasticidade SNAP

Sinapses fortes resistem a fortalecimento adicional (como sinapses neurais reais). Impede que qualquer conexão única domine a rede.

Escalonamento Anti-Recall

Arquivos recuperados mas nunca abertos recebem decaimento progressivamente mais forte. Ignorâncias consecutivas escalam: 1ª = 10%, 2ª = 19%, 3ª = 27%. Abrir o arquivo redefine a sequência.

Detecção de Hubs e Alertas de Obsolescência

Identifique os neurônios mais conectados na sua rede e detecte superestradas em decaimento antes que desapareçam.

Marcação de Projetos

Marque automaticamente neurônios de arquivos por projeto. Recall limitado ao projeto atual reduz ruído entre projetos.

Arquitetura

src/
  hebbian.ts     # Core engine: record, recall, decay, SNAP, BCM, spreading activation
  db.ts          # SQLite schema: neurons, synapses, access_log, sessions
  embeddings.ts  # Optional vector embeddings (all-MiniLM-L6-v2, 384 dims)
  installer.ts   # Auto-installer: adds hooks + MCP to ~/.claude/settings.json
  mcp.ts         # MCP server (6 tools)
  hook.ts        # Claude Code PostToolUse hook
  prompt-hook.ts # Claude Code UserPromptSubmit hook
  kilo-plugin.ts # Kilo/OpenCode native plugin
  bootstrap.ts   # Git/vault/import seeder
  daemon.ts      # FSEvents file watcher (macOS, opt-in)
  cli.ts         # CLI interface
  test.ts        # 59 tests, all passing

Detalhes do Algoritmo

Componente	Mecanismo
Formação de sinapses	Janela sequencial (25 itens), decaimento posicional
Fortalecimento	Plasticidade sigmoide SNAP (ponto médio 0,5, inclinação 8)
Mielinização	Limiar deslizante BCM + retornos decrescentes, teto de 0,95
Confiança	Multiplicativa: contextScore * (1 + myelin + recency + path)
Propagação	BFS de 2 saltos, limite de fan-out 10, efeito de leque 1/sqrt(grau)
Decaimento	Ativação -15%, sinapses -2%, mielinização -0,5% por ciclo
Aprendizado de erros	Taxa de aprendizado 2x aumentada para neurônios de erro
Anti-recall	Decaimento composto: 1 - (1 - 0.1)^streak, piso em 0,1

Detalhes completos em WHITEPAPER.md.

Testes

npm test  # 59 tests, ~2s

Requisitos

• Node.js 18+
• macOS ou Linux (o daemon FSEvents é exclusivo do macOS, todo o resto é multiplataforma)

Licença

MIT