BHGBrain: memoria persistente para agentes de IA

Todo agente de IA empieza cada sesión con amnesia. La decisión de arquitectura de ayer, el avance de depuración de la semana pasada, la convención de nombres que tu equipo acordó hace tres sprints: todo desaparece. O vuelves a explicarlo, o el agente se equivoca.

BHGBrain lo resuelve. Es un servidor MCP open source que da a tus agentes de IA una memoria persistente, consultable y compartida que se mantiene entre sesiones, herramientas y equipos.

Cómo funciona

BHGBrain se ubica entre tus agentes de IA y una capa de almacenamiento duradera. Cualquier cliente compatible con MCP —Claude Code, Codex, OpenClaw, Gemini— se conecta a BHGBrain y obtiene acceso a una base de conocimiento compartida.

AI Agents (Claude / Codex / OpenClaw / Gemini)
  → MCP transport (stdio or HTTP)
    → BHGBrain server
      → Qdrant (semantic vector search)
      → SQLite (metadata, fulltext index, audit log, archive)

Cuando un agente guarda una memoria, BHGBrain la procesa en un pipeline inteligente:

1. Normalización: la entrada se limpia y estandariza antes del hashing, lo que mejora la precisión de la deduplicación en contenido parafraseado o con otro formato
2. Deduplicación: se compara con las memorias existentes mediante hashing de contenido SHA-256 y similitud coseno (umbral: 0.92), con umbrales ajustados por nivel para controlar la precisión
3. Decisión: determina si se agrega conocimiento nuevo, se actualizan entradas existentes o se descartan duplicados
4. Asignación de retención: asigna la memoria al nivel de retención adecuado (T0–T3) según su tipo, su importancia y la preferencia indicada por quien la envía
5. Almacenamiento: genera los embeddings, indexa y persiste las memorias aceptadas con puntuaciones de importancia que influyen en el ranking de búsquedas futuras

Cuando un agente necesita contexto, BHGBrain se lo entrega mediante búsqueda híbrida con RRF, que combina similitud semántica (70 %) y coincidencia de texto completo (30 %) con Reciprocal Rank Fusion, con pesos configurables. Los agentes reciben las memorias relevantes, no toda la base de conocimiento.

Capacidades clave

• Retención por niveles (T0–T3): las memorias viven mientras importan. T0 (base) nunca caduca. T1 (institucional) dura un año. T2 (operativo) dura 90 días. T3 (efímero) dura 30 días. Cada nivel tiene presupuestos de capacidad configurables (T1: 100K, T2: 200K, T3: 200K entradas).
• TTL de ventana deslizante: cada acceso reinicia el reloj de caducidad. Una memoria que se sigue usando se mantiene viva automáticamente.
• Ascenso automático: las memorias consultadas 5 o más veces ascienden automáticamente al siguiente nivel de retención. El conocimiento de alto valor se selecciona solo para volverse permanente.
• Avisos previos a la caducidad: las memorias se marcan 7 días antes de caducar, lo que da tiempo a agentes y operadores para actuar antes de perder conocimiento.
• Archivar antes de eliminar: las memorias caducadas se escriben en una tabla de archivo antes de eliminarse. Nada se purga de forma permanente sin un registro recuperable.
• Búsqueda híbrida con RRF: Reciprocal Rank Fusion combina resultados semánticos (70 %) y de texto completo (30 %) en una única lista ordenada. Los pesos se configuran por consulta.
• Deduplicación semántica: la similitud coseno con umbral de 0.92 detecta casi duplicados. Las sumas de verificación SHA-256 detectan los exactos. La normalización del contenido se ejecuta antes del hashing para que las entradas parafraseadas se dedupliquen correctamente.
• Puntuación de importancia: cada memoria lleva una puntuación de importancia de 0 a 1 que influye directamente en el ranking de los resultados de búsqueda. Las memorias de mayor importancia aparecen primero.
• Categorías / espacios de políticas persistentes: las categorías de políticas con nombre (por ejemplo, architecture-decisions, coding-standards, security-policies) ofrecen espacios persistentes para el conocimiento institucional que siempre debe estar disponible, sin depender del TTL.
• Memoria compartida entre agentes: Claude Code aprende tus convenciones de API y Codex las recoge automáticamente en la siguiente sesión. Una memoria, todos los agentes, cero desviaciones.
• Clasificación de memorias: las memorias se tipifican automáticamente como episódicas (eventos), semánticas (hechos) o procedimentales (flujos de trabajo).
• Aislamiento por namespaces: separa proyectos, equipos o clientes sin contaminación cruzada. Namespaces globales para estándares transversales.
• Colecciones: agrupa memorias relacionadas dentro de los namespaces (por ejemplo, api-design, infrastructure, security).
• Inyección de contexto: un recurso MCP especial entrega un bloque de contexto con presupuesto al inicio de la sesión, para que los agentes empiecen con el conocimiento relevante sin indicaciones manuales.
• CLI completa: lista, busca, gestiona categorías, ejecuta la recolección de basura y crea copias de seguridad, todo desde la línea de comandos.

Preparado para la empresa de serie

BHGBrain no es un prototipo. Está diseñado para uso en producción desde el primer día.

Para quién es

• Equipos con flujos de trabajo multiagente: cuando Claude Code, Codex y OpenClaw necesitan compartir el mismo conocimiento del proyecto sin desviaciones.
• Departamentos de TI empresariales: organizaciones que necesitan pistas de auditoría, autenticación e infraestructura autoalojada para la memoria de IA.
• Consultores y agencias: el aislamiento por namespaces mantiene separado el conocimiento de cada cliente mientras se comparten los estándares internos entre proyectos.
• Desarrolladores independientes: cualquier persona cuyas necesidades de memoria de IA ya superaron un archivo MEMORY.md.

Empieza en 5 minutos

1. Inicia Qdrant

docker run -d --name qdrant -p 6333:6333 qdrant/qdrant

2. Instala BHGBrain

git clone https://github.com/Big-Hat-Group-Inc/BHGBrain.git
cd BHGBrain && npm install && npm run build

3. Configura tu API key y ejecútalo

export OPENAI_API_KEY=sk-...
node dist/index.js

4. Conecta tu agente

Agrega BHGBrain a la configuración de tu cliente MCP: Claude Desktop, OpenClaw o cualquier herramienta compatible con MCP. Tus agentes ya pueden usar remember y recall entre sesiones.

Para ver la configuración detallada, las opciones de configuración y el prompt de entrevista inicial (bootstrap), consulta la documentación completa en GitHub.

Documentación multilingüe

BHGBrain incluye documentación completa en cinco idiomas:

📦 GitHub: github.com/Big-Hat-Group-Inc/BHGBrain

📖 A fondo: BHGBrain: Dale a tus Agentes de IA una Memoria Compartida y Persistente