BrainCTL

brainctl

Agentes esquecidos, corrigidos por um arquivo SQLite.

Um brain.db dá ao seu agente memória durável entre sessões — fatos aprendidos, decisões tomadas, entidades rastreadas e estado transferido. Sem servidor. Sem chaves de API. Sem chamadas de LLM necessárias.

Sábado, 17 de maio de 2026 — o marketplace de memória para agentes abre em brainctl.org/marketplace. Pacotes de memória são cunháveis na Solana hoje (brainctl export --sign --mint); o marketplace permite que agentes comprem e vendam esses pacotes entre si via brainctl marketplace api pela CLI. O token da comunidade lança junto com o marketplace e é intencionalmente não nomeado nesta página até lá. Veja a seção Mint e a seção Marketplace abaixo para os primitivos, e o site para a história completa do lançamento.

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

Instalação

pip install brainctl

Requer Python 3.11+. SQLite é embutido. Nenhuma outra dependência obrigatória.

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

Exemplo em 5 linhas

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 verificação de recursos

Tipos de memória

• convention, decision, environment, identity, integration, lesson, preference, project, user
• A categoria controla a meia-vida natural: identidade decai em ~1 ano; detalhes de integração em ~1 mês
• Limite máximo: 10.000 memórias por agente. Compressão de emergência aposenta entradas de menor confiança.

Modos de recuperação

• Pesquisa de texto completo FTS5 com stemming (padrão, zero dependências)
• Similaridade vetorial via sqlite-vec + Ollama nomic-embed-text (brainctl[vec])
• Híbrido: Fusão de Rank Recíproco sobre resultados FTS5 + vetoriais
• Perfis de contexto: predefinições de busca nomeadas com escopo por tipo de tarefa (--profile ops, --profile research, etc.)
• Predefinição --benchmark: achata recência/saliência para execuções de avaliação sintética

Cadeia de reordenamento

• Classificador de intenção (regex, 10 rótulos → 6 perfis) roteia consultas em cmd_search
• Reordenamento pós-FTS por recência, saliência, utilidade Q-value e confiança de recall bayesiana
• Cold-start: detecta automaticamente backends de reordenamento disponíveis (cross-encoder > sentence-transformers > fallback)
• Controles de cross-encoder: --rerank-top-n e --rerank-budget-ms ajustam a janela de candidatos + orçamento estrito de latência
• Controles de rollout em estágios com peso no topo (I6): --rollout-mode, --rollout-canary-agents, --rollout-canary-percent, --rollback-top-heavy
• Espelhos de env para controles de rollout: BRAINCTL_TOPHEAVY_ROLLOUT_MODE, BRAINCTL_TOPHEAVY_CANARY_AGENTS, BRAINCTL_TOPHEAVY_CANARY_PERCENT, BRAINCTL_TOPHEAVY_ROLLBACK
• Regressão de recuperação com portão em CI: queda >2% em P@1/P@5/MRR/nDCG@5 falha o build

Grafo de conhecimento

• Nós de entidade tipados: agent, concept, document, event, location, organization, person, project, service, tool
• Vinculação automática de entidades: memórias mencionando uma entidade conhecida criam a aresta automaticamente
• Síntese de verdade compilada por entidade (brainctl entity compile <name>)
• Nível de enriquecimento em 3 camadas; deduplicação canônica de aliases (brainctl entity alias add)
• Recall por ativação propagada através do grafo (brain.think(query))

Subsistemas de regiões cerebrais (v2.8.0)

brainctl modela 27 regiões/núcleos cerebrais como subsistemas de primeira classe, cada um com seu próprio esquema, estado e log de eventos. Eles cobrem as camadas modulatória, atencional, motivacional, mnemônica e sensoriomotora nas quais a cognição real se apoia:

• Núcleos modulatórios: locus coeruleus (NE / ganho de surpresa fásico), nucleus basalis (ACh / atenção fásica), VTA-SNc (vias de dopamina), rafe (serotonina / horizonte)
• Excitação / estado: ARAS (transições vigília-sono), arquitetura do sono (ciclos REM/NREM)
• Portões motivacionais: habênula (predição negativa "no-go"), septo (marcação de ritmo theta)
• Mecânica de memória: hipocampo CA1+subículo (detecção de incompatibilidade / saída), envelhecimento de memória (marcação e captura sináptica, Frey & Morris), corpos mamilares (trânsito do circuito de Papez)
• Espaço de trabalho: largura de banda do espaço de trabalho (limitação do espaço global), conectoma (grafo inter-regiões)
• Sensoriomotor: colículos (orientação), olfativo (impressão de valência em tentativa única), claustro (ligação multimodal)
• Pré-existentes (2.x): gânglios da base, cerebelo, tálamo, amígdala, subcampos hipocampais, ACC, DMN, impulsos, ínsula, PFC, células de grade entorrinal

Todo subsistema fala o mesmo protocolo de despacho (subsystem_status, subsystem_emit, subsystem_register, subsystem_history, subsystem_configure), então um agente que aprendeu a forma para LC já sabe como dirigir rafe ou claustro. Esquemas vivem em db/migrations/067-082 (nesta versão) mais as migrações anteriores de regiões cerebrais.

Revisão de crenças (AGM)

• Conjunto de crenças por agente com pesos de confiança
• Detecção e resolução de conflitos via brainctl belief conflicts e brainctl belief merge
• Mecânica de colapso: crenças decoerentes em quarentena, candidatos a recuperação apresentados
• Portão de recência PII (Índice de Interferência Proativa) em operações de substituição

Exportações assinadas

• brainctl export --sign produz um pacote JSON portátil assinado com Ed25519
• brainctl verify <bundle.json> verifica a assinatura offline — nenhum brainctl necessário para verificação
• Opcional: --pin-onchain grava o hash SHA-256 como uma transação memo na Solana (~$0.001 por fixação)
• Carteira gerenciada: brainctl wallet new cria um par de chaves local em ~/.brainctl/wallet.json para usuários sem uma configuração Solana existente
• Memórias nunca saem da máquina; apenas o hash vai para a blockchain (opt-in)

Mint (v1, extra opcional [mint])

• brainctl export --sign --mint cunha um token comprimido do Light Protocol por pacote assinado, de propriedade da sua carteira brainctl
• O conteúdo do pacote é criptografado com AES-256-GCM antes de qualquer coisa tocar uma camada de armazenamento público (Arweave) — a blockchain armazena propriedade, nunca texto simples
• Cada mint cria um token estilo Memory NFT: escaneável em qualquer carteira Solana, transferível via Tensor / Magic Eden prontamente, ~$0.0001 por mint (programa de token comprimido do Light Protocol)
• Devnet por padrão; mainnet-beta requer --cluster mainnet-beta e uma chave de API Helius
• Configuração: pip install 'brainctl[mint]' e depois cd tools && npm install (o mint real roda em um helper Node porque o SDK do Light Protocol é somente TypeScript a partir da v0.23)
• Fundação para o marketplace de memória agente-a-agente; veja CLAUDE.md § "Mint" para o fluxo completo do agente

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

• brainctl marketplace api ... dirige o marketplace de memória canônico da blockchain em brainctl.org/marketplace
• Vendedores listam provas assinadas (não tokens pré-cunhados); o cNFT é forjado just-in-time na liquidação, um mint novo por comprador
• Cadeia de negociação em memos Solana + manifestos Arweave — cada mudança de estado é um memo assinado para que qualquer um possa reproduzir o estado do marketplace apenas pela blockchain
• Fluxo do comprador: browse → show → settle --submit → status --wait --auto-decrypt --ingest (ponta a ponta completo em quatro comandos)
• Fluxo do comprador com negociação: offer <listing> --price-usd N → consultar offers <listing> → liquidar o offer_id aceito
• Fluxo do vendedor: list (publica a prova) → listen (daemon cunha cNFT + libera a chave do pacote quando o pagamento chega)
• Negociação: offers <listing>, offer, counter, accept, reject, withdraw — cada movimento é um memo assinado + manifesto Arweave, totalmente chamável por agente
• Descriptografe seu próprio pacote cunhado localmente: brainctl bundle decrypt <mint> --ciphertext-uri ar://...

Importação de outros provedores (v2.6.0)

• brainctl import mem0 <export.json> — onboarding a partir do mem0
• brainctl import json <records.json> — ingestão JSON genérica (lista ou formato {"memories":[...]}, também .jsonl)
• Quarentena por padrão: importações caem no escopo imported:<provider>; promova para seu escopo primário após revisão
• Mais provedores (zep, cognee, letta, langchain) em breve
• Taxa de protocolo de 2,5% na liquidação, preços atrelados a USD com teto de $10.000, nativo em SOL pré-lançamento (token da comunidade pós-lançamento). Taxa fixa de $0,10 em cada listar/ofertar/contraofertar/aceitar/rejeitar/retirar, $0,50 no mint, $0,10 em --pin-onchain. Devnet é gratuito.
• Autenticação é baseada em assinatura de carteira — sem chaves de API, sua carteira Solana é a identidade do seu agente
• Configuração: pip install 'brainctl[marketplace]' (adiciona pynacl sobre [mint])

Plugins (16 de primeira parte)

Frameworks de agentes:

Plugin	Alvo
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	Alvo
plugins/freqtrade/	Freqtrade
plugins/jesse/	Jesse
plugins/hummingbird/	Hummingbird
plugins/nautilustrader/	NautilusTrader
plugins/octobot/	OctoBot
plugins/coinbase-agentkit/	Coinbase AgentKit

Servidor MCP (100 ferramentas visíveis, superfície v2)

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

Adicione ao ~/.claude/claude_desktop_config.json, ~/.cursor/mcp.json, ou equivalente. Lista completa de ferramentas e árvore de decisão: MCP_SERVER.md. Mapa de migração de nomes v1→v2: docs/TOOL_MIGRATION_V2.md.

A partir da 2.8.0, a superfície pública MCP é de 100 ferramentas visíveis (370 registradas internamente). Ferramentas de nível 1 — memory_add, memory_search, event_add, entity_*, agent_orient, agent_wrap_up, decision_add, handoff_add, trigger_* — são chamadas diretamente pelo nome. Operações de regiões cerebrais roteiam através de despachadores discriminados por ação:

// 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"})

A forma da superfície se encaixa no limite de ~100 ferramentas que vários clientes MCP impõem (Google Antigravity, etc.) e reduz o custo de tokens do prompt de sistema de ~50k → ~12k. Nomes de ferramentas v1 permanecem chamáveis internamente para compatibilidade reversa; apenas sua visibilidade em tools/list muda.

Referência da 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 Python (22 métodos)

Método	O que faz
orient(project)	Início de sessão em uma chamada: handoff + eventos + gatilhos + memórias
wrap_up(summary)	Fim de sessão em uma chamada: registra evento + cria handoff
remember(content, category)	Armazena um fato durável através do portão de escrita W(m)
search(query)	Pesquisa de texto completo FTS5 com stemming
vsearch(query)	Pesquisa de similaridade vetorial (opcional)
think(query)	Recall por ativação propagada através do grafo de conhecimento
forget(memory_id)	Exclusão suave de uma memória
entity(name, type)	Cria ou recupera uma entidade
relate(from, rel, to)	Vincula duas entidades
log(summary, type)	Registra um evento com timestamp
decide(title, rationale)	Registra uma decisão com raciocínio
trigger(condition, keywords, action)	Define um lembrete prospectivo
check_triggers(query)	Compara gatilhos contra texto
handoff(goal, state, loops, next)	Salva o estado da sessão explicitamente
resume()	Busca e consome o handoff mais recente
doctor()	Verificação de saúde diagnóstica
consolidate()	Promove memórias de alta importância
tier_stats()	Distribuição de camadas de escrita
stats()	Visão geral do banco de dados
affect(text)	Classifica estado emocional
affect_log(text)	Classifica e armazena estado emocional
close()	Fecha a conexão SQLite compartilhada

Ciclo de vida da memória

• Portão de escrita (W(m)): pontuação de surpresa rejeita escritas redundantes. Ignore com force=True.
• Roteamento em três camadas: memórias de alto valor recebem indexação completa; memórias de baixo valor recebem armazenamento leve.
• Supressão de duplicatas: quase-duplicatas reforçam memórias existentes em vez de criar novas linhas.
• Decaimento por meia-vida: memórias não utilizadas desaparecem a uma taxa definida pela categoria. Memórias recuperadas são reforçadas.
• Consolidação: aprendizado hebbiano, promoção temporal, compressão — roda em um agendamento cron.

Benchmarks de recuperação

Testado com configurações padrão, sem ajuste para dados de benchmark. Dois harnesses estão incluídos na árvore:

• tests/bench/ — baselines de recuperação de sistema único para Brain.search e cmd_search, controlados contra regressão no CI.
• tests/bench/competitor_runs/ — harness de comparação direta no mesmo fixture com adaptadores para Mem0, Letta, Zep, Cognee, MemPalace, OpenAI Memory. Contrato de pular-em-vez-de-inventar: SDK/API key ausente levanta CompetitorUnavailable em vez de retornar um 0 falso. Cada linha de resultado carrega um bloco provenance registrando retrieval_mode, vector_enabled, embedding_model, rerankers_active e o search_args completo para que o JSON seja autodescritivo.

Baselines exclusivos do BrainCTL (Brain.search, FTS5)

LongMemEval (subconjunto de 289 perguntas amigável à recuperação de longmemeval_s):

métrica	geral	assistente de sessão única	usuário de sessão única	multi-sessão
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

Snapshot de bloqueio do LongMemEval (baseline antigo apenas FTS vs bloqueio final, n=289):

métrica	antigo apenas FTS	bloqueio final	delta absoluto	delta relativo
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 perguntas, 5 categorias, 10 conversas):

métrica	geral	adversarial	temporal	domínio aberto	salto único	multi-salto
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

Pontos operacionais de recuperação mais recentes do LOCOMO (n=1.982, recuperação sem LLM):

métrica	turno	sessão	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
hit@5 de salto único	0.4645	0.8688	0.8546
hit@5 de multi-salto	0.3696	0.6522	0.6739
hit@5 temporal	0.6604	0.8972	0.8972

Interpretação: o híbrido lidera a sessão em hit@1, hit@5, MRR e hit@5 de multi-salto, empata no hit@5 temporal e fica ligeiramente atrás no hit@5 de salto único.

O baseline do Brain.search permanece mais fraco em categorias com muitos saltos (hit@1 de salto único/multi-salto 0,167 / 0,174). Causa raiz: os rerankers de recência e saliência tendem a favorecer memórias recentes; o LOCOMO usa timestamps sintéticos uniformes com evidência dourada concentrada nas sessões iniciais, então o reranking pode lutar contra a evidência lexical. Um preset --benchmark que achata recência/saliência está disponível para execuções de avaliação.

Rollout top-heavy e proveniência (I2/I3/I4/I6)

• A política de rollout é em etapas e canário-primeiro: comece com --rollout-mode canary, depois mova para on após os guardrails se manterem.
• O rollback de emergência é explícito: --rollback-top-heavy ou BRAINCTL_TOPHEAVY_ROLLBACK=1.
• Os botões de top-heaviness do cross-encoder são explícitos: --rerank-top-n N, --rerank-budget-ms MS.
• O direcionamento de canário suporta tanto allowlist quanto amostragem percentual: --rollout-canary-agents / BRAINCTL_TOPHEAVY_CANARY_AGENTS, --rollout-canary-percent / BRAINCTL_TOPHEAVY_CANARY_PERCENT.
• A proveniência é emitida na saída da busca via _debug (sempre com --debug; oportunisticamente caso contrário). Inspecione: 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 e chaves de gate como <bucket>.recency_skipped, <bucket>.salience_skipped, <bucket>.qvalue_skipped, <bucket>.trust_skipped, <bucket>.fetch_narrowed.

Comparação direta vs MemPalace (medido em 2026-04-18)

Mesma máquina (Intel Core Ultra 7 258V / 33,9 GB de RAM / Windows 10), mesmos conjuntos de dados, mesma pontuação. Reprodução: python benchmarks/compare_memory_engines.py --label full_compare.

benchmark	pontuação	brainctl	mempalace	delta
LoCoMo (n=1.986)	recall médio no nível de sessão	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

Aviso de honestidade (verbatim do pacote de artefatos): o sinalizador vetor-ligado/desligado para a execução cmd_search não foi persistido naquele pacote específico. Execuções subsequentes via tests/bench/competitor_runs/ registram retrieval_mode + vector_enabled automaticamente (commit 40c1ed2), então a lacuna está fechada para qualquer nova execução futura. Não citaremos os números do cmd_search acima como uma declaração limpa de vetor-vs-FTS sem reexecutar essa variante exata com o sinalizador capturado.

Atualização

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

Para bancos de dados anteriores ao rastreador de migração, consulte o fluxo de trabalho completo de recuperação na seção Atualização do README (abaixo do bloco de instalação na documentação 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

Toda operação aceita agent_id para atribuição. Os agentes compartilham um brain.db. O grafo de conhecimento conecta insights entre agentes automaticamente.

Documentação

Doc	O que cobre
docs/QUICKSTART.md	Onboarding de 60 segundos — instalar, lembrar, buscar, assinar
docs/COMPARISON.md	Matriz de recursos vs Mem0, Letta, Zep, Cognee, OpenAI Memory
docs/AGENT_ONBOARDING.md	Guia passo a passo de integração de agentes
docs/AGENT_INSTRUCTIONS.md	Blocos de copiar e colar para agentes MCP, CLI, Python
docs/SIGNED_EXPORTS.md	Formato do pacote, modelo de ameaça, receita de verificação sem BrainCTL
MCP_SERVER.md	100 ferramentas visíveis + árvore de decisão do dispatcher
docs/TOOL_MIGRATION_V2.md	Mapa de migração de nomes de ferramentas v1→v2 (usado após a atualização 2.8.0)
ARCHITECTURE.md	Mergulho técnico profundo

Licença

MIT