RecallLoom
RecallLoom 是一個可攜式的上下文掛鉤工具,專為基於工作階段的代理設計。
它提供一個輕量級的檔案模型,讓專案能在不同工作階段之間保持連續性,無需依賴龐大的基礎設施。
目標不是記住所有事情,而是將正確的專案狀態持久化、可讀且可在不同工作階段之間恢復。
套件範疇
此檔案是可供安裝的 recallloom/ 技能套件面向代理的入口點。
透過主機代理的正常技能探索流程來安裝並觸發此套件。 RecallLoom 本身在套件內不需要自訂的主機特定啟動器。 該套件仍可能為支援的主機提供可選的原生包裝器範本。
此可安裝套件刻意保持精簡。 面向人類的儲存庫登陸頁面和行銷文件可能存在於上游,但它們不會被捆綁到已安裝的技能目錄中。
在原始儲存庫中,README.md 和 README.en.md 是簡潔的公開入口,README.zh-CN.md 是相容性條目,INDEX.md 是完整地圖,而 USAGE.md 是操作指南。
這些檔案描述了與此已安裝套件入口點相同的輔助合約,而不是定義第二套邏輯。
關於套件庫存、協定細節和輔助腳本行為,請依賴套件本身內附的檔案:
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 套件的支援狀態與專案的 sidecar 協定相容性分開處理。
- 輔助腳本必須執行套件支援檢查,且不得將支援狀態寫入專案的
.recallloom/目錄中。 - 如果支援狀態為
readonly_only,則變更輔助腳本必須封鎖,而診斷與唯讀輔助腳本可繼續執行。 - 如果支援狀態為
diagnostic_only,則僅診斷輔助腳本應繼續執行。 - 如果支援狀態為
unknown_offline,診斷與唯讀動作可繼續執行,但變更動作必須封鎖,直到支援狀態可被驗證。 - 被封鎖的動作必須返回一個帶有
blocked_reason: package_support_blocked和一個package_support物件的共用失敗合約。請參閱references/package-support-policy.md。
公開表面與必要檢查
- 公開的套件與發佈表面必須僅限於使用者需要安裝、理解和操作該套件所需的檔案。
- 公開表面不得包含複製的專案記憶、產生的執行期輸出、機器本機資料、僅維護者使用的工作檔案,或非安裝套件所需的資料。
- 公開的 CI 與必要檢查可以驗證儲存庫內容與後設資料。
- 必要檢查的措辭不得將儲存庫檢查視為使用者本機工作區狀態、主機行為或 sidecar 信任狀態的證明。
非侵入式預設值與 UX 閘門
- 核心安裝與日常使用不得要求或自動安裝掛鉤、守護行程、監視器、MCP/外掛強制措施、主機轉接器、遙測/指標或遠端承載傳輸。
- 原生指令包裝器是選擇性的便利性入口點,用於存取同一個調度器,而非強制性的強制層。
- 在受管理的 sidecar 外部對一般文件/來源/計畫進行的編輯,除非影響到涉及來源追溯的 RecallLoom 狀態,否則應保持靜默允許或低摩擦。
- 受管理的 sidecar 或影響來源追溯的動作,應在輔助腳本就緒輸出中顯示
allow、warn、ask或block之一(當來源追溯狀態相關時)。 warn用於低風險的結構性唯讀或可讀的舊有狀態,應保持簡短;對於同一工作階段內重複的低風險警告,應有冷卻機制。ask用於舊有審查/修復匯入或已審查的匯入基準線動作,並且在執行較高風險的寫入前需要操作員明確確認。block是不可豁免的,適用於偽造的標記、偵測到的收據/儲存不一致、直接編輯state.json/config.json、隱私權違規,以及任何被歸類為inconsistent_or_tampered_evidence的狀態。- 不得將遠端服務、主機記憶、外掛、MCP、掛鉤或包裝器呈現為本機輔助證據的權威來源。
- 以收據為基礎的變更僅限於調度器發出的受管理檔案寫入、對目前最新游標進行的每日記錄附加,以及附加後的摘要同步。封存套用與橋接套用仍僅為預覽狀態,直到這些表面獲得自己的收據支援。
寫入協定紅線
- 受管理的 sidecar 寫入必須使用輔助腳本。不得使用盲目檔案取代、盲目修補或手動建立的 sidecar 檔案來繞過它們。
- 每日記錄寫入必須使用
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..N,而正規的entry-id是entry-{entry_seq}。不得將任何一個視為全域唯一。 - 將
state.json.daily_logs.entry_count保留為entry_count;它表示最新活躍每日記錄中的條目標記計數,而非全域累計計數。 - 如果輔助腳本寫入失敗,請進行診斷、修正、重試,然後如果仍無法完成,則回報輔助腳本失敗合約。
- 損壞的 sidecar 復原必須使用正規的復原提案/審查/推廣輔助腳本和
validate_context.py;不得手動編輯受管理的標記、state.json、config.json、收據或輔助證據儲存。
何時使用
當您需要以下情況時,請使用 RecallLoom:
- 在暫停後繼續進行現有專案
- 從維護的檔案中還原專案上下文
- 維護當前狀態的專案記憶
- 記錄有意義的里程碑進度
- 減少跨工作階段或工具間的上下文偏差
典型的觸發條件包括:
- 繼續此專案
- 還原專案上下文
- 從我們離開的地方繼續
- rl-init
- 更新專案記憶
- 記錄今日進度
- 在維護的專案檔案中準備一個乾淨的下一步交接
首次附加行為
在專案中首次明確呼叫時,RecallLoom 不應假設工作區已經初始化。
正確流程是:
- 偵測是否已存在有效的 RecallLoom sidecar
- 如果存在,則正常繼續,不將初始化變成額外的儀式
- 如果不存在,則說明專案尚未初始化,並詢問是否應執行初始化
- 如果使用者明確確認,或直接說
rl-init,則執行標準初始化動作 - 如果環境無法提供 Python
3.10+,則以封鎖的執行時期結果停止,而不是手動建立 sidecar
rl-init 的含義是:初始化 sidecar,驗證工作區,並返回下一個建議動作。即使主機未暴露原生命令,也應將其視為穩定的高階動作名稱。
當前動作表面
對於目前套件線,穩定的面向操作員的包裝器目標為:
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 進行乾執行;僅在 preflight 允許僅後設資料的 post_append_summary_sync 之後,才使用 sync-current-state-after-append --reuse-current-summary --semantic-unchanged-assertion-json <json>;請參閱 references/recording-workflow.md 以了解受約束的斷言 JSON 骨架。
當 state.json.daily_logs 不再與解析出的最新活躍每日記錄相符時,請先以預覽模式使用 repair-daily-log-cursor。套用模式需要 --apply --yes,應在進行新的預覽/狀態檢查後包含 --expected-workspace-revision,其支援閘門為變更操作,並且會修復游標欄位,而不會寫入輔助收據或重寫每日記錄內容。
這些調度器新增項目對於現有的 v0.3.4 專案是選用的,並且不會改變 sidecar 協定 1.0。
rl-init、rl-resume、rl-status 和 rl-validate 的原生包裝器僅是便利性入口點。它們必須委派給同一個調度器,且不得取代自然語言的還原請求、繞過輔助腳本,或建立主機特定的產品邏輯副本。
已初始化專案的還原合約
當主機或代理看到一個通用的已初始化專案還原請求時:
- 在廣泛的技能分發之前,檢查是否存在有效的 RecallLoom sidecar
- 如果 sidecar 有效,則路由到正常的 RecallLoom 快速路徑
- 僅當 sidecar 缺失、衝突、明顯不足,或使用者明確要求深入審查時,才讓更廣泛的記憶或工作流程系統參與
對於目前套件線,rl-resume 是該已初始化專案還原檢查點的單一穩定面向操作員的動作名稱。
自然語言的還原請求仍然是主要的公開路徑。
請勿發明一個未由套件合約支援的手動 sidecar 後備方案或主機本機的還原別名。
公開互動規則
RecallLoom 應預設使用使用者的任務語言,而非實作語言。
- 偏好使用「初始化」、「還原」、「匯入現有專案狀態」、「繼續」和「記錄進度」。
- 除非使用者明確在進行操作員/除錯工作,否則不要以輔助腳本名稱、章節鍵或
coldstart標籤作為開頭。 - 保持第一個回應以結果為先、動作輕量:一個明確的下一步勝過揭露路由細節。
- 當缺少執行時期需求時,請勿發明手動 sidecar 後備方案;應回報封鎖狀態並停止。
- 這不是手動建立 sidecar;這是打包的還原與輔助合約。
快速與深入路徑
RecallLoom 應將快速路徑視為預設的互動模式。
- 快速路徑:最小的可信來源集合,最短的互動,最低的中斷成本。
- 深入路徑:僅當來源衝突、來源覆蓋範圍不足、風險過高無法給出直接建議,或使用者明確要求深入審查時使用。
- 主機記憶輸入保持選用且僅供提示;其存在應促使代理進行明確審查,而不是靜默提升。
恢復模式選擇:
- 當下一個代理在決定讀取什麼之前需要正常的分層讀取計畫指導時,使用一般的
resume或status。 - 當當前狀態導向已足夠,且可以從
state.json加上rolling_summary.md中選擇下一個安全動作時,使用resume --fast。 - 當需要穩定的框架、事實來源路由,或專案本機的
update_protocol.md指導才能執行動作時,使用resume --full。 - 透過
query_continuity.py按需提供每日記錄證據;快速與完整恢復模式預設不應展開每日記錄。
核心檔案模型
RecallLoom 使用三個主要的記憶層:
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:機器可讀的 sidecar 狀態,供並行感知輔助腳本使用STORAGE_ROOT/update_protocol.md:建議的專案本機覆蓋層,用於讀取和寫入行為
一句話說明檔案職責:
context_brief.md解釋這個專案是什麼以及應如何處理。rolling_summary.md解釋當前的真實狀態。daily_logs/解釋在里程碑層級發生了什麼事。config.json保持儲存和語言設定的穩定性。state.json追蹤工作區修訂和輔助腳本可見的 sidecar 狀態。update_protocol.md(若存在)可以縮小或加強此特定專案的預設讀寫規則。
STORAGE_ROOT 是 PROJECT_ROOT/.recallloom/ 或 PROJECT_ROOT/recallloom/。最多只能存在一個有效的儲存根目錄;如果兩者同時存在,則停止而非猜測。
機器可讀的標記(而非標題標籤)是規範的檔案合約。協定 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