brain-v42

MCP上で提供される、コーディングエージェント向けの永続メモリ。

brain-v42は、Claude Code、Codex、その他のMCPクライアントに永続的なセカンドブレインを提供します：決定、学び、コードスニペット、ランブック、ADR、チケット、プロジェクトロードマップをPostgreSQLに保存し、全文検索+セマンティック検索とリランキングで取得し、毎晩エージェントパイプラインによって統合されます。

• 型付けされた知識であり、単なるメモの寄せ集めではない — 決定はそのWHYと代替案を記録し、スニペットはその意図を記録し、ランブックは実行可能なステップを記録します。各型は独自のライフサイクルを持ちます（置き換えチェーン、ADRの受理、ラーニングの検証）。

• 明示的なセッションライフサイクル — すべてのセッション境界はユーザーが所有します。セッションは生成した成果物を記録し、クローズはフェイルクローズです：セッションは、記録された知識または明示的な「nothing to capture」という理由のいずれかで終了し、決して沈黙はしません。

• ランキングを行う検索 — pgvectorによるセマンティック検索 + PostgreSQL FTSを、クロスエンコーダーで融合して再ランキングします。

• 夜間の統合（「dream」） — エージェントパイプラインが、孤立リンクの掃除、重複のマージ、ラーニングの統合、プロモーションの提案を行います。すべてのフェーズは初期状態で無効化されたキルスイッチの背後で実行されます。

• マルチプロジェクト — プロジェクトごとのフォーカスに、比較と交換によるリビジョン、ロードマップ、プロジェクト横断のチケット。

アーキテクチャ

Claude Code / Codex (MCP client)
       │ HTTP loopback :8765/mcp (production) · stdio (dev/fallback)
  brain-v42 (FastMCP)
       ├── SQLAlchemy async ─▶ PostgreSQL 16 + pgvector   (source of truth)
       ├── HTTP ─────────────▶ embedding endpoint :8003   (optional, pluggable)
       ├── HTTP ─────────────▶ :8003/rerank               (optional reranker)
       └── bolt ─────────────▶ Neo4j 5 Community          (relationship index, optional)

MCPトランスポート：本番 = HTTPループバック http://127.0.0.1:8765/mcp; 設定デフォルトおよび開発/フォールバック = stdio。

PostgreSQLが唯一の真実源です。Neo4jはリレーショナルな台帳/アウトボックスから供給される使い捨て可能なプロジェクションであり、常にPostgreSQLから再構築できますが、その逆はありません。この正規パスは2026年7月22日から本番で稼働しています。設計と根拠はdocs/ARCHITECTURE.mdとgraph ledger runbookにあります。

埋め込みはオプションかつプラグイン可能です。サーバー自体はモデル非依存です。POST /embed、POST /embed/query、POST /rerank の3ルートからなるHTTP契約のみを話し、エンドポイントが利用できない場合はグレースフルに劣化します。brain_searchは全文検索にフォールバックし、書き込みはNULL埋め込みで永続化され、後でバックフィルされます。この契約を実装するサーバーならどれでも動作します。バンドルされているリファレンススタック（services/）は、ローカルGPU上のllama.cppを介してQodo-Embed-1-1.5BをGGUFとして提供します。EMBEDDING_DIMENSIONはインストール時に選択され、後でモデルを切り替える場合はコーパスの再埋め込み（scripts/regen_embeddings.py）が必要です。

クイックスタート

git clone https://github.com/hawkixs/brain-v42 && cd brain-v42
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# 1. Local Neo4j secret (skip if you run without the graph)
install -d -m 0700 .secrets
read -rsp "Neo4j password (same value as NEO4J_PASSWORD in .env): " PW
(umask 0022; printf 'neo4j/%s\n' "$PW" > .secrets/neo4j-auth); unset PW

# 2. Databases (PostgreSQL 16 + pgvector, Neo4j)
docker compose up -d

# 3. Migrations
export POSTGRES_URL="postgresql+asyncpg://brain:REPLACE_WITH_PASSWORD@localhost:5433/brain"
BRAIN_ALEMBIC_ALLOW_PROD=1 alembic upgrade head

# 4. Run the MCP server (stdio)
python -m brain_v42.mcp.server

Claude Codeに配線するには、リポジトリルートの.mcp.jsonがすでに本番HTTPループバックエンドポイントを対象にしています。プレーンなstdio開発セットアップの場合は：

claude mcp add brain-v42 -- python -m brain_v42.mcp.server

BRAIN_ALEMBIC_ALLOW_PRODは、データベース名が正確にbrainの場合にのみ必要です。これを1コマンドのオプトインに留め、永続的にエクスポートしないでください。AlembicはDSNクエリパラメータを拒否します。上記のプレーンな形式で、ホスト、ポート、ユーザー名、パスワードをすべて指定してください。

MCPツール

シグネチャ付きの完全なカタログ：docs/MCP_TOOLS.md。

デフォルトのカタログプロファイルはcompactです。7つのセッションライフサイクルツールは表示されたままになり、その他のすべてのツールは2つのゲートウェイ、つまり発見のためのbrain_find_toolと呼び出しのためのbrain_call_toolを介してアクセスされます。BRAIN_MCP_PROFILE=nativeを設定すると、すべてのツールを直接公開できます。

セッション

ユーザーはすべてのセッション境界を制御します。start、resume、end、abandonは明示的なコマンドであり、フック、エージェント、クライアントによって推測されることはありません。セッションは生成した永続的な成果物を排他的な台帳に記録し、クローズはフェイルクローズです。記録された知識、または明示的な「nothing to capture」という理由のいずれかであり、沈黙はありません。

ハートビートが24時間ない場合、オープン中のセッションはis_stale=trueを公開します。このマーカーは導出されるものであり、永続的なステータスはopenのままです。明示的なユーザーコマンドなしにセッションを放棄するのは、7日間のサーバーサイドスイープだけです。

完全なライフサイクル契約（キャプチャルール、フォーカスセマンティクス、ブリーフィング）はdocs/MCP_TOOLS.mdにあります。契約はv4であり、まだ進化中です。

設定 (.env)

# Required
POSTGRES_URL=postgresql+asyncpg://brain:REPLACE_WITH_PASSWORD@localhost:5433/brain

# Optional — semantic search and reranking
EMBEDDING_SERVICE_URL=http://localhost:8003
EMBEDDING_DIMENSION=1536
RERANKER_URL=http://localhost:8003

# Optional — relationship graph (safe defaults for a fresh environment)
GRAPH_ENABLED=false
GRAPH_LEDGER_WRITE_ENABLED=false

# Tool catalog profile
BRAIN_MCP_PROFILE=compact   # compact (default) or native

LOG_LEVEL=INFO

MCP_HTTP_TOKENやMCP_HTTP_DREAM_TOKENSを共有の.envに置かないでください。ベアラートークンはプライベートな0600ファイル（~/.config/brain-v42/mcp-token.env）に置き、グラフプロジェクターの認証情報は専用のファイル（~/.config/brain-v42/graph-projector.env）に置きます。完全なリファレンス — すべての変数、プライベートな秘密ファイル、事前チェック、ロールアウトゲート： docs/OPERATIONS.md。

ネットワーク信頼モデル

このデプロイは、信頼できるLAN上の個人エージェントを対象としています。MCP、PostgreSQL、Neo4jはループバックにバインドされ、メトリクスと自動化もデフォルトでループバックです。

埋め込みトポロジー：本番/デフォルト = ローカル統合エンドポイント http://localhost:8003; deploy/dev-pcは置き換えられたロールバック/リファレンスパスです。

リランカーは統合埋め込みエンドポイント:8003/rerankを共有します。自分で実際のバインドを確認するまで:8003はLANに公開されているものとして扱い、インターネットには決して公開しないでください（MCPポートも同様です）。リポジトリのコードだけでは、実際のファイアウォールの状態を証明できません。

Dreamモード

夜間のエージェントパイプライン（scripts/dream.sh：スキャン → クリーン → 接続 → 統合 → プロモート → 再編成）に加え、サーバーサイドのチケット抽出、ロードマップキュレーション、セッションスイープジョブがあります。変更を伴うすべてのフェーズはキルスイッチの背後にあり、すべてのキルスイッチは初期状態で無効化されています。ドライランが標準のデフォルトです。各フェーズは正確なMCPツール許可リストの下で実行されます。詳細： docs/ARCHITECTURE.md と docs/OPERATIONS.md。

本番状態

リポジトリのマイグレーションターゲットはマイグレーション045です。このリポジトリのどのページも、実際のスキーマヘッドを証明するものではありません — ここで読むのではなく、測定してください：

docker exec brain_v42_postgres psql -U brain -d brain -Atc "select version_num from alembic_version;"

実行中のビルドはそれ自体を名乗ります。GET /healthはversion（インストールされたディストリビューション）とalembic_head（それに同梱されるリビジョン）を返します。どちらも測定された値であり、手書きされることはありません。

開発

pytest tests/unit -v                          # no PostgreSQL required
pytest --cov=brain_v42 --cov-report=term-missing
ruff check src/ tests/ && ruff format --check src/ tests/
mypy src/

• スタック: Python 3.12+、FastMCP 3.x、SQLAlchemy 2.0 async + asyncpg、Alembic、Pydantic 2、structlog。

• TDDは必須 — レッド、グリーン、リファクタリング。コードを通過させるためにテストを編集することは決してありません。

• カバレッジ下限: 60%（CIがそれ未満をブロックします）。

• 開発ツールチェーンは正確に固定されています（pip install -e ".[dev]"）。これにより、ローカルは常にCIと一致します。

プロジェクト構成

brain-v42/
├── src/brain_v42/
│   ├── config.py              # pydantic-settings — single config surface
│   ├── db/                    # SQLAlchemy engine + tables
│   ├── models/                # Pydantic models
│   ├── repositories/          # CRUD + FTS + pgvector + graph adapters
│   ├── services/              # business logic, embedding, reranker, dream, dedup
│   ├── metrics/               # sidecar + collector + cockpit endpoint
│   ├── automation/            # independent webhook/dedup runtime (:9201)
│   └── mcp/                   # FastMCP server + brain_*/dream_* tool handlers
├── tests/{unit,integration}
├── alembic/versions/          # migrations (shipped inside the wheel)
├── scripts/                   # operational CLIs (dream.sh, canaries, repair)
├── services/                  # GPU embedding service + shim + supervisor
├── deploy/                    # systemd units, per-host compose, install.sh
└── docs/                      # ARCHITECTURE, SCHEMA, MCP_TOOLS, OPERATIONS, runbooks

CIではトップレベルのモジュールグラフが非巡回であることが強制されます（scripts/check_module_layering.py）。これにより、どのモジュールもサイクルを引きずらずにスタンドアロンサービスとして抽出できます。

CI/CD

ステージ：lint → test → security → build。セキュリティゲート：pip-audit、bandit、gitleaks、コンテナイメージのピン留めチェック。Dockerイメージはmain上でビルドされプッシュされます。デプロイステージはありません。ホストへのロールアウトは常に手動の帯域外ステップです。リリースはタグ駆動です。リリースレールはwheel + sdistをビルドし、wheelがマイグレーションを同梱していることを証明し、両方をGitHubリリースに添付します。

バージョニング

• 出荷バージョンは0.2.0であり、意図的に0.xのままです。1.0.0は安定したインターフェースと後戻りの道を約束することになりますが、このプロジェクトにはそのどちらもまだありません。

• どのバージョンでも、ロスレスなダウングレードは保証されません。 2つのマイグレーションは自身のdowngradeを拒否します。037はセッションキャプチャが失われるとすぐにSQLEXCEPTIONを発生させ、039はオペレーターが明示的な-xオプトインを渡さない限り発生させます。

• したがって、スキーマのロールバックはランブックを伴うオペレーター手順であり、バージョン保証ではありません。代わりにスナップショットから復元してください。

ライセンス

ソースコード： Apache-2.0。

モデルの重みはそのライセンスの対象ではありません。これは形式的なものではありません。本番用埋め込みモデル Qodo/Qodo-Embed-1-1.5B は、QodoAI-Open-RAIL-M の下で公開されています — これは、使用に基づく制限を伴うライセンスであり、寛容なライセンスではありません。このリポジトリには重みは保存も配布もされていません：すべてのモデルは、ビルド時にオペレーターがアップストリームのホストからダウンロードし、各モデルの規約をその発行元から直接受け入れます。再配布する前に NOTICE を参照してください。