brain-core

brain-core

セッションが終わっても残る、Claude Code エージェントのためのメモリです。 ローカル MCP サーバーは1つ、ツールは5つ、読める Markdown ボルト、想起を検証する評価機能。コマンド1つでインストールできます。

brain-core は、ディスク上に保存される長期メモリを Claude Code エージェントに提供します。エージェントに名前を付け、自分がどんな人かを伝えると、それ以降のすべてのセッションで、前日の概要、自分が下した決定、変化した事実、伝えた修正を含む状態で始められます。メモリは、どのエディターでも開ける Markdown ファイルを書き込むことで保存され、ローカル SQLite インデックスとセルフホスト可能なベクターメモリであるHindsightを通じて、必要な情報を再び見つけます。すでに行っている LLM の呼び出し以外に、マシンの外にデータが出ることはありません。

これは、自分のコンピューターで1つ以上のエージェントを実行する個人向けです。個人開発者、創業者、毎朝プロジェクトについて説明し直すことにうんざりしている人などが対象です。ホスティングサービスでも、チーム向け製品でもありません。

MCP サーバーですか、それともツールですか？

両方です。1つの Python パッケージから、3つの方法で利用できます。

構成要素	内容	利用者
brain serve	エージェントの .mcp.json から Claude Code が起動する MCP サーバーで、5つのツールを公開します	毎回のセッションで、何も操作することなくエージェントが利用します
brain コマンド	CLI：brain init、brain doctor、brain index、brain hindsight install、brain cron install、brain daily、brain weekly	初期設定時はユーザーが、その後は cron が利用します
brain_core.Agent	上記2つの基盤となる Python ライブラリです	評価ランナー、デモスクリプト、独自のスクリプトが利用します

Claude Code ユーザーにとっては、5つのメモリツールと1行のインストーラーを備えた MCP サーバーです。Python 開発者にとっては、MCP フロントエンドを備えたメモリライブラリです。

curl -fsSL https://raw.githubusercontent.com/xy-claude/brain-core/main/install.sh | bash -s -- --agent Atlas --user Alex

---

課題

コーディングエージェントとのセッションは、毎回ゼロから始まります。プロジェクトについて、先週下した決定について、火曜日に間違えたことについて、何度も説明しなければなりません。メモリを追加する製品はありますが、メモを他社のクラウドに保存し、エージェントが使い分けられない30個ものツールを公開し、評価結果を見せることもありません。

brain-core はその正反対です。ローカルで、ツールは5つ、自分で所有できる Markdown ファイルを使い、ヒット率を報告するテストスイートを備えています。

仕組み

1. brain init はエージェントのフォルダーを作成します。 エージェント名とあなたの名前を記した CLAUDE.md、5つのルールファイル（identity、doctrine、authority、memory、system）、3つのスキル、安全フック、.mcp.json、空の vault を作成します。Claude Code はこのフォルダーをプロジェクトとして読み込むため、エージェントは最初のメッセージからメモリの使い方を把握しています。
2. brain serve は Claude Code 内で MCP サーバーとして動作します。 5つのツールだけを公開します。エージェントはほかのツールと同じようにこれらを呼び出すため、手動で実行する必要はありません。
3. すべてのセッションには決まった流れがあります。 エージェントは brain_session('start') で開始します。これにより、今日のブリーフ、エグゼクティブ状態、メンタルモデル、有効なミッションごとのリコール、前回のセッションがクラッシュしたかどうかを示すフラグが、1つのブロックとして返されます。brain_session('end') で終了すると、その日のアーカイブが保存され、翌日に向けて状態が書き換えられます。
4. メモリは推測されるのではなく、書き込まれます。 残しておく価値のあることを伝えると、エージェントは brain_remember(text, kind) を呼び出します。テキストはまず vault に書き込まれ、次に SQLite インデックス、Hindsight、関係テーブルの順に記録され、各レイヤーで何が行われたかが応答に示されます。重複はスキップされます。事実の値が変わると ⚠ Fact changed バナーが表示され、古い行も残るため、履歴を確認できます。
5. リコールでは、すべてのストアを一度のクエリで検索します。 brain_recall(query) は vault、インデックス、Hindsight を一度に検索し、重複を除去し、関連度と新しさで順位付けして、応答を6kトークンに制限するため、コンテキストがあふれることはありません。
6. 2つの cron ジョブがメンテナンスを行います。 brain daily は翌朝のブリーフを作成し、Hindsight をバックアップします。brain weekly は30日を超えるセッションを月次サマリーにアーカイブし、メンタルモデルを更新します。

flowchart LR
    CC[Claude Code] -->|MCP, 5 tools| B[brain serve]
    B --> V[(vault/ markdown)]
    B --> S[(brain.db SQLite + FTS)]
    B --> H[(Hindsight vector memory)]
    B --> G[(relations table)]
    CRON[brain daily / weekly] --> V
    CRON --> H

5つのツール

ツール	1回の呼び出しで行うこと
brain_session('start')	開始ブロック全体を返します。日次ブリーフ、エグゼクティブ状態、メンタルモデル、ミッションごとのリコール、受信トレイの件数、前回のセッションがクラッシュしたかどうかを示すフラグが含まれます
brain_recall(query, scope)	すべてのストア、このフォルダーの Claude Code トランスクリプト、および含まれている stores.notes フォルダーを一度のクエリで検索し、重複を除去して関連度と新しさで順位付けし、6kトークンに制限します。scope='transcript' は過去のセッションでの発言や実行内容を検索するもので、初日から役立ちます
brain_remember(text, kind)	vault → SQLite → Hindsight → グラフの順に書き込み、各レイヤーの処理内容を報告します。類似した重複はスキップされ、値が変わると ⚠ Fact changed バナーが表示され、古い行も残ります
brain_distill(source)	URL、GitHub リポジトリ、YouTube 動画、PDF、ファイル、または貼り付けたテキストを、エージェントがまとめられるよう不変の raw/ フォルダーに保存します
brain_session('end')	キューを処理し、その日のセッションファイルを閉じ、状態と振り返りを書き換え、正常終了マーカーを書き込みます

さらに、1回の呼び出しで状態を確認できる brain_status() もあります。各ストアが稼働しているか、常時読み込まれるコンテキストに必要なトークン数、セッションが開いているか、あなたの判断待ちの項目を確認できます。

インストール

始める前に

必要なもの	理由	確認方法
macOS、または systemd を備えた Linux	インストーラーがバックグラウンドサービスと cron を設定します	uname
ディスク容量約2 GBと10分	Hindsight には埋め込み型 Postgres と CPU 向け埋め込みモデルが含まれます
Anthropic API キー、または Claude Code ログイン	Hindsight は LLM を使ってメモリを推論します	echo $ANTHROPIC_API_KEY
Claude Code	エージェントはその中で動作します。不足している場合はインストーラーが追加します	claude --version

コマンドを実行する前に、名前を2つ決めてください。1つはエージェントの名前（--agent）で、フォルダー名とアイデンティティになります。もう1つはあなたの名前（--user）で、エージェントがあなたを呼ぶときに使います。どちらも後から CLAUDE.md を編集して変更できます。

macOS、1 行で

curl -fsSL https://raw.githubusercontent.com/xy-claude/brain-core/main/install.sh | bash -s -- --agent Atlas --user Alex

実行される処理は以下の順です。再実行時は、すでにあるものはスキップされます。そのため、失敗した場合は原因を解消して、同じ行をもう一度実行してください。

== 1/8 Xcode command line tools      present
== 2/8 Homebrew                      present
== 3/8 uv, gh, gitleaks, node, Claude Code
== 4/8 brain-core (v0.4.0)           installed with uv tool
== 5/8 Agent Atlas at ~/Agents/Atlas  31 files written
== 6/8 Hindsight (required store)    service: healthy
== 7/8 Cron                          daily 06:07, weekly Sun 07:13
== 8/8 Doctor                        Health check: OK

手順	処理内容	ここで停止した場合
1	Xcode のコマンドラインツールを通じて git があるか確認します	macOS にインストールダイアログが表示されます。完了してから再実行してください
2	Homebrew がない場合はインストールします	Homebrew がパスワードを求めます
3	Homebrew で uv、gh、gitleaks、node、Claude Code をインストールします	すでにインストールされているものはそのまま残ります
4	uv tool を使って PyPI から brain コマンドをインストールします	--ref v0.4.0 を指定すると、代わりに git タグを固定します
5	brain init を実行し、エージェントのフォルダーを書き込みます	既存の brain.yaml が上書きされることはありません
6	Hindsight を 127.0.0.1:8888 の launchd サービスとしてインストールします	初回起動時に埋め込みモデルがダウンロードされます。数分お待ちください
7	brain daily と brain weekly を launchd エージェントとしてインストールします
8	新しいエージェントで brain doctor を実行します	いつでも brain doctor ~/Agents/Atlas で再実行できます

インストーラーの実行後

インストーラーでは代わりに実行できないことが 2 つあります。

export ANTHROPIC_API_KEY=sk-ant-...     # add it to ~/.zshrc too
brain hindsight install                 # copies the key into ~/.config/hindsight/env (mode 600) and restarts the service
claude                                  # sign in to Claude Code once

実行時にシェルにキーが設定されていなかった場合、インストーラーはその旨を表示します。API キーを使わない場合は、--provider claude-code を渡すと、Hindsight は代わりに Claude Code のログイン情報を使用します。このモードは個人利用のみを対象としています。

フラグ	意味
--agent NAME	エージェントの名前（必須）
--user Alex	エージェントがあなたを呼ぶときの名前
--dir PATH	エージェントの保存場所。デフォルトは ~/Agents/NAME
--provider	anthropic（デフォルト）、openai、または claude-code（Claude Code のログイン情報を使用。個人利用のみ）
--api-key-env VAR	<PROVIDER>_API_KEY 以外の変数からキーを読み込みます
--profile DIR	独自の指針を設定するため、一般的なルールの後にコピーされるフォルダー
--dashboard	Hindsight の Web UI（http://localhost:9999）
--ref v0.4.0	PyPI リリースの代わりに git タグを固定します

Linux

同じ 1 行で実行できます。あらかじめ git と curl がインストールされている必要があります。その後、astral.sh から uv をインストールし、node がある場合は npm で Claude Code をインストールします。Hindsight は systemd --user サービスとして実行し、2 つのジョブはユーザーの crontab にタグ付きの行として書き込みます。再実行時には、その行を見つけて置き換えられます。

手動でのインストール（すべてのプラットフォーム）

uv tool install brain-core-mcp   # or: uv tool install git+https://github.com/xy-claude/[email protected]
brain init Atlas --path ~/Agents/Atlas --user Alex
brain hindsight install          # launchd on macOS, systemd --user on Linux
brain cron install ~/Agents/Atlas
brain doctor ~/Agents/Atlas

正しく動作したか確認する

brain doctor ~/Agents/Atlas

エージェント名、設定ファイルのパス、テーブルごとの行数、Health check: OK が表示されます。ストアのヘルス状態は、最初の brain_session('start') の応答と brain_status() に表示されます。よくある問題は次のとおりです。

症状	原因	対処方法
brain: command not found	uv tool の bin フォルダーが PATH に含まれていません	uv tool update-shell を実行してから、新しいターミナルを開いてください
ERROR: no brain.yaml at ...	パスが間違っています	エージェントのフォルダー、またはその中の brain.yaml を指定してください
hindsight unreachable at http://127.0.0.1:8888	サービスの起動中か、インストールされていません	1 分ほど待ってください。それでも接続できない場合は、brain hindsight install を実行してください
インストーラーのメッセージ ANTHROPIC_API_KEY is not set in this shell	サービスのインストール時にキーがシェルに設定されていませんでした	キーをエクスポートしてから、brain hindsight install を再実行してください。~/.config/hindsight/env が書き換えられます
Claude Code に brain ツールが表示されない	エージェントのフォルダーの外から起動しました	cd ~/Agents/Atlas && claude を実行し、次に /mcp で確認してください

初回セッション

cd ~/Agents/Atlas && claude

エージェントの CLAUDE.md では、brain_session('start') で開始するよう指示しています。実行すると、次のように返ってきます。

{
  "session_id": "s-20261102-a1b2c3",
  "brief": "# Daily Brief — 2026-11-02 ...",
  "executive_state": "## Primary Objective ... ## Top Missions ... ## Pending Decisions ...",
  "mental_models": {"active-priorities": "..."},
  "missions": {"M-001 first mission": [ ...3 recall hits... ]},
  "inbox": 0,
  "recovery": null
}

初日はブリーフが空で、エグゼクティブ状態はテンプレートです。これは想定どおりです。最初のセッションでは、プロジェクトや技術スタック、すでに決めたこと、好みの作業方法など、取り組んでいる内容をエージェントに伝えてください。重要な発言はそれぞれ brain_remember の呼び出しになり、応答には各レイヤーで行われた処理が表示されます。

{"status": "written", "layers": {"vault": {"status": "written", "detail": "facts.md › System"},
                                 "sqlite": {"status": "written"},
                                 "hindsight": {"status": "written", "detail": "op 162bdbaa"}}}

最初のセッションで試してみること：

• 事実を伝えてから、変更する。「API は 8887 でリッスンしています」。その後で「訂正です。8888 です」。2 回目の書き込みでは ⚠ Fact changed バナーが表示され、vault/facts.md には両方の行が残ります。
• 情報源を渡す。 URL または GitHub リポジトリを貼り付け、要点をまとめるよう依頼します。ページはそのまま vault/raw/ に保存され、エージェントが vault/knowledge/ にページを作成します。
• 以前の内容について尋ねる。「データベースについて何を決めましたか？」という質問は 1 回の brain_recall 呼び出しで処理され、各ヒットには出典ファイルが表示されます。
• エディターでボールトを開く。 先ほど確認した書き込みはすべて、Markdown ファイルの行として記録されています。エージェントが間違えた場合は、編集してください。

「ありがとう、これで終わりです」と伝えると、brain_session('end') が実行されます。翌日の 06:07 に brain daily がその日の作業内容から次のブリーフを書き込み、次の claude セッションはそのブリーフとともに始まります。

エージェントフォルダーの内容

~/Agents/Atlas
├── CLAUDE.md                 identity and the five-tool protocol (3k tokens always loaded)
├── .claude/
│   ├── rules/                01-identity 02-doctrine 03-authority 04-memory 05-system
│   ├── skills/               distill, session-end, brain-check
│   └── hooks/                block-dangerous-bash.sh (rm -rf, force-push, curl|sh …)
│                             + recall of past sessions when a command fails
├── .mcp.json                 brain serve . + Hindsight
├── brain.yaml                stores, session files, cron schedule
├── vault/                    facts.md patterns.md decisions_log.md corrections.md
│   ├── sessions/             one file per day (HSAM)
│   ├── knowledge/ raw/       the LLM-wiki: immutable sources, compiled pages
│   └── executive_state.md    objective, missions, pending decisions
└── data/brain.db             SQLite + FTS5 + relations + transcript index

すべて Markdown または SQLite です。Obsidian でボールトを開いたり、grep したり、コミットしたり、行を削除したりできます。エージェントは気にしません。

動作しますか？

評価はテストスイートの一部で、CI で実行されます。

セット	ヒット数
合成フィクスチャーボールトでの 28 件の想起タスク（CI）、層別化：シングルホップ 20 件、マルチホップ 2 件、知識更新 1 件、回答保留 2 件、時間に関するタスク 3 件。それぞれ 3 回実行（pass^3）	28 / 28
作者の実際のボールトでの調整用想起タスク 20 件と保留用想起タスク 10 件、セッション 7 か月分	20 / 20 と 10 / 10
11 件の書き込みシナリオ：重複排除、値変更バナー、関係の振り分け、秘密情報の拒否	11 / 11
成長：30 日分のセッション後のフィクスチャーブレインは、初日の同じブレインよりも、妥当なすべての特性シグナルで高いスコアを示す（CI）	維持

この分類は、メモリーベンチマーク（LoCoMo、LongMemEval）が単一のヒット率では見えないと示しているものです。変更後の値は古い値より優先される必要があり、回答できない質問には何も返さず、特定の日についての質問にはその日のアーカイブを提示する必要があります。Hindsight を使った場合、想起にはクエリあたり約 1.7 秒かかります。開始時のブロック全体では約 4 秒、6k トークン未満です。

python tests/eval/run_recall.py --config ~/Agents/Atlas/brain.yaml   # your own vault

生得的なものと成長するもの、12 の特性

brain-core エージェントは 12 の特性を備えて生まれ、経験とともにそれらを伸ばします。生得的な特性は brain init に含まれ、ボールトを消去してコールドスタートしても残るものです。成長する特性はボールトに蓄積されます。brain_status() はディスク上の証拠からそれぞれのスコアを算出し、brain daily は 1 日 1 行を記録するため、数週間にわたる推移を確認できます。

メモリー	制御	社会性
ワーキングメモリー	学習	ユーザーモデル
エピソード記憶	推論と計画	権限
意味記憶	意思決定
手続き記憶	メタ認知
	実行
	目標管理

特性に単一の数値が割り当てられることはありません。それぞれサンプルサイズと判定を伴うシグナルが得られます。回答の根拠が、そのセッション中にエージェントが書いていないファイルにある場合は「妥当」、サイズや経過時間に関するものは「コスト」、まだ証拠がない場合は「保留」です。成果物の件数や自己採点はシグナルではありません。特性の一覧とその背景にある研究については、docs/TRAITS.md を参照してください。

メモリの構成

種類	保存場所	書式
事実	vault/facts.md の ## Domain 配下	- text (date)
パターン	vault/patterns.md	- **title** — text (date)
決定	vault/decisions_log.md	## date — title + Decision / Reason / Classification / Confidence
修正	vault/corrections.md	### [date] title + Error / Correction / Implied rule / Theme
メモ	vault/sessions/YYYY-MM-DD.md	HSAM セクション内の箇条書き
関係	data/brain.db	subject —[predicate]→ object
生データ	vault/raw/	sha256 付きの不変なソース。エージェントが vault/knowledge/ をコンパイルします

ルール：コンテンツハッシュによる冪等性、追記のみ、削除なし、ストアに渡される前にシークレットを拒否します。詳細は docs/VAULT_SCHEMA.md をご覧ください。

要件

• インストーラーは macOS または Linux が必要です。ライブラリと MCP は Python 3.12 が動作する環境ならどこでも実行できます
• ベクトルストアとして Hindsight（MIT）を使用します。インストールは自動で行われます。Postgres は組み込みで、埋め込み処理は CPU 上で実行されます
• Hindsight の推論には LLM キー、または個人利用には Claude Code のログインが必要です

PyPI 上のパッケージ名は brain-core-mcp です（単純な名前は無関係なプロジェクトと競合します）。コマンドは引き続き brain、インポート名は引き続き brain_core です。

ロードマップ

• 初回実行時に Hindsight を使わない SQLite 専用モード
• 既存のノートフォルダーを対象とする import

claude-mem、mem0 OpenMemory、および通常の CLAUDE.md との比較：docs/COMPARISON.md。リリース済みのマイルストーン：docs/MILESTONES.md。設計：docs/SPEC_v0.2.md。信頼できないテキストを読み取るメモリの脅威モデル：docs/THREAT_MODEL.md。

コントリビューション

Issue やプルリクエストを歓迎します。uv sync --all-extras --all-groups を実行してから、ruff check、mypy、pytest を実行してください。CONTRIBUTING.md をご覧ください。

ライセンス

MIT。