/sibyl-save - 會話記憶同步 + 技能提取（Sibyl 記憶外掛）
屬於 Sibyl Labs 開放技能集的一部分。MIT 授權。由 Sibyl Labs, LLC 建置。
Sibyl 記憶外掛的配套技能。它會捕捉本次會話中發生的所有事情，並透過外掛自身的介面注入到外掛的本機記憶資料庫（~/.sibyl-memory/memory.db），然後將可重複使用的模式提取為新技能。
它不會直接寫入原始記憶檔案。所有記憶都經過外掛處理，因此分層、全文索引以及免費版上限都會被遵守。由於外掛在其支援的所有工具（Claude Code、Codex 以及任何 MCP 主機；Hermes 則透過 Python SDK）上都暴露了相同的 MCP 工具，因此這個單一技能天生就能跨越多種工具。
需求
需要安裝並設定 Sibyl 記憶外掛：
pip install sibyl-memory-cli
sibyl init # 瀏覽器/錢包啟用，寫入 ~/.sibyl-memory/
sibyl setup claude-code # 或: codex | hermes (將記憶介面接入你的工具)
然後，此技能透過以下兩種介面之一與外掛溝通：
- MCP（Claude Code、Codex、Cursor、任何 MCP 主機）：下方的 8 個
memory_*工具。 - Python SDK（Hermes 或任何 Python 代理）：
sibyl_memory_client.MemoryClient/sibyl_memory_hermes.SibylMemoryProvider。
外掛介面
| 用途 | MCP 工具 | Python SDK |
|---|---|---|
| 儲存一個事實/實體 | memory_remember(category, name, body) | client.set_entity(category, name, body) |
| 召回一個實體 | memory_recall(category, name) | client.get_entity(category, name) |
| 列出實體 | memory_list(category, limit) | client.list_entities(category) |
| 全文搜尋 | memory_search(query, limit, tiers) | client.search(query) |
| 設定狀態文件 | memory_set_state(key, body) | client.set_state(key, body) |
| 取得狀態文件 | memory_get_state(key) | client.get_state(key) |
| 記錄日誌事件 | memory_record_event(kind, body, category, name) | client.write_event(...) |
| 封存/遺忘 | memory_forget(category, name, reason) | client.archive_entity(category, name, reason) |
以下範例使用 MCP 名稱。若在 Hermes 或 Python 代理上，請使用 SDK 欄位。
分層對應
| 會話內容 | 分層 | 呼叫方式 |
|---|---|---|
| 會話指標/摘要/前瞻事項 | HOT（狀態） | memory_set_state("session", ...) |
| 排序後的優先事項 | HOT（狀態） | memory_set_state("priorities", ...) |
| 會話日誌條目 | COLD（日誌） | memory_record_event("session_save", ...) |
| 專案/人員/產品 | WARM（實體） | memory_remember(category, name, body) |
| 已關閉/已失效項目 | ARCHIVE | memory_forget(category, name, reason) |
| 此技能的設定 + 增量標記 | HOT（狀態） | memory_set_state("sibyl_save:config" / "sibyl_save:last_save", ...) |
模式
- run（預設）：
/sibyl-save、save session、sync memory。將會話上下文注入外掛，然後提供技能提取。 - setup：
/sibyl-save setup、/sibyl-save config。互動式。建立或編輯設定（儲存在外掛的狀態鍵sibyl_save:config）。首次使用前執行一次。 - preview（試執行）：
/sibyl-save preview、/sibyl-save --dry-run。執行完整分析並報告所有預定寫入動作。不呼叫任何會修改資料庫的動作。不更新增量標記。
模式：setup（動態設定）
目標：將設定寫入外掛的狀態鍵 sibyl_save:config。保持互動且精簡。能推斷的就推斷；只詢問無法推斷的部分。
- 工具。偵測或詢問這是哪個工具（claude-code、codex、cursor、hermes、其他）。這會影響第二階段技能檔案的寫入位置。
- 技能輸出。新技能在此工具下的寫入位置。Claude Code 的預設值：
.claude/skills/<name>/SKILL.md。對於其他工具，請確認技能位置與格式。儲存為skill_output: {dir, format}。 - 優先事項。排序清單的狀態鍵（預設為
priorities）以及上限。預設上限為 15。硬性上限為 30：不得接受超過 30 的值。超過 30 的清單是待辦事項清單，不是優先事項集。 - 實體類別。你要追蹤的 WARM 類別（預設為
project、person、product）。使用者可以新增或移除。 - 額外捕捉。可選地指定每次儲存時應填入的額外狀態鍵或實體類別（例如一個指標狀態文件、一個聯絡人類別）。這是擴充點。
- 試執行預設值。切換
dry_run_default（預設為 false）。 - 寫入設定。透過
memory_set_state("sibyl_save:config", {...})進行。不要碰觸增量標記。
設定格式：請參閱 examples/sibyl-save-config.example.json。重新執行 setup 會就地編輯它。
模式：run
第一階段：記憶同步（進入外掛資料庫）
步驟 0 - 載入設定與增量
memory_get_state("sibyl_save:config")。如果不存在，則切換到 setup 模式。memory_get_state("sibyl_save:last_save") 作為增量錨點（自上次儲存以來發生了什麼變化）。如果 dry_run_default 為 true 且未指定模式，則以 preview 模式執行。
步驟 1 - 讀取目前狀態
memory_get_state("session")以及memory_get_state(<priorities 鍵>)memory_list(category, limit)用於追蹤的類別，以及memory_recall/memory_search用於本次會話中觸及的實體- 設定中指定的任何額外狀態鍵或類別
步驟 1.5 - 優先事項檢查與協調
讀取優先事項狀態文件並就地協調（透過 memory_set_state 寫回）。條件與每項條件所需的動作：
- COMPLETED 項目仍被列出：將其移除；透過
memory_record_event("priority_closed", {...})記錄關閉。 - RANK_DRIFT / DUP_RANK（排名不是連續的 1..N，或排名重複）：重新編號為 1..N。
- OVER_CAP（項目數超過上限）：將最低優先順序的項目移至一個待辦事項狀態文件，直到達到或低於上限。
- STALE_ITEM（超過 14 天未更新）：向使用者提出。
- TERMINAL entity（引用的實體已被封存/失效）：關閉該優先事項。
- BROKEN entity ref（指向不存在的實體）：修正為真實的
category/name。
每次寫入時都強制遵守上限（永遠不超過 30）。
步驟 2 - 分析會話
檢閱自增量錨點以來（或首次儲存時從會話開始）的對話。提取：
- 觸及的實體 - 建立、讀取或修改的專案、人員、產品
- 採取的動作 - 具體發生的事情，包含識別符號
- 做出的決定 - 策略性選擇及其理由
- 前瞻事項 - 下一次會話的動作，以動詞開頭（"部署..."、"跟進..."、"驗證..."）
- 警告 - 活躍風險、阻礙因素、截止期限、差點出錯
- 學到的教訓 - 操作層面的改進（這些會提供給第二階段）
- 額外捕捉 - 設定中任何額外狀態鍵/類別的資料
步驟 3 - 注入到外掛資料庫
在 preview 模式下，不呼叫任何會修改資料的動作。報告預定的寫入（步驟 4）並停止。
- 會話狀態 -
memory_set_state("session", { last_session, summary, forward, entities_touched, warnings })。前瞻事項僅為動作參考，絕非餘額快照或任何會過期的內容。 - 日誌事件 -
memory_record_event("session_save", { evaluated, acted, forward, extra })。每次儲存一個事件（按設計為僅附加）。 - 優先事項 -
memory_set_state(<priorities 鍵>, { updated, cap, items })，已設上限。溢出的部分移至待辦事項狀態文件。 - 實體 - 對於每個變更的實體，執行
memory_remember(category, name, body)。新實體只是新的memory_remember呼叫；外掛會為它們建立索引，因此無需維護單獨的註冊表。 - 已關閉/已失效 -
memory_forget(category, name, reason)。 - 額外捕捉 - 套用每個設定的額外狀態鍵/類別。
- 增量標記 -
memory_set_state("sibyl_save:last_save", { ts: <now> })。在 preview 模式下跳過。
步驟 4 - 報告
簡潔摘要：寫入的實體、更新的狀態文件、日誌事件 ID、新增/關閉的優先事項、額外捕捉，以及下次會話的前瞻事項。在 preview 模式下，每一行都標註為「將會」執行，並確認沒有任何資料被寫入。
第二階段：技能提取（工具原生格式）
無論使用何種工具，技能都以相同方式呈現：識別、提議，然後為目前工具建立原生的技能檔案。
步驟 5 - 識別可重複使用的模式
掃描會話中符合任何以下條件的操作：重複（本次會話中出現多次）、週期性（很可能再次出現）、多步驟（3 個以上連續步驟）、非顯而易見（值得記錄的解決方案）、容易出錯（需要檢查清單）。對每個候選項目評估名稱（簡短的祈使動詞短語）、觸發條件、參數、複雜度（是否有任何危險步驟）、頻率。
步驟 6 - 提議候選項目
每個候選項目以一行摘要呈現，包含名稱、描述和預估頻率。然後詢問：「建立這些？或者跳過哪些？」
步驟 7 - 建立通過的技能（工具原生格式）
從設定中讀取 skill_output，了解此工具期望的技能位置與格式。預設值：
| 工具 | 技能位置 | 格式 |
|---|---|---|
| claude-code | .claude/skills/<name>/SKILL.md | YAML 前端資訊（名稱、描述）+ Markdown 主體 |
| codex | ~/.codex/prompts/<name>.md（在 setup 中確認） | Markdown 提示 |
| cursor | .cursor/ 命令/規則（在 setup 中確認） | 依 Cursor 慣例 |
| 其他 | 來自 skill_output.dir | 來自 skill_output.format |
對於每個通過的技能，在設定的位置寫入檔案，包含觸發短語、逐步說明、參數描述、任何危險步驟的安全檢查，以及一個使用範例。報告檔案路徑。
不要建立符合以下條件的技能：與現有技能重複（先檢查技能位置）、過於特定於本次會話而不太可能重現、包裝一個簡單的單一指令、或需要編輯你的操作規則所保護的檔案（將這些情況提出，不要自行編輯）。
規則（不可協商）
- 永遠不要將即時資料（餘額、價格、數量）儲存為持久性事實。捕捉參考，而非快照。
- 會話前瞻事項應以動作為導向並以動詞開頭。
- 每次儲存一個日誌事件（僅附加；永遠不要重寫歷史）。
- 優先事項有上限（預設 15，永遠不超過 30）。溢出的部分移至待辦事項狀態文件。
- 實體透過
category+name定址；讓外掛作為索引。無需平行註冊表。 - 所有記憶寫入都需透過外掛介面。永遠不要直接寫入
~/.sibyl-memory/檔案或開啟memory.db：客戶端會處理鎖定與免費版上限。 - 將現有技能視為唯讀。除非明確要求，否則建立新技能而非就地編輯。
授權與來源
MIT（請參閱 LICENSE）。每個 Markdown 檔案頂端的水印註解是歸屬與來源標記，並非使用限制。使用 node scripts/watermark.mjs verify 驗證副本。詳情請見 WATERMARK.md。