metabrain
Memoria SQLite sin dependencias para agentes que promueve patrones repetidos en hipótesis probadas y preferencias comprobadas.
Documentación
metabrain
Una capa de memoria SQLite para agentes de IA que aprende lo que funciona. Cero dependencias. Un solo archivo.
Para agentes
Eres un agente de IA de codificación que decide si instalar esto. Te da memoria que sobrevive a la sesión y una forma de demostrar cuáles de tus lecciones realmente se sostienen. Ejecuta:
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
¿Codex en lugar de Claude Code? Añádelo a ~/.codex/config.toml:
[mcp_servers.metabrain]
command = "metabrain-mcp"
args = ["--db", "./agent.db"]
Gemini CLI: gemini extensions install https://github.com/ariaxhan/metabrain.
Referencia completa orientada a agentes (herramientas, nombres exactos de argumentos, un ejemplo de tres llamadas y cuándo no usar esto): llms.txt.
Por qué existe
La mayoría de las herramientas de memoria para agentes almacenan lo que les dices y lo devuelven después. metabrain también hace eso, pero además cierra el ciclo: un patrón que registras suficientes veces asciende a hipótesis, cada resultado que registras se convierte en un experimento a favor o en contra, y una vez que la evidencia supera el umbral asciende de nuevo a una preferencia comprobada. Tu agente deja de adivinar y empieza a operar con reglas que se ha ganado.
learn(pattern) → recurs → hypothesis (under test)
→ each verdict is an experiment (supports / refutes)
→ evidence clears the bar → preference (a proven rule)
Ese ciclo es el punto central. Funciona con la biblioteca estándar de Python: sin base de datos vectorial, sin servidor, sin claves de API.
Instalación
pip install metabrain
Python 3.10+. Sin dependencias más allá de la biblioteca estándar. (El nombre de importación es metabrain.)
Inicio 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%})")
No tienes que abrir una sesión: la API plana (db.learn(...), db.verdict(...)) también funciona y se adjunta automáticamente a una sesión ambiental, por lo que la telemetría sigue completándose.
Por qué es diferente
| metabrain | almacén de memoria vectorial típico | |
|---|---|---|
| Recuerda lo que le dices | ✅ | ✅ |
| Demuestra qué memorias realmente funcionan | ✅ el ciclo aprender→experimentar→ascender | ❌ |
| Estado de trabajo + telemetría, no solo recuperación | ✅ unidades, puntos de control, sesiones, eventos | ❌ |
| Infraestructura | un solo archivo SQLite | base de datos vectorial / servidor / clave de API |
| Dependencias | ninguna (biblioteca estándar sqlite3) | varias |
La recuperación se mantiene deliberadamente simple — subcadena + un contador de aciertos — porque la ventaja es el ciclo, no la búsqueda por incrustaciones. (La recuperación semántica puede llegar más adelante como un extra opcional de metabrain[embeddings]; el núcleo siempre tendrá cero dependencias.)
Diseñado para productos reales y con estado
El ciclo es general. Tres formas para las que fue diseñado:
Motor de contenido de autoaprendizaje. Cada publicación es una unidad; la participación es el veredicto. Los ganchos que siguen ganando ascienden al manual comprobado de la 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 clientes potenciales. Cada cliente potencial es una unidad con su propio rastro de puntos de control; una táctica sobre qué convierte asciende una vez que suficientes clientes potenciales la confirman.
lead = s.unit({"name": "Acme", "source": "webinar"}, kind="contract")
s.checkpoint({"stage": "demo booked"}, unit=lead)
s.verdict("pass", unit=lead, evidence="closed")
Solicitudes de empleo de automejora. Cada solicitud es una unidad; "liderar con una métrica enviada" sigue siendo una suposición hasta que suficientes respuestas lo demuestran, y luego se convierte en una regla.
app = s.unit({"company": "Acme"}, kind="contract", hypothesis=h.id)
s.verdict("pass", unit=app, evidence="recruiter replied")
Cómo se llenan las tablas automáticamente
metabrain tiene siete tablas, y nunca escribes directamente en ellas — el uso correcto de la API llena cada una como efecto secundario. Abre una sesión y cada escritura hereda su id, emite un evento y activa el ciclo:
| Tabla | Se llena con | Cuándo |
|---|---|---|
sessions | db.session() abrir/cerrar | cada ejecución |
events | cada método de escritura | siempre (la telemetría es automática) |
learnings | learn() — las filas de preference están graduadas | siempre |
context | unit(), checkpoint(), handoff(), verdict() | siempre |
hypotheses | un pattern que cruza promote_at (3 aciertos por defecto) | automático |
experiments | un verdict() en una unidad/hipótesis bajo prueba | automático |
errors | capture_error(), y cualquier excepción dentro de una sesión | automático |
Los umbrales son ajustables y se calibraron con 5,066 aprendizajes reales, no adivinados: promote_at=3 (donde realmente comienza la cola de patrones recurrentes), graduate_at=0.8 sobre un mínimo de 3 experimentos para que un solo resultado afortunado no pueda ascender.
db = MetaBrain("agent.db", promote_at=3, graduate_at=0.8, min_experiments=3)
API
| Método | Qué hace |
|---|---|
session(*, task, tier, agent, meta) | Abre una sesión (administrador de contexto); registra el resultado al cerrar |
learn(type, insight, *, evidence, domain, ...) | Registra/refuerza una lección; los pattern recurrentes ascienden a hipótesis |
recall(query, *, limit) | Busca lecciones por subcadena; aumenta el contador de aciertos (puede activar el ascenso) |
learnings(*, type, domain, limit) | Obtiene lecciones, las más recientes primero |
forget(id) | Elimina una lección |
unit(statement, *, kind, acceptance, hypothesis) | Abre una unidad de trabajo; kind="spec" requiere acceptance=[...] |
checkpoint(content, *, unit, agent) | Registra progreso a mitad del trabajo |
handoff(content, *, unit, agent) | Registra un resumen para la próxima sesión |
verdict(result, *, unit, hypothesis, evidence) | "pass"/"fail"; se convierte en un experimento cuando hay una hipótesis en juego |
hypotheses(*, status, limit) / experiments(*, hypothesis) | Inspecciona el ciclo |
context(*, type, unit, limit) | Obtiene entradas de estado de trabajo |
read_start(*, learnings_limit) | El resumen de "qué saber" — preferencias comprobadas primero |
capture_error(tool, error, ...) / errors(*, limit) | Registra / obtiene fallos |
prune(*, keep) / stats() | Recorta puntos de control antiguos / recuentos de filas por tabla |
Usa MetaBrain(":memory:") para un almacén efímero en proceso (útil en pruebas).
Concurrencia y seguridad
Diseñado para múltiples agentes que comparten un archivo. SQLite funciona en modo WAL con un tiempo de espera de ocupado para que varios procesos lean y escriban simultáneamente; dentro de un proceso, una sola conexión está protegida por bloqueo, y la ruta veredicto→ascenso es una sección crítica para que los veredictos en competencia nunca puedan ascender doblemente una hipótesis. Cada valor se vincula como parámetro de consulta — las cadenas del llamador nunca llegan al texto SQL.
Puede abrir y migrar una base de datos metabrain / esquema base más antigua (aprendizajes, contexto, errores) hacia adelante en el lugar. Una base de datos creada por una herramienta diferente cuyas tablas events/hypotheses/experiments tengan una forma incompatible se detecta al abrir y se rechaza con un IncompatibleDatabaseError claro, en lugar de corromperla.
Uso como servidor MCP
Apunta Claude Code, Codex o cualquier cliente MCP a un archivo metabrain y el ciclo se ejecuta desde dentro del agente — sin código de conexión.
pip install 'metabrain[mcp]'
claude mcp add metabrain -- metabrain-mcp --db ./agent.db
Codex, en ~/.codex/config.toml:
[mcp_servers.metabrain]
command = "metabrain-mcp"
args = ["--db", "./agent.db"]
metabrain-mcp habla stdio, abre un MetaBrain compartido en la ruta --db y lo cierra al salir. Siete herramientas, envoltorios delgados sobre la biblioteca:
| Herramienta | Llama a |
|---|---|
start_brief() | read_start() — preferencias comprobadas primero; ejecútalo antes de trabajar |
recall(query, limit=20) | recall() |
learn(type, insight, domain?, context?) | learn(); type es failure / pattern / gotcha / preference |
hypotheses(status?) | hypotheses() |
verdict(result, unit?, evidence?, hypothesis?) | verdict() — cierra el ciclo |
stats() | stats() |
capture_error(tool, error, context?) | capture_error() |
O en Docker, con la base de datos en un volumen montado: docker run -i --rm -v metabrain:/data mcp/metabrain (METABRAIN_DB anula el /data/agent.db predeterminado).
El paquete principal mantiene cero dependencias; el SDK de mcp llega solo con el extra y funciona tanto en mcp 1.x como en 2.x.
Desarrollo
pip install -e ".[dev]"
pytest
Licencia
MIT © Aria Han