ツール一覧¶
対象: CPersona 2.5.x。 各引数の権威ある説明は、そのツール自身の MCP description です。あなたのクライアントがそれを読み、いま動かしている版と一緒に 配布されます。このページはすべてのツールを「何に使うか」でグループ分けし、 名前から想像できない挙動を持つものは契約へリンクします。
翻訳について: 正本は英語版です。日本語版が古い場合は英語版を参照してください。
日常の読み書き¶
| ツール | 何をするか |
|---|---|
store |
メッセージ 1 件を記憶に書きます。分岐は ok ではなく result — stored / skipped / rejected — で行ってください (重複排除の契約) |
recall |
3 層ハイブリッド検索で記憶を取り出します。末尾の要素が最良のマッチです (順序の契約) |
recall_with_context |
想起 と同時に、渡した会話履歴と重複排除しつつ統合します。返るのはスコア順ではなく時系列の統合です |
get_contents |
recall が返したプレビュー参照 (mem:<id> / ep:<id>) を全文に展開します (プレビュー階層の設計) |
archive_episode |
セッション要約を保存します。同時に エピソード境界 を動かし、それ以前に書かれたものを減点します |
update_memory |
既存の記憶の内容を変更します。保存済みの事実を訂正する方法はこれであって、同じ msg_id での再 store ではありません |
プロフィールと運用者コンテキスト¶
| ツール | 何をするか |
|---|---|
get_profile |
エージェントに蓄積されたユーザー/プロジェクトのプロフィールを読みます |
update_profile |
あなたが計算した要約でプロフィールを置き換えます。CPersona が代わりに書くことはありません — LLM 非依存 を参照 |
get_operating_context |
接続中の全クライアントへ配られる運用者所有の指示を読みます。MCP 越しでは読み取り専用で、編集はファイルシステム上で行います (設計) |
プロフィール行は recall 応答に注入されますが
スコアを持ちません。
limit を絞るときに効いてくる違いです。
一覧の閲覧¶
| ツール | 何をするか |
|---|---|
list_memories |
直近の記憶を新しい順に — 検索もスコアリングもしません |
list_episodes |
アーカイブ済みエピソードを新しい順に |
get_queue_status |
バックグラウンドタスクキューの深さと再試行状態 |
保護と削除¶
| ツール | 何をするか |
|---|---|
lock_memory |
記憶の編集と削除を拒否させます。これは保護であってランキングの押し上げではありません (契約) |
unlock_memory |
その保護を解除します |
delete_memory |
記憶を 1 件削除します。所有権が強制されるのは agent_id を渡した場合だけです — 省略すると走査範囲が絞られず、他エージェントの行も削除できます (ロックはどちらでも拒否) |
delete_episode |
エピソードを 1 件削除します。所有権の扱いは上の delete_memory と同じ条件付きです |
delete_agent_data |
1 エージェントに属するものすべてを削除します。他のツールと同様にネットワークへ露出するため、HTTP トランスポート で CPERSONA_AUTH_TOKEN を設定すべき十分な理由になります |
検索品質¶
| ツール | 何をするか |
|---|---|
set_recall_precision |
主要なゲートのつまみ。エージェントの精度設定を変更し、融合後の品質ゲートを再較正します — 生の閾値をいじる前にこちらへ手を伸ばしてください (調整の順序) |
get_recall_precision |
そのエージェントに効いている精度設定を読みます |
calibrate_threshold |
ベクトルの閾値をコーパス自身から導出し直します。既定 (separation) はランダムペアの null 分布と同一セッション正例が分離する点から求め、percentile / zscore も選べます。ラベル不要。再埋め込みや大量インポートの後に実行してください |
移植と移行¶
| ツール | 何をするか |
|---|---|
export_memories |
記憶・エピソード・プロフィールを JSONL に書き出します。スキーマ版に依存しないため論理バックアップも兼ねます (バックアップ runbook) |
import_memories |
その JSONL を読み戻します。冪等ですが鍵は 1 つではありません: 記憶は msg_id と project/channel スコープ内の同一内容で、エピソードは同一の要約で重複排除されます (エピソードは msg_id を持ちません) |
merge_memories |
あるエージェントのデータを別のエージェントへ、原子的かつ重複排除つきで移動/複製します |
migrate_channel_axis |
ブリッジ種別の記憶を具体的なチャネルへ振り直します。日常運用ではなく一度きりの修復です |
ヘルスと保守¶
| ツール | 何をするか |
|---|---|
check_health |
レジストリ駆動の検査。重大度つきの検出項目を返し、fix=true で自動修復します: 汚染、重複、FTS 整合性、埋め込み次元のずれ、スキーマオブジェクト、滞留タスク、不正データ。設計上あえて報告のみの検査もあり、分離軸の衛生はその 1 つです — どの綴りを正とするかは修復ではなく運用者の判断だからです |
deep_check |
意味的なデータ品質の検査: 匿名ソース、短すぎる内容、古いプロフィール、孤児エピソード |
get_session_findings |
同じ検出結果を、必要な時に引く形で受け取ります — SuperAuditor の pull 契約 (規格)。設計上データベース全体が対象 (agent / project で絞りません)、読み取り専用で、per_kind_limit を超えた kind は capped_kinds に名指しされます。例外を起こした検査は呼び出し全体を失敗させず、kind check_crashed の finding として現れます |
check_health と deep_check は MCP の外から python -m cpersona.checkup として
も実行できます。CI ではこの形を使ってください。実行頻度の指針は
運用 runbook にあります。
ツールではないコマンドが 1 つ同梱されています。cpersona-policy (同じものが
python -m cpersona.policy) は、常時ロードされるポリシーブロックを表示し、クライアント
が毎セッション読み込む指示ファイルへインストールします。説明は、それを使う場所である
はじめに §5
にあります。
サーバーのバージョン¶
| ツール | 何をするか |
|---|---|
check_update |
サーバー自身の新しいリリースがあるか — あるいは今動いているリリースが PyPI で撤回 (yank) されたか。後者はインストール済みのサーバーが他の手段では知りようのない事実です。検査はプロセス起動ごとに 1 回走り 24 時間キャッシュされます。このツールはその判定を読み、refresh=true で取得し直し、apply=true で更新を実行します (pip とソースチェックアウトのみ) |
同じ判定は recall 応答に update キーとして乗ります (セッションごとに 1 回、
伝えることがなければキー自体が付きません)。check_health でも update_available
(info) または version_yanked (warn) の検出項目として現れます。
副作用として更新が行われることはありません。インストールするのは apply=true だけ
で、その後は必ず再起動が必要です。インストールを実行したプロセス自身が、
古いコードのまま動いているからです。
拒否される構成が 2 つあり、それぞれ理由があります。uvx では実行環境が起動引数を
キーとするキャッシュエントリなので、変更すべきは MCP クライアント側の設定です
(uvx cpersona@latest)。ブランチ上にないソースチェックアウト (リリースタグに
留め置いたクローンで、配備の仕方としては普通のものです) も同じように拒否されます。
detached HEAD からは git pull が fast-forward する先を持たないため、ツールは何も
実行する前に拒み、代わりに使うべき git fetch --tags && git checkout <tag> の形を
答えます。
CPERSONA_UPDATE_CHECK=false は、唯一の外向きリクエストを含めて機能全体を
無効化します (何を送るか)。
セッション制御¶
| ツール | 何をするか |
|---|---|
pause_persistence |
TTL の間、書き込みを no-op にします。応答は persisted: false を伴います — id ではなくこれで分岐してください |
resume_persistence |
書き込みを即座に再開します |
persistence_status |
書き込みが停止中か、残り TTL はどれだけかを返します |
ベンチマークや、コーパスに残したくない使い捨ての探索に使ってください。
影響範囲は session_key に従います。 3 つのツールはいずれもそれを scope として
返します。停止と、それが覆うべき書き込み呼び出しに同じキーを宣言すれば、停止はその
キーだけを覆います (scope: "session")。別のキーを送るセッションは、それによって
黙らされることも、それを解除することもありません。キーは比較されるだけで検証され
ないので、分割されるのは呼び出し元ではなくキーです。同じ文字列を送る者は誰でも同じ
停止を共有します。
キーを省略すると、キーを持たない全呼び出し元が共有するバケットを止めます
(scope: "process")。クライアントが自分のプロセスを所有する stdio では、その
バケットがセッションそのものです。streamable-HTTP の配備では 1 プロセスが全
クライアントに応じるため、キーなしの停止は他のキーなしセッション全員の書き込みを
黙らせます。しかも、それらのセッションには何も伝わりません。
persisted: false の形に収まらない経路が 2 つあります。check_health と
deep_check はブロックされず fix=false に降格します。migrate_channel_axis は
dry-run を強制されて repairs_skipped を返し、persisted キー自体を持ちません。
分離のための引数¶
3 つの分離軸は一様には提供されていません。agent_id はほとんどのツール (22 個) が受け取り、
project_id は 6 個、channel はちょうど 4 個 (store / recall /
recall_with_context / archive_episode) だけです。
これらは入れ子の階層ではなく独立した 3 軸であり、読み取り時に「空の値」と「省略」は 異なる意味を持ちます。分離軸 を参照してください。