運用ダッシュボード導入手順
〜トークン消費の見える化と、メモリ圧縮を安全に行うための汎用ガイド〜

この手順は、Muse の利用者なら誰でも自分の環境に導入できるよう、
特定のユーザーやキャラクターに依存しない汎用仕様として書かれています。

正直な位置づけを最初に書いておきます。
これは「渡して一言で完成する手順書」ではなく、
「設計ガイド＋導入チェックリスト」です。
導入する側の負担を極力減らす方針で書かれており、利用者に聞くのは
原則として「圧縮してはいけない項目」だけ。あとは選択式の質問が
最大2つ（1通にまとめて聞く）で、残りはすべて Muse 側の判断と
デフォルト値で進めます（第2章）。


■ 0. これは何か

「運用ダッシュボード」は、Muse との日常運用で見えにくい3つを
1画面にまとめて確認できるアーティファクト（フルスタック型）です。

1. 裏で動いているタスクの進捗
2. トークン消費量の計算と残量の目安
3. メモリファイルの状態チェックと、メモリ圧縮（最適化）の実行

画面には「最終更新日時」を必ず表示し、表示が古いまま放置されないようにします。
更新はボタン押下で裏側のエージェントが最新情報を収集して保存する方式です。
なお、保存済みの表示を見るだけではトークンは消費しません。
消費するのは「更新」や「分析」などのボタンを押して裏のエージェントが
動く時だけです。


■ 1. 前提条件（満たさない場合は先に整える）

（1）メモリの階層構造
この手順のメモリ管理は、次の階層構造を前提としています。

・MEMORY.md：要点とポインタだけの「軽い索引」
・詳細ファイル：人物別・テーマ別の詳細メモ
・日次ログ：日付別の追記専用アーカイブ（圧縮・編集の対象にしない）

この構造がない環境でいきなり圧縮機能だけを入れると、行き場のない情報が
消えたように見える事故が起きます。構造がない場合は、まず索引ファイルと
日次ログの置き場を用意し、詳細をそちらへ逃がす形に整えてから導入して
ください。移行は Muse が利用者と相談しながら行えます。

（2）プラットフォーム能力
この設計は次の機能が使える Muse 環境を前提としています。
・保存機能付きアーティファクト（フルスタック型）の作成
・画面のボタンから裏側のエージェント（タスク）を起動できること
・シェルスクリプトの実行と、ファイルの読み書き
これらが使えない環境では、この形のままでは実装できません。
その場合は「表示のみの簡易版に縮小するか」を最初に相談してください。


■ 2. 導入時の進め方（利用者の負担を最小にする）

基本方針：利用者に考えさせるのは「安全に関わること」だけ。
それ以外は Muse が調べて、決めて、進めます。

―― 利用者へ必ず伝えること（第5章の必須表示） ――
メモリ圧縮の危険性と、「圧縮してはいけない項目」の指定が必要な旨は、
作成の許可を求める前に必ず伝えてください（文面は第5章）。

―― 利用者に聞くこと：原則これだけ ――
1.「絶対に圧縮しない項目」はどれか。
ただし、利用者は自分のメモリの中身を把握していないのが普通です。
「選んでください」と丸投げせず、Muse が現在のメモリの中身を
提示し、守るべき候補を先に挙げたうえで、利用者は
「これとこれは守って」「あとはおまかせ」と答えるだけで済む形に
してください。候補出しは選択式が理想です。
なお、候補に挙がらなかった項目が利用者の目に触れないまま無防備に
なるのを防ぐため、候補とあわせて現在のメモリの「全見出し一覧」も
必ず併記してください（網羅性の担保）。

―― 選択式の質問：最大2つ（1通にまとめて聞く） ――
該当するものだけを、1通のメッセージにまとめて聞いてください。
2. 裏で動いているタスクの進捗を表示するか。
※ただしこれは、Muse の環境調査で「表示できるタスクの候補」が
実際に見つかった場合だけ聞いてください。候補が何もない環境では
聞かずに、タスク進捗セクション自体を省略して作ります。
※聞く際は、候補となったタスクの名前を具体的に添えること。
名前がないと利用者に判断材料がありません。
3.「消費を分析」に、節約の改善アドバイスを表示するか。
※集計元データが見つからず分析機能自体が付かない場合は聞きません。
※聞く際は、アドバイスの生成自体にもトークンを使う旨を一言添える
こと（消費を減らすための機能にも消費の側面があることの開示）。
どちらの質問も、未回答のままならデフォルト（表示する／表示する）で
進めてよいものとし、回答待ちで作業を止めないでください。
なお、選択式の質問への回答は「作成の許可」ではありません。
作成は、許可確認への明示の返事をもらってから開始してください。

―― あとは全部 Muse 側で決める（デフォルト表） ――
・メモリの上限サイズ：MEMORY.md は約16KBを目安に、ファイルごとに設定
・トークン無料枠の想定総量：1億で固定して概算計算する
（画面には必ず「概算」と明記。実総量と異なる前提の目安である旨も表示）
・追加購入分の使用率・残量、リセット日時：Muse がサブスクリプション
状況から調査して表示。取得手段がない場合は、そのセクションを
省略または「取得できませんでした」表示にして、推測で数字を作らない
・更新方式：ボタン手動のみがデフォルト。定期更新は利用者が言い出す
まで入れない
・効率化アイデア置き場：デフォルトでは付けない（後から追加可能）
・タスク進捗セクション：候補タスクがなければ省略（上記2の通り）

―― Muse 側の環境調査（利用者に負担させない） ――
作成の許可を求める前に、次を自分で調べておいてください。
・メモリファイルの実在・パス・現在のサイズと構成、前提の階層構造に
なっているか
・サブスクリプション状況の取得手段の有無
・トークン利用記録（消費分析の集計元データ）の所在
★この所在特定に限り、初回はエージェントによる探索作業を許可します。
ただし探索は主要な候補の確認までを範囲とし、時間にして30分程度を
上限の目安として打ち切ること。際限なく探し続けないでください。
見つからない場合は「分析機能なし」で納品し、その旨を表示します
・表示候補になる「裏で動くタスク」の有無と、状態の置き場所
（ログファイル／状態ファイル／ジョブ一覧など）

調査結果で「取れる／取れない」が分かったら、それを許可確認の文面で
正直に伝えたうえで、作成の許可を求めてください。その際、許可確認の
文面には次を必ず含めること：
・デフォルトで決めた重要事項を1行ずつ明記する（上限サイズ、想定総量
1億固定、手動更新のみ、付けた／付けなかったセクション等）。
利用者が「何が自動で決まったか」を知らないまま運用が始まらない
ようにする
・それらの設定は後から変更できる旨の案内
・前提の階層構造への移行が必要な場合は、その旨と作業規模の目安
（移行はダッシュボード構築より大きな作業になり得るため）


■ 3. 画面の構成（表示要素）

（1）タスク進捗セクション（候補タスクがある場合のみ）
・裏で動いているタスク（長時間の生成バッチ、定期ジョブなど、
使用者の環境でバックグラウンド動作しているもの全般）の状態を表示。
・タスク名、状態（実行中／待機中／完了／要再開）、進捗（完了数／総数）、
直近の出来事（自動再開の発動など）を表示します。

（2）トークンセクション
・無料枠の使用率（％）と、想定総量1億から逆算した概算消費量
・追加購入分の使用率（％）と残量（取得できた場合）
・リセット日時
・「消費を分析」ボタン：直近24時間の消費をチャット別・エージェント
種別に集計し上位を表示。改善アドバイスの表示は選択式質問の結果に
従う（集計元が特定できた場合のみ）

（3）システムチェックセクション
・メモリファイルのサイズと上限超過の有無
・仮想マシンの空きメモリなど、環境の基本状態
・（任意）圧縮候補のカウントダウン表示（第5章の接触記録がある場合のみ）

（4）メモリ最適化ボタン
・押すと裏側で「バックアップ → ドライラン（圧縮案の提示）→ 利用者承認
→ 本圧縮 → 検証 → 結果保存」を実行します。詳細は第5章。

（5）（任意）効率化アイデア置き場
・改善アイデアを貯めるメモ欄。タイトル／内容／期待効果／
状態（提案中・採用・見送り）／日付を持ちます。デフォルトでは付けず、
希望があった場合のみ追加します。


出来上がりのばらつきを減らすため、最低限これだけは決めてから作ります。
・スナップショットの項目：最終更新日時、タスク一覧（名前・状態・進捗・
直近の出来事）、トークン（無料％・概算量・追加％・残量・リセット日時）、
システム確認事項の一覧
・読み書きの口：状態取得／スナップショット保存／最適化の実行と結果保存／
分析結果の保存、の4系統を用意する
・ファイルの命名規則：バックアップは対象と同じ場所に
「<対象ファイル名>.bak-YYYYMMDD-HHMM」、落とした項目の要約は
「<対象ファイル名>.dropped-YYYYMMDD.md」
・バックアップの保持：直近5世代だけを残し（デフォルト。変更可）、
それより古いものは定期チェックの際に「掃除候補」として提示する。
自動では消さず、利用者の確認を取ってから整理する（バックアップも
無限には溜めないが、勝手にも消さない）


■ 4. トークン消費量の計算について

・使用率（％）は Muse のサブスクリプション状況から取得します。
取得手段の有無は第2章の環境調査で先に確認してください。
・消費「量」の概算は、無料枠の想定総量1億（固定）に使用率を掛けて
算出します。あくまで概算であり、請求単位そのものではありません。
画面には「概算」であることと、固定の仮定値ベースであることを
明記してください。なお、実際の総量が後から判明した場合は、
固定値をそちらに差し替えてください。
・入力トークンは、会話履歴＋常駐ファイル＋ツール結果を毎ターン再送信
する構造上、出力より桁違いに大きくなります。消費の主因は利用者の
文章量ではありません。この前提を踏まえて分析結果を解釈してください。


■ 5. メモリ圧縮機能の仕様（最重要）

―― 導入時の必須表示事項 ――

メモリ圧縮機能を搭載する際は、実装担当の Muse は必ず、
機能を有効化する前に利用者へ次の旨を伝えてください。

「メモリが上限を超えた分は、細かいニュアンスの部分から圧縮の対象に
なります。要約で落ちやすいのは、条件付きのルール、正確な識別子
（ファイル名・ID・数値）、程度や頻度（回数）の指定、例外条項、
一文だけの味付けのような要素です。
そのため、圧縮してはいけない項目を事前に選んで指定してください。
指定された項目は圧縮対象から除外します。」

そして、利用者が「絶対に圧縮しない項目リスト」を決めるまでは、
圧縮を自動実行しないでください。
なお項目の選び方は第2章の通り、Muse が中身と候補を提示し、
利用者は選ぶだけ、が基本形です。

―― 保護項目の識別方法（必ず実装すること） ――

「指定したのに圧縮された」という最悪の事故を防ぐため、保護は
仕組みで担保します。口頭の約束だけに頼らないでください。

・識別方法は次の2方式から、環境に合う方を選ぶ：
A. 保護リストファイル方式（推奨）：守る項目名を別ファイルに列挙
するだけ。既存メモリの並べ替えが不要なので、項目がテーマ別に
散らばっている環境でも安全に導入できる
書式：置き場所は対象メモリと同じ階層、ファイル名は
protect-list.txt を標準とする。1行に1項目を書き、メモリ内の
見出し名と完全一致で照合する。同名の見出しが複数ある場合は
「ファイル名#見出し名」の形で区別する。空行と「#」で始まる行は
コメントとして無視する
B. 専用見出し方式：メモリファイル内の専用見出し（例：「## 圧縮禁止」）
の配下に保護項目を置く。新規にメモリを作る場合や、すでに整理
済みの環境向け。既存項目の大規模な移動が必要な場合は、移動自体が
脱落事故の元になるため A を選ぶこと
・圧縮を実行するエージェントは、開始前に保護リストを読み込み、
該当項目を対象から除外する
・フェイルセーフ：保護リストが存在しない／読み込めない／空の場合は、
保護が効いていない状態として圧縮を実行せず、失敗として報告する
こと（リストの消失を「守るものなし」と解釈しない。安全側に倒す）
・圧縮後の検証で、保護項目が圧縮前と一字一句変わっていないこと
（原文一致）を機械的に照合する。一致しない場合は失敗として報告し、
バックアップからの復旧を案内する

―― 圧縮の本体手順（何をどう書き換えるか） ――

・実行主体：最適化ボタンで起動するエージェントが、対象ファイルごとに
1回ずつ行う
・圧縮してよいもの：経緯の長い説明文、重複した記述、エピソードの
詳細（ただし元は日次ログやバックアップに残っているものに限る）
・圧縮の書き換えルール：
- 識別子（ファイル名・ID・数値・日付・固有名）は要約せず原文転記
- 条件付きルール、例外条項、程度・頻度の指定は、意味を変えずに
文のまま残す（短く言い換えない）
- 残すのは「現在の状態」と「教訓」。修正や中止の経緯そのものは
落としてよいが、そこから得た教訓は残す
・ドライラン標準：初回の圧縮は必ず「圧縮案の提示のみ」にし、
利用者の承認を得てから本圧縮を行う。自動化（承認なしの実行）へ
切り替える場合は、切り替え時に一度、利用者の明示的な確認を取って
からにすること。承認なしに安全弁を外さない

―― 圧縮は「削除」ではありません ――

この仕組みで行うメモリ整理は、あくまで「圧縮」です。削除ではありません。
以下の安全装置を必ずセットで実装してください。

・圧縮前に必ずバックアップを作成する（命名規則・保持世代は第3章）
・圧縮で落とした項目は「落とした項目の要約」を残す
（何を落としたか／どのルールで落としたか／元の全文がどこに残るか）
・日次ログは追記専用アーカイブとして扱い、圧縮対象にしない。
詳細の置き場は日次ログや詳細ファイル側に逃がし、MEMORY.md は
「要点とポインタの軽い索引」という役割に徹する
・復旧経路はバックアップ、または日次ログ／会話履歴からの再構成のみ。
元に戻せない完全な消去は、利用者が明示的に「忘れて」と依頼した
場合だけ

―― 圧縮後の検証（機械的照合の方法と、その限界） ――

・圧縮前に、対象ファイルから識別子らしい文字列（ファイルパス、ID、
数値＋単位、日付、引用符で囲まれた固有名）を抽出して一覧化する
・圧縮後に、その一覧の全件が圧縮後のファイルに残っているかを照合する
・不足があれば「検証失敗」として、不足分を明示して報告する。
検証を通らない圧縮を「成功」と表示しない
・限界の明記：この照合は「抽出できた識別子」しか守れません。抽出漏れが
あれば、照合を通過しても落ちている可能性は残ります。過剰な安心感を
与えないよう、この限界を利用者にも伝えてください

―― 未接触カウントダウン（任意機能） ――

・「長く触れていない項目を圧縮候補にする」ルールを入れる場合、
項目ごとの最終接触日を記録する管理ファイル（項目名と日付の対応表）
を別に用意し、定期チェックのたびに更新する仕組みが前提です。
この記録が用意できない環境では、カウントダウン機能は入れないこと
・「接触」の定義：その項目が、会話で言及された／ファイル編集で変更
された、のいずれかが起きた日を最終接触日とする（読んだだけは
接触に数えない）
・候補までの残り2日以内になったら事前に「あと○日で圧縮候補」と表示し、
期限未満のものは落とさず警告リストに留める
・保護指定されたカテゴリは、経過日数ルールより常に優先する


■ 6. 更新処理（リフレッシュ）の実装上の工夫

・更新ボタンの裏側では「決められた手順の収集スクリプトを1回実行 →
トークン状況を確認 → 保存」の固定3ステップにしてください。
エージェントに自由な探索をさせるのは初回の所在特定まで（第2章）。
定常運用で毎回探索させると、時間がかかり、トークンも余計に消費
します。固定手順化すれば所要時間は大幅に短くなります
（短縮後の具体的な時間は環境依存なので、目安は実測してから書くこと）。
・収集スクリプトは、タスクの状態・その日のイベント・メモリファイルの
サイズ・空きメモリなどを1回の実行で JSON 形式で出力するものが理想。
・定期チェック（例：夜間の定期報告）とダッシュボード更新で同じ収集を
二重に行わないよう、収集は1系統に一本化してください。


■ 7. 導入の際の注意点

1. ダッシュボードの構築・更新・分析にはトークンを使います。
構築自体にも相応の消費があるため、導入時に「今回の構築で
おおよそこれくらい使った」という実績ベースの一言を添えると、
利用者が今後の判断をしやすくなります（目安の絶対値は環境依存
なので断定しないこと）。表示の閲覧は無料でも「最新化」は無料では
ありません。更新頻度は必要最小限に。
2. 初回は必ず実地確認をしてください。設計上つながっていても、実際の
データ読み取り（消費集計など）が本番環境で動くかは、初回のボタン
押下が実質的な検証になる部分があります。失敗した場合は推測で
埋めず、失敗した旨を表示する実装にすること。
3. 概算と実績を混同しないこと。特にトークンの「量」は固定の仮定総量
（1億）ベースの概算です。断定表現を避け、「約」「概算」と明記して
ください。
4. 運用ルールの全文を、ボタンの処理プロンプトなどに複写（コピペで
埋め込み）しないこと。ルールは原本ファイルへの参照に留めます。
複写すると、原本を直してもコピー側が古いまま残り、齟齬の原因に
なります。
5. 変更はまとめて一括で行うこと。小刻みな変更は、そのたびに
エージェントが起動して入力トークンを消費します。
6. 状態表示は「見た時点のもの」です。長時間タスクの状態を伝える
際は、直前に最新の状態を再確認してから表示してください。数分前の
確認結果がすでに古くなっていることがあります。


■ 8. カスタマイズのポイント

・裏で動くタスクの種類は環境ごとに差し替えてください
（生成系のバッチ、定期ジョブ、監視ジョブなど）。タスクが無い環境では
セクションごと省略するのが正解です。
・メモリの上限サイズや、圧縮候補になるまでの日数は、自分の使い方に
合わせて調整してください。
・夜間の定期報告と組み合わせると、「その日のタスク発動状況」と
「トークン消費の概算」を1行ずつ報告に含める運用も可能です。
・自動でタスクを監視・再開する仕組み（ウォッチドッグ等）を併用する
場合は、その発動記録もこのダッシュボードに集約すると確認が
1か所で済みます。


■ 9. 導入手順（まとめ）

1. 自分の Muse に本手順を渡し、「この仕様で作って」と依頼する
2. Muse が必須表示（メモリ圧縮の注意）を行い、現在のメモリの中身と
保護候補を提示するので、「圧縮してはいけない項目」を選ぶ
3.（候補がある場合のみ）選択式の質問に答える：裏タスクの表示可否、
改善アドバイスの表示可否。無回答ならデフォルトで進む
4. Muse の環境調査の結果（取れるデータ／取れないデータ）と
作成内容の確認を受けて、作成許可を出す
5. 初回の更新ボタンと「消費を分析」を実際に押し、表示が正しいか
確認する
6. 初回のメモリ圧縮はドライラン（圧縮案の提示）で承認してから実行
7. 以後は、状態確認はこのダッシュボードに集約し、都度の口頭確認や
定期的な進捗連絡を減らして運用する

以上