BrainBox

BrainBox

Memoria Hebbiana para agentes de codificación con IA. Aprende qué archivos accedes juntos, qué errores conducen a qué correcciones y qué cadenas de herramientas usas más — y luego las recuerda al instante.

No es una base de datos vectorial. No es RAG. Es memoria procedimental.

Si BrainBox te ahorró tokens, dale una estrella — ayuda a que otros lo encuentren. Construido 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

Instalación

npm install brainbox-hebbian

Eso es todo. El script de postinstalación automáticamente:

1. Agrega el hook PostToolUse a ~/.claude/settings.json (aprende de cada lectura/edición/búsqueda de archivos)
2. Agrega el hook UserPromptSubmit (inyecta recuerdo neuronal en los prompts automáticamente)
3. Registra el servidor MCP vía claude mcp add (6 herramientas para recuerdo/grabación manual)
4. Crea el directorio de base de datos ~/.brainbox/

BrainBox aprende pasivamente de tu próxima sesión de Claude Code. No se necesita configuración.

Qué NO sucede automáticamente

El daemon de macOS (observador de archivos FSEvents a nivel de sistema) es completamente separado y 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

El daemon observa cambios de archivos en todos tus editores — no solo Claude Code. Requiere aceptación explícita porque registra un LaunchAgent y monitorea tus directorios de proyecto configurados.

Desinstalación

brainbox uninstall  # removes hooks + MCP server, preserves database

Sembrar desde historial de git (recomendado)

Elimina el arranque en frío iniciando desde tu historial de git existente:

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

Esto siembra la red neuronal desde co-cambios de commits de git y grafos de importación, para que BrainBox comience con conocimiento en lugar de desde cero.

Cómo Funciona

BrainBox implementa aprendizaje inspirado en neurociencia:

• Neuronas — archivos, herramientas y errores con los que interactúas
• Sinapsis — conexiones formadas cuando las cosas se acceden juntas ("las neuronas que se disparan juntas, se conectan juntas")
• Mielinización — las rutas de uso frecuente se vuelven más rápidas (como memoria muscular)
• Activación propagada — recordar un archivo activa archivos relacionados
• Decaimiento — las conexiones no utilizadas se debilitan naturalmente, manteniendo la red limpia

Aprendizaje Hebbiano en Acción (clic para reproducir)

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

Activación Propagada — recordar un archivo activa archivos relacionados a través de conexiones sinápticas

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

Formación de Autopistas — las rutas de uso frecuente se convierten en autopistas de recuerdo instantáneo

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

Sistema Inmune de Corrección de Errores — recuerda qué archivos corrigieron qué errores

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

Otras Integraciones

Servidor MCP (cualquier agente)

Si no estás usando Claude Code, puedes ejecutar el servidor MCP de forma independiente:

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

Kilo / OpenCode (plugin nativo)

Agrega a ~/.config/kilo/config.json:

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

OpenClaw (NeuroVault)

BrainBox puede desplegarse como un plugin de ranura de memoria de OpenClaw. Consulta NeuroVault para la implementación de referencia.

Aspecto	Claude Code	OpenClaw
Nombres de herramientas	PascalCase (Read)	Minúsculas (read)
Inyección de contexto	hook UserPromptSubmit	ciclo de vida before_agent_start
Disparador de aprendizaje	hook PostToolUse	ciclo de vida after_tool_call
Embeddings	all-MiniLM-L6-v2	Solo palabras clave (umbral de confianza más bajo)

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

Características Clave

Aprendizaje Hebbiano

Los archivos accedidos juntos forman sinapsis. Accede a auth.ts y luego a session.ts 10 veces y BrainBox aprende que están relacionados — recordar uno activa el otro.

Sistema Inmune de Corrección de Errores

Cuando corriges un error, BrainBox recuerda qué archivos corrigieron qué errores. La próxima vez que aparezca un error similar, sugiere los archivos de corrección inmediatamente.

Predicción de Secuencia de Herramientas

Después de 20 cadenas Grep-Read-Edit, BrainBox predice que harás Read después de Grep y precarga los archivos probables.

Plasticidad SNAP

Las sinapsis fuertes resisten un fortalecimiento adicional (como las sinapsis neuronales reales). Evita que una sola conexión domine la red.

Escalada Anti-Recuerdo

Los archivos recordados pero nunca abiertos reciben un decaimiento progresivamente más fuerte. Los ignorados consecutivos escalan: 1º = 10%, 2º = 19%, 3º = 27%. Abrir el archivo reinicia la racha.

Detección de Hubs y Alertas de Obsolescencia

Identifica las neuronas más conectadas en tu red y detecta autopistas en decaimiento antes de que se desvanezcan.

Etiquetado de Proyectos

Etiqueta automáticamente las neuronas de archivos por proyecto. El recuerdo limitado al proyecto actual reduce el ruido entre proyectos.

Arquitectura

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

Detalles del Algoritmo

Componente	Mecanismo
Formación de sinapsis	Ventana secuencial (25 elementos), decaimiento posicional
Fortalecimiento	Plasticidad sigmoide SNAP (punto medio 0.5, pendiente 8)
Mielinización	Umbral deslizante BCM + rendimientos decrecientes, tope 0.95
Confianza	Multiplicativa: contextScore * (1 + myelin + recency + path)
Propagación	BFS de 2 saltos, límite de expansión 10, efecto de abanico 1/sqrt(grado)
Decaimiento	Activación -15%, sinapsis -2%, mielinización -0.5% por ciclo
Aprendizaje de errores	Tasa de aprendizaje 2x potenciada para neuronas de error
Anti-recuerdo	Decaimiento compuesto: 1 - (1 - 0.1)^streak, piso en 0.1

Detalles completos en WHITEPAPER.md.

Pruebas

npm test  # 59 tests, ~2s

Requisitos

• Node.js 18+
• macOS o Linux (el daemon FSEvents es solo para macOS, todo lo demás es multiplataforma)

Licencia

MIT