metabrain

metabrain

効果のある方法を学習する、AI エージェント向けの SQLite メモリレイヤーです。依存関係はゼロ。ファイルは 1 つです。

エージェント向け

あなたは、これをインストールするかどうかを判断している AI コーディングエージェントです。セッションをまたいで保持されるメモリと、学んだことが実際に通用するかを証明する方法を利用できます。次を実行してください。

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

Claude Code ではなく Codex をお使いですか？~/.codex/config.toml に追加してください。

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

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

エージェント向けの完全なリファレンス（ツール、正確な引数名、3 回の呼び出し例、使用すべきでない場面）はこちらです：llms.txt。

開発の背景

一般的なエージェントメモリツールは、あなたが 伝えた 内容を保存し、後でそれを返します。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	一般的なベクトルメモリストア
伝えた内容を記憶する	✅	✅
記憶が実際に役立つことを証明する	✅ learn→experiment→graduate のループ	❌
単なる想起にとどまらない、作業状態とテレメトリー	✅ ユニット、チェックポイント、セッション、イベント	❌
インフラストラクチャ	SQLite ファイル 1 つ	ベクトル DB／サーバー／API キー
依存関係	なし（標準ライブラリの sqlite3）	複数

想起機能は、意図的にシンプルなままにしています。部分文字列とヒット数カウンターだけです。強みは埋め込み検索ではなく、一連の流れにあるからです。（セマンティック想起は、将来的にオプトインの metabrain[embeddings] エクストラとして追加される可能性があります。コアは今後も依存関係ゼロを維持します。）

実際のステートフルなプロダクト向けに設計

この一連の流れは汎用的です。設計時に想定した 3 つの形態を紹介します。

自己学習型コンテンツエンジン。 各投稿がユニットとなり、エンゲージメントが判定結果になります。継続して成果を上げるフックは昇格し、ブランドで実証済みのプレイブックに加わります。

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 には 7 つのテーブルがあります。これらに直接書き込む必要はありません。API を正しく使えば、副作用としてすべてのテーブルが埋まります。 セッションを開くと、各書き込みがセッション ID を引き継ぎ、イベントを発生させ、一連の流れを進めます。

テーブル	更新するもの	タイミング
sessions	db.session() の開始／終了	実行ごと
events	すべての書き込みメソッド	常時（テレメトリーは自動）
learnings	learn() — preference 行は 昇格済み	常時
context	unit()、checkpoint()、handoff()、verdict()	常時
hypotheses	pattern が promote_at（デフォルトは 3 件のヒット）を超えたとき	自動
experiments	テスト中のユニット／仮説に対する verdict()	自動
errors	capture_error()、およびセッション内で発生した例外	自動

しきい値は調整可能で、推測ではなく 5,066 件の実際の学習データに基づいて調整されています。promote_at=3（繰り返し出現するパターンの裾野が実際に始まる値）と、1 回の偶然の成功で昇格しないよう、最低 3 回の実験を条件とした graduate_at=0.8 です。

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

API

メソッド	内容
session(*, task, tier, agent, meta)	セッションを開始します（コンテキストマネージャー）。終了時に結果を記録します
learn(type, insight, *, evidence, domain, ...)	教訓を記録／強化します。繰り返し現れるpatternは仮説に昇格します
recall(query, *, limit)	教訓を部分一致検索します。ヒット数を増やし（昇格が発生する場合があります）、
learnings(*, type, domain, limit)	教訓を新しい順に取得します
forget(id)	教訓を削除します
unit(statement, *, kind, acceptance, hypothesis)	作業単位を開始します。kind="spec"ではacceptance=[...]が必要です
checkpoint(content, *, unit, agent)	作業中の進捗を記録します
handoff(content, *, unit, agent)	次のセッション向けの概要を記録します
verdict(result, *, unit, hypothesis, evidence)	"pass"／"fail"を指定します。仮説が関与している場合は実験になります
hypotheses(*, status, limit) / experiments(*, hypothesis)	ループの状態を確認します
context(*, type, unit, limit)	作業状態のエントリーを取得します
read_start(*, learnings_limit)	「把握しておくべきこと」のダイジェストです。実証済みの好みを先に表示します
capture_error(tool, error, ...) / errors(*, limit)	エラーを記録／取得します
prune(*, keep) / stats()	古いチェックポイントを整理／テーブルごとの行数を表示します

テストなどで一時的なプロセス内ストアを使う場合は、MetaBrain(":memory:")を使用します。

並行処理と安全性

複数のエージェントが1つのファイルを共有できるように設計されています。SQLiteはビジータイムアウト付きのWALモードで動作するため、複数のプロセスが並行して読み書きできます。プロセス内では単一の接続をロックで保護し、verdictから昇格までの処理は1つのクリティカルセクションで実行されるため、verdictが競合しても仮説が二重に昇格することはありません。すべての値はクエリパラメーターとしてバインドされるため、呼び出し元の文字列が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で通信し、--dbで指定されたパスにある共有MetaBrainを1つ開き、終了時に閉じます。ライブラリを薄くラップした7つのツールを提供します。

ツール	呼び出し先
start_brief()	read_start() — 実証済みの好みを先に表示します。作業を始める前に実行してください
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() — ループを完了します
stats()	stats()
capture_error(tool, error, context?)	capture_error()

またはDockerで、データベースをマウントしたボリュームに置いて使用できます。docker run -i --rm -v metabrain:/data mcp/metabrain（METABRAIN_DBでデフォルトの/data/agent.dbを上書きできます）。

コアパッケージに依存関係はありません。mcp SDKは追加機能をインストールした場合にのみ導入され、mcpの1.xと2.xのどちらでも動作します。

開発

pip install -e ".[dev]"
pytest

ライセンス

MIT © Aria Han