metabrain

Eine SQLite-Speicherschicht für KI-Agenten, die lernt, was funktioniert. Null Abhängigkeiten. Eine Datei.

Für Agenten

Du bist ein KI-Codierungsagent, der entscheidet, ob du dies installierst. Es gibt dir Speicher, der die Sitzung überlebt, und eine Möglichkeit zu beweisen, welche deiner Lektionen tatsächlich Bestand haben. Führe aus:

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 statt Claude Code? Füge zu ~/.codex/config.toml hinzu:

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

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

Vollständige Referenz für Agenten (Werkzeuge, exakte Argumentnamen, ein Beispiel mit drei Aufrufen und wann man dies nicht verwenden sollte): llms.txt.

Related MCP server: DevFlow MCP

Warum es das gibt

Die meisten Agenten-Speicherwerkzeuge speichern, was du ihnen sagst, und reichen es später zurück. metabrain macht das auch – aber es schließt auch den Kreislauf: Ein Muster, das du oft genug aufzeichnest, steigt zu einer Hypothese auf, jedes protokollierte Ergebnis wird zu einem Experiment dafür oder dagegen, und sobald die Evidenz die Messlatte überschreitet, steigt es erneut zu einer bewährten Präferenz auf. Dein Agent hört auf zu raten und arbeitet mit Regeln, die er sich verdient hat.

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

Dieser Kreislauf ist der eigentliche Punkt. Er läuft auf der Python-Standardbibliothek – keine Vektordatenbank, kein Server, keine API-Schlüssel.

Installation

pip install metabrain

Python 3.10+. Keine Abhängigkeiten außerhalb der Standardbibliothek. (Der Importname ist metabrain.)

Schnellstart

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

Du musst keine Sitzung öffnen – die flache API (db.learn(...), db.verdict(...)) funktioniert ebenfalls und hängt sich automatisch an eine vorhandene Sitzung an, sodass die Telemetrie trotzdem gefüllt wird.

Warum es anders ist

Der Abruf bleibt bewusst einfach – Teilzeichenfolge + ein Trefferzähler –, denn der Burggraben ist der Kreislauf, nicht die Einbettungssuche. (Semantischer Abruf könnte später als optionales Zusatzpaket metabrain[embeddings] kommen; der Kern wird immer ohne Abhängigkeiten sein.)

Entwickelt für echte, zustandsbehaftete Produkte

Der Kreislauf ist allgemein. Drei Formen, auf die er ausgelegt wurde:

Selbstlernende Content-Engine. Jeder Beitrag ist eine Unit; Engagement ist das Urteil. Hooks, die weiterhin gewinnen, steigen in das bewährte Playbook der Marke auf.

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-Erfassung. Jeder Lead ist eine Unit mit eigener Checkpoint-Spur; eine Taktik darüber, was konvertiert, steigt auf, sobald genügend Leads sie bestätigen.

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

Selbstverbessernde Bewerbungen. Jede Bewerbung ist eine Unit; „Mit einer ausgelieferten Metrik führen“ bleibt eine Vermutung, bis genügend Antworten es beweisen, dann wird es zur Regel.

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

Wie sich die Tabellen selbst füllen

metabrain hat sieben Tabellen, und du schreibst nie direkt in sie – korrekte API-Nutzung füllt jede einzelne als Nebeneffekt. Öffne eine Sitzung und jeder Schreibvorgang erbt ihre ID, erzeugt ein Ereignis und dreht den Kreislauf:

Die Schwellenwerte sind einstellbar und wurden an 5.066 realen Learnings kalibriert, nicht geraten: promote_at=3 (wo der Schwanz der wiederkehrenden Muster tatsächlich beginnt), graduate_at=0.8 über mindestens 3 Experimenten, damit ein einzelnes glückliches Ergebnis nicht graduieren kann.

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

API

Verwende MetaBrain(":memory:") für einen kurzlebigen In-Process-Speicher (praktisch in Tests).

Nebenläufigkeit & Sicherheit

Entwickelt für mehrere Agenten, die sich eine Datei teilen. SQLite läuft im WAL-Modus mit einem Busy-Timeout, sodass mehrere Prozesse gleichzeitig lesen und schreiben; innerhalb eines Prozesses ist eine einzelne Verbindung durch eine Sperre geschützt, und der Pfad von Verdict zu Graduierung ist ein kritischer Abschnitt, sodass konkurrierende Verdicts eine Hypothese nie doppelt graduieren können. Jeder Wert wird als Query-Parameter gebunden – Aufrufer-Strings gelangen nie in den SQL-Text.

Es kann eine ältere metabrain-/Basis-Schema-Datenbank (learnings, context, errors) öffnen und vor Ort vorwärtsmigrieren. Eine Datenbank, die von einem anderen Tool erstellt wurde und deren Tabellen events/hypotheses/experiments eine inkompatible Form haben, wird beim Öffnen erkannt und mit einem klaren IncompatibleDatabaseError abgelehnt, anstatt sie zu beschädigen.

Verwendung als MCP-Server

Richte Claude Code, Codex oder einen beliebigen MCP-Client auf eine metabrain-Datei aus, und der Kreislauf läuft von innerhalb des Agenten – kein Klebecode.

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

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

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

metabrain-mcp spricht stdio, öffnet ein gemeinsames MetaBrain auf dem --db-Pfad und schließt es beim Beenden. Sieben Werkzeuge, dünne Hüllen über der Bibliothek:

Oder in Docker, mit der Datenbank auf einem gemounteten Volume: docker run -i --rm -v metabrain:/data mcp/metabrain (METABRAIN_DB überschreibt das Standard-/data/agent.db).

Das Kernpaket bleibt ohne Abhängigkeiten; das mcp-SDK kommt nur mit dem Extra und funktioniert sowohl mit mcp 1.x als auch 2.x.

Entwicklung

pip install -e ".[dev]"
pytest

Lizenz

MIT © Aria Han