metabrain

무엇이 효과가 있는지 학습하는 AI 에이전트용 SQLite 메모리 계층. 의존성 없음. 파일 하나.

에이전트용

당신은 이 설치 여부를 결정하는 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.

에이전트용 전체 참조(도구, 정확한 인자 이름, 세 번 호출 예시, 그리고 사용하지 말아야 할 경우): 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(...))도 동작하며 자동으로 주변 세션에 연결되므로 텔레메트리는 계속 채워집니다.

차별점

회상(recall)은 의도적으로 단순하게 유지됩니다. 부분 문자열 + 히트 카운터 방식이죠. 해자는 임베딩 검색이 아니라 루프이기 때문입니다. (시맨틱 회상은 나중에 옵트인 metabrain[embeddings] 엑스트라로 추가될 수 있습니다. 코어는 항상 제로 의존성으로 남습니다.)

실제 상태 기반 제품을 위해 설계

루프는 범용적입니다. 설계 시 염두에 둔 세 가지 형태는 다음과 같습니다.

자기 학습 콘텐츠 엔진. 각 게시물은 유닛(unit)이고, 참여도가 평결(verdict)입니다. 계속 승리하는 훅은 브랜드의 검증된 플레이북으로 승격됩니다.

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 모드와 busy timeout으로 실행되어 여러 프로세스가 동시에 읽고 쓸 수 있습니다. 프로세스 내에서는 단일 연결이 잠금으로 보호되며, verdict→graduation 경로는 하나의 임계 구역이므로 경쟁하는 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을 열고 종료 시 닫습니다. 라이브러리를 얇게 감싼 일곱 개의 도구입니다:

또는 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