PersonaMCP

PersonaMCP

AI エージェントのコミュニケーションスタイルと記憶。

PersonaMCP は会話のエクスポートデータをインポートして、あなたの文章の書き方を測定し、AI エージェントにコンパクトなスタイルプロファイルと、関連する受信メッセージ／返信の例を提供します。生の履歴はお使いのコンピューター上に保存されます。モデルのトレーニング、ウェブダッシュボード、クラウドでの埋め込み処理は不要で、テレメトリーや自動返信生成もありません。

文章の好みはあいまいになりがちです。「くだけた感じに」と伝えるだけでは、すべて小文字で書く、短いメッセージを3つ送る、言語を切り替える、同僚には違う書き方をするといった特徴は伝わりません。PersonaMCP は、推測された性格ではなく、根拠に基づいた情報を、接続されたライティングエージェントに提供します。

インストール

Python 3.11 以降が必要です。PyPI からインストールします。

python -m pip install personamcp
persona --help

または、uv を使ってインストールせずに実行できます：uvx personamcp --help。

このリポジトリのチェックアウトから作業する場合：

git clone https://github.com/robyroro/PersonaMCP.git
cd PersonaMCP
uv sync --locked
uv run persona --help

または、独自の仮想環境にインストールします：

python -m venv .venv
# Linux/macOS: source .venv/bin/activate
# Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install .
persona --help

uv のチェックアウトでは、以下の persona コマンドの先頭に uv run を付けてください。pip でインストールして仮想環境を有効化している場合は、persona を直接実行します。

基本インストールでは、インポート、分析、FTS 検索、語彙ベースの会話検索、MCP に対応しています。セマンティック検索はオプションで、すべてローカルで処理されます。

初期化とインポートの後（以下で説明します）：

uv sync --locked --extra semantic
uv run persona model prepare
uv run persona index

pip の場合は、python -m pip install '.[semantic]' を実行します。モデルの準備では、Hugging Face から重みを明示的にダウンロードし、変更できないリビジョンに固定します。チャットを読み取ったり送信したりすることはありません。インデックス作成とその後のクエリでは、リモートコードを無効にした状態でローカルファイルのみを読み込みます。

クイックスタート

persona init
persona config set-name "Robert"
persona config add-alias "roby"
persona config set-name "Exact Instagram display name" --platform instagram
persona config set-name "snapchat_username" --platform snapchat

persona import instagram ./instagram-export/
persona import snapchat ./snapchat-export/
persona import whatsapp ./chat.txt
persona import json ./messages.json

persona stats
persona analyze
persona search "cat costa"
persona similar "mai vii azi?" --person "David"
persona writing-context "ce faci diseara?" --person "David" --platform instagram

合成データで最初に試す場合は、専用のデータディレクトリを使用してください。

persona --home ./sample-persona init
persona --home ./sample-persona config set-name "Owner"
persona --home ./sample-persona import json ./examples/messages.json
persona --home ./sample-persona analyze
persona --home ./sample-persona writing-context "mai vii azi la cafea?" --person "Alex"

プライベートなインポートデータとカスタムデータディレクトリは、リポジトリの外部に置いてください。付属の .gitignore では一般的な名前のプライベートフォルダーを対象にしていますが、任意の名前のパスをすべて保護できるわけではありません。

ID には、エクスポートデータに含まれる送信者名または送信者 ID と完全一致する値を指定する必要があります。そのプラットフォーム上では、プラットフォームのエイリアスがグローバル名より優先されます。メッセージ量を基準に参加者が推測されることはありません。所有者のメッセージに一致しないインポートは、何も書き込む前に失敗します。名前やエイリアスを変更すると、所有者と会話の再計算が行われ、プロファイルとベクトルが無効化されます。再度 analyze と index を実行してください。

対応しているインポート形式

プラットフォーム	対応する入力形式	備考
Instagram	message_N.json または現在の Meta の message_N.html フォルダー	ページ分割されたデータは統合されます。一般的な JSON の Unicode 破損は修復されます。HTML のスクリプト、リンク、メディアが実行されることはありません。
Snapchat	chat_history.json、対応するチャットカードの HTML サブページ、または元の ZIP エクスポート	受信者キー形式とネストされた JSON レイアウトに対応しています。ZIP は展開せずに読み込まれます。重複する HTML より JSON が優先されます。
WhatsApp	UTF-8 TXT、Android 形式、および角括弧付きの iOS タイムスタンプ	スラッシュ区切りの日付に対応しています。既定では日／月形式で、米国向けエクスポートには --month-first を使用します。複数行のテキストは保持されます。システム通知やメディア通知は文体の対象外です。
汎用	JSON の会話オブジェクト、conversations オブジェクト、メッセージ配列、または JSONL	以下のスキーマを参照してください。

チャットファイルのみがインポートされます。メディアが開かれたり、文字起こし、ダウンロード、分析されたりすることはありません。対応していない形式は、明確なエラーを返します。ファイルが不正な場合、インポート全体がロールバックされます。元のファイルは変更されません。コンテンツハッシュと安定したメッセージ ID により、再インポート時の行の重複を防ぎます。

WhatsApp には安定したエクスポートスレッド ID がありません。既定ではファイル名が会話を識別します。名前を変更したエクスポートや更新されたエクスポートをインポートする場合は、--conversation-id "stable-chat-name" を使用してください。 タイムゾーンオフセットのないタイムスタンプには、壁時計の順序付けに関する仕様として文書化された UTC 規約が適用されます。記録時刻が UTC だったと主張するものではありません。Instagram／Snapchat の HTML 形式では、英語のエクスポート日付に対応しています。

汎用 JSON：

{
  "id": "stable-conversation-id",
  "platform": "json",
  "title": "Alex",
  "participants": ["Owner", "Alex"],
  "context": "casual",
  "messages": [
    {"id": "external-message-id", "sender": "Alex", "sender_id": "account-123",
     "text": "mai vii azi?", "timestamp": "2024-01-01T10:00:00Z"},
    {"sender": "Owner", "text": "da gen vin acu", "timestamp": "2024-01-01T10:00:10Z"}
  ]
}

JSONL では、各行が sender、text、timestamp と、任意の conversation_id を持つメッセージです。任意の外部 ID と reply_to も保持されます。汎用の話者識別には、設定済みのエイリアスのみが使用され、インポートされた is_user の指定は使用されません。異なるデータセットをインポートする場合は、明示的な会話 ID を使用してください。ID がない場合は、仕様として文書化された default の会話が使用されます。

測定内容

persona analyze は、プライベートデータディレクトリに persona.md と persona-profile.json を書き込み、構造化されたプロフィールを SQLite に保存します。分析に使われるのは送信テキストのみです。受信テキストは、上限を設けた検索用コンテキストとして保持されます。

測定項目には、文字数・単語数・文の長さ、短いメッセージの連続、大小文字の使い分け、句読点、絵文字のコードポイント、繰り返し文字、よく使われる単語やフレーズ、繰り返し使われるスラングや略語の表記、あいさつ、結びの言葉、ルーマニア語のダイアクリティカルマーク、ルーマニア語／英語の単語マーカーが含まれます。 言語マーカーはヒューリスティックであり、言語分類器ではありません。絵文字のカウント対象はコードポイントであり、完全な書記素クラスタではありません。繰り返し使われるフレーズや表記は、少なくとも3回確認された場合に対象となります。単発の誤字は、意図的に誤字を加える指示ではありません。

コンテキストラベルは明示的に指定でき、拡張可能です。

persona conversations
persona set-context CONVERSATION_ID business
persona set-context OTHER_ID casual
persona analyze
persona person "David"

グローバルプロフィールでは、利用可能な送信テキストが常に使用されます。コンテキスト別／人物別のプロフィールには、既定で少なくとも20件のメッセージが必要です。その場で人物統計を取得する場合は、根拠となるメッセージ数が報告されます。家族関係、交際関係、性格、皮肉、心理に関する分類が推定されることはありません。複数のプラットフォームで同じ名前が使われている場合があります。その区別が重要なときは、検索や執筆コンテキストの取得時にプラットフォームを指定してください。

検索とセマンティック検索

SQLite FTS5 は、送信メッセージと受信時のやり取りのコンテキストを検索します。やり取りには、最大3件の受信メッセージと、最大8件の連続する送信返信が保持されます。2時間の空白、またはメディアの記録があるとペアリングは中断されます。送信メッセージの連続は、メッセージ間が最大5分の範囲に収まります。

ローカルのセマンティックプロバイダーは sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 を使用します。受信時のコンテキストを埋め込み、float32 ベクトルを SQLite に保存します。クエリでは対象となるベクトルをすべて走査してコサイン類似度を正確に計算します。これは、外部のベクトルサーバーよりシンプルなローカルアーキテクチャを優先するためです。インデックス作成は、中断後に再開されます。ランキングの前に、受信者／コンテキスト／プラットフォームのフィルターが適用されます。

対象となるベクトルがない場合、検索結果には明示的に lexical と表示されます。構築途中のインデックスでは、そのカバー範囲が報告されます。0.25未満のセマンティックスコアは除外されます。これらのスコアは確率でも、関連性を保証するものでもありません。別の受信者への暗黙のフォールバックはありません。今後、EmbeddingProvider プロトコルを実装するプロバイダーを、インポートや書き込みのインターフェースを変更せずに追加できます。

MCP のセットアップ

このサーバーは、公式の Python MCP SDKと stdio トランスポートを使用します。標準出力にはプロトコルメッセージのみが出力され、診断出力は標準エラー出力に送られます。

persona serve

データディレクトリがまだ初期化されていない場合、serve は persona init と同じ方法でディレクトリを作成し、その旨を標準エラー出力に表示します。エクスポートをインポートするまでは、ツールは空の結果を返します。通常、このコマンドはクライアントが起動します。クライアントの作業ディレクトリはターミナルのものと異なる場合があるため、絶対パスを使用してください。一般的な mcpServers 構造を使用するクライアントの設定例：

{
  "mcpServers": {
    "personamcp": {
      "command": "/absolute/path/to/venv/bin/persona",
      "args": ["--home", "/absolute/path/to/private/persona-data", "serve"]
    }
  }
}

uv がインストールされていれば、クライアントから公開済みパッケージを直接実行できます：

{
  "mcpServers": {
    "personamcp": {
      "command": "uvx",
      "args": ["personamcp", "--home", "/absolute/path/to/private/persona-data", "serve"]
    }
  }
}

Windows では、コマンドは C:\\absolute\\path\\.venv\\Scripts\\persona.exe です。Codex の場合：

codex mcp add personamcp -- /absolute/path/to/venv/bin/persona --home /absolute/path/to/private/persona-data serve
codex mcp list

Codex MCP のセットアップを参照してください。他のクライアントでは設定場所が異なる場合がありますが、実行ファイルと引数は同じものが必要です。リモート HTTP MCP のみをサポートするホステッドクライアントから、このローカルの stdio サーバーを直接起動することはできません。PersonaMCP にはトンネル／HTTP ブリッジは含まれていません。機密性の高いローカルデータをリモートから公開するには、別途、明示的なデプロイの判断が必要です。

セマンティックモデルの準備ができている場合でも、マシンの処理速度が遅いときは、起動に最大90秒、ツールの実行に最大120秒を見込んでください。Windows での BLAS ローダーのデッドロックを避けるため、stdio のリーダースレッドが起動する前に、ネイティブ数値ランタイムが読み込まれます。重みは最初のセマンティッククエリ時に読み込まれ、キャッシュされます。Codex では、これらの設定をサーバーの設定テーブルに記述します：

[mcp_servers.personamcp]
command = "/absolute/path/to/venv/bin/persona"
args = ["--home", "/absolute/path/to/private/persona-data", "serve"]
startup_timeout_sec = 90
tool_timeout_sec = 120

ツール：

ツール	結果
get_style_profile(context?)	全体または指定したコンテキストの測定済みプロフィール
get_person_style(person)	正確に一致する人物のコミュニケーション統計と証拠数
search_messages(query, person?, platform?, limit?)	件数を制限した送信テキストの一致結果
find_similar_interactions(message, person?, context?, platform?, limit?)	類似する実際の受信／返信ペア
get_writing_context(message, person?, context?, platform?)	適切な文体と、引用例（最大3件）
get_persona_summary()	プロフィールとデータベース件数の概要

過去のコンテンツは historical_quote 内に、信頼できないデータであることを明示する注意書きとともに返されます。ツールが提供するのは証拠です。最終的な返信はエージェントが生成し、過去の指示をデータとして扱うこと、およびモデルプロバイダーに何を送信するかを判断する責任を負います。

スキルのセットアップ

再利用可能なスキルはskills/write-like-me/SKILL.mdです。wheel にも含まれており、persona skill-pathを実行するとインストール先が表示されます。そのフォルダーを、エージェントが検出するスキルディレクトリにコピーしてください。現在の Codex のリポジトリ検出先は次のとおりです。

mkdir -p .agents/skills
cp -R skills/write-like-me .agents/skills/

Windows PowerShell の場合は、New-Item -ItemType Directory -Force .agents/skillsを実行してから、Copy-Item -Recurse skills/write-like-me .agents/skills/を実行します。Codex のスキル検出を参照してください。

次に、接続されたエージェントにwrite-like-meを使うよう依頼します。たとえば次のようにします。

PersonaMCP の根拠を使って、「mai vii azi la cafea?」について、私らしい短い Alex への返信を書いてください。

このスキルは、誤字を強制したり古い事実をコピーしたりせずに、対応する大文字・小文字の使い分け、スペル、語彙、文の長さを維持します。また、ローカルシェル経由でpersona writing-contextを使用することも、MCP が利用できない場合に明示的に指定されたプロファイルを使用することもできます。インストールによって、クライアントのグローバル設定が変更されることはありません。

プライバシーとデータ管理

デフォルトのデータディレクトリは、オペレーティングシステムのアプリケーションデータの場所から取得されます。--home /private/pathまたはPERSONAMCP_HOMEで別の場所を指定できます。設定はローカルのconfig.jsonに保存されます。データベースでは、SQLite の外部キー、バージョン管理されたスキーマ、トランザクションによるインポートを使用します。

persona stats --json
persona export-profile ./my-style.md
persona export-profile ./my-style.json --json
persona delete-person "Name"
persona delete-conversation CONVERSATION_ID
persona reset

削除やリセットの際は確認が求められます。意図したスクリプト実行には--yesを使用できます。人物を削除すると、その人物を含むグループの会話も含め、会話全体が削除されます。その人物に関するコンテキストが残らないようにするためです。プロファイル、FTS の行、ベクトルは無効化または消去され、SQLite はバキュームされます。resetは設定済みの所有者 ID も消去しますが、ダウンロード済みの個人情報を含まないモデルアセットは保持します。元のエクスポートファイルやコピーしたプロファイルは引き続き管理下にあり、削除されません。

SQLite は暗号化されていません。プライベートなデータディレクトリとディスク暗号化を使用してください。生成された語彙や例も機密情報です。エージェントが外部 LLM を使用する場合、ツールの結果がそのプロバイダーに送信される可能性があります。「ローカル優先」とはストレージと計算処理についての説明であり、接続されたクライアントの動作を指すものではありません。削除とプロンプトインジェクションの制限については、SECURITY.mdをお読みください。

オフラインベンチマーク

persona benchmark --limit 30

タイムスタンプ順で最後の 20% のやり取りをホールドアウトデータとします。検索とスタイルプロファイルには、それより前のデータのみを使用します。実際の返信のうちホールドアウトされたものは、スコアリングにのみ使用します。デフォルトの候補は検索された過去の返信であり、LLM が生成した回答ではありません。

レポートには、検索の網羅率、返信の長さの類似度、語彙の重複度、句読点の類似度、大文字・小文字の類似度、およびそれらの平均であるスタイル類似度スコアが含まれます。ローカルモデルが利用可能な場合は、埋め込みの類似度も別途報告されます。ベンチマークの生の返信は出力されません。CandidateResponseProviderは、将来、明示的に設定された生成器を追加するための拡張ポイントです。スコアは、人物の文体の模倣、著者、関連性、生成品質を証明するものではありません。データセットが小さい場合や、期間の偏りがない場合、この評価は行えません。

アーキテクチャ

exports → platform adapters → normalized conversations/messages
                                  ↓
                      SQLite + participants + FTS5
                                  ↓
                   bounded incoming/outgoing interactions
                         ↙                    ↘
              deterministic profiles      local embedding vectors
                         ↘                    ↙
                        retrieval/service layer
                            ↙           ↘
                         CLI          MCP stdio → writing skill → agent

このパッケージはsrc/personamcpレイアウトを使用しています。インポーター、モデル、設定、ストレージ、分析、埋め込み、検索、共有サービス、MCP サーバー、CLI、ベンチマークが含まれます。外部データベースや LLM プロバイダーは必要ありません。スキーマの互換性はPRAGMA user_versionで管理されます。古いバージョンのデータベースを受け取った場合、読み取り方法を推測するのではなく、新しいデータベースとして拒否します。

開発、ロードマップ、制限事項

uv sync --locked を実行し、続けて uv run pytest、uv run ruff check src tests、 uv run ruff format --check src tests、uv run mypy src を実行してください。CI では Windows/Linux と Python 3.11～3.13 をチェックし、個人データやモデルのダウンロードは使用しません。公開されているフィクスチャは合成データです。CONTRIBUTING.md、CODE_OF_CONDUCT.md、実装上の判断を参照してください。

次のステップとして、追加のエクスポートアダプター（Discord、Telegram、Messenger、iMessage、Signal）、明示的な墨消しルール、非常に大規模なアーカイブ向けの高速なローカルベクトルインデックス、より豊富な言語シグナル、任意の生成ベース評価を予定しています。これらはMVPでは実装されていません。

このバージョンはCLI/MCPエンジンです。エクスポートスキーマは変更される場合があります。グループの受信者推定、心理プロファイリング、自動誤字修正、音声・メディア分析、保存データの暗号化、クラウド埋め込みプロバイダー、HTTPホスティング、フロントエンドは、現在のサポート対象外です。

MITライセンス © Robert Vind-Gardoș (@robyroro)。モデルの重みと依存関係にはそれぞれ独自のライセンスが適用されます。多言語MiniLMモデルカードおよびSentence Transformersドキュメントを参照してください。