RecallLoom
RecallLoomは、セッションベースのエージェント向けのポータブルなコンテキストハーネスです。
重いインフラストラクチャを必要とせずに、セッション間でのプロジェクトの継続性を維持するための軽量なファイルモデルを提供します。
目標はすべてを記憶することではありません。目標は、適切なプロジェクト状態をセッション間で永続的で、読み取り可能で、回復可能に保つことです。
パッケージスコープ
このファイルは、インストール可能な recallloom/ スキルパッケージのエージェント向けエントリポイントです。
ホストエージェントの通常のスキルディスカバリフローを通じてこのパッケージをインストールし、トリガーしてください。 RecallLoom自体は、パッケージ内にカスタムホスト固有のランチャーを必要としません。 パッケージは、サポートされているホスト向けのオプションのネイティブラッパーテンプレートを含む場合があります。
このインストール可能なパッケージは、意図的に軽量に保たれています。 人間向けのリポジトリランディングページやマーケティングドキュメントは上流に存在する可能性がありますが、インストールされたスキルディレクトリにはバンドルされません。
ソースリポジトリでは、README.md と README.en.md は簡潔な公開
フロントドアであり、README.zh-CN.md は互換性エントリ、INDEX.md は完全なマップ、USAGE.md は操作ガイドです。
これらのファイルは、このインストールされたパッケージのエントリポイントと同じヘルパー契約を記述しており、2番目のロジックセットを定義するものではありません。
パッケージのインベントリ、プロトコルの詳細、ヘルパースクリプトの動作については、パッケージ内に同梱されているファイルを参照してください。
managed-assets.jsonpackage-metadata.jsonreferences/file-contracts.mdreferences/operation-playbooks.mdreferences/package-support-policy.mdreferences/recording-workflow.mdreferences/protocol.md
パッケージ情報
- パッケージバージョン:
0.4.6.1 - プロトコルバージョン:
1.0 - サポートされているプロトコルバージョン:
1.0
ランタイムの前提条件
- Python 3.10 以降
- サポートされているワークスペース言語:
enzh-CN
- サポートされているブリッジターゲット:
AGENTS.mdCLAUDE.mdGEMINI.md.github/copilot-instructions.md
パッケージサポートゲート
RecallLoom パッケージのサポートは、プロジェクトのサイドカープロトコルの互換性とは別のものです。
- ヘルパーはパッケージサポートチェックを実行し、サポート状態をプロジェクトの
.recallloom/に書き込んではなりません。 - サポートが
readonly_onlyの場合、変更を行うヘルパーはブロックし、診断および読み取り専用のヘルパーは続行してもかまいません。 - サポートが
diagnostic_onlyの場合、診断ヘルパーのみが続行する必要があります。 - サポートが
unknown_offlineの場合、診断および読み取り専用のアクションは続行してもかまいませんが、変更アクションはサポートが確認されるまでブロックする必要があります。 - ブロックされたアクションは、
blocked_reason: package_support_blockedとpackage_supportオブジェクトを含む共有障害契約を返す必要があります。references/package-support-policy.mdを参照してください。
公開サーフェスと必須チェック
- 公開パッケージおよびリリースサーフェスは、ユーザーがパッケージをインストール、理解、および操作するために必要なファイルに制限する必要があります。
- 公開サーフェスには、コピーされたプロジェクトメモリ、生成されたランタイム出力、マシンローカルデータ、メンテナ専用の作業ファイル、またはインストール可能なパッケージに不要な素材を含めてはなりません。
- 公開 CI および必須チェックは、リポジトリのコンテンツとメタデータを検証してもかまいません。
- 必須チェックの文言は、リポジトリチェックをユーザーのローカルワークスペース状態、ホストの動作、またはサイドカーの信頼ステータスの証明として提示してはなりません。
非侵入型デフォルトとUXゲート
- コアインストールと日常的な使用には、フック、デーモン、ウォッチャー、MCP/プラグインの強制、ホストアダプター、テレメトリ/メトリクス、またはリモートペイロード送信を必要としたり、自動インストールしたりしてはなりません。
- ネイティブコマンドラッパーは、同じディスパッチャーに対するオプトインの便利なエントリポイントであり、必須の強制レイヤーではありません。
- 管理対象サイドカー外の通常のドキュメント/ソース/計画編集は、RecallLoom の状態に影響を与える場合を除き、デフォルトで許可されるか、低摩擦であるべきです。
- 管理対象サイドカーまたは真正性に影響を与えるアクションは、ヘルパーの準備完了出力において、
allow、warn、ask、またはblockのいずれかを表示します。 warnは低リスクの構造のみ、または読み取り可能なレガシー状態に対するものであり、簡潔に保つ必要があります。同一セッション内の低リスク警告の繰り返しは、クールダウン対応とする必要があります。askは、レガシーレビュー/修復インポート、またはレビューされたインポートされたベースラインアクションに対するものであり、高リスクの書き込みの前に明示的なオペレーターの確認が必要です。blockは、偽造マーカー、検出された受信/ストアの不一致、直接的なstate.json/config.jsonの編集、プライバシー違反、およびinconsistent_or_tampered_evidenceとして分類された状態に対しては、放棄不可です。- リモートサービス、ホストメモリ、プラグイン、MCP、フック、またはラッパーをローカルヘルパーエビデンスの権威として提示してはなりません。
- 受信に基づく変更は、ディスパッチャー発行の管理対象ファイル書き込み、最新のカーソルへのデイリーログ追記、および追記後のサマリー同期に限定されます。アーカイブ適用とブリッジ適用は、それらのサーフェスが独自の受信サポートを獲得するまで、プレビューのみのままです。
書き込みプロトコルレッドライン
- 管理対象サイドカーの書き込みにはヘルパースクリプトを使用する必要があります。ブラインドファイル置換、ブラインドパッチ、または手作業によるサイドカーファイルでバイパスしてはなりません。
- デイリーログの書き込みには
append_daily_log_entry.pyまたはディスパッチャーappendを使用する必要があります。daily-log-entryマーカーを手書きしてはなりません。 - デイリーログカーソルの修復には
repair_daily_log_cursor.pyまたはディスパッチャーrepair-daily-log-cursorを使用する必要があります。state.json.daily_logsを手動編集してはなりません。 - 上書き形式の管理対象ファイルは、リビジョン認識型のヘルパーコミットを使用する必要があります。
file-stateマーカーを手書きしてはなりません。 - 通常の操作中に
STORAGE_ROOT/state.jsonおよびSTORAGE_ROOT/config.jsonを手動編集してはなりません。 - プロトコル
1.0のデイリーログカウンターはファイルローカルです。entry-seqは1つのデイリーログ内で1..Nであり、正規のentry-idはentry-{entry_seq}です。どちらもグローバルに一意として扱わないでください。 state.json.daily_logs.entry_countはentry_countのままにします。これは、最新のアクティブなデイリーログ内のエントリマーカー数を意味し、グローバルな累積数ではありません。- ヘルパー書き込みが失敗した場合、診断、修正、再試行を行い、それでも完了できない場合はヘルパー障害契約を表面化します。
- 破損したサイドカーの回復には、正規の回復提案/レビュー/昇格ヘルパーと
validate_context.pyを使用する必要があります。管理対象マーカー、state.json、config.json、受信、またはヘルパーエビデンスストアを手動編集してはなりません。
使用すべきタイミング
RecallLoom は、以下の場合に使用します。
- 一時停止後の既存プロジェクトを継続する
- 維持されているファイルからプロジェクトコンテキストを復元する
- 現在の状態のプロジェクトメモリを維持する
- 意味のあるマイルストーンの進捗を記録する
- セッションやツール間のコンテキストドリフトを減らす
典型的なトリガーは以下のとおりです。
- このプロジェクトを続ける
- プロジェクトコンテキストを復元する
- 中断したところから再開する
- rl-init
- プロジェクトメモリを更新する
- 今日の進捗を記録する
- 維持されているプロジェクトファイル内でクリーンな次のステップのハンドオフを準備する
初回アタッチ時の動作
プロジェクトで最初に明示的に呼び出された場合、RecallLoom はワークスペースがすでに初期化されていると想定すべきではありません。
正しいフローは次のとおりです。
- 有効な RecallLoom サイドカーがすでに存在するかを検出する
- 存在する場合は、初期化を余計な儀式にせずに通常通り続行する
- 存在しない場合は、プロジェクトがまだ初期化されていないことを説明し、初期化を実行するかどうかを尋ねる
- ユーザーが明示的に確認するか、
rl-initと直接言った場合は、標準の初期化アクションを実行する - 環境が Python
3.10+を提供できない場合は、手動でサイドカーを構築する代わりに、ブロックされたランタイム結果で停止する
rl-init は次のことを意味する必要があります。サイドカーを初期化し、ワークスペースを検証し、推奨される次のアクションを返します。ホストがネイティブスラッシュコマンドを公開していない場合でも、安定した高レベルアクション名として扱います。
現在のアクションサーフェス
現在のパッケージラインでは、安定したオペレーター向けラッパーターゲットは次のとおりです。
rl-initrl-resumerl-statusrl-validate
rl-init は、オペレーターフレンドリーな初回アタッチアクション名の第一です。
その他は、ホストエージェントによって解釈されるか、ホストがそのサーフェスをサポートしている場合にネイティブカスタムコマンドにマッピングできる、オペレーター向けの安定したアクション名です。
rl-bridge はブリッジ作業のための正規のディスパッチャー/ヘルパーアクションラベルのままですが、このパッケージラインは、そのラベルのユニバーサルなネイティブラッパーまたは確定的なファーストホップルーティングを約束しません。
自然言語は、これらのアクションのデフォルトの公開表現のままです。
ディスパッチャーコマンドサーフェスには、quick-summary、record --plan、append、write、sync-current-state-after-append、repair-daily-log-cursor も含まれます。
現在の状態のスナップショットには quick-summary を、記録インテントを分類し次の安全なヘルパーステップを取得するには record --plan を、マイルストーンログには append --entry-json を、型指定された管理対象ファイルの書き込み前には write --type ... --source-file <prepared-file> --dry-run または write --type ... --stdin --dry-run を、プレフライトがメタデータのみの post_append_summary_sync を許可した場合にのみ sync-current-state-after-append --reuse-current-summary --semantic-unchanged-assertion-json <json> を使用します。バインドされたアサーションJSONスケルトンについては references/recording-workflow.md を参照してください。
state.json.daily_logs が解析された最新のアクティブなデイリーログと一致しなくなった場合は、まずプレビューモードで repair-daily-log-cursor を使用します。適用モードでは --apply --yes が必要で、新しいプレビュー/ステータスチェックの後には --expected-workspace-revision を含める必要があり、変更としてサポートゲートされ、ヘルパー受信を書き込んだりデイリーログコンテンツを書き換えたりせずにカーソルフィールドを修復します。
これらのディスパッチャー追加は、既存の v0.3.4 プロジェクトではオプションであり、サイドカープロトコル 1.0 を変更しません。
rl-init、rl-resume、rl-status、rl-validate のネイティブラッパー
は、便利なエントリポイントにすぎません。これらは同じディスパッチャーに委任する必要があり、
自然言語の復元要求を置き換えたり、ヘルパーをバイパスしたり、ホスト固有の製品ロジックコピーを作成したりしてはなりません。
初期化済みプロジェクトの復元契約
ホストまたはエージェントが一般的な初期化済みプロジェクトの復元要求を認識した場合:
- 広範なスキルファンアウトの前に、有効な RecallLoom サイドカーを確認する
- サイドカーが有効な場合、通常の RecallLoom 高速パスにルーティングする
- より広範なメモリまたはワークフローシステムは、サイドカーが存在しない、競合している、明らかに不十分である、またはユーザーが明示的に詳細なレビューを要求した場合にのみ参加させる
現在のパッケージラインでは、rl-resume は、初期化済みプロジェクトの復元チェックポイントのための単一の安定したオペレーター向けアクション名です。
自然言語による復元要求は、依然として主要な公開パスです。
パッケージ契約によってバックアップされていない手動サイドカーフォールバックやホストローカルな復元エイリアスを発明してはなりません。
公開インタラクションルール
RecallLoom は、デフォルトで実装言語ではなくユーザータスク言語を使用する必要があります。
- 「初期化」、「復元」、「既存のプロジェクト現実をインポート」、「続行」、「進捗を記録」を優先します。
- ユーザーが明示的にオペレーター/デバッグ作業を行っている場合を除き、ヘルパー名、セクションキー、または
coldstartラベルを先頭に付けないでください。 - 最初の応答は結果優先でアクションは軽めに保ちます。1つの明確な次の動きが、ルーティングの詳細を公開するよりも優れています。
- ランタイム要件が欠落している場合に手動サイドカーフォールバックを発明せず、ブロックされた状態を表面化して停止します。
- これはサイドカーを手動で構築することではなく、パッケージ化された復元およびヘルパー契約です。
高速パスと深層パス
RecallLoom は、高速パスをデフォルトのインタラクションモードとして扱う必要があります。
- 高速パス: 最小の信頼できるソースセット、最短のインタラクション、最低の中断コスト。
- 深層パス: ソースが競合している場合、ソースカバレッジが不十分な場合、直接の推奨に対してリスクが高すぎる場合、またはユーザーが明示的に詳細なレビューを要求した場合のみ。
- ホストメモリ入力はオプトインでヒントのみのままです。その存在は、エージェントをサイレントプロモーションではなく明示的なレビューに向けるバイアスをかける必要があります。
レジュームモードの選択:
- 次のエージェントが何を読むかを決定する前に通常の階層化された読み取り計画ガイダンスを必要とする場合は、アンビエントな
resumeまたはstatusを使用します。 - 現在の状態の把握で十分であり、次の安全なアクションを
state.jsonとrolling_summary.mdから選択できる場合はresume --fastを使用します。 - アクションの前に安定したフレーミング、ソースオブトゥルースルーティング、またはプロジェクトローカルの
update_protocol.mdガイダンスが必要な場合はresume --fullを使用します。 - デイリーログのエビデンスは
query_continuity.pyを通じてオンデマンドで提供します。高速およびフルレジュームモードは、デフォルトでデイリーログに展開するべきではありません。
コアファイルモデル
RecallLoom は3つの主要なメモリレイヤーを使用します。
STORAGE_ROOT/context_brief.md: 安定したプロジェクトフレーミングSTORAGE_ROOT/rolling_summary.md: 上書き形式の現在の状態スナップショットSTORAGE_ROOT/daily_logs/YYYY-MM-DD.md: 追記専用のマイルストーンエビデンスSTORAGE_ROOT/config.json: 機械可読なワークスペース設定STORAGE_ROOT/state.json: 並行性認識ヘルパーのための機械可読なサイドカー状態STORAGE_ROOT/update_protocol.md: 読み取りおよび書き込み動作のための推奨プロジェクトローカルオーバーライドレイヤー
各ファイルの責任を一文で説明します。
context_brief.mdは、このプロジェクトが何であるか、どのようにアプローチすべきかを説明します。rolling_summary.mdは、現在何が真であるかを説明します。daily_logs/は、マイルストーンレベルで何が起こったかを説明します。config.jsonは、ストレージと言語設定を安定させます。state.jsonは、ワークスペースリビジョンとヘルパーから見えるサイドカー状態を追跡します。update_protocol.mdは、存在する場合、この特定のプロジェクトのデフォルトの読み取り/書き込みルールを狭めたり強化したりできます。
STORAGE_ROOT は PROJECT_ROOT/.recallloom/ または PROJECT_ROOT/recallloom/ のいずれかです。有効なストレージルートは1つだけ存在してもかまいません。両方が存在する場合は、推測せずに停止します。
ヘッダーラベルではなく、機械可読なマーカーが規範的なファイル契約です。プロトコル 1.0 はワークスペース言語 en および zh-CN をサポートします。references/file-contracts.md を参照してください。
最小コールドスタートフロー
- プロジェクトルートを見つける。
STORAGE_ROOT/config.jsonを読む。STORAGE_ROOT/state.jsonを読む。STORAGE_ROOT/rolling_summary.mdを読む。- `STORAGE_ROOT/update_protoco