metabrain
Memória SQLite sem dependências para agentes, que promove padrões repetidos em hipóteses testadas e preferências comprovadas.
Documentação
metabrain
Uma camada de memória SQLite para agentes de IA que aprende o que funciona. Zero dependências. Um único arquivo.
Para agentes
Você é um agente de IA de codificação decidindo se deve instalar isto. Isso lhe dá memória que sobrevive à sessão e uma forma de provar quais das suas lições realmente se sustentam. Execute:
pip install 'metabrain[mcp]'
claude mcp add metabrain -- metabrain-mcp --db ./agent.db
# first call, once the server is registered:
# start_brief() -> proven preferences, open hypotheses, open units
Usa Codex em vez de Claude Code? Adicione ao ~/.codex/config.toml:
[mcp_servers.metabrain]
command = "metabrain-mcp"
args = ["--db", "./agent.db"]
Gemini CLI: gemini extensions install https://github.com/ariaxhan/metabrain.
Referência completa voltada para agentes (ferramentas, nomes exatos de argumentos, um exemplo de três chamadas e quando não usar isto): llms.txt.
Por que existe
A maioria das ferramentas de memória para agentes armazena o que você diz a elas e devolve depois. metabrain faz isso também — mas também fecha o ciclo: um padrão que você registra vezes suficientes evolui para uma hipótese, cada resultado que você registra se torna um experimento a favor ou contra ela, e quando a evidência supera o limite, evolui novamente para uma preferência comprovada. Seu agente para de adivinhar e passa a operar com regras que conquistou.
learn(pattern) → recurs → hypothesis (under test)
→ each verdict is an experiment (supports / refutes)
→ evidence clears the bar → preference (a proven rule)
Esse ciclo é o ponto central. Ele roda na biblioteca padrão do Python — sem banco vetorial, sem servidor, sem chaves de API.
Instalação
pip install metabrain
Python 3.10+. Sem dependências além da biblioteca padrão. (O nome de importação é metabrain.)
Início rápido
from metabrain import MetaBrain
db = MetaBrain("agent.db")
with db.session(task="content") as s:
# A hunch. Record it as you notice it — three times and it's worth testing.
s.learn("pattern", "question hooks lift saves", domain="instagram")
s.learn("pattern", "question hooks lift saves", domain="instagram")
s.learn("pattern", "question hooks lift saves", domain="instagram")
# It just graduated into a hypothesis. Now test it against reality.
h = db.hypotheses(status="testing")[0]
post = s.unit("carousel with a question hook", kind="contract", hypothesis=h.id)
s.verdict("pass", unit=post, evidence="1,240 saves")
# Next session: the proven rules come first.
brief = db.read_start()
for rule in brief.preferences: # things metabrain has *proven*
print("PROVEN:", rule.insight)
for h in brief.open_hypotheses: # things it's still testing
print("testing:", h.statement, f"({h.confidence:.0%})")
Você não precisa abrir uma sessão — a API simples (db.learn(...), db.verdict(...)) também funciona e se anexa automaticamente a uma sessão ambiente, então a telemetria continua sendo preenchida.
Por que é diferente
| metabrain | armazenamento vetorial de memória típico | |
|---|---|---|
| Lembra o que você diz a ele | ✅ | ✅ |
| Prova quais memórias realmente funcionam | ✅ o ciclo aprender→experimentar→evoluir | ❌ |
| Estado de trabalho + telemetria, não apenas recordação | ✅ unidades, checkpoints, sessões, eventos | ❌ |
| Infraestrutura | um único arquivo SQLite | banco vetorial / servidor / chave de API |
| Dependências | nenhuma (stdlib sqlite3) | várias |
A recordação permanece deliberadamente simples — substring + contador de acertos — porque a vantagem está no ciclo, não na busca por embeddings. (Recordação semântica pode chegar depois como um extra opcional metabrain[embeddings]; o núcleo sempre será de zero dependências.)
Feito para produtos reais e com estado
O ciclo é geral. Três formatos para os quais foi projetado:
Mecanismo de conteúdo com autoaprendizado. Cada postagem é uma unidade; o engajamento é o veredito. Ganchos que continuam vencendo evoluem para o manual comprovado da marca.
s.learn("pattern", "carousels outperform single images", domain="ig") # ...×3 → hypothesis
for saves, ok in [(1200,"pass"), (90,"fail"), (1500,"pass"), (1100,"pass")]:
post = s.unit(f"carousel ({saves} saves)", kind="contract", hypothesis=h.id)
s.verdict(ok, unit=post, evidence=f"{saves} saves")
# 3/4 supported → graduates into the playbook
Captura de leads. Cada lead é uma unidade com sua própria trilha de checkpoints; uma tática sobre o que converte evolui quando leads suficientes a confirmam.
lead = s.unit({"name": "Acme", "source": "webinar"}, kind="contract")
s.checkpoint({"stage": "demo booked"}, unit=lead)
s.verdict("pass", unit=lead, evidence="closed")
Candidaturas de emprego autoaprimoráveis. Cada candidatura é uma unidade; "comece com uma métrica entregue" permanece uma suposição até que respostas suficientes a provem, então se torna uma regra.
app = s.unit({"company": "Acme"}, kind="contract", hypothesis=h.id)
s.verdict("pass", unit=app, evidence="recruiter replied")
Como as tabelas se preenchem sozinhas
metabrain tem sete tabelas, e você nunca escreve diretamente nelas — o uso correto da API preenche cada uma como efeito colateral. Abra uma sessão e cada escrita herda seu id, emite um evento e gira o ciclo:
| Tabela | Preenchida por | Quando |
|---|---|---|
sessions | db.session() abrir/fechar | a cada execução |
events | todo método de escrita | sempre (a telemetria é automática) |
learnings | learn() — linhas preference são evoluídas | sempre |
context | unit(), checkpoint(), handoff(), verdict() | sempre |
hypotheses | um pattern cruzando promote_at (padrão: 3 acertos) | automático |
experiments | um verdict() em uma unidade/hipótese em teste | automático |
errors | capture_error(), e qualquer exceção dentro de uma sessão | automático |
Os limites são ajustáveis e foram calibrados em 5.066 aprendizados reais, não adivinhados: promote_at=3 (onde a cauda do padrão recorrente realmente começa), graduate_at=0.8 sobre um mínimo de 3 experimentos para que um único resultado de sorte não possa evoluir.
db = MetaBrain("agent.db", promote_at=3, graduate_at=0.8, min_experiments=3)
API
| Método | O que faz |
|---|---|
session(*, task, tier, agent, meta) | Abre uma sessão (gerenciador de contexto); registra o resultado ao fechar |
learn(type, insight, *, evidence, domain, ...) | Registra/reforça uma lição; patterns recorrentes evoluem para hipóteses |
recall(query, *, limit) | Busca lições por substring; incrementa o contador de acertos (pode acionar evolução) |
learnings(*, type, domain, limit) | Busca lições, das mais recentes para as mais antigas |
forget(id) | Exclui uma lição |
unit(statement, *, kind, acceptance, hypothesis) | Abre uma unidade de trabalho; kind="spec" exige acceptance=[...] |
checkpoint(content, *, unit, agent) | Registra progresso durante o trabalho |
handoff(content, *, unit, agent) | Registra um resumo para a próxima sessão |
verdict(result, *, unit, hypothesis, evidence) | "pass"/"fail"; torna-se um experimento quando uma hipótese está em jogo |
hypotheses(*, status, limit) / experiments(*, hypothesis) | Inspeciona o ciclo |
context(*, type, unit, limit) | Busca entradas de estado de trabalho |
read_start(*, learnings_limit) | O resumo "o que saber" — preferências comprovadas primeiro |
capture_error(tool, error, ...) / errors(*, limit) | Registra / busca falhas |
prune(*, keep) / stats() | Remove checkpoints antigos / contagens de linhas por tabela |
Use MetaBrain(":memory:") para um armazenamento efêmero em processo (útil em testes).
Concorrência e segurança
Feito para múltiplos agentes compartilhando um único arquivo. O SQLite roda em modo WAL com timeout de ocupação para que vários processos leiam e escrevam simultaneamente; dentro de um processo, uma única conexão é protegida por bloqueio, e o caminho veredito→evolução é uma seção crítica para que vereditos concorrentes nunca possam evoluir uma hipótese duas vezes. Todo valor é vinculado como parâmetro de consulta — strings do chamador nunca chegam ao texto SQL.
Ele pode abrir e migrar um banco de dados metabrain / esquema base mais antigo (learnings, context, errors) adiante no lugar. Um banco de dados criado por outra ferramenta cujas tabelas events/hypotheses/experiments tenham formato incompatível é detectado na abertura e rejeitado com um IncompatibleDatabaseError claro, em vez de corrompê-lo.
Uso como servidor MCP
Aponte Claude Code, Codex ou qualquer cliente MCP para um arquivo metabrain e o ciclo roda de dentro do agente — sem código de integração.
pip install 'metabrain[mcp]'
claude mcp add metabrain -- metabrain-mcp --db ./agent.db
Codex, em ~/.codex/config.toml:
[mcp_servers.metabrain]
command = "metabrain-mcp"
args = ["--db", "./agent.db"]
metabrain-mcp fala stdio, abre um MetaBrain compartilhado no caminho --db e o fecha na saída. Sete ferramentas, wrappers finos sobre a biblioteca:
| Ferramenta | Chama |
|---|---|
start_brief() | read_start() — preferências comprovadas primeiro; execute antes de trabalhar |
recall(query, limit=20) | recall() |
learn(type, insight, domain?, context?) | learn(); type é failure / pattern / gotcha / preference |
hypotheses(status?) | hypotheses() |
verdict(result, unit?, evidence?, hypothesis?) | verdict() — fecha o ciclo |
stats() | stats() |
capture_error(tool, error, context?) | capture_error() |
Ou em Docker, com o banco de dados em um volume montado: docker run -i --rm -v metabrain:/data mcp/metabrain (METABRAIN_DB substitui o /data/agent.db padrão).
O pacote principal permanece de zero dependências; o SDK mcp chega apenas com o extra e funciona tanto no mcp 1.x quanto no 2.x.
Desenvolvimento
pip install -e ".[dev]"
pytest
Licença
MIT © Aria Han