CPersona

---

スタンドアロンリポジトリ — これは Claude Desktop、Claude Code、Codex CLI、Cursor、VS Code、その他すべての MCP クライアントで使用するスタンドアロン版です（登録一覧）。 ClotoCore ユーザーの場合は、代わりにアプリ内マーケットプレイス（ClotoHub）から CPersona をインストールしてください。同じリポジトリが配布されます。

プロジェクトの状況 — 2.4.x は安定版、2.6.x は現行版です。現在、本番環境での稼働実績による認定を待ちながら、すべての修正がこちらに反映されています。最初の正式版である 2.6.0 は、初回起動時にスキーマをバージョン 13 から 17 に移行し、一部のツールの動作も変更します。そのため、2.5 のストアを移行する場合は、2.5 から 2.6 へのアップグレードを確認してください。 2.5.x は候補版です。最新の系列ではなく、まだ認定されていません。特定のバージョンを指定すれば利用できます。実行するバージョンや、各系列で修正が提供される期間については、SUPPORT.mdを参照してください。 各系列の今後の予定については、ロードマップを参照してください。

2.5.2 以前からアップグレードしますか？ 2 つの点について判断が必要です。 v2.5.3 では、CPERSONA_AUTH_TOKEN が設定されていないと HTTP トランスポートは起動しません。バインド先にかかわらず、トークンを設定するか、CPERSONA_ALLOW_UNAUTHENTICATED_HTTP=true で無効化してください（理由。stdio には影響しません）。 v2.5.2 ではツールの応答形式が変更されました。ok is false を条件分岐で確認し、ok の有無にかかわらず、error を含む応答はすべて失敗として扱ってください（契約 §10）。

問題

Claude はセッションが終わるとすべてを忘れてしまいます。会話を始めるたびにゼロからのスタートとなり、プロジェクトや好み、昨日話した内容についてのコンテキストがありません。

cpersona がこの問題を解決します。ローカルの SQLite ファイルに記憶を保存し、ハイブリッド検索で取得する MCP サーバーです。Claude があなたを記憶します。Claude Desktop、Claude Code、ClotoCore（cpersona が生まれた AI エージェントプラットフォームであり、そのメモリレイヤーでもあります）、または独自のクライアントなど、MCP 互換のホストであればどれでも動作します。

クイックスタート

AI エージェントとしてセットアップしますか？
エージェントスキル — このリポジトリをクローンした場合は skills/cpersona-memory/SKILL.md — を読み、最初から最後まで手順に従ってください。インストール、埋め込みサーバー、登録に加え、クイックスタートでは省略されがちな2つの手順、つまり新しいセッションからの確認と、次のセッションがメモリを保持する agent_id を把握できるようにメモリポリシーを永続化する手順まで網羅しています。

ご自身で Claude Code を使っていますか？ 同じスキルが wheel に含まれています。cpersona をインストールしたら、次のコマンドでコピーして、"Set up CPersona." と伝えてください。

python -c "import cpersona,pathlib,shutil; s=pathlib.Path(cpersona.__file__).parent/'skills'/'cpersona-memory'; shutil.copytree(s, pathlib.Path.home()/'.claude/skills/cpersona-memory', dirs_exist_ok=True)"

1. インストール — Python 3.11 以降と、1つのコマンドで実行する場合は uv が必要です。

uvx cpersona          # run directly, no install step
pip install cpersona  # or install it

2. 埋め込みサーバーを実行 — 強く推奨します。ベクトルレイヤーを支えます。

uvx --from "cembedding[onnx]" cembedding-download-model --model jina-v5-nano
EMBEDDING_PROVIDER=onnx_jina_v5_nano uvx --from "cembedding[onnx]" cembedding   # serves http://127.0.0.1:8401/embed

リファレンスサーバーの稼働期間は標準入力に依存します。サービスマネージャーや nohup … </dev/null、またはエージェントのバックグラウンドシェルから標準入力を閉じた状態で起動すると、ポートをバインドした後、同じ秒内にステータス 0 で終了します。開いたままの標準入力を渡してください（sleep infinity | cembedding）。詳細ははじめにをご覧ください。

埋め込みコントラクトを実装するエンドポイントであれば、どれでも同様に推奨されます。CEmbedding はリファレンス実装です。バックエンドの選択は自由です。推奨しているのはバックエンドを接続することであり、特定のバックエンドを接続することではありません。

バックエンドがなくても cpersona は実行できます — FTS5 とキーワード検索を使い、検索のたびに、静かに結果を減らすのではなく、機能が縮退していることを通知します。これはサポート対象のフォールバックですが、推奨される実行方法ではありません。検索では共通する単語が照合されるため、質問とは異なる表現のメモリや、古いメモリが見つからない場合があります。

3. MCP クライアントに登録する

Codex、Cursor、VS Code、または Claude Desktop の場合は、 MCP クライアントへの登録表に従ってください。 以下のコマンドは Claude Code 用です。

claude mcp add-json cpersona '{"type":"stdio","command":"uvx","args":["cpersona"],"env":{"CPERSONA_DB_PATH":"/home/you/.claude/cpersona.db","EMBEDDING_MODE":"http","EMBEDDING_HTTP_URL":"http://127.0.0.1:8401/embed"}}' -s user

4. 新しいセッションで確認する — エージェントに何かを store させ、新しいセッションでそれを recall させてください。セッションをまたいで保持されることが、この仕組みの目的です。

5. 永続化する — 登録によってエージェントはツールを使えるようになりますが、次のセッションでそれらを使うことや、メモリを保持する agent_id は伝わりません。recall は完全一致する agent_id に限定されるため、誤った ID を推測したセッションには何も返されません。クライアントが毎回のセッションで読み込むファイル（~/.claude/CLAUDE.md、AGENTS.md など）に短いポリシーブロックを保存してください — はじめに §5。

サーバーは起動時に pypi.org に新しいリリースがあるか確認し、recall を通じて呼び出し元のエージェントに通知します。無効にするには CPERSONA_UPDATE_CHECK=false を設定してください。更新が自動で行われることはありません。

Claude Desktop の設定、Windows のパス、ソースからのインストール、手順の全体については、はじめにをご覧ください。

得られる機能

• ハイブリッド検索 — ベクトル検索（埋め込みサーバーが支えるレイヤー）、FTS5 （トライグラム方式のため、日本語などの空白で区切られない文字体系でも機能します）、キーワード検索を、 順位または相対スコアで統合します。FTS とキーワードの各レイヤーが、ベクトル検索で見落とす識別子、 エラー文字列、正確な名称を補います。
• 追跡可能な根拠 — メモリを参照して回答する推奨方法である reconstruct は、 文字数の上限内で、保存された行を引用する項目を返します。長いレコードの埋め込みウィンドウを 超えたテキストにも引き続きアクセスできます（ブロックへのアクセスはデフォルトで有効です）。
• 3 種類のメモリ — 事実、セッションの要約、蓄積されるプロフィール。
• LLM への依存なし — cpersona は生成モデルを呼び出しません。エージェントが要約し、結果を引き渡します。 想起は調整済みのゲートに基づいて決定的ですが、ゲートはサンプリングされるため、同一データでも インストールごとに異なる状態に落ち着くことがあります。
• 単一ファイルの SQLite — 外部データベースは不要です。sqlite3 .backup でコーパスをコピーできます （調整用サイドカーも一緒にコピーする必要があります。また、ACL 行で per_subject を設定している場合は、 エイリアス台帳もコピーする必要があります）。
• 運用性 — 閾値の自動調整、自動修復機能付きヘルスチェック、埋め込みレイヤーの停止を知らせる警告、 JSONL のエクスポート／インポート、エージェント間のマージ。
• 分離 — agent_id、project_id、channel により、複数のエージェントやプロジェクトが 互いのデータに干渉せずに 1 つのデータベースを共有できます。

全体の仕組み：アーキテクチャ · ツールの機能：ツール · 準拠している動作：動作コントラクト。

ベンチマーク

OmniMemEval の LongMemEval-S パイプラインで測定しました。クリーニング済みの LongMemEval-S の500問に gpt-4.1-mini で回答し、gpt-4o-mini で判定しています。メモリバックエンドを再現する OmniMemEval と同じ ハーネス、プロンプト、モデルを使用しています。正解率は正解と判定された質問の割合です。 コンテキストトークン数は、プロンプトを含め、質問ごとに回答モデルへ送信されたトークン数の平均です。

バックエンド	デプロイ	SS-User	SS-Asst	SS-Pref	Temp. Reas	Multi-S	Know. Upd	全体	コンテキストトークン数
CPersona 2.6.11（pro mode）	ローカル	97.14	94.64	96.67	86.47	85.71	88.46	89.60	4,262.5
CPersona 2.6.11（lite mode）	ローカル	95.71	83.93	90.00	80.45	74.44	82.05	82.20	993.3
MemOS	クラウド	100.00	100.00	100.00	89.47	78.95	84.62	89.20	4,151

このプロジェクトによる実行では、1問あたり4,262.5トークンで89.60％となり、首位タイでした。 OmniMemEval が同じパイプラインで再現する12のバックエンドのうち、MemOS は同等の成績（4,151トークンで89.20％）で、それ以外はすべて少なくとも9ポイント下回りました。CPersona の各モードは、この500問のうち100問を使って調整し、残りの400問をリリースチェックに使用しました。この400問では、pro の正解率は88.75％で、MemOS と引き続き同等です（「同等」とは、独立した2回の実行における95％のサンプリング誤差の範囲内を意味します）。より小規模な応答を行う lite mode は、993.3トークンで82.20％です。MemOS を下回りますが、EverOS、Zep / Graphiti、mem9、Letta と同等で、それらのいずれかが送信するトークン数の4分の1以下です。LoCoMo（1,540問、同じモデル）では、pro の正解率は4,441トークンで84.03％です。MemOS（88.83％）を下回りますが、Cognee、EverOS、Hindsight と同等で、それらのいずれよりもトークン数は少なくなっています。CPersona は各会話をそのまま保存し、保存にも想起にも生成モデルを呼び出しません。

OpenViking 0.5.0 との比較では、推奨される再ランキングを使わずにこのプロジェクトで実行したところ、LoCoMo で84.03％対59.09％でした。また、Open Agent Memory Benchmark の60問の LongMemEval スクリーニングでは、証拠トークン数が4分の1で、書き込み時に生成モデルのトークンを使わずに、60問中52問対51問の正解でした（OpenViking のモデルは入力と出力で3,700万トークンを使用）。すべてのコストで CPersona が有利なわけではありません。LoCoMo では pro mode の検索速度が遅く（中央値72.7対50.0ミリ秒）、コンテキストは OpenViking の0.58倍でした。

このプロジェクトによる、2.6.11 リリース時点での各1回の実行結果です。セットアップ、登録ルール、クリーンな実行からのすべての逸脱については、結果をご覧ください。以前の実行結果：2.6.3a1 と 2.6.4a1。LMEB での検索のみの測定結果：benchmarks/。

ドキュメント

cloto-dev.github.io/CPersona が正規の情報源です。この README の内容と異なる場合は、サイトの内容を優先してください。

はじめに	インストール、埋め込みサーバー、クライアント登録、検証
動作仕様	依存できる内容：想起の順序、重複排除、スキャン範囲、応答形式
ツール	用途別にまとめた、すべてのツール
アーキテクチャ	ストレージ、検索パイプライン、分離の軸
ロードマップ	各リリース系列の目的と互換性が損なわれる可能性がある点、予定されている検索機能、スケールの段階
運用手順書	バックアップ、劣化の検出、調整、CJK 向けのガイダンス、コーパスの同期
設定	すべての環境変数とそのデフォルト値
品質保証	リリースの判定方法：監査、バグ台帳、構造ゲート、ミューテーションゲート
FAQ	運用担当者からよく寄せられる質問への簡潔な回答

日本語訳は言語セレクターから利用できます（正規の言語は英語です）。エージェントは llms.txt を参照できます。 日本語の詳しい解説：設計とセットアップに関する書籍と、セッション終了 → /clear → recall のトークン効率に関する記事もあります。

品質保証

すべてのリリースは、機械検証可能なプロセスを通じて判定されます。敵対的検証を伴う複数エージェントによる監査ラウンド、修正マーカーが消えたり、削除済みの欠陥が再発したりすると CI が失敗するバグ台帳、通常のテストでは表現できない不変条件を検証する構造ゲート、不変条件が破られるとそれらのゲートが失敗することを証明するミューテーションテスト、そしてドキュメントに記載された件数、デフォルト値、バージョン情報が、それらを定義するソースと一致していることを保証するゲートがあります。

その基盤となるのは、Schema v20 上で動作する、約 297 のテストモジュールにまたがる 約 3,865 個のテスト関数（パラメーター化された約 5,413 件。テストコードはサーバーコードより多い）です。リリースの判定方法については、こちらをご覧ください。

サポート

サポート対象は 3 つの段階に分かれています。Stable（本番環境認定済み。重大な修正のみ）、Current （最新の系列。すべての修正が反映されます）、Experimental（オプトイン式のプレリリース）です。後継版が出た系列も、さらに 30 日間は重大な修正のサポートを受けられます。バージョンを固定する前に、 SUPPORT.md § Known issues をお読みください。記載された問題によって、実行すべき内容が変わる場合があります。

バグを見つけた場合や、ドキュメントで説明されていないことがあれば、 バグ報告または機能リクエストを作成してください。確信がなくても構いません。バグと誤認された設定の問題は、ドキュメントが不明瞭だったことを意味し、それ自体が欠陥です。セキュリティ上の脆弱性は、 SECURITY.mdを通じて非公開で報告してください。

スポンサーシップ

CPersona は MIT ライセンスのもとで提供されており、スポンサーの有無にかかわらず、引き続き完全に利用できます。スポンサーシップによって機能が追加されたり、リリースのグレードが変わったり、課題対応の優先順位が上がったりすることはありません。課題は影響度、再現性、安全性に基づいてトリアージされ、誰に対してもその方針は変わりません。

CPersona が皆さまのワークフローに役立っており、開発の継続を応援したい場合は、GitHub で Cloto-dev をスポンサーすることができます。同じページでは CPersona、ClotoCore、およびこのアカウントで公開されているほかのプロジェクトも対象となります。スポンサーシップは、開発時間、テストとインフラ、ドキュメント、メンテナンスに役立てられます。

資金だけが支援になるわけではありません。また、このプロジェクトが最も必要としているものでもありません。リポジトリにスターを付けること、セットアップのどの部分が分かりにくかったかを伝えること、再現可能な課題を報告すること、ドキュメントの一文を修正することも、プロジェクトの前進につながります。

ライセンス

MIT — あらゆる MCP ホストから制限なく無料で利用できます。