Mindtrail

---

新しいエージェントセッションは毎回、何も知らない状態から始まります。コーディング規約をもう一度説明し、好みを改めて伝え、先週決めたことを説明し直す必要があります。Mindtrail は、Model Context Protocol を通じてエージェント間で共有できる長期メモリを提供します。あるセッションが学んだことを、後続のあらゆるセッションで（どのツールでも）呼び出せます。

• 🔌 あらゆる MCP クライアントで使えます。 Claude Code、Claude Desktop、Cursor、VS Code、Codex、ご自身のエージェント間で、1 つのメモリを共有できます。
• 🏠 ローカルファーストでプライベートです。 お使いのマシン上に SQLite ファイルを 1 つ保存します。アカウントも API キーもテレメトリーも不要です。
• ⚡ コマンド 1 つでインストールできます。 PyPI と公式の MCP Registry で公開されています。uv を使えば、事前のインストールも不要です。
• 🗂️ スコープは自動的に設定されます。 リポジトリに関する情報はリポジトリに紐づき（git リモートから検出）、個人の好みはどこへ行っても引き継がれます。
• 🔎 ハイブリッド検索に対応しています。 キーワード検索（BM25）とベクトル検索を統合して順位付けし、各結果の順位付けシグナルも表示します。
• 🛡️ デフォルトで安全です。 認証情報の保存を拒否し、呼び出したメモリには信頼できないデータとして印を付け、確実に削除します。

実際に役立つのでしょうか？

Claude Code の実際のセッションを使ってテストしました。あるセッションで、ユーザーがプロジェクトに関する事実をさりげなく伝えます（「参考までに、このプロジェクトでは pnpm を使っています」）。その後、新しいセッションで、その事実に依存するタスクが与えられます（「lodash を追加するにはどうすればよいですか？」）。エージェントには Mindtrail を使うよう指示していません。

	事実を自動で保存した	後続のセッションで適用した
Mindtrail なしの Claude Code	–	0/12
mindtrail[semantic] を使った Claude Code	36/36	36/36

メモリがなければ、エージェントは毎回、いつものやり方で答えます。たとえば npm install lodash を実行したり、間違った形式のコミットメッセージを書いたり、ポート 5433 ではなく 5432 を使ったりします。Mindtrail があれば、まず確認し、プロジェクトに合った答えを得られます。これは小規模なテストであり（12 個の事実を 3 回ずつ実行、モデル 1 つ、空のリポジトリ）、大規模なコードベースでのタスク成功率を測るものではありません。 手法、生データ、再現方法。

インストール

Mindtrail には Python 3.11 以降が必要です。最も手軽な方法は uv です。uvx が Mindtrail を必要に応じてダウンロードして実行するため、クライアントに追加するだけで使えます。サーバーの初回起動時に、埋め込みモデル（約 210 MB）がバックグラウンドでダウンロードされます。

Claude Code

claude mcp add mindtrail --scope user -- uvx --from "mindtrail[semantic]" mindtrail serve

--scope user を指定すると、すべてのプロジェクトで Mindtrail を利用できます。claude mcp list で確認してください。

Cursor と VS Code

Claude Desktop、Windsurf、その他の JSON 設定クライアント

クライアントの MCP 設定に追加します（Claude Desktop の場合：Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "mindtrail": {
      "command": "uvx",
      "args": ["--from", "mindtrail[semantic]", "mindtrail", "serve"]
    }
  }
}

Codex

# ~/.codex/config.toml
[mcp_servers.mindtrail]
command = "uvx"
args = ["--from", "mindtrail[semantic]", "mindtrail", "serve"]

uv を使わない場合

pipx（または pip）で CLI を一度インストールし、クライアントから mindtrail serve を指定します：

pipx install "mindtrail[semantic]"
mindtrail init                                             # downloads the model now and prints client configs
claude mcp add mindtrail --scope user -- mindtrail serve   # Claude Code

最小限のインストールにしたい場合は、[semantic] を外してください。Mindtrail はモデルをダウンロードせず、意味ではなく単語でマッチングします（より優れたセマンティック検索を参照）。 その他のクライアントとトラブルシューティングについては、docs/integrations.md をご覧ください。

試してみる

Session 1 › FYI, this project uses conventional commits and squash merges.
Session 2 › Write a commit message for these changes.
            → the agent recalls the convention and writes "feat(api): add pagination to /orders"

アップグレード

uvx は新しいリリースを自動的に取得します（uvx --refresh ... を実行すると確認を強制します）。pipx の場合は、 pipx upgrade mindtrail を実行してください。記憶は ~/.mindtrail に保存され、アップグレード後も保持されます。 変更内容については、変更履歴をご覧ください。

日常的な使い方

特別なコマンドは必要ありません。いつもどおり作業すれば、エージェントが何を記憶するか判断します。

• 一度伝えるだけで記憶されます。 「release ブランチからデプロイします」、「unittest より pytest が好きです」、「不安定なテストはタイムゾーンのバグで、TZ=UTC に固定して修正しました」などです。エージェントはこうした事実を自動で保存します。確実に記憶させたい場合は、「覚えておいて……」と伝えてください。
• プロジェクト用と個人用。 リポジトリに関する事実は、同じ git リモートのすべてのクローンで共有されるプロジェクト領域に保存されます。「短い回答が好きです」のようなあなたに関する事実は個人用領域に保存され、すべてのプロジェクトで適用されます。
• 変化にも対応します。 「npm から pnpm に移行しました」と伝えると、エージェントは古い記憶と新しい記憶を両方残すのではなく、古い記憶を置き換えます。古い記憶は履歴として保持されますが、以後は呼び出されません。
• 記憶している内容を確認できます。 「このプロジェクトについて何を覚えていますか？」と尋ねるか、ターミナルで mindtrail list や mindtrail recall "<question>" を実行してください。
• いつでも忘れさせられます。 チャットで「ステージング URL を忘れて」と伝えるか、mindtrail forget <id> を実行してください。削除は取り消せません。
• ツールを自由に切り替えられます。 同じ Mindtrail に接続した Claude Code、Cursor、Codex は記憶を共有するため、あるツールで教えた規約はすべてのツールで認識されます。

保存に適した情報は、規約、コマンド、担当者、設定ファイルの場所、決定事項とその理由、厄介なバグの根本原因などです。コードや git の履歴にすでに記載されていることを保存する必要はありません。シークレットは自動的に拒否されます。

仕組み

エージェントは 3 つのツールを利用し、Mindtrail のサーバー指示によって使用するタイミングが示されます。

ツール	機能
remember	事実、好み、決定事項、出来事を 1 つ、プロジェクトまたは個人用の領域に保存します。古くなった記憶を置き換えるには replaces を指定します。
recall	現在のプロジェクトと個人用領域から、関連する記憶を検索します。関連する情報がない場合は何も返しません。
forget	記憶を完全に削除します。

MINDTRAIL_TOOLS=full を設定すると、さらに 4 つのツールが使えます。search_memory（領域、種類、有効性によるフィルタリング）、get_context（トークン予算内でプロンプトにそのまま使えるブロックを取得）、update_memory（バージョン履歴を残して編集）、get_memory です。

これらのツールを支えるのは、重複の統合、置き換え、有効期間、バージョン履歴、ハイブリッドランキングに対応した、十分にテストされた小規模なエンジンです。docs/architecture.md をご覧ください。

ターミナルからメモリーを管理する

mindtrail recall "how do we deploy?"   # search project + personal memory
mindtrail remember "Staging is at staging.example.com" --scope project
mindtrail list                         # newest first
mindtrail forget <id>                  # permanent delete
mindtrail export -o memories.jsonl     # everything you've stored, as JSON Lines
mindtrail doctor                       # diagnose the install

より優れた意味検索

デフォルトの埋め込みモデルは、単語や単語の一部を照合します。意味に基づいて検索する場合（「どうやってデプロイする？」→「デプロイは GitHub Actions 経由で行う」）、ローカルのニューラルモデルをインストールしてください。CPU で動作し、API キーも必要ありません。

pipx install "mindtrail[semantic]"   # or use the uvx config above
mindtrail init        # downloads the model once (~210 MB) and re-indexes existing memories

ダウンロードサイズを小さくする場合（67 MB、検索精度はやや低下します）は、 MINDTRAIL_EMBEDDING_MODEL=BAAI/bge-small-en-v1.5 を設定してください。別のモデルで保存されたメモリーは、次回サーバーの起動時に自動的に再埋め込みされます。

検索ベンチマーク

エージェントのテストについては、実際に役立つのでしょうか？をご覧ください。調整には一度も使用していない、開発者メモリーに関する質問の2つのホールドアウトセット（合計82件）での結果です（手法）。

	recall@1	recall@5	言い換えの recall@5	「何も保存されていない」と正しく回答	古い／無関係な情報の漏えい
デフォルトのインストール	58–64%	68–75%	44–46%	82–100%	0%
mindtrail[semantic]	82–90%	93–94%	85–89%	100%	0%

これは、私たちが作成した小規模な合成検索ベンチマークです。再現するには mindtrail bench を実行するか、独自のデータセットを追加してください。

Python から使用する

from mindtrail import MemoryService

memory = MemoryService.from_config()
memory.remember("The API uses FastAPI and PostgreSQL", space_id="project:shop")
print(memory.get_context("add a new endpoint", space_ids=["project:shop"]).text)

プライバシーとセキュリティ

すべてのデータは、お使いのマシン上の ~/.mindtrail/mindtrail.db に保存されます。Mindtrail は、API キー、トークン、秘密鍵と思われる内容の書き込みを拒否します。forget は削除したデータをディスク上で上書きします。また、呼び出されたメモリーは信頼されていない参照データとしてマークされるため、エージェントがその中に保存された指示に従うことはありません。問題の報告については SECURITY.md をご覧ください。

ロードマップ

• コアエンジン：ハイブリッド検索、重複排除、置き換え、有効期間、履歴
• プロジェクトのスコープ設定を自動で行う MCP サーバーと CLI
• CI の検索ベンチマークスイート（recall@k、MRR、回答保留率、漏えい率）
• PyPI と公式 MCP Registry で公開（v0.1.0）
• マルチテナント分離に対応した PostgreSQL + pgvector バックエンド
• ワンクリック OAuth コネクターを備えたホスト型リモート MCP
• Web メモリービューアー（閲覧、編集、削除、エクスポート）
• エンティティグラフ、矛盾の検出、メモリーの統合

コントリビューション

Issue と PR を歓迎します。セットアップ方法は CONTRIBUTING.md をご覧ください。スイート全体は約15秒で実行できます。Mindtrail によってコードベースを何度も説明し直す手間が省けたら、⭐ を付けていただくと、ほかの人にも見つけてもらいやすくなります。

ライセンス

MIT