Memories

Memories / 文件

本頁目錄

無人值守桌面 CLI 與 MCP

無人值守存取是明確授予、僅限本機且唯讀的能力，適用於選定的現用保險庫。它包含一般及私人記憶／卡片、原始二進位檔案、修訂歷程，以及明確要求的憑證明文。只有在您信任接收端用戶端能接觸這些保險庫中的每一項資產與機密時，才應啟用。這不是一般 MCP 權限，也不是永久 sudo 工作階段。

註冊並選擇保管方式

在另一個終端機啟動常駐程式，所有命令都使用同一個專用的絕對 home 路徑。請先以一般方式初始化您的資料庫並建立保險庫。以下路徑僅為範例；請在各平台使用自己的私人目錄。

memories --home /absolute/private/home daemon

在互動式終端機中明確選擇後端：

memories --home /absolute/private/home unattended enable --backend linux-secret-service

註冊流程會警告用戶端可以讀取儲存的密碼，要求您輸入 ENABLE，接著提示輸入本機密碼以解鎖，再次輸入以執行 sudo。這項同意／密碼設定只在註冊時需要一次，無須在每次無人值守讀取時執行。不要透過引數或環境變數傳遞密碼。後續管理仍需要一般以密碼解鎖、取得 sudo 授權的終端機。

後端 保管方式與需求
windows-dpapi 目前使用者的 Windows DPAPI；受保護檔案採用僅擁有者可存取的權限。不使用整部機器範圍或驗證介面。
macos-keychain 不同步的 macOS Keychain 項目；鎖定或需要核准的存取會直接拒絕，不會顯示提示。
linux-secret-service 工作階段匯流排上的 Secret Service，需有已解鎖的集合／項目。不會要求 Unlock 或呼叫 Prompt。
owner-file 桌面上明確選用的較低保護方案：將明文包裝材料存放於僅擁有者可存取的檔案，不提供防範作業系統帳號的密碼學保護。

例如，若刻意選擇較低保護方案，請使用 unattended enable --backend owner-file。原生後端無法使用或需要互動時，不會自動改用其他方式。Secret Service 依賴本機作業系統帳號／D-Bus 邊界；用戶端無法控制供應者特有的任意介面行為。後端只能在建立時選擇。不要編輯其中繼資料來切換後端。保管資料綁定正規化的儲存區路徑與目前標頭識別，因此將它複製到另一個儲存區不等於註冊。

密碼包裝仍可用於一般解鎖與復原。註冊會新增獨立的主金鑰包裝，其包裝金鑰保留在資料庫外；它不會取代密碼驗證。

簽發用戶端檔案

在同一個已授權的終端機中，為用戶端需要的保險庫簽發授權：

memories --home /absolute/private/home unattended mint --vault VAULT_ID --client-file /absolute/private/home/client.json
# Repeat --vault VAULT_ID to include another vault in this grant.

父目錄必須已存在，且僅擁有者可存取。簽發會以不可分割的方式發布檔案，不覆寫既有檔案，並拒絕不安全的擁有權、權限或連結。發布失敗時會嘗試撤銷新授權，並回報撤銷失敗。輸出包含授權 ID 與檔案路徑，絕不包含 bearer 權杖。請保留 ID 以便撤銷。

這個用戶端檔案與一般 MCP 授權檔案分開。請像密碼一樣保護它；不要顯示其內容、提交至版本控制，或將其權杖放入命令引數。CLI/MCP 讀取需要明確使用 --client-file 選擇檔案，並使用相同的 home／儲存區。範圍是選定保險庫的 read_only_all_assets，不是逐項資產或僅限一般內容的授權。每次讀取都會重新檢查目前本機裝置的成員資格與保險庫範圍。

啟動與讀取

註冊後重新啟動常駐程式，以使用僅載入金鑰的啟動模式。停止時不要執行 memories lock，接著以相同 home 再次啟動。成功啟動會載入無人值守金鑰，但一般狀態仍回報 unlocked: false：一般讀取、寫入、sudo、雲端作業與 RAG 會持續鎖定，直到以密碼解鎖。後端失敗會使無人值守金鑰維持未載入，不會改用密碼或環境既有驗證。

在 Unix 上，強制終止可能在 home 目錄留下 service.sock。僅在確認其常駐程式已停止後，才移除該失效 socket。

memories --home /absolute/private/home unattended list VAULT_ID --client-file /absolute/private/home/client.json
memories --home /absolute/private/home unattended history VAULT_ID ASSET_ID --client-file /absolute/private/home/client.json
memories --home /absolute/private/home unattended read VAULT_ID ASSET_ID --client-file /absolute/private/home/client.json
memories --home /absolute/private/home unattended credential-bytes VAULT_ID CREDENTIAL_ID --client-file /absolute/private/home/client.json

清單回傳資產中繼資料，包含私人、檔案與憑證資產，但不含其主體；會略過刪除標記。歷程回傳修訂中繼資料，包含目前版本／已刪除／隔離旗標，不含憑證主體。目前資產若有衝突，必須明確指定相符的修訂。可以明確讀取歷史與已刪除修訂，但隔離修訂會遭拒絕。此途徑讀取現用保險庫歷程，而非復原封存。

read 回傳記憶／卡片的 Content JSON 位元組，或檔案的原始位元組。它拒絕憑證。credential-bytes 只接受憑證，並回傳儲存主體的 UTF-8 位元組，明確選取時也包含歷史值。它不會新增任意二進位憑證儲存能力。受保護卡片與 wiki 機密參照仍保留為參照；需要時請另外要求其參照的憑證。

重組完整位元組

回應使用 data 承載不含填補字元的 base64url，並包含從零起算的 offset、位元組 total、next（完成時為 null）、實際 revision 與 encoding（content_json 或 raw_bytes）。取得完整內容的方式：

  1. 從位移 0 開始要求資料，--limit 設為 1 到 65536 位元組（預設 65536）。
  2. 將每個回應的 data 分別以不含填補字元的 base64url 解碼。
  3. 使用 next 作為下一個 --offset，並在後續每個請求中以 --revision REVISION_ID 固定使用第一次回傳的修訂。
  4. 持續至 next 為 null，然後依序串接已解碼的位元組範圍。只有在此之後，才於適用時解碼 UTF-8/JSON；單一範圍可能切開 UTF-8 字元。

例如，後續範圍使用：

memories --home /absolute/private/home unattended read VAULT_ID ASSET_ID --client-file /absolute/private/home/client.json --revision REVISION_ID --offset NEXT_OFFSET --limit 65536

credential-bytes 使用相同選項。不要串接已編碼字串，也不要把第一個範圍當作整項資產。清單／歷程使用 --offset，以及 1 到 100 項的 --limit（預設 100）；分頁反映目前狀態，而非快照，因此請求之間的變更可能改變排序與總數。

透過 MCP 連接 AI 用戶端

以相同 home 與用戶端檔案設定獨立的 stdio 伺服器命令：

memories --home /absolute/private/home mcp serve-unattended --client-file /absolute/private/home/client.json

它只提供 unattended_list、unattended_history、unattended_read 與 unattended_credential_bytes。工具引數為 vault、asset（清單除外）、選用的 revision（位元組讀取）、offset 與 limit。工具結果在 MCP 文字內容中包含相同的分頁／範圍 JSON；完整下載遵循上述位元組範圍契約。不提供資產修改、執行、管理、同步、備份匯出、搜尋／模型執行或推進 OTP 計數器的工具。讀取會先儲存已簽署的交付意圖，再回傳輸出；稽核／儲存失敗時會拒絕交付。

一般 mcp serve --grant-file 維持不變，仍排除私人內容、檔案與憑證讀取。兩種伺服器都不會繼承終端機 sudo。Center 管理的儲存區拒絕無人值守註冊／啟動／使用。HTTP/WebSocket、中繼 RPC、行動版 FFI/Share 與 WebUI 無法使用無人值守權限。這些命令會拒絕遠端旗標、環境連線選項與儲存的遠端預設值，即使執行檔的說明列出了全域遠端選項。

憑證 base64 是編碼，不是加密。 無人值守 MCP 刻意將機密位元組交給接收端用戶端。AI 供應者、對話紀錄、工具日誌、快取或外掛可以保留或傳送編碼值或解碼後的明文。唯讀範圍防止透過這項能力修改資料，無法防止洩漏或在其他地方使用已複製的機密。測試時請使用合成機密。

鎖定、恢復、撤銷與停用

memories --home /absolute/private/home lock

手動鎖定會清除金鑰，並持久阻止無人值守啟動，重新啟動後仍有效。單純以密碼解鎖不會恢復此功能。若持久寫入失敗，鎖定會回傳錯誤；不要假設禁止狀態已保存在無法寫入的裝置上。閒置／關機清理不等於手動禁止。

管理需要在本機終端機以密碼解鎖並執行 sudo：

memories --home /absolute/private/home unlock
memories --home /absolute/private/home sudo
memories --home /absolute/private/home unattended status
memories --home /absolute/private/home unattended resume

狀態會回報啟用／禁止狀態與授權 ID，不會回報權杖。恢復後，在不手動鎖定的情況下重新啟動常駐程式，即可回到僅載入金鑰的狀態。若要移除單一用戶端或停用所有無人值守存取：

memories --home /absolute/private/home unattended revoke GRANT_ID
memories --home /absolute/private/home unattended disable

撤銷會持久保存，且重複執行結果相同。停用會持久停用權限，並在後端清理前撤銷每一項授權。若有人已複製用戶端檔案，單純刪除檔案不等於撤銷。鎖定、撤銷與停用無法收回已交付的明文；請向供應者輪替已暴露的憑證。

復原與驗證限制

無人值守包裝／權限紀錄不包含在邏輯匯出備份、裝置配對或保險庫同步中。還原邏輯備份不會還原無人值守註冊。完整複製原始本機資料庫仍會包含輔助資料表，檔案系統備份也可能複製用戶端檔案或保管材料。同帳號程序、作業系統管理員、程序記憶體、整部裝置回復與安全抹除，仍不在 SECURITY.md 的保證範圍內。

已實作的介接器涵蓋 Windows DPAPI、macOS Keychain、Linux Secret Service 與 owner-file 保管方式。Linux 端對端驗證以 owner-file 保管方式搭配真正的常駐程式、私人記憶、原始二進位檔案與合成 UTF-8 憑證。涵蓋僅載入金鑰的重新啟動、CLI／標準輸入輸出 MCP、一般／雲端／RAG 拒絕、跨重新啟動的手動禁止、恢復、撤銷與停用。Linux 保管測試與隔離的 D-Bus 協定測試環境提供額外涵蓋，但該環境不是實際桌面金鑰圈測試。

Windows/macOS 原生往返測試、原生鎖定／需要核准及不顯示介面的行為，以及實際桌面金鑰圈驗證，仍是發布門檻。跨目標建置或錯誤轉換測試無法證明這些原生行為。獨立審查尚待完成；通過測試不等於安全稽核。聚焦驗證命令請參閱 CLI 實作說明 與核心契約。