metabrain

Слой памяти на SQLite для ИИ-агентов, который учится на том, что работает. Ноль зависимостей. Один файл.

Для агентов

Вы — ИИ-агент, пишущий код, и решаете, стоит ли это устанавливать. Это даёт вам память, которая переживает сессию, и способ доказать, какие из ваших уроков действительно работают. Выполните:

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 вместо Claude Code? Добавьте в ~/.codex/config.toml:

[mcp_servers.metabrain]
command = "metabrain-mcp"
args = ["--db", "./agent.db"]

Gemini CLI: gemini extensions install https://github.com/ariaxhan/metabrain.

Полная документация для агентов (инструменты, точные имена аргументов, пример с тремя вызовами и когда это не стоит использовать): llms.txt.

Related MCP server: DevFlow MCP

Зачем это существует

Большинство инструментов памяти для агентов хранят то, что вы им говорите, и возвращают это позже. metabrain делает то же самое — но также замыкает цикл: паттерн, который вы записали достаточное число раз, повышается до гипотезы, каждый зафиксированный результат становится экспериментом за или против неё, и когда доказательства преодолевают порог, он снова повышается до подтверждённого предпочтения. Ваш агент перестаёт гадать и начинает работать по правилам, которые он заслужил.

learn(pattern)  →  recurs  →  hypothesis (under test)
        →  each verdict is an experiment (supports / refutes)
        →  evidence clears the bar  →  preference  (a proven rule)

Весь смысл — в этом цикле. Он работает на стандартной библиотеке Python — без векторной базы данных, без сервера, без API-ключей.

Установка

pip install metabrain

Python 3.10+. Никаких зависимостей, кроме стандартной библиотеки. (Имя для импорта — metabrain.)

Быстрый старт

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

Вам не обязательно открывать сессию — плоский API (db.learn(...), db.verdict(...)) тоже работает и автоматически привязывается к активной сессии, так что телеметрия по-прежнему заполняется.

Чем он отличается

Поиск намеренно остаётся простым — подстрока + счётчик совпадений — потому что основное преимущество — это цикл, а не поиск по эмбеддингам. (Семантический поиск, возможно, появится позже как опциональный дополнительный пакет metabrain[embeddings]; ядро всегда останется без зависимостей.)

Создан для реальных продуктов с состоянием

Цикл универсален. Вот три сценария, под которые он спроектирован:

Самообучающийся контент-движок. Каждый пост — это юнит; вовлечённость — вердикт. Зацепки, которые продолжают побеждать, повышаются до проверенного сборника практик бренда.

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

Захват лидов. Каждый лид — это юнит со своим треком чекпоинтов; тактика о том, что конвертирует, повышается после того, как достаточное количество лидов её подтвердит.

lead = s.unit({"name": "Acme", "source": "webinar"}, kind="contract")
s.checkpoint({"stage": "demo booked"}, unit=lead)
s.verdict("pass", unit=lead, evidence="closed")

Самоулучшающиеся заявки на работу. Каждая заявка — это юнит; «начинайте с метрики запущенного продукта» остаётся догадкой, пока достаточное количество ответов не докажет это, и затем становится правилом.

app = s.unit({"company": "Acme"}, kind="contract", hypothesis=h.id)
s.verdict("pass", unit=app, evidence="recruiter replied")

Как таблицы заполняются сами

У metabrain семь таблиц, и вы никогда не пишете в них напрямую — правильное использование API заполняет каждую из них как побочный эффект. Откройте сессию, и каждая запись наследует её id, порождает событие и запускает цикл:

Пороги настраиваются и были откалиброваны на 5 066 реальных уроках, а не угаданы: promote_at=3 (где на самом деле начинается хвост повторяющихся паттернов), graduate_at=0.8 при минимуме в 3 эксперимента, чтобы один случайный удачный результат не мог повысить гипотезу.

db = MetaBrain("agent.db", promote_at=3, graduate_at=0.8, min_experiments=3)

API

Используйте MetaBrain(":memory:") для временного хранилища внутри процесса (удобно в тестах).

Параллельность и безопасность

Спроектирован для нескольких агентов, использующих один файл. SQLite работает в режиме WAL с таймаутом ожидания, поэтому несколько процессов читают и пишут одновременно; внутри процесса одно соединение защищено блокировкой, а путь вердикт→повышение — это единая критическая секция, поэтому соревнующиеся вердикты никогда не смогут дважды повысить гипотезу. Каждое значение передаётся как параметр запроса — строки вызывающего кода никогда не попадают в текст SQL.

Он может открыть и перенести вперёд на месте более старую базу metabrain / базу с базовой схемой (learnings, context, errors). База данных, созданная другим инструментом, у которой таблицы events/hypotheses/experiments имеют несовместимую структуру, обнаруживается при открытии и отклоняется с понятной ошибкой IncompatibleDatabaseError, а не повреждается.

Использование в качестве MCP-сервера

Подключите Claude Code, Codex или любой MCP-клиент к файлу metabrain — и цикл заработает изнутри агента, без связующего кода.

pip install 'metabrain[mcp]'
claude mcp add metabrain -- metabrain-mcp --db ./agent.db

Codex, в ~/.codex/config.toml:

[mcp_servers.metabrain]
command = "metabrain-mcp"
args = ["--db", "./agent.db"]

metabrain-mcp работает через stdio, открывает один общий экземпляр MetaBrain по пути --db и закрывает его при выходе. Семь инструментов — тонкие обёртки над библиотекой:

Или в Docker, с базой данных на смонтированном томе: docker run -i --rm -v metabrain:/data mcp/metabrain (METABRAIN_DB переопределяет путь по умолчанию /data/agent.db).

Основной пакет остаётся без зависимостей; SDK mcp появляется только вместе с дополнительным пакетом и работает как в mcp 1.x, так и в 2.x.

Разработка

pip install -e ".[dev]"
pytest

Лицензия

MIT © Aria Han