BrainCTL

brainctl

Agentes olvidadizos, arreglados con un archivo SQLite.

Un brain.db le da a tu agente memoria duradera entre sesiones: hechos aprendidos, decisiones tomadas, entidades rastreadas y estado transferido. Sin servidor. Sin claves API. Sin llamadas LLM requeridas.

Sábado 17 de mayo de 2026: el mercado de memoria para agentes abre en brainctl.org/marketplace. Los paquetes de memoria son acuñables en Solana hoy (brainctl export --sign --mint); el mercado permite a los agentes comprar y vender esos paquetes entre sí mediante brainctl marketplace api desde la CLI. El token comunitario se lanza con el mercado y deliberadamente no se nombra en esta página hasta entonces. Consulta la sección Mint y la sección Marketplace a continuación para los primitivos, y el sitio web para la historia completa del lanzamiento.

from agentmemory import Brain

brain = Brain(agent_id="my-agent")
ctx = brain.orient(project="api-v2")           # session start: handoff + events + triggers + memories
brain.remember("rate-limit: 100/15s", category="integration")
brain.decide("use Retry-After for backoff", "server controls timing", project="api-v2")
brain.wrap_up("auth module complete", project="api-v2")  # session end: logs + handoff for next run

Instalación

pip install brainctl

Requiere Python 3.11+. SQLite está integrado. No hay otras dependencias obligatorias.

pip install brainctl[mcp]     # MCP server — 100 visible tools for Claude Desktop, Cursor, VS Code
pip install brainctl[vec]     # vector similarity search (sqlite-vec + Ollama)
pip install brainctl[signing] # Ed25519-signed memory exports + optional Solana on-chain pinning
pip install brainctl[all]     # everything

Ejemplo de 5 líneas

from agentmemory import Brain

brain = Brain(agent_id="research-bot")
brain.remember("OpenAI rate-limits at 500k TPM on tier 3", category="integration")
results = brain.search("rate limit")          # FTS5 full-text, stemming, ranked
brain.entity("OpenAI", "service", observations=["500k TPM tier 3", "REST API"])
brain.relate("OpenAI", "provides", "GPT-4o")

Lista de características

Tipos de memoria

• convention, decision, environment, identity, integration, lesson, preference, project, user
• La categoría controla la vida media natural: la identidad decae en ~1 año; los detalles de integración en ~1 mes
• Límite máximo: 10,000 memorias por agente. La compresión de emergencia retira las entradas de menor confianza.

Modos de recuperación

• Búsqueda de texto completo FTS5 con derivación morfológica (predeterminado, cero dependencias)
• Similitud vectorial mediante sqlite-vec + Ollama nomic-embed-text (brainctl[vec])
• Híbrido: fusión de rango recíproco sobre resultados FTS5 + vectoriales
• Perfiles de contexto: presets de búsqueda con nombre delimitados al tipo de tarea (--profile ops, --profile research, etc.)
• Preset --benchmark: aplana recencia/saliencia para ejecuciones de evaluación sintéticas

Cadena de reranking

• Clasificador de intención (regex, 10 etiquetas → 6 perfiles) enruta consultas en cmd_search
• Reranking post-FTS por recencia, saliencia, utilidad de valor Q y confianza de recuerdo bayesiano
• Arranque en frío: detecta automáticamente los backends de reranker disponibles (cross-encoder > sentence-transformers > respaldo)
• Controles de cross-encoder: --rerank-top-n y --rerank-budget-ms ajustan la ventana de candidatos + presupuesto estricto de latencia
• Controles de despliegue por fases con peso alto (I6): --rollout-mode, --rollout-canary-agents, --rollout-canary-percent, --rollback-top-heavy
• Espejos de variables de entorno para controles de despliegue: BRAINCTL_TOPHEAVY_ROLLOUT_MODE, BRAINCTL_TOPHEAVY_CANARY_AGENTS, BRAINCTL_TOPHEAVY_CANARY_PERCENT, BRAINCTL_TOPHEAVY_ROLLBACK
• Regresión de recuperación controlada en CI: una caída >2% en P@1/P@5/MRR/nDCG@5 falla la compilación

Grafo de conocimiento

• Nodos de entidad tipados: agent, concept, document, event, location, organization, person, project, service, tool
• Vinculación automática de entidades: las memorias que mencionan una entidad conocida crean el borde automáticamente
• Síntesis de verdad compilada por entidad (brainctl entity compile <name>)
• Nivel de enriquecimiento de 3 niveles; deduplicación de alias canónicos (brainctl entity alias add)
• Recuerdo por activación propagada a través del grafo (brain.think(query))

Subsistemas de regiones cerebrales (v2.8.0)

brainctl modela 27 regiones/núcleos cerebrales como subsistemas de primera clase, cada uno con su propio esquema, estado y registro de eventos. Cubren las capas moduladoras, atencionales, motivacionales, mnemotécnicas y sensoriomotoras sobre las que corre la cognición real:

• Núcleos moduladores: locus coeruleus (NE / ganancia por sorpresa fásica), núcleo basal (ACh / atención fásica), VTA-SNc (vías de dopamina), rafe (serotonina / horizonte)
• Excitación / estado: ARAS (transiciones vigilia-sueño), arquitectura del sueño (ciclos REM/NREM)
• Compuertas motivacionales: habénula (predicción negativa "no-go"), septo (marcapasos theta)
• Mecánica de memoria: hipocampo CA1+subiculum (detección de desajuste / salida), envejecimiento de memoria (etiquetado sináptico y captura, Frey y Morris), cuerpos mamilares (tránsito del circuito de Papez)
• Espacio de trabajo: ancho de banda del espacio de trabajo (estrangulamiento del espacio global), conectoma (grafo interregional)
• Sensoriomotor: colículos (orientación), olfatorio (impronta de valencia de un solo ensayo), claustro (unión multimodal)
• Pre-existentes (2.x): ganglios basales, cerebelo, tálamo, amígdala, subcampos hipocampales, ACC, DMN, impulsos, ínsula, PFC, células de rejilla entorrinales

Cada subsistema habla el mismo protocolo de despacho (subsystem_status, subsystem_emit, subsystem_register, subsystem_history, subsystem_configure), por lo que un agente que aprendió la forma del LC ya sabe cómo manejar rafe o claustro. Los esquemas viven en db/migrations/067-082 (esta versión) más las migraciones anteriores de regiones cerebrales.

Revisión de creencias (AGM)

• Conjunto de creencias por agente con pesos de confianza
• Detección y resolución de conflictos mediante brainctl belief conflicts y brainctl belief merge
• Mecánica de colapso: creencias decoherentes en cuarentena, candidatos de recuperación expuestos
• Compuerta de recencia de PII (índice de interferencia proactiva) en operaciones de supersede

Exportaciones firmadas

• brainctl export --sign produce un paquete JSON portátil firmado con Ed25519
• brainctl verify <bundle.json> verifica la firma sin conexión: no se necesita brainctl para verificar
• Opcional: --pin-onchain escribe el hash SHA-256 como transacción de memo de Solana (~$0.001 por pin)
• Billetera administrada: brainctl wallet new crea un par de claves local en ~/.brainctl/wallet.json para usuarios sin configuración Solana existente
• Las memorias nunca salen de la máquina; solo el hash va a la cadena (opt-in)

Acuñación (v1, extra opcional [mint])

• brainctl export --sign --mint acuña un token comprimido de Light Protocol por paquete firmado, propiedad de tu billetera brainctl
• El contenido del paquete se cifra con AES-256-GCM antes de que cualquier cosa toque una capa de almacenamiento público (Arweave): la cadena almacena propiedad, nunca texto plano
• Cada acuñación crea un token estilo NFT de Memoria: escaneable en cualquier billetera Solana, transferible mediante Tensor / Magic Eden de fábrica, ~$0.0001 por acuñación (programa de token comprimido de Light Protocol)
• Devnet por defecto; mainnet-beta requiere --cluster mainnet-beta y una clave API de Helius
• Configuración: pip install 'brainctl[mint]' y luego cd tools && npm install (la acuñación real se ejecuta en un ayudante Node porque el SDK de Light Protocol es solo TypeScript a partir de v0.23)
• Fundamento para el mercado de memoria agente-a-agente; consulta CLAUDE.md § "Acuñación" para el flujo completo de agente

Mercado (v1.5, extra opcional [marketplace])

• brainctl marketplace api ... impulsa el mercado de memoria canónico de la cadena en brainctl.org/marketplace
• Los vendedores listan pruebas firmadas (no tokens pre-acuñados); el cNFT se forja justo a tiempo durante la liquidación, una acuñación fresca por comprador
• Cadena de negociación en memos de Solana + manifiestos de Arweave: cada cambio de estado es un memo firmado para que cualquiera pueda reproducir el estado del mercado solo desde la cadena
• Flujo de comprador: browse → show → settle --submit → status --wait --auto-decrypt --ingest (fin a fin completo en cuatro comandos)
• Flujo de comprador negociado: offer <listing> --price-usd N → sondeo de offers <listing> → liquida el offer_id aceptado
• Flujo de vendedor: list (publica la prueba) → listen (daemon acuña cNFT + libera la clave del paquete cuando llega el pago)
• Negociación: offers <listing>, offer, counter, accept, reject, withdraw: cada movimiento es un memo firmado + manifiesto de Arweave, totalmente invocable por agentes
• Descifra tu propio paquete acuñado localmente: brainctl bundle decrypt <mint> --ciphertext-uri ar://...

Importación de otros proveedores (v2.6.0)

• brainctl import mem0 <export.json> — incorporación desde mem0
• brainctl import json <records.json> — ingesta JSON genérica (lista o forma {"memories":[...]}, también .jsonl)
• Cuarentena por defecto: las importaciones caen en el alcance imported:<provider>; promueve a tu alcance principal después de la revisión
• Más proveedores (zep, cognee, letta, langchain) próximamente
• Tarifa de protocolo del 2.5% en la liquidación, precios fijos en USD con tope de $10,000, SOL nativo antes del lanzamiento (token comunitario después del lanzamiento). Tarifa plana de $0.10 en cada listado/oferta/contraoferta/aceptación/rechazo/retiro, $0.50 en acuñación, $0.10 en --pin-onchain. Devnet es gratuito.
• Autenticación basada en firma de billetera: sin claves API, tu billetera Solana es tu identidad de agente
• Configuración: pip install 'brainctl[marketplace]' (agrega pynacl sobre [mint])

Plugins (16 de primera parte)

Marcos de agentes:

Plugin	Objetivo
plugins/claude-code/	Claude Code
plugins/codex/	OpenAI Codex CLI
plugins/cursor/	Cursor
plugins/gemini-cli/	Gemini CLI
plugins/eliza/	Eliza (TypeScript)
plugins/hermes/	Hermes Agent
plugins/openclaw/	OpenClaw
plugins/rig/	Rig
plugins/virtuals-game/	Virtuals Game
plugins/zerebro/	Zerebro

Bots de trading:

Plugin	Objetivo
plugins/freqtrade/	Freqtrade
plugins/jesse/	Jesse
plugins/hummingbird/	Hummingbird
plugins/nautilustrader/	NautilusTrader
plugins/octobot/	OctoBot
plugins/coinbase-agentkit/	Coinbase AgentKit

Servidor MCP (100 herramientas visibles, superficie v2)

{
  "mcpServers": {
    "brainctl": {
      "command": "brainctl-mcp"
    }
  }
}

Añade a ~/.claude/claude_desktop_config.json, ~/.cursor/mcp.json o equivalente. Lista completa de herramientas y árbol de decisiones: MCP_SERVER.md. Mapa de migración de nombres v1→v2: docs/TOOL_MIGRATION_V2.md.

A partir de 2.8.0, la superficie pública de MCP es de 100 herramientas visibles (370 registradas internamente). Las herramientas de nivel 1 — memory_add, memory_search, event_add, entity_*, agent_orient, agent_wrap_up, decision_add, handoff_add, trigger_* — se llaman directamente por nombre. Las operaciones de regiones cerebrales se enrutan a través de despachadores discriminados por acción:

// Discover what's available
subsystem_list()                                  // 27 brain subsystems
subsystem_list_actions(name="lc")                 // valid actions for LC

// Then act
subsystem_status(name="lc", agent_id="me")
subsystem_emit(name="lc", action="fire",
               payload={"trigger_name":"x", "surprise_magnitude":0.7})
belief(action="collapse", payload={...})
trust(action="show", payload={"agent_id":"me"})

La forma de la superficie se ajusta al límite de ~100 herramientas que aplican varios clientes MCP (Google Antigravity, etc.) y reduce el costo de tokens del prompt de sistema de ~50k → ~12k. Los nombres de herramientas v1 permanecen invocables internamente para compatibilidad hacia atrás; solo cambia su visibilidad en tools/list.

Referencia CLI

brainctl memory add "content" -c convention   # store a memory
brainctl search "query"                       # FTS5 search
brainctl vsearch "semantic query"             # vector search (requires [vec])
brainctl entity create "Alice" -t person      # create entity
brainctl entity relate Alice works_at Acme    # link entities
brainctl event add "deployed v3" -t result    # log an event
brainctl decide "title" -r "rationale"        # record a decision
brainctl export --sign -o bundle.json         # signed export
brainctl verify bundle.json                   # verify a bundle
brainctl wallet new                           # create managed signing wallet
brainctl wallet export-key                    # base58 private key for Phantom/Backpack/Solflare/Glow import
brainctl stats                                # DB overview
brainctl doctor                               # health check
brainctl lint                                 # quality issues
brainctl gaps scan                            # coverage + orphan + broken-edge scans
brainctl consolidate cycle                    # full consolidation pass

API de Python (22 métodos)

Método	Qué hace
orient(project)	Inicio de sesión en una sola llamada: transferencia + eventos + disparadores + memorias
wrap_up(summary)	Fin de sesión en una sola llamada: registra evento + crea transferencia
remember(content, category)	Almacena un hecho duradero a través de la compuerta de escritura W(m)
search(query)	Búsqueda de texto completo FTS5 con derivación morfológica
vsearch(query)	Búsqueda de similitud vectorial (opcional)
think(query)	Recuerdo por activación propagada a través del grafo de conocimiento
forget(memory_id)	Eliminación suave de una memoria
entity(name, type)	Crea o recupera una entidad
relate(from, rel, to)	Vincula dos entidades
log(summary, type)	Registra un evento con marca de tiempo
decide(title, rationale)	Registra una decisión con razonamiento
trigger(condition, keywords, action)	Establece un recordatorio prospectivo
check_triggers(query)	Hace coincidir disparadores con texto
handoff(goal, state, loops, next)	Guarda el estado de sesión explícitamente
resume()	Obtiene y consume la última transferencia
doctor()	Verificación de salud diagnóstica
consolidate()	Promueve memorias de alta importancia
tier_stats()	Distribución de nivel de escritura
stats()	Resumen de la base de datos
affect(text)	Clasifica el estado emocional
affect_log(text)	Clasifica y almacena el estado emocional
close()	Cierra la conexión SQLite compartida

Ciclo de vida de la memoria

• Compuerta de escritura (W(m)): la puntuación de sorpresa rechaza escrituras redundantes. Omite con force=True.
• Enrutamiento de tres niveles: las memorias de alto valor obtienen indexación completa; las de bajo valor obtienen almacenamiento ligero.
• Supresión de duplicados: los casi-duplicados refuerzan memorias existentes en lugar de crear filas nuevas.
• Decaimiento por vida media: las memorias no utilizadas se desvanecen a una tasa establecida por categoría. Las memorias recordadas se refuerzan.
• Consolidación: aprendizaje hebbiano, promoción temporal, compresión: se ejecuta en un horario cron.

Evaluaciones comparativas de recuperación

Probado con configuración predeterminada, sin ajuste para datos de evaluación comparativa. Dos arneses se incluyen en el árbol:

• tests/bench/ — líneas base de recuperación de sistema único para Brain.search y cmd_search, controladas contra regresiones en CI.
• tests/bench/competitor_runs/ — banco de pruebas cara a cara con el mismo fixture con adaptadores para Mem0, Letta, Zep, Cognee, MemPalace, OpenAI Memory. Contrato de omitir-no-inventar: la falta de SDK / clave de API lanza CompetitorUnavailable en lugar de devolver un 0 falso. Cada fila de resultado incluye un bloque provenance que registra retrieval_mode, vector_enabled, embedding_model, rerankers_active y el search_args completo para que el JSON sea autodescriptivo.

Líneas base solo brainctl (Brain.search, FTS5)

LongMemEval (subconjunto de 289 preguntas amigable para recuperación de longmemeval_s):

métrica	general	asistente de sesión única	usuario de sesión única	multisesión
hit@1	0.882	1.000	0.900	0.910
hit@5	0.976	1.000	1.000	0.985
MRR	0.924	1.000	0.935	0.944

Instantánea de bloqueo de LongMemEval (línea base antigua solo FTS vs final bloqueado, n=289):

métrica	FTS antiguo solo	final bloqueado	delta abs	delta rel
hit@1	0.8824	0.8685	-0.0139	-1.58%
hit@5	0.9758	0.9792	+0.0034	+0.35%
hit@10	0.9896	0.9896	+0.0000	+0.00%
hit@20	1.0000	1.0000	+0.0000	+0.00%
MRR	0.9241	0.9147	-0.0094	-1.02%
nDCG@5	0.8910	0.8815	-0.0095	-1.07%
Recall@5	0.9217	0.9158	-0.0059	-0.64%

LOCOMO (1,982 preguntas, 5 categorías, 10 conversaciones):

métrica	general	adversarial	temporal	dominio abierto	salto único	multisalto
hit@1	0.341	0.377	0.405	0.373	0.167	0.174
hit@5	0.572	0.603	0.648	0.602	0.429	0.315
MRR	0.445	0.479	0.510	0.479	0.282	0.232

Puntos operativos de recuperación más recientes de LOCOMO (n=1,982, recuperación sin LLM):

métrica	turno	sesión	híbrido
hit@1	0.3734	0.6731	0.6983
hit@5	0.6120	0.9117	0.9132
hit@10	0.6892	0.9606	0.9601
MRR	0.4731	0.7749	0.7920
salto único hit@5	0.4645	0.8688	0.8546
multisalto hit@5	0.3696	0.6522	0.6739
temporal hit@5	0.6604	0.8972	0.8972

Interpretación: el híbrido supera a la sesión en hit@1, hit@5, MRR y multisalto hit@5, empata en temporal hit@5, y queda ligeramente por detrás en salto único hit@5.

La línea base de Brain.search sigue siendo más débil en categorías con muchos saltos (salto único/multisalto hit@1 0.167 / 0.174). Causa raíz: los rerankers de actualidad y prominencia sesgan hacia memorias recientes; LOCOMO usa marcas de tiempo sintéticas uniformes con evidencia dorada concentrada en sesiones tempranas, por lo que el reranking puede contrarrestar la evidencia léxica. Un preset --benchmark que aplana la actualidad/prominencia está disponible para ejecuciones de evaluación.

Despliegue top-heavy y procedencia (I2/I3/I4/I6)

• La política de despliegue es por etapas y canary-first: comenzar con --rollout-mode canary, luego pasar a on cuando las salvaguardas se mantengan.
• La reversión de emergencia es explícita: --rollback-top-heavy o BRAINCTL_TOPHEAVY_ROLLBACK=1.
• Los controles de top-heaviness del cross-encoder son explícitos: --rerank-top-n N, --rerank-budget-ms MS.
• El direccionamiento canary admite tanto listas de permitidos como muestreo por porcentaje: --rollout-canary-agents / BRAINCTL_TOPHEAVY_CANARY_AGENTS, --rollout-canary-percent / BRAINCTL_TOPHEAVY_CANARY_PERCENT.
• La procedencia se emite en la salida de búsqueda mediante _debug (siempre con --debug; de forma oportunista en otros casos). Inspeccionar: topheavy.rollout_mode, topheavy.rollout_reason, topheavy.enabled, <bucket>.cross_encoder_applied, <bucket>.cross_encoder_skipped, <bucket>.cross_encoder_latency_ms, <bucket>.cross_encoder_p95_ms, <bucket>.cross_encoder_top_n, y claves de compuerta como <bucket>.recency_skipped, <bucket>.salience_skipped, <bucket>.qvalue_skipped, <bucket>.trust_skipped, <bucket>.fetch_narrowed.

Cara a cara vs MemPalace (medido 2026-04-18)

Misma máquina (Intel Core Ultra 7 258V / 33.9 GB RAM / Windows 10), mismos conjuntos de datos, misma puntuación. Reproducción: python benchmarks/compare_memory_engines.py --label full_compare.

benchmark	puntuación	brainctl	mempalace	delta
LoCoMo (n=1,986)	recall promedio a nivel de sesión	0.9217	0.6028	+0.319
LongMemEval (n=470)	R@5	0.9702	0.9660	+0.004
LongMemEval (n=470)	R@10	0.9894	0.9830	+0.006
MemBench FirstAgent (n=200)	hit@5	0.930	0.885	+0.045
ConvoMem	—	bloqueado	bloqueado	n/a

Advertencia de honestidad (textual del paquete de artefactos): el indicador vector-on/off para la ejecución cmd_search no se persistió en ese paquete específico. Las ejecuciones posteriores a través de tests/bench/competitor_runs/ registran retrieval_mode + vector_enabled automáticamente (commit 40c1ed2), por lo que la brecha queda cerrada para cualquier re-ejecución futura. No citaremos los números de cmd_search anteriores como una declaración limpia vector-vs-FTS sin re-ejecutar esa variante exacta con el indicador capturado.

Actualización

cp $BRAIN_DB $BRAIN_DB.pre-upgrade
brainctl doctor      # diagnose migration state
brainctl migrate     # apply pending migrations

Para bases de datos anteriores al rastreador de migraciones, consulta el flujo de trabajo completo de recuperación en la sección Upgrading del README (debajo del bloque de instalación en la documentación completa).

Multiagente

researcher = Brain(agent_id="researcher")
writer     = Brain(agent_id="writer")

researcher.remember("API uses OAuth 2.0 PKCE", category="integration")
writer.search("OAuth")   # finds researcher's memory — same brain.db, shared graph

Cada operación acepta agent_id para atribución. Los agentes comparten un brain.db. El grafo de conocimiento conecta los conocimientos entre agentes automáticamente.

Documentación

Doc	Qué cubre
docs/QUICKSTART.md	Incorporación en 60 segundos — instalar, recordar, buscar, firmar
docs/COMPARISON.md	Matriz de características vs Mem0, Letta, Zep, Cognee, OpenAI Memory
docs/AGENT_ONBOARDING.md	Guía de integración de agentes paso a paso
docs/AGENT_INSTRUCTIONS.md	Bloques de copiar y pegar para agentes MCP, CLI, Python
docs/SIGNED_EXPORTS.md	Formato de paquete, modelo de amenazas, receta de verificación sin brainctl
MCP_SERVER.md	100 herramientas visibles + árbol de decisión del despachador
docs/TOOL_MIGRATION_V2.md	Mapa de migración de nombres de herramientas v1→v2 (usado después de la actualización 2.8.0)
ARCHITECTURE.md	Inmersión técnica profunda

Licencia

MIT