CPersona ドキュメント¶

CPersona は MCP サーバーです。Claude をはじめとする MCP 対応エージェントに、セッションをまたいで残る記憶を与えます。

記憶はローカルの SQLite ファイル 1 つに保存されます。recall はそれを 3 通り (vector・FTS5・keyword) で検索し、ランクまたは相対スコアで融合します。

サーバーは LLM に一切依存しません: 生成モデルを呼びません。ただし、これは次の 2 つを意味しません。

常に無料とは限りません。 EMBEDDING_MODE=api では、埋め込みリクエストごとに課金されます (既定のエンドポイントは OpenAI)。自前の埋め込みサーバーを指す http モードでは課金されません。
どの環境でも同じとは限りません。 recall は品質ゲートが較正済みであれば決定論的です。較正はコーパスをランダムに標本して行うため、同じデータを持つ 2 つの環境が別のゲートに落ち着くことがあります。

対象: CPersona 2.6.x。 このサイトが正式ドキュメントです。README や同梱 skill の記述とこのサイトが食い違う場合はサイトが優先で、その食い違い自体が報告に値するバグです。

翻訳について: 正本は英語版です。日本語版が古い場合や存在しないページは英語版を参照してください (未翻訳ページは自動的に英語で表示されます)。

目的別ガイド¶

はじめに

インストールし、MCP クライアントに登録し、接続を検証します。

はじめに
アーキテクチャ

記憶がどこに保存され、3 つの検索器がどう探し、融合 → ゲート → 反転のパイプラインが何をするか。図付きです。

アーキテクチャ
ツール一覧

全ツールを目的別にまとめています。名前から想像できない挙動をするツールは、その理由を説明する契約へリンクしています。

ツール一覧
挙動契約

依存してよい挙動です。ここを変えることは、好みの変更ではなくバグとして扱います。

挙動契約
設定リファレンス

全環境変数と既定値、そして HTTP トランスポートが応答するための要件。

設定リファレンス
運用 Runbook

バックアップ、劣化検知、recall を調整する順序、日本語コーパス、保守の周期。

運用 Runbook
2.6 への移行

2.5.x のストアを 2.6.0 へ一度に移行する手順: バックアップ、最初の起動で移行されるもの、後で作るもの、戻し方。

2.6 への移行
FAQ

運用者からよく来る質問への短い回答。それぞれ詳細のあるページへリンクします。

FAQ
品質保証

リリースがどう検査されるか: 監査ラウンド、バグ登録簿、構造ゲート、変異証明。

品質保証

設計ノートと標準¶

ガイドの下には 2 種類のページがあります。それぞれ別の問いに答えます。

プロジェクト標準 は、リリース・監査報告・生成されるポリシーブロックがどうあるべきかを定めます。他のプロジェクトでも採用できます。

リリースライフサイクル標準 — ティア定義 (Stable / Current)、リスク駆動の pre-release ladder、サポート期間。本リポジトリが実際に運用している内容は SUPPORT.md にあります。
SuperAuditor 標準 — クライアントがサーバーから findings を取得する方法。深刻度の語彙と、上限の意味。何を検出すべきかについては意図的に何も定めていません。
ポリシーブロック標準 — プロジェクトの skill が、エージェントが毎セッション読み込むファイル (CLAUDE.md、AGENTS.md、…) へマーカー付きポリシーブロックを書き込む方法と、skill だけではブロックの存在を保証できない理由。

これからの方向。 ロードマップは、各リリースラインが何のためにあり、何を破ってよく、計画中の機能がどの実測された問題に答えるかを記録します。軸は 3 つ (リリースライン・ランタイムとスケール・サポート tier) です。これは意図の記述であって納期の約束ではありません。実際に出荷されたものはリリースノートと SUPPORT.md にあります。

2.6 系には専用ページ Reliable Recall があります。1 回の呼び出しの中で反復する想起ループ、手がかりの契約、prior 関数、再構成の出口とその件数の窓、失敗の分類、そして何をもって完了とするか。その完了条件の一つ一つを証拠と突き合わせたページが 2.6 系の進捗です。その次のラインにも専用ページ Memory Intelligence (2.7 系) があります。訂正と矛盾、時間状態、証拠で重み付けした確信度、保持の方針、想起のフィードバック — 設計のみで、決まっていない問いは未決定と明記してあります。

設計ノート は、ある挙動がどう決まったかを、却下された経路も含めて記録します。ある時点の記録です。ノートとガイドが食い違う場合はガイドが優先します。

クライアント別の権限 (ACL) — 名前付きベアラトークン、エージェント単位の読み書き権限、既定拒否。
OAuth 対応 — リソースサーバーのメタデータ、トークン検証、比較した 3 経路、subject 単位の境界がどこに引かれるか。
サーバー供給の運用コンテキスト — 接続中の全 MCP クライアントへ運用者の指示を配布する仕組み。
申告型セッション同一性 — streamable HTTP では 1 プロセスが 1 セッションにならない理由と、session_key がプロセス全体のどの状態を分割し直すか。
アクセス元の記録 — agent_id が誰も名指さない経路のために、観測した呼び出し元を各行へ記録します。
recall プレビュー階層 — プレビューの切り詰めと get_contents による展開経路。
埋め込み索引の連続配置 — ベクトル走査の読み出しを SQLite の行から連続配置の sidecar ファイルへ移します。答えは変わりません。
走査窓の到達範囲と新しさの優遇 — ベクトル走査窓を広げると最近の答えを失う理由と、新しさの優遇を捨てずに窓を広げるための 2 本目の順位付きリスト。
到達範囲・新しさ・far の票 — 3 つの計測を 1 つにまとめ、それぞれ何を確立したか、そして 2.6 系で far の票に値段を付ける計画。
一本化した事前分布 — 位置と年齢の重みをすべて 1 つの関数にまとめ、順位だけに効かせて足切りには効かせないこと。confidence は並べ直しに使わず、各行の横に別の値として返すこと。
想起のプロセス v0 — 失敗をどの段で起きたかに帰属できる想起の記録と、指定した時期に見つかった行を、ゲートに触れずに上限付きの段数だけ上げる時期の手がかり。
適応的融合 — 各検索器にプールの取り分を確保すること、プールサイズ gate から順位カットを外すこと、そして「いま計測済みの lexical 重み」と「後の条件付き証拠の融合モード」のどちらを採るかを決める事前登録済みの比較。
Block による到達 — 長いレコードを節に相当する Block へ分け、 1 次元 1 ビットの Hamming 距離で順位付けし、親へ畳んで別枠で通すことで、品質 gate に新しいスコアを入れずに末尾へ到達できるようにすること。
1 ビット粗探索 — 全レコードの 1 ビット索引を Hamming 距離で走査し、保存済みのベクトルで並べ直すことで、走査窓を広げずに、窓の外のレコードを答えの横に別枠で置き、時間の手がかりの期間を丸ごと探せるようにすること。
溢れ分の tree — 長いレコードを埋め込みの窓に収まる区間に分け、 recall が返すものを変えずに、返されたレコードを関連する部分で引用できるようにすること。
連想記憶 — entity・別名・関係の宣言されたグラフ。再構成想起が cue・束ねキー・根拠・roles として辿る。宣言が無ければ何も変わらない。
埋め込み劣化の通知 — 埋め込み層が死んだとき、静かに質を落とすのではなく recall がそれを報告する仕組み。

研究ノート¶

設計ページが拠って立つもの (導出・実測・反証) を、信じるのではなく検算できる形で置いた記録です。概要に status の語彙があります。

適応的融合の導出 — 各検索アームを、そのスコアが偶然で超えられる確率を通じて結合します。この規則は行ごとの影響度を閉じた形で持ち、現行の reciprocal rank fusion はその極限にあたります。
較正と admission floor — recall が負けていた 7 タスクを 3 つの較正法で測りました。床は原因ではありません。 null は誤ったペア母集団から取られていました。小さなコーパスでは dense アームが飢餓します。
損失はどこにあるか、凍結段リプレイ — Track B 経路の全段を、凍結した埋め込みの上で 3 モデル分採点し、稼働中の pipeline に固定しました。純 ranking のタスクは融合段で、Gorilla は admission で、EPBench は gate で負けています。QASPER の利得は補充によるものです。
2 本のアーム、1 つの決定 — その損失を避けるために融合則が知らねばならないもの。アームごとの較正ではなく、dense スコアを 与えたうえで lexical がどれだけ情報を足すか、です。同時密度比はそれを、重みを当てはめずに供給します。飢餓・gate の全滅・予約の閉形式も導いています。

3 つの記憶タイプ¶

宣言的記憶 — 個別の事実・決定・ルール (store / recall)。
エピソード記憶 — セッション要約 (archive_episode)。有効にした時のエピソード境界ペナルティの駆動源でもあります。
プロフィール — 蓄積されたユーザー/プロジェクト属性 (update_profile)。スコアリング上の注意があります。

AI エージェント向け¶

このサイトの機械可読索引を llms.txt で公開しています。同梱の cpersona-memory skill はエージェントに store / recall / archive の日常ワークフローを教え、正確な詳細はこのサイトへリンクで戻します。

支援について¶

CPersona は MIT ライセンスで、この先も変わりません。役に立って、この作業が続いてほしいと思っていただけたなら、支援のページをご覧ください。支援が買うもの・買わないものと、お金のかからない助け方を書いています。