MemoriesMemories 使用說明
本文說明如何用目前 CLI 完成已實現的主要任務。範例裡的 VAULT_ID、ASSET_ID 和其他大寫識別碼，都要換成命令實際回傳的短 ID。密碼從互動式終端機無回顯讀取。沒有密碼參數，也沒有密碼環境變數。應用不限制本機密碼和備份密碼的長度，空輸入也可以；仍需要確認的步驟會要求再次輸入。
所有資料命令都先要有一個正在執行、並且使用同一資料目錄的常駐程式。全域選項：
| 選項 | 作用 |
|---|---|
--home PATH 或 MEMORIES_HOME |
選擇資料目錄。預設是作業系統的應用資料目錄 |
--config PATH 或 MEMORIES_CONFIG |
選擇 TOML 設定。命令列優先於環境變數，然後是設定檔案，最後是內建預設值 |
--lang en\|zh\|ja\|de\|fr |
只影響這一次命令的介面語言 |
命令輸出是帶版本的 JSON。失敗時結束代碼非零。確認詞 USE 和 APPROVE 保持英文，不隨介面語言改變。
Linux 可以執行 CLI、常駐程式、中繼、FFI 和下面的狀態頁。Linux 沒有原生系統匣。手機端沒有模型檢索介面，也沒有背景同步，也不能用相機匯入 OTP QR 碼。代管裝置配對可以掃描配對碼，見裝置間端到端秘密。真實雲帳號的端到端驗證尚未完成。命令列可以匯入 HOTP、otpauth://、otpauth-migration://，並用 --image 解碼 OTP QR 碼圖片。
按任務找入口
| 要做什麼 | 閱讀位置 |
|---|---|
| 第一次儲存筆記 | 啟動與初始化，再寫入、讀取和搜尋 |
| 選擇記憶、brain、persona 或檔案 | 產品概念 |
| 搜尋文件或獲得帶引用的回答 | 檢索與問答 |
| 儲存密碼、權杖、金鑰或 OTP | 憑證與受保護卡片 |
| 換裝置、給別人共享或還原備份 | 裝置、同步和備份 |
| 接入 AI 用戶端 | MCP 與 skill |
| 用步驟或清單追蹤工作 | 工作流程卡片與清單範本 |
| 由組織統一簽發授權 | 授權中心 |
| 手機首次使用、連線自建服務或 SaaS | 手機模式選擇與切換 |
不清楚參數時，先看總幫助，再逐級看子命令；幫助不需要常駐程式：
memories --help
memories --lang zh memory --help
memories --lang zh memory put --help
--lang zh 只切換幫助與提示語言，不改變命令名或參數寫法。本文的 sh 範例使用 POSIX shell；多行命令的行尾 \ 是續行符，在 PowerShell/CMD 中請合併成一行。
啟動常駐程式並初始化保管庫
在一個終端機中啟動服務。它只接受目前作業系統使用者的連線：Windows 使用具名管道，Linux 和 macOS 使用 Unix 通訊端。
memories daemon
另開一個終端機初始化裝置、建立保管庫、鎖定和重新解鎖：
memories init --name laptop
memories vault create Personal
memories vault list
memories lock
memories unlock
memories status
memories identity
--name 可省略，預設裝置名是 local-device。identity 顯示本裝置的公開身分。初始化、解鎖和 sudo 必須在互動式終端機中輸入密碼。不要把 --home 指到一個已有的一般資料夾；程式會收緊該目錄的權限。
這裡的本機儲存（store）是 --home 選擇的資料目錄，初始化建立本機身分與密碼保護；保管庫（vault）是其中按成員和權限劃分的資料集合，一個儲存可以有多個保管庫。自訂目錄時，服務和每個用戶端命令都要帶相同的 --home PATH。已有儲存以後只需 unlock，不要重複 init。如果要把新裝置加入已有身分，先完成裝置配對，不要先建立 Personal 或「此裝置」保管庫。
完成上面的步驟後，用編輯器新建 UTF-8 檔案 notes.md，寫入一句含「專案」的測試筆記。把下面範例的 VAULT_ID 換成 vault create 或 vault list 回傳的 id，即可儲存並搜尋第一條記憶：
memories memory put VAULT_ID --title "项目笔记" --input notes.md
memories memory search VAULT_ID "项目"
儲存結果中的 id 就是後續讀取所用的 ASSET_ID。一般筆記用 memory；需要標籤、分類和關係時用 card；原始 PDF 等檔案用 file，不會自動變成可搜尋文字；秘密用 credential，不要放進一般筆記。
普通 unlock 允許權限範圍內的一般資料操作，並不開放私人內容、檔案或憑證。
sudo 是本機授權工作階段，不是作業系統管理員權限。它使用同一個本機密碼，最長 15 分鐘，空閒 5 分鐘後失效，並且只屬於該終端機的父程式。鎖定或重啟服務會清除它。一般解鎖在空閒 15 分鐘後失效。
檢視或建立非秘密設定：
memories config path
memories config init
memories config init --output ./development.toml
memories --config ./development.toml config show
config init 不會覆蓋已有檔案。config show 不開啟加密庫。設定項包括 storage_dir、relay_url，以及 [desktop] 和 [rag]。不要把密碼、私鑰、OAuth 權杖或 MCP 授權寫進這個檔案。改儲存目錄或模型設定後，要同時重啟常駐程式。
寫入、讀取和搜尋記憶與卡片
寫入一般記憶。內文放在 UTF-8 檔案裡，用 --input 傳入：
memories memory put VAULT_ID --title "项目笔记" --input notes.md
memories memory search VAULT_ID "项目"
memories memory read VAULT_ID ASSET_ID
memories memory history VAULT_ID ASSET_ID
memories memory diff VAULT_ID ASSET_ID FROM_REVISION
memories memory diff VAULT_ID ASSET_ID FROM_REVISION --to TO_REVISION
memories memory grep VAULT_ID 'project|release' -i -n
memory grep 用正規表示式逐行匹配所選保管庫中一般記憶的解密內文，輸出 DOCUMENT_ID:LINE；加 -n / --line-number 時輸出 DOCUMENT_ID:LINE_NUMBER:LINE，-i / --ignore-case 忽略大小寫。私有文件、衝突版本、卡片、檔案和憑證都不參與匹配，與一般搜尋排除私有內容的方式一致。沒有匹配時不輸出任何內容。
FROM_REVISION 和 TO_REVISION 都取自 history 回傳的 revision 欄位，而不是 id 欄位。基準版本是位置參數，不是 --from；省略 --to 時比較目前 head。
每次建立/更新都會在保管庫的簽章修訂 DAG 中追加版本（一般記憶、知識/腦圖卡片、受保護卡片中繼資料、檔案、憑證）。memory / card / file 的 history 列出版本（revision、時間戳、作者、是否 head、摘要）；read --revision 讀取歷史內文；diff 輸出統一文字差異（含標題與卡片中繼資料）。檔案 diff 省略二進位內文，只比較中繼資料與長度；憑證的秘密內文不可透過 diff/read 回傳。修訂隨保管庫長期保留，無自動修剪。
讀取某一歷史版本時加 --revision REVISION。替換已有記錄時加 --id ASSET_ID。出現多個未合併版本時，審閱歷史後再用 --id ASSET_ID --resolve 提交一個同時指向這些父版本的新版本。刪除目前可見記錄：
memories memory delete VAULT_ID ASSET_ID
刪除不擦除簽章歷史。--private 把記錄標為私有。私有記錄需要 sudo，並排除在一般搜尋和 MCP 之外。
知識卡片使用同一組資產子命令，並可以帶標籤、來源、別名、備註、分類和關係。card list（也可用頂層 memories list / memories ls）可省略保管庫 ID，掃描所有可存取保管庫（每個結果含 vault）。--type knowledge|brain|persona|workflow|account|env|token|totp|hotp|otp 按 summary.type 篩選（knowledge 為一般知識卡片；brain 為帶摘要與有類型連結的結構化知識卡片；otp 表示 totp+hotp），--otp 等同 --type otp。--category 按分類篩選，--group-by-category 按分類分組：
memories card put VAULT_ID --title "一个想法" --input notes.md --tag design --source "会议" --alias "设计备忘" --notes "工作坊" --category design
memories list
memories ls --type knowledge
memories card list --type brain
memories list --type otp
memories ls --otp --category security
memories card list VAULT_ID --category design
memories card list VAULT_ID --group-by-category
memories card brain VAULT_ID --title "Alice" --abstract "连接设计与工程的产品负责人" \
--link CARD_A=reports-to --link "OTHER_VAULT/CARD_B=collaborates|共同路线图" \
--alias "Alice" --notes "组织图" --category people
memories card brain VAULT_ID --id BRAIN_ID --title "Alice" --abstract "更新后的摘要" --link CARD_B=partner
memories card link VAULT_ID CARD_A CARD_B --relation supports
memories card unlink VAULT_ID CARD_A CARD_B --relation supports
memories card graph VAULT_ID
memories card graph VAULT_ID --include-private
memories card search VAULT_ID design
memories card list VAULT_ID
memories card read VAULT_ID CARD_ID
memories card delete VAULT_ID CARD_ID
card delete 與 memory delete 一樣，只把卡片從目前檢視中移除，簽章歷史仍保留早先的版本。刪除私有卡片或受保護卡片需要 sudo。
腦圖（brain）卡片儲存可搜尋的純文字 abstract（不升格為受保護機密），以及可跨保管庫的連結 { vault?, card, role?, note? }。--link 的寫法是 [VAULT/]CARD[=ROLE][|NOTE]，含 | 或空格時給整個值加引號，避免被 shell 當成管道。summary.type 為 brain，並含 link_count。列表/圖譜/讀取在權限允許時解析連結標題與類型，缺失或無權目標標記為 broken（不連帶刪除）。搜尋索引標題、摘要、連結角色/備註以及同庫公開目標摘要，從不索引機密。同庫腦圖連結也會出現在 card graph 中。
移動端編輯器支援手寫輸入和拍照/圖片文字識別，全部在裝置上完成，詳見 手寫與文字識別。
工作流程（workflow）卡片與清單範本
工作流程卡片的 summary.type 為 workflow。有序步驟儲存在卡片修訂中，每一步的狀態是 pending、active、done 或 skipped，卡片本身還有一個總體狀態。--step 的寫法是 TITLE 或 ID:TITLE，可在末尾加 =CARD 關聯一張卡片，每一步重複一次：
memories card workflow VAULT_ID --title Release --step "Write notes" --step Ship
memories card workflow-update VAULT_ID WORKFLOW_ID --advance
memories card workflow-update VAULT_ID WORKFLOW_ID --step STEP_ID --step-status done
memories card list --type workflow
--advance 推進指定的步驟；沒有指定時推進目前 active 的步驟，再沒有就推進第一個 pending 步驟。
清單範本也是 workflow 類型的卡片，資料中的 template 為 true。建立範本時 --template 不帶值，並需要 --assignee、--summary 和 --goal。--assignee 可以是人格卡片 ID、人格 ID 或任意名字；--assignee-name 是顯示名，指向人格卡片時預設用人格的顯示名。--template TEMPLATE_ID 會把範本的清單欄位和工作流程連結複製成一個任務：
memories card workflow VAULT_ID --template --assignee PERSONA_ID --summary "每周发布检查" --goal "按时发布"
memories card list --type workflow --template
memories card workflow VAULT_ID --template TEMPLATE_ID --workflow WORKFLOW_ID --archive MEMORY_ID
memories card workflow-update VAULT_ID TASK_ID --acceptance "已发布并通知" --status done
--workflow 關聯同一保管庫中的另一張工作流程卡片，--archive 歸檔一條記憶或卡片，可重複。workflow-update 的 --clear-workflow 和 --clear-archives 分別移除這兩類連結。任務本身沒有步驟時，--advance、--step、--step-status 和 --status 會作用在它關聯的工作流程上。驗收報告 --acceptance 在任務完成前可以為空。
人格（persona）卡片
人格卡片用於在 Grok Bot / Muse 等產品間同步性格與行為。保管庫中的人格卡片與其關聯檔案為權威來源。
memories persona import VAULT_ID /path/to/xiaoya-persona
memories card list --type persona
memories card read VAULT_ID PERSONA_ID
memories card history VAULT_ID PERSONA_ID
memories card diff VAULT_ID PERSONA_ID REVISION_ID
memories persona append-event VAULT_ID PERSONA_ID --text "行为记录" --kind note
- 核心（core）：怎麼說話、怎麼演；透過
persona put/persona_card修訂。 - 檔案（archives）：契約、日記、裝扮、視角等獨立知識卡片，由人格
archives連結，勿抄回核心。 - 行為事件：
append-event追加到events檔案（追加式）。
世界狀態、物品、自動化和人格間聊天也透過 persona 子命令維護。省略 VAULT_ID PERSONA_ID 時使用用戶端預設值中的 persona：
memories persona world-get VAULT_ID PERSONA_ID
memories persona world-set VAULT_ID PERSONA_ID --place "书房" --weather-condition "多云" --weather-temp-c 26
memories persona world-rollover VAULT_ID PERSONA_ID
memories persona thing put VAULT_ID PERSONA_ID --id notebook --name 笔记本 --count 1 --attrs '{"color":"blue"}'
memories persona thing list VAULT_ID PERSONA_ID
memories persona thing attr set VAULT_ID PERSONA_ID --id notebook --path color --value '"red"'
memories persona dice-roll VAULT_ID PERSONA_ID --sides 6
memories persona schedule-list VAULT_ID PERSONA_ID
memories persona automation list VAULT_ID PERSONA_ID
memories persona automation trigger VAULT_ID PERSONA_ID --id morning --source manual
memories persona chat send VAULT_ID PERSONA_A PERSONA_B --text "你好"
memories persona chat history VAULT_ID PERSONA_A --with PERSONA_B --limit 20
- 世界狀態：
world-set更新地點、姿態、裝扮、物品數量、天氣、骰子、轉盤、日程等；world-rollover在隔日時明確開始新的帳本日，只清除meals、orders_done、簡短look摘要和counters_today等當日欄位，累計計數保留。 - 物品（things）：
thing put/get/list/delete/image管理任意物品，thing attr get/set/delete用點號路徑或 JSON Pointer 讀寫單個屬性，attrs是自由 JSON。 - 自動化：
automation put/list/run/trigger/delete管理存放在世界狀態中的 hook，時區使用人格的timezone；出站webhook_out只能發往白名單中完全一致的 URL，預設空名單會攔截所有出站 POST，用automation webhook-allow --add URL/--remove URL管理。webhook 權杖不會在回應中回傳，只顯示webhook_token_set。 - 聊天：同一保管庫中兩張人格卡片之間的訊息，傳送時會觸發雙方的
chat_message自動化 hook（酬載不含訊息內文）；chat list檢視工作階段，讀取history不會標為已讀，需要chat mark-read。
詳見英文人格卡片指南。
建立一般卡片時也可以重複 --link TARGET_ID=RELATION。這類關係必須指向同一保管庫中的卡片。圖譜省略已刪除、衝突和未授權的節點，以及連線到這些節點的邊。--include-private 需要 sudo。
私人檔案：
memories sudo
memories file import VAULT_ID document.pdf
memories file export VAULT_ID FILE_ID exported.pdf
memories file history VAULT_ID FILE_ID
memories file diff VAULT_ID FILE_ID FROM_REVISION
file import 可用 --title 和 --id。file export 可用 --revision。file history 列出檔案的簽章修訂；file diff 只比較標題、中繼資料和長度，不輸出二進位內文。
用 file exec 把代管設定交給本機程式，命令參數中的 {file} 會替換為臨時檔案的絕對路徑：
memories sudo
memories file import VAULT_ID ./Caddyfile
# 将返回的文件 ID 填入 FILE_ID；这里使用 Caddy 2 的 Caddyfile 格式。
memories file exec VAULT_ID FILE_ID -- caddy run --config "{file}" --adapter caddyfile
權限與 file export 相同，需要解鎖、保管庫存取權和同一終端機的 memories sudo。
在 -- 前加 --revision REVISION 可使用歷史版本。即使讀取的是遠端或代管 daemon，
程式也在 CLI 本機、以目前使用者執行。命令直接啟動程式，不經過 Shell；保留工作目錄、
環境變數、標準輸入輸出和結束代碼，沒有五分鐘執行上限，也不輸出 JSON 成功回應。
臨時目錄和檔案僅允許目前使用者存取（Unix 權限為 0700/0600，Windows 使用使用者 ACL）。 程式應以前景方式執行：臨時檔案保留到子程式結束，啟動失敗也會清理。Windows 的 Ctrl+C/Ctrl+Break 和 Unix 的 SIGINT/SIGTERM/SIGHUP 會觸發退出清理，最多等待十秒， 再終止直接子程式。Unix 訊號會轉發給子程式；Windows 控制檯事件由同一控制檯的程式接收。
執行期間設定是明文，程式及外掛能夠讀取和輸出它，輸出不會脫敏。鎖庫或撤銷授權不會
收回已交付的副本或停止程式。強制結束 Memories、斷電或關閉 Windows 控制檯可能留下
臨時檔案；刪除不等於安全擦除，也不管理脫離父程式的背景後代程式。每次執行只使用一個
名為 config 的固定快照，不自動更新、reload、展開範本或匯入關聯檔案。相對路徑按
目標程式自己的規則解釋；關聯設定和憑證建議使用絕對路徑，需要時明確指定設定格式。
列表和搜尋回傳的短 ID 要原樣使用。長 UUID、完整修訂雜湊和帶前綴的 ID 會被拒絕。輸入有歧義時命令失敗，需要重新列表或搜尋。
只在本機記錄 Python：
memories local-python
memories local-python --program /path/to/python
它以隔離模式執行所選直譯器，記錄版本和可執行檔案目錄，不收集環境變數。結果寫入帶 local_only 的「此裝置」保管庫。
檢索和帶引用的回答
先讓常駐程式使用包含 [rag] 的同一設定。匯入一份 UTF-8 文字或 Markdown 會建立一張一般知識卡片，並回傳預計分塊數：
memories rag ingest VAULT_ID notes.md --title "研究笔记" --source "本地文件"
memories memory search VAULT_ID "中文 关键词"
memories rag search VAULT_ID "关键词" --mode bm25 --match-mode all
rag search 和 rag ask 的選項：
| 選項 | 取值 |
|---|---|
--mode |
bm25、vector、hybrid。搜尋和問答的預設值都是 hybrid |
--match-mode |
any、all、phrase。預設 any |
--limit |
1 到 100，預設 10 |
--no-rerank |
跳過可選的結果重排 |
--cards-only |
只檢索知識卡片 |
安裝內建 EmbeddingGemma 權重並建立記憶體向量索引：
memories rag model-install
memories rag index VAULT_ID
memories rag status VAULT_ID
memories rag search VAULT_ID "这段文档在说什么" --mode vector
memories rag search VAULT_ID "找出证据" --mode hybrid --limit 8
memories rag ask VAULT_ID "根据证据概括"
model-install 不初始化加密庫。權重預設裝到所選資料目錄下的 models/embeddinggemma。本機推理在 Memories 程式內執行，不需要 Ollama。向量和混合檢索在索引未建滿時也會按需補算嵌入。
rag ask 需要設定裡的生成位址。只做詞法檢索時使用 --mode bm25；只要呼叫問答，生成位址仍然必需。沒有證據時不會呼叫生成服務，結果裡 insufficient_evidence 為真。回答中的 [S1] 只是這一次結果裡的引用標籤。開啟原文時使用結果中的資產 id，不要把分塊雜湊當成資產 ID：
memories memory read VAULT_ID ASSET_ID
PDF、DOCX 和二進位檔案不會自動抽取文字。先轉換成 UTF-8 文字再匯入。不要把應當保密的文字匯入為一般卡片。更改模型設定後重啟常駐程式。
遠端嵌入、生成和重排寫在設定的 [rag.embedding]、[rag.generation] 和 [rag.rerank] 中。API 金鑰只寫環境變數名，例如 api_key_env = "GEMINI_API_KEY"，金鑰值放在常駐程式的環境裡。省略 [rag.embedding] 時嵌入保持在本機模型。Gemini Embedding 是線上 API，不是離線的 EmbeddingGemma。
捕獲和使用憑證與受保護卡片
先在同一終端機執行 memories sudo。
隱藏輸入新增憑證，或從已有檔案匯入。匯入不會刪除原始檔：
memories credential add VAULT_ID "API 令牌"
memories credential import VAULT_ID "SSH 身份" existing-private-key
捕獲命令 memories catch 與 memories credential catch 相同。不加來源時提示隱藏輸入：
memories catch VAULT_ID "数据库密码"
從管道讀取時加 --stdin。用 --regex 提取唯一匹配；有一個捕獲組時儲存該組，沒有捕獲組時儲存整個匹配。用 --json-pointer 選擇一個 JSON 字串。兩者不能同時使用：
secret-tool | memories catch VAULT_ID "数据库密码" --stdin --regex "password=([^\r\n]+)"
memories catch VAULT_ID "API 令牌" --stdin --json-pointer /token < response.json
memories catch VAULT_ID "API 令牌" --exec secret-tool --json-pointer /token -- issue --format json
--exec PROGRAM 直接啟動該程式並捕獲標準輸出，關閉其子程式標準輸入並丟棄標準錯誤。-- 後面是程式參數，不要在參數、正則或標題裡放真實秘密。--timeout 的範圍是 1 到 300 秒，預設 30 秒。管道標準輸入一直等到 EOF，沒有超時。輸入上限是 1 MiB。成功結果只含憑證 ID。用 --id CREDENTIAL_ID 替換已有憑證。
在庫內生成金鑰。私鑰不會被輸出：
memories credential generate VAULT_ID "笔记本 SSH"
memories credential generate VAULT_ID "笔记本 SSH" --algorithm rsa --bits 4096
memories credential generate VAULT_ID "数据库 CA" --kind tls-ca --algorithm rsa --subject memories-ca
memories credential generate VAULT_ID "数据库服务器" --kind tls --ca CA_ID --algorithm rsa --name db.example.test
memories credential public VAULT_ID KEY_ID
--kind 可以是 ssh、tls-ca、tls。--algorithm 可以是 ed25519、rsa、ecdsa。credential public 只回傳 SSH 公鑰或 TLS 憑證。
把憑證交給一個絕對路徑上的程式。預設從標準輸入注入；--env 明確允許一個環境變數。程式的 SHA-256 必須在互動時確認，或事先用 --approve-digest 批准。子程式的兩路輸出都被抑制：
memories run --vault VAULT_ID --credential CREDENTIAL_ID /absolute/program/path
memories run --vault VAULT_ID --credential CREDENTIAL_ID --env API_TOKEN /absolute/program/path
執行綁定把一個憑證固定到一個程式的指紋上，讓程式設計代理不需要你終端機裡的 sudo 也能用它。credential bind gh 需要 sudo 並輸入 USE 確認：它在 PATH 中找到 gh，記錄 SHA-256，並只把綁定存進本機的加密狀態，不會同步，還原備份時也會清除。綁定在 --hours 小時後過期（預設 8，最多 720），而且只在資料庫解鎖時可用。之後 run --binding gh -- 参数 會在目前目錄啟動程式，把憑證放進指定的環境變數，原樣回傳輸出，但其中出現的憑證都會替換成 [REDACTED]（加 --suppress-output 則丟棄輸出），並用程式自己的結束代碼退出：
memories credential bind gh --vault VAULT_ID --credential CREDENTIAL_ID --env GH_TOKEN
memories credential bindings
memories credential unbind gh
memories run --binding gh -- pr list --state open
memories hook install --commands gh
memories hook uninstall
--deny 词 拒絕非選項參數中按順序含有這些詞的命令；--ask 词 讓 hook 在執行前徵求確認。對 gh 預設拒絕 auth、alias、extension（以及別名 extensions、ext），並對 pr merge、repo delete、release delete 徵求確認，加 --no-default-rules 可關閉。規則只按輸入的詞匹配，你之前用 gh alias set 定義的別名不會被展開。在綁定過期前，以你的身分執行的任何程式都能帶著憑證執行這個程式，但無法透過 memories 讀到憑證本身；程式自己、它的擴充套件和子程式則能讀到，所以只綁定可信的程式。不帶 --credential 和 --env 的綁定只應用規則。
hook install --commands gh 會在展示條目並要求輸入 APPROVE 後，把 PreToolUse hook 寫入 Claude Code 使用者設定。Claude Code 在 Bash 或 PowerShell 裡要執行 gh ... 時，hook 把這個命令詞改寫成 memories run --binding gh --，命令列其餘部分保持不變。在 $( )、反引號、sh -c、xargs 等包裝裡執行的 gh 會被拒絕並說明原因；heredoc 內文、以及作為參數的命令替換（例如 --body "$(cat <<'EOF' ... EOF)"）不受影響。管道或重新導向的輸入會透過 --stdin 轉發（最多 16 MiB）。程式在常駐程式的環境裡執行，所以 NAME=value gh ... 這種前綴會被拒絕，請改用程式自己的參數。執行時才展開的參數（$var、萬用字元）無法按規則檢查，hook 會先徵求確認。只有整條命令都是綁定程式的呼叫時，hook 才會直接放行；如果還會執行其他程式或寫檔案，仍走 Claude Code 平常的確認。綁定程式留下的背景程式如果一直佔著輸出管道，讀取這些管道的執行緒數量有上限，超過上限時會拒絕新的綁定執行。Claude Code 自己的 deny / ask 權限規則仍然生效，但它們可能看到的是改寫後的命令，所以敏感子命令請寫進綁定規則。綁定的程式在服務鎖之外執行，長時間的 gh run watch 不會擋住其他用戶端，但 5 分鐘上限不變。
限制憑證可用的主機，並讓常駐程式發出只回傳狀態碼的 HTTPS 請求：
memories credential allow-host VAULT_ID CREDENTIAL_ID api.example.com
memories credential http VAULT_ID CREDENTIAL_ID https://api.example.com/status
credential http 只使用 HTTPS 的 443 連接埠，不跟隨重新導向，也不繼承代理。
受保護卡片同樣從隱藏輸入讀取秘密，不把秘密放在參數裡：
memories card account VAULT_ID --title "示例邮箱" --email user@example.test --smtp smtp.example.test
memories card env VAULT_ID ./app.env --title "应用配置"
memories card token VAULT_ID --title "API 会话" --host api.example.test
memories card token VAULT_ID --title "浏览器会话" --host app.example.test --cookie
memories card request VAULT_ID TOKEN_CARD_ID https://api.example.test/session
memories card otp VAULT_ID --title "示例 OTP" --issuer Example --account user@example.test
memories card otp VAULT_ID --title "示例 HOTP" --issuer Example --account user@example.test --hotp --counter 0
memories card otp-import VAULT_ID --title "导入的 OTP" "otpauth://totp/Example:user@example.test?secret=GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ&issuer=Example"
memories card otp-import VAULT_ID --image ./ga-export.png --title "GA import"
memories card otp-code VAULT_ID OTP_CARD_ID
帳號 SMTP 預設是 SSL 連接埠 465，可用 --port 和 --no-ssl 調整。這只記錄設定，不傳送郵件。--cookie 把權杖卡片存成 Cookie 頭。card request 的 --method 預設是 GET，只接受 GET 或 POST。OTP 可用 --algorithm sha1|sha256|sha512、--digits 和 --period。--hotp 改為 HOTP，--counter 是初始計數器，省略時為 0；TOTP 忽略計數器。otp-import 接受參數中的 URI；沒有 URI 也沒有 --image 時，從標準輸入讀一行。單個帳號使用 otpauth://。URI 裡的 totp 或 hotp 會自動識別；沒寫類型時，帶 counter 的是 HOTP，否則是 TOTP。Google Authenticator 遷移使用 otpauth-migration://offline?data=...，可能一次建立多張卡片。--image PATH 從圖片中解碼第一種 otpauth:// 或 otpauth-migration:// QR 碼，不能和 URI 同時使用。--title 可省略：只有一張卡片時它就是標題，有多張時它是標題前綴；省略時標題為「發行者 / 帳號」。--id 只能替換一張卡片，不能用於包含多個帳號的遷移匯入。otp-code 回傳短時驗證碼，不回傳種子；HOTP 的結果包含下一個計數器。上面的 secret 是公開的 RFC 測試向量，不要換成真實種子。
替換已有受保護卡片時加 --id CARD_ID。憑證 ID 和卡片連結會保留；未傳的 --alias / --notes / --category 保持原值，傳空字串可清除。普通 card put 不能替換受保護引用。OTP 標題可保留 issuer / account，用別名和備註單獨存顯示名。
在文件內文中保護一個精確出現的秘密。標籤由 1 到 64 個 ASCII 字母、數字、下劃線或連字元組成，並且在該文件中尚未使用：
memories memory protect-secret VAULT_ID DOCUMENT_ID API_KEY
memories card protect-secret VAULT_ID CARD_ID API_KEY
memories credential copy VAULT_ID DOCUMENT_ID --label API_KEY
memories credential copy VAULT_ID CREDENTIAL_ID
protect-secret 會提示輸入秘密。複製文件引用時必須帶 --label。複製結果只有 "copied": true。Windows 使用系統剪貼簿，macOS 使用 pbcopy，Linux 需要 Wayland 的 wl-copy 或 X11 的 xclip。受保護的帳號、權杖、環境和 OTP 卡片也可以直接複製；OTP 複製的是種子，不是一次性驗證碼。
手機端有「受保護卡片」「匯入 .env」和「匯入登入資訊（CSV）」，也可以貼上 otpauth:// URI 來匯入 TOTP 或 HOTP。檔案選單中的「替換資料中的金鑰」和「複製金鑰」對應上述操作。OTP 的「生成 OTP」產生一次性驗證碼。手機端沒有相機匯入 OTP QR 碼；OTP 圖片和遷移 URI 使用上面的命令列。代管裝置配對的掃描 QR 碼是另一條路徑，見裝置間端到端秘密。
匯入和匯出網站登入資訊
網站登入儲存在 login 受保護卡片裡（公開的站點位址和使用者名稱，密碼作為獨立憑證），通常成批匯入匯出。匯入和匯出都需要 memories sudo 和可寫角色：
memories sudo
# 浏览器 CSV（Chrome/Edge/Brave，或 Firefox 的 about:logins）；自动识别表头。
memories login import VAULT_ID --from chrome passwords.csv
memories login import VAULT_ID --from firefox firefox-logins.csv --with-notes
# 直接读取 Firefox 配置文件（现代 key4.db，会提示输入主密码，没有则留空）。
memories login import VAULT_ID --from firefox-profile "/路径/Profiles/xxxx.default"
# Windows 凭据管理器的通用凭据（仅 Windows）。
memories login import VAULT_ID --from windows --filter github
memories login import VAULT_ID --from windows --all
# 之前导出的加密文件。
memories login import VAULT_ID --from memories logins.mlx
# 导出：便携加密文件（推荐）或浏览器兼容的 CSV。
memories login export VAULT_ID --format encrypted logins.mlx
memories login export VAULT_ID --format csv logins.csv
站點主機和使用者名稱都與已有卡片相同、且密碼一致時跳過；密碼不同時記為衝突並另建一張卡片，加 --update 才覆蓋。CSV 裡的壞行會跳過並按行號報告，單次匯入上限 2000 條。瀏覽器的 note 列只有加 --with-notes 才匯入，因為備註會進入一般全文索引。Firefox 直讀支援現代金鑰格式（Firefox 58 及以上）；更舊的設定檔案請從 about:logins 匯出 CSV。讀取瀏覽器儲存的密碼不會修改瀏覽器自身的儲存。
加密匯出使用獨立密碼，可匯入任意保管庫。CSV 匯出是明文，用於把登入資訊導回瀏覽器或其他密碼管理器：僅限本機 CLI，會先告警，寫入僅所有者可讀、且必須尚不存在的檔案，並對以 = + - @ 開頭的儲存格做防公式注入處理，用完請刪除。僅本裝置的保管庫不能匯出。
遠端工作階段和迴路代理
先用 credential allow-host 授權目標主機。SSH 還要用探針得到的主機金鑰指紋，並經可信渠道核對：
memories remote probe example.test --port 22
memories remote open ssh --vault VAULT_ID --credential KEY_ID --host example.test --user alice --host-key HOST_KEY
memories remote open ssh --vault VAULT_ID --credential KEY_ID --certificate CERT_ID --host example.test --user alice --host-key HOST_KEY
memories remote sessions
memories remote run SESSION_ID -- uname -a
memories remote propose SESSION_ID -- uname -a
memories remote approve TICKET_ID
memories remote exec TICKET_ID
memories remote close SESSION_ID
remote run 一次完成提議、互動批准和執行。指令碼需要拆開時，用 remote propose 排隊並回傳票據，remote approve 批准（需要 sudo，票據只能用一次），再由同一個已提權的呼叫方 remote exec 執行。
資料庫預設啟用 TLS 並校驗主機名稱。--tls-ca CA_ID 增加一個庫內 PEM CA。--no-tls 明確關閉 TLS。--database 是 MySQL/PostgreSQL 的庫名，或 Redis 的邏輯庫索引：
memories remote open mysql --vault VAULT_ID --credential CREDENTIAL_ID --host db.example.test --user app --database appdb
memories remote open postgres --vault VAULT_ID --credential CREDENTIAL_ID --tls-ca CA_ID --host db.example.test --user app --database appdb
memories remote open redis --vault VAULT_ID --credential CREDENTIAL_ID --host redis.example.test --user default
memories remote run SESSION_ID --op query -- SELECT 1
remote open 的協議是 ssh、ftp、tcp、mysql、redis、postgres。FTP 使用檔案操作，SSH 和資料庫工作階段使用 exec 或 query。每個指令先提議再批准。remote run 把提議、互動批准和執行連在一起。批准詞是 APPROVE。MCP 不能開啟或批准遠端工作階段。
迴路代理在 127.0.0.1 上監聽。回傳的 command 可在常駐程式所在機器的終端機裡執行，其中不含儲存的密碼或私鑰：
memories proxy start ssh --vault VAULT_ID --credential KEY_ID --host example.test --user alice --host-key HOST_KEY
memories proxy start postgres --vault VAULT_ID --credential PASSWORD_ID --host db.example.test --user app --database appdb
memories proxy start mysql --vault VAULT_ID --credential PASSWORD_ID --host db.example.test --user app --database appdb
memories proxy start redis --vault VAULT_ID --credential PASSWORD_ID --host cache.example.test --user default
memories proxy list
memories proxy stop PROXY_ID
代理協議只有 ssh、mysql、redis、postgres。可選 --listen-port，0 表示由系統選擇連接埠。可選 --certificate、--tls-ca、--tls 和 --no-tls。任何能連上該本機連接埠的程式都能使用已經授權的遠端帳號。鎖定、保管庫空閒鎖定、proxy stop 和常駐程式退出會關閉監聽和已有連線。代理最長 30 分鐘，最多四個代理，每個最多 16 個連線。MCP 不能啟動、列出或停止代理。
執行密碼學作業
郵件和簽章工具要單獨安裝。身分和密碼分成兩個憑證匯入。--credential、--password_id 和 --key-password 都是憑證 ID，不是秘密本身。--password 和 --password-id 是 --password_id 的別名。
先加 --dry-run。它讀取輸入和工具、輸出計劃和 approval 摘要，不需要常駐程式，也不寫輸出檔案。確認後在同一終端機執行 sudo，再執行去掉 --dry-run 的同一命令。非互動執行改為帶上 --approve-digest DIGEST。輸出必須是已存在目錄中的新路徑。
S/MIME 使用 OpenSSL。PKCS#12 身分加 --pkcs12。加密只使用收件人公鑰，所以不傳身分憑證：
memories crypto smime-sign --vault VAULT_ID --input message.eml --output signed.eml --credential IDENTITY_ID --password_id PASSWORD_ID --pkcs12 --tool openssl=/path/to/openssl --dry-run
memories crypto smime-encrypt --vault VAULT_ID --input signed.eml --output encrypted.eml --recipient recipient.pem --tool openssl=/path/to/openssl --dry-run
memories crypto smime-decrypt --vault VAULT_ID --input encrypted.eml --output decrypted.eml --credential IDENTITY_ID --password_id PASSWORD_ID --pkcs12 --tool openssl=/path/to/openssl --dry-run
OpenPGP 需要成對的 gpg 和 gpgconf。--identity 是完整指紋。Git for Windows 裡的 MSYS 版 GnuPG 要加 --msys-gpg：
memories crypto pgp-sign --vault VAULT_ID --input message.eml --output message.sig.asc --credential KEY_ID --password_id PASSWORD_ID --identity FULL_FINGERPRINT --tool gpg=/path/to/gpg --tool gpgconf=/path/to/gpgconf --dry-run
memories crypto pgp-encrypt --vault VAULT_ID --input message.eml --output message.eml.asc --recipient recipient.asc --identity FULL_FINGERPRINT --tool gpg=/path/to/gpg --tool gpgconf=/path/to/gpgconf --dry-run
memories crypto pgp-decrypt --vault VAULT_ID --input message.eml.asc --output decrypted.eml --credential KEY_ID --password_id PASSWORD_ID --tool gpg=/path/to/gpg --tool gpgconf=/path/to/gpgconf --dry-run
Android 簽章不生成安裝套件，也不聯絡應用商店。apksigner 的路徑是 SDK 的 lib/apksigner.jar：
memories crypto android-apk --vault VAULT_ID --input unsigned.apk --output signed.apk --credential KEYSTORE_ID --password_id STORE_PASSWORD_ID --identity release --tool java=/jdk/bin/java --tool zipalign=/sdk/build-tools/35.0.0/zipalign --tool apksigner=/sdk/build-tools/35.0.0/lib/apksigner.jar --dry-run
memories crypto android-bundle --vault VAULT_ID --input unsigned.aab --output signed.aab --credential KEYSTORE_ID --password_id STORE_PASSWORD_ID --identity release --tool jarsigner=/jdk/bin/jarsigner --dry-run
金鑰密碼與資料庫密碼不同時，用 --key-password KEY_PASSWORD_ID。
iOS 簽章只在 macOS 上可用。輸入是已經包含匹配 embedded.mobileprovision 的 .app：
memories crypto ios-app --vault VAULT_ID --input Unsigned.app --output Signed.app --credential APPLE_P12_ID --password_id PASSWORD_ID --identity CERTIFICATE_SHA1 --entitlements App.entitlements --tool openssl=/path/to/openssl --tool security=/usr/bin/security --tool codesign=/usr/bin/codesign --dry-run
這些命令不傳送郵件，也不釋出應用。MCP 和手機端不能執行它們。
配對裝置、同步和備份
裝置配對讓同一個人的新裝置加入已有身分；成員邀請則給另一個人授予某個保管庫的角色。兩者都用請求和批准檔案，但不能互換。
新裝置先用自己的密碼執行 init，並且在加入前不能已有保管庫。然後：
memories sudo
memories device invite request.json
把請求檔案交給已有裝置。對照請求裝置上顯示的完整邀請指紋後再批准。批准命令會回傳批准裝置的公鑰；在新裝置接受之前，透過可信渠道核對這把公鑰：
memories sudo
memories device approve request.json approval.json --fingerprint REQUEST_FINGERPRINT
回到新裝置，在執行接受命令的同一終端機重新執行 sudo，再接受批准並檢查裝置列表：
memories sudo
memories device accept approval.json --sender APPROVING_DEVICE_PUBLIC_KEY
memories device list
請求 10 分鐘後過期，並且只能使用一次。
為另一個人批准某個保管庫的成員資格：
memories member approve VAULT_ID request.json approval.json --fingerprint REQUEST_FINGERPRINT --role reader
memories member list VAULT_ID
memories member role VAULT_ID USER_PUBLIC_KEY editor
memories member remove VAULT_ID USER_PUBLIC_KEY
memories member transfer VAULT_ID USER_PUBLIC_KEY
memories device revoke VAULT_ID DEVICE_PUBLIC_KEY
邀請批准的 --role 與 member role 的角色參數應使用 admin、editor 或 reader，並受操作者權限限制：所有者管理管理員，管理員只能管理一般讀者和編輯；編輯可以寫，讀者可以讀和使用。CLI 雖接受 owner，但保管庫策略要求恰有一個所有者，不能用邀請或一般角色修改新增所有者。要轉交所有權，由現任所有者執行 memories member transfer VAULT_ID USER_PUBLIC_KEY，目標必須是已有成員，原所有者隨後成為管理員。撤銷裝置要在每個相關保管庫上執行。移除成員不會擦掉對方已經持有的副本。
不經過中繼的檔案交換：
memories sync export VAULT_ID RECIPIENT_DEVICE_PUBLIC_KEY packet.json
memories sync import packet.json
線上傳輸時，先在 TLS 反向代理後面執行 memories-relay，再用 sync room 生成房間號。接收方先等待，傳送方再傳送：
memories sync room
memories sync receive --relay wss://relay.example.com --room ROOM
memories sync send VAULT_ID RECIPIENT_DEVICE_PUBLIC_KEY --relay wss://relay.example.com --room ROOM
遠端中繼只接受 wss://。ws:// 只允許本機開發位址。URL 不能包含使用者名稱或密碼。設定檔案中的 relay_url 可作為預設位址，命令上的 --relay 覆蓋它。--slot 的預設值在傳送時是 a，接收時是 b。傳送成功只表示封包交給了中繼，不表示對方已經匯入。中繼不為離線裝置排隊。sync export/import 和中繼 sync send/receive 都是明確整庫傳輸，不是雲端物件同步，也不是遠端 RPC。
檢視隔離區、把舊紀元修訂重新簽入目前紀元，以及在雙方都有效的所有者身分下保留本機策略分支：
memories sync quarantine VAULT_ID
memories sync reapply VAULT_ID REVISION
memories sync resolve-policy VAULT_ID packet.json --keep-local
雲帳號使用你自己註冊的 OAuth 應用。登入前解鎖庫並在同一終端機執行 sudo：
memories cloud login onedrive --client-id YOUR_MICROSOFT_CLIENT_ID
memories cloud login google-drive --client-config /path/to/google-desktop-client.json
memories cloud status
memories cloud sync onedrive
memories cloud logout onedrive
cloud login 可用 --no-browser 和 --port。0 表示自動選擇本機回呼連接埠。狀態不輸出權杖。登出只刪除本機授權。cloud sync 會更新權杖，並透過已連線的 OneDrive 或 Google Drive 應用資料夾上傳和下載不可變密文。手機端提供雲端連線和前景同步控制。真實 OneDrive 與 Google Drive 帳號上的端到端驗證尚未完成。手機背景同步未啟用。不要把資料庫目錄放進雲端硬碟用戶端的同步資料夾。
稽核和離線備份：
memories audit VAULT_ID --verify
memories sudo
memories audit VAULT_ID
memories backup offline-backup.memories
還原必須使用新的資料目錄，並在該目錄啟動常駐程式：
memories --home NEW_DIRECTORY restore offline-backup.memories --name replacement
memories --home NEW_DIRECTORY sudo
memories --home NEW_DIRECTORY archive list
memories --home NEW_DIRECTORY archive history VAULT_ID
memories --home NEW_DIRECTORY archive read VAULT_ID REVISION
memories --home NEW_DIRECTORY archive audit VAULT_ID
還原出的是包含目前資產和衝突頭的獨立保管庫。原始版本、墓碑和簽章稽核留在唯讀歸檔中。歷史憑證值不能透過一般介面或歸檔介面輸出。裝置專用庫和雲權杖不在備份中。
開啟桌面狀態介面
Windows 釋出包中雙擊與 memories.exe 放在一起的 memories-tray.exe。macOS 開啟封裝的 Memories.app。終端機中：
memories tray
memories webui
memories --home /path/to/development-home webui --no-open --port 0
memories webui --open
memories-tray --home /path/to/development-home --no-open
tray 開啟原生系統匣或選單欄，並帶狀態頁。webui 只開啟瀏覽器儀表板並留在前景。--port 0 選擇空閒的迴路連接埠。--no-open 不自動開啟瀏覽器。--open 在設定關閉自動開啟時仍然開啟。--config 和 --lang 同樣適用於這兩個命令和 memories-tray。
系統匣可以顯示離線、需要初始化、已鎖定或已解鎖，並可以啟動常駐程式。它不初始化、不解鎖、也不提權。狀態頁約每兩秒重新整理，顯示庫數量、代理和遠端工作階段數量、已設定的雲端服務供應商種類，以及上傳、下載和待同步計數。它不顯示內文、庫名、憑證、帳號、路徑或權杖。退出系統匣或中斷前景 webui 只停止該狀態頁，不停止已經執行的常駐程式。
Linux 使用 memories webui。Linux 沒有原生系統匣，Linux 釋出包也不包含系統匣啟動器。
授予 MCP 並安裝 AI skill
本節先介紹一般 MCP：按一個保管庫、期限和操作範圍授予 AI 用戶端能力，不繼承終端機的 sudo。授權寫到檔案裡，不會輸出出來；檔案本身是 bearer 憑證，需要保護。預設唯讀，--scope read_write 允許一般資料讀寫，--scope read_write_delete 還允許刪除，--write 是 read_write 的相容簡寫。時間用 --minutes，範例為 15 分鐘：
memories sudo
memories mcp grant VAULT_ID PRIVATE_GRANT_FILE --minutes 15
memories mcp serve --grant-file PRIVATE_GRANT_FILE
memories mcp revoke PRIVATE_GRANT_FILE
把 AI 用戶端的 stdio MCP 命令配成 memories mcp serve --grant-file ...，並使用與常駐程式相同的資料目錄。工具是 memory_search、memory_retrieve、memory_ask、memory_read、memory_read_revision、memory_history、memory_diff、memory_write、memory_delete、card_write、card_graph、card_link、workflow_card、workflow_read、workflow_update 和 workflow_list，另有英文人格卡片指南列出的 persona 工具。workflow_card 建立步驟工作流程、清單範本或從範本複製的任務，workflow_update 修改清單欄位或推進步驟，兩者都需要寫權限；workflow_read 和 workflow_list 只需讀權限。每次呼叫都帶已授權的保管庫 ID。memory_retrieve 預設是本機 BM25；vector 和 hybrid 使用常駐程式已設定的嵌入提供方。memory_ask 在設定了生成位址後回答，並拒絕不在檢索證據中的引用。
一般 MCP 不包含私人記憶、檔案、憑證、程式執行、遠端工作階段、代理、密碼學作業、成員管理和桌面狀態。即使選擇 --scope allow_all，也不會越過這條邊界。授權的簽發、列表、撤銷和權限申請是另外的 MCP 工具，仍不繼承 sudo。鎖定使這些授權暫時不可用，未過期的在解鎖後還原。協議版本是 2024-11-05。帶秘密引用的卡片不能用目前的 card_write 更新，因為該工具不保留引用映射；請用 CLI 或手機端編輯。
需要無人值守讀取時，另行閱讀無人值守 CLI/MCP。該路徑必須明確選擇金鑰代管後端，輸入 ENABLE 並完成密碼授權，再建立保管庫範圍內的用戶端檔案；使用 mcp serve-unattended --client-file PATH，不是普通 mcp serve。它僅限本機、唯讀，但包含私人資料、原始檔案、歷史和明確請求的憑證明文，不繼承 sudo。AI 用戶端及其記錄可能保留秘密，Base64 不是加密。手動鎖定會持續阻止該存取，直到密碼授權的 unattended resume；遠端傳輸、手機和 Center 管理的儲存不能使用它。
memories unattended enable --backend windows-dpapi
memories unattended mint --vault VAULT_ID --client-file /private/dir/client.json
memories unattended list VAULT_ID --client-file /private/dir/client.json
memories unattended history VAULT_ID ASSET_ID --client-file /private/dir/client.json
memories unattended read VAULT_ID ASSET_ID --client-file /private/dir/client.json
memories unattended credential-bytes VAULT_ID CREDENTIAL_ID --client-file /private/dir/client.json
memories mcp serve-unattended --client-file /private/dir/client.json
memories unattended status
memories unattended resume
memories unattended revoke GRANT_ID
memories unattended disable
後端可選 windows-dpapi、macos-keychain、linux-secret-service，或需明確選擇、保護較弱的 owner-file。用戶端檔案所在目錄必須已存在且只有所有者可存取，mint 不會覆蓋已有檔案。read 和 credential-bytes 按 base64url 位元組分段回傳：從 --offset 0 開始，每次用上一次回應的 next 作為新的 --offset，並用 --revision 固定第一次回傳的修訂，直到 next 為 null，再按順序拼接解碼後的位元組。list / history 每頁最多 100 條。status、resume、revoke 和 disable 需要已解鎖並已 sudo 的終端機。
安裝隨程式提供的 skill。安裝本身不開啟庫，也不設定 MCP：
memories inject all --dry-run
memories inject all
memories inject codex
memories inject opencode claude
memories inject all --project /path/to/project
all 包含 Codex、OpenCode 和 Claude Code。claude-code 是 claude 的別名。--project 安裝到一個已存在的專案目錄。升級 CLI 後，用 --force 替換以前裝過的不同內容：
memories inject all --force
--force 只替換 SKILL.md。相同內容會保持不動。指向技能檔案或目錄的連結會被拒絕。
為專案生成說明如何操作 Memories 的 AGENTS.md，或 Cursor/Codex 風格的 skill 目錄，可選嵌入一張人格卡片的核心概要。agents 是 skill 的別名：
memories skill generate --out AGENTS.md
memories skill generate --out AGENTS.md --persona VAULT/PERSONA
memories agents generate --out ./skills/memories-persona --layout skill --persona VAULT/PERSONA
--layout agents（預設）寫一個 Markdown 檔案；--layout skill 在輸出目錄下寫 SKILL.md（輸出路徑已以 .md 結尾時直接寫該檔案）。省略 --persona 時使用用戶端預設值裡的 persona。帶人格生成時透過常駐程式讀取該卡片，需要先解鎖；不帶人格時離線生成，不需要常駐程式。--force 替換內容不同的已有檔案，--dry-run 只預覽不寫入。
用戶端預設值
非秘密的命令列預設值儲存在資料目錄（--home / MEMORIES_HOME）下的 defaults.json，不進入保管庫密文：
memories default set persona VAULT/PERSONA
memories default set vault VAULT_ID
memories default set type persona
memories default get
memories default get type
memories default delete type
| 鍵 | 含義 |
|---|---|
persona |
persona 命令省略保管庫和資產時使用的 VAULT/ASSET |
vault |
list / card list 以及單參數 persona 命令的預設保管庫 |
type |
列表命令預設的 --type 篩選 |
category |
列表命令預設的 --category 篩選 |
daemon |
預設的 --daemon URL |
daemon_relay |
預設的 --daemon-relay URL |
daemon_room |
預設的 --daemon-room |
明確參數總是優先。接受保管庫和資產的 persona 子命令（world-get、thing、append-event 等）會把省略的位置參數當作預設值；persona import 仍要在 skill 路徑前寫明保管庫 ID。
授權中心（Center）
Center 是外部的授權控制面，向各端分發登記票據和能力票據。只要設定檔案裡列出任何一個 [[centers]]，該端就由 Center 管理：本機 init / restore 自舉和本機 MCP 授權都會被禁止，改用 Center 簽發的票據。保管庫解鎖仍在本機用裝置密碼完成，Center 拿不到保管庫金鑰或秘密明文；監聽權杖、Center 簽章金鑰和管理權杖都不寫進 TOML。
# 管理员：生成写入配置的公钥并签发票据（或使用 memories-center HTTP 服务）
export MEMORIES_CENTER_SECRET="…" # 32 字节，URL 安全 base64 或 64 位十六进制
memories center public-key
memories center issue-bootstrap --center corp --device-name laptop
memories center issue-grant --center corp --vault VAULT_ID --scope read --minutes 15
# 终端（守护进程已按含 centers 的配置运行）
memories center list
memories center enroll --ticket "$BOOTSTRAP_TICKET"
memories sudo
memories center import-grant --ticket "$GRANT_TICKET"
授權範圍（read、write、read_write、read_write_delete、allow_all 及其別名）、設定格式和威脅模型詳見英文 Authorization Center。
代管保管庫（SaaS）
memories-center --data DIR（或環境變數 MEMORIES_CENTER_DATA）讓 Center 執行完整的代管保管庫：伺服器端用營運者持有的密碼加密儲存 Store，複用常駐程式的同一套服務介面。設定中唯一的 mode = "saas" 條目會讓本機常駐程式進入 SaaS 模式，內容操作由該 Center 控制（權杖來自 MEMORIES_CENTER_TOKEN）。管理員可透過 /v1/admin/lock、/v1/admin/unlock 遠端加鎖/解鎖，透過 /v1/admin/members 管理成員。代管資料對營運者可見，不是端到端加密。請求中繼資料存於 DIR/requests.json，雜湊鏈稽核存於 DIR/audit.jsonl。
授權鏈
保管庫角色為 Owner、Admin、Editor、Reader。只有 Admin 及以上可以簽發或委託授權；簽發只需已解鎖的保管庫，不需要終端機提權，但批准角色請求需要提權。授權範圍不超過簽發者角色（及上級授權），被授權者角色不能高於簽發者，center-admin 不能作為被授權者。委託深度最多 2 層。省略範圍時預設為 read，而不是 allow_all。本機常駐程式和代管 Center 同時最多 10000 張有效授權。
權限請求可廣播給所有有資格的審核者，或用 --approver 指定審核者；可以批准或拒絕，但不能決定自己的請求。批准不回傳權杖，請求者需領取一次：memories request claim VAULT ID、memories center request claim ID、MCP request_claim，或 POST /v1/requests/{id}/claim。每個請求者在每個保管庫最多 20 個待處理請求，每個保管庫最多 200 個（Center 回傳 HTTP 429）；待處理及已批准未領取的請求 7 天后過期，已結束的請求保留 30 天。
memories access list VAULT # 按级别列出成员、设备、待处理与已批准未领取的请求
memories grant list VAULT
memories request create VAULT --scope read --approver MEMBER_ID
memories request approve VAULT ID
memories request claim VAULT ID
移除成員會連帶撤銷其簽發的授權（按成員代數失效）；授權只持久化雜湊；稽核記錄為雜湊鏈。詳見英文 Authorization。
選擇語言
手機端在鎖定畫面和庫介面都有語言選單，預設跟隨系統，手動選擇會在重啟後保留。
命令列的優先順序是 --lang、MEMORIES_LANG、已儲存的語言，然後是第一個非空的 LC_ALL、LC_MESSAGES 或 LANG。Windows 在這些變數都沒有時還會看作業系統語言。無法識別的區域設定回退到英語。zh-CN 和 fr_FR.UTF-8 可以識別。
memories --lang zh --help
memories language zh
memories language
memories language system
language 後面可省略，用來顯示已儲存和目前生效的語言。system 清除選擇並重新跟隨系統。儲存的語言按 --home 區分，不需要常駐程式。命令名、選項名、JSON 欄位、錯誤碼以及 USE 和 APPROVE 不翻譯。使用者內容也不翻譯。
遠端常駐程式（HTTP/WebSocket / 中繼 RPC）
可選的權杖認證 HTTP/WebSocket 監聽與 WSS 中繼 RPC 使用同一套 WebSocket 二進位 JSON 幀（AuthFrame 後接 Wire），與本機 IPC 的 service::Request 協議一致。
RPC 在遠端主機的儲存上執行命令，不在呼叫方建立保管庫副本。要交換副本用 sync；要透過 OneDrive/Google Drive 的持久雲端物件佇列同步用 cloud sync PROVIDER。中繼承載 RPC 或整庫傳輸時都不是離線資產倉庫。
監聽權杖只能透過標誌或環境變數提供，不能寫入 TOML。預設明文 HTTP/WS 不需要憑證；需要時用 --tls-cert / --tls-key 啟用 HTTPS/WSS。桌面常駐程式在遠端解鎖/提權後提供與本機 IPC 相同的全功能操作面（ws:remote / relay:remote 提權命名空間）；移動端 Share 仍遵循 FFI 拒絕列表。詳情見 remote-daemon.md。
中繼也可以轉發人格自動化 webhook：POST /v1/persona/{room}/{vault}/{persona}/automation/trigger，請求主體和 webhook 權杖與常駐程式相同，中繼只把它轉給已連線的主機，不對外發起 POST。
全域 TLS 選項：--ca-file PATH（MEMORIES_CA_FILE）為出站 TLS 用戶端新增 PEM CA；--insecure 跳過憑證和主機名稱校驗但仍使用 TLS，僅限開發/自我簽署環境，優先使用 --ca-file。
memories daemon --listen http://127.0.0.1:7900 --listen-token "$TOKEN"
export MEMORIES_DAEMON=http://127.0.0.1:7900
export MEMORIES_DAEMON_TOKEN="$TOKEN"
memories status
手機模式選擇與切換
首次啟動時選擇模式；從沒有模式設定的舊版升級後，也會顯示選擇頁。App 會記住選擇，下次直接進入對應模式。
| 模式 | 資料位置 | 開始使用 |
|---|---|---|
| 單機模式 | 手機本機加密資料庫，可離線使用 | 建立資料庫，或解鎖已有資料庫 |
| Center 模式 | 客戶自建伺服器上的代管庫 | 填寫完整的 HTTPS 服務位址和成員權杖，點擊“連線” |
| SaaS 模式 | https://memories.ivjn.us 的代管庫 |
位址固定，填寫該服務的成員權杖並連線 |
這裡的 Center 模式是自建代管服務，伺服器需啟用 memories-center --data DIR。它與只簽發裝置及權限票據的授權 Center 不同。手機端不需要編輯 config.toml、設定 mode = "saas" 或先解鎖本機庫；這些 TOML 設定用於桌面常駐程式。
Center 位址只填伺服器來源位址，例如 https://center.example.com，不要加 /v1/rpc、查詢參數或使用者名稱密碼。非迴路位址必須使用 HTTPS；手機上的 localhost 指手機本身。成員權杖由服務營運者提供，能執行的操作取決於其保管庫、角色、範圍和有效期。營運者的管理權杖不能直接代替成員權杖讀寫內容。
使用中切換
主介面頂部的雙向箭頭是“切換模式”，登入前後均可使用。彈窗標記目前模式，選擇另一個模式即切換；取消則保留目前工作階段。編輯頁需先儲存或退出，未儲存內容會提示確認。
| 操作 | 結果 |
|---|---|
| 切換模式 | 鎖定本機庫、停止共享、關閉目前代管連線並清除頁面內容，記住新模式 |
| 切回單機 | 原資料庫保留，需要重新解鎖 |
| 再次進入 Center 或 SaaS | 如有已儲存的連線資訊，嘗試還原對應連線 |
| 斷開連線 | 移除目前模式儲存的權杖，保留位址，不影響另一模式的連線資訊 |
| 應用進入背景 | 鎖定本機存取，關閉代管工作階段及敏感頁面，丟棄未儲存草稿 |
| 從背景回傳 | 代管頁需點擊“重新連線已儲存的工作階段”，或重新輸入權杖連線 |
切換不會上傳、搬遷、合併或刪除庫中的資料。斷開連線不會在伺服器端撤銷權杖。Center 和 SaaS 的位址與權杖分別儲存在系統安全儲存中；舊版連線只遷移到對應模式，正式 SaaS 位址進入 SaaS，其餘位址進入 Center。
各模式的功能範圍
單機模式保留本機資料的瀏覽、搜尋、編輯、備份還原、共享和雲端連線入口。Center / SaaS 提供代管知識列表、搜尋、詳情、編輯、建立和刪除，以及授權請求審核和已配對裝置管理。連線後可檢視目前庫和授權範圍，進入“代管知識”管理內容。新建卡片暫不提供標籤、來源和關係；編輯已有一般卡片支援這些欄位並保留其他中繼資料。一般記憶使用內文編輯器；結構化設定、受保護卡片、類型範本及端到端卡片在此僅供檢視，修改需使用專用編輯器。
授權頁分為“待處理”和“歷史記錄”。批准或拒絕前可檢視申請人、保管庫、範圍、時長和完整原因，並需確認；批准後仍由申請者單獨領取授權。歷史記錄包含本次連線內的處理記錄及伺服器端回傳的已批准請求，不是完整稽核記錄。連線失敗時檢查網路、憑證、位址、成員權杖，以及自建 Center 是否已啟用代管儲存。
手機代管模式（Hosted Center）
搜尋由伺服器端執行，不包含私密內容、憑證和檔案；清空關鍵詞後回傳知識列表，有讀取權限時可檢視列表中的私密卡片。唯讀帳號不顯示修改入口，只寫帳號可直接建立，刪除需要刪除權限並再次確認。儲存失敗保留草稿，伺服器確認刪除後才退出詳情。目前儲存未提供基於預期版本的原子併發檢查，多人同時編輯同一卡片可能覆蓋彼此最新欄位。
升級 App 時需同步升級自建 Center，以提供 /v1/session 介面。工作階段過期或被撤銷時，請斷開連線後使用有效權杖重新連線；權限不足請聯絡服務管理員；服務不可用或庫鎖定時稍後重試。
Center 和 SaaS 共用 FFI memories_call 的 hosted_* 介面：連線、請求列表與審核、存取列表、斷開，以及受限的 hosted_rpc。連線透過 hosted_status 校驗，對應 GET /v1/session，回傳目前庫、範圍、角色、到期時間和讀取、寫入與刪除能力，不回傳權杖。hosted_rpc 支援列表、讀取、搜尋、刪除、卡片類型、知識卡片建立、欄位和憑證操作；put 支援 memory、card 和 credential。完整白名單和裝置介面見 手機代管介面。FFI 支援的操作不一定都有對應的 Flutter 頁面。
代管模式下伺服器端可讀：Store 在磁碟上加密儲存，但營運者持有解鎖密碼，可以讀取代管內容；App 會顯示“伺服器端可讀”標記。活躍權杖由 Rust 用戶端儲存在記憶體中，Flutter 用系統安全儲存儲存各模式的連線資訊。裝置間密封秘密具有獨立的端到端保護邊界，見下一節。
裝置間端到端（E2E）秘密同步
代管 Center 上的普通內容伺服器端可讀。對於不能讓伺服器看到的秘密，請配對裝置併傳送密封信封（X25519 加密，傳送方 Ed25519 簽章）；Center 只儲存公鑰和密文。
配對流程：
1. 電腦：memories device hosted init --backend … 在系統金鑰代管中生成裝置身分。
2. 電腦（成員權杖）：memories device hosted pair --vault V，Center 建立帶裝置指紋的權限請求，回傳一次性配對碼和 QR 碼內容（含 Center id）。配對碼 5 分鐘過期。終端機（stderr）輸出的 QR 碼同時包含一次性配對碼，手機掃描 QR 碼即可；stdout JSON 不變。已啟用的裝置重複配對回傳 409，撤銷後可用同一金鑰重新配對。
3. 手機（管理員）：輸入/掃描配對碼獲取裝置公鑰（只能獲取一次，失敗過多會限流）。
4. 手機透過 /v1/requests/{id}/approve 批准，並附上用手機 Ed25519 金鑰簽章的裝置證明（attestation）。
5. 電腦：memories device hosted claim --request-id ID 一次性領取裝置授權，權杖儲存在系統金鑰代管中，Center 只存雜湊。
6. 比對 SAS：手機在批准前顯示（分組，如 123 456）；批准後電腦執行 memories device hosted sas --pairing-id P 應顯示相同數字，不同則撤銷裝置並重新配對。
手機掃描 QR 碼會拒絕非 Memories 配對碼、Center id 與目前連線不一致、或裝置指紋不一致的 QR 碼。權限：Android CAMERA（相機為可選特性），iOS NSCameraUsageDescription。拒絕相機權限時，手機提示到系統設定開啟，並可手動輸入配對碼。CLI 與手機會把 Center 狀態碼轉為可操作提示（404 過期/已用/其他 Center，409 已處理或已配對，403 無權限或裝置已撤銷，422 e2e 內容被拒，429 請求過多）。
SAS 定義：SHA-256("memories/device-sas/v1\0" ‖ 手机公钥 ‖ "\0" ‖ 电脑公钥 ‖ "\0" ‖ pairing_id) 前 8 位元組按大端轉為整數，對 10^6 取模，補零為 6 位。不一致說明公鑰被替換，應立即撤銷。
規則：裝置授權綁定裝置與成員代數，委託深度 ≤ 2；裝置不能簽發授權或審核請求；成員變更會使裝置失效並刪除其信封；e2e: true 的卡片在代管 Center 上拒絕明文秘密；存取列表包含裝置；MCP 提供 device_list 和需要明確意圖（intent: "reveal_plaintext" + 理由）的 sealed_reveal。
威脅模型：Center 無法讀取密封秘密，但能看到中繼資料，也可能扣留信封。撤銷無法收回已經送達裝置的明文——撤銷後請在來源端輪換該秘密。
E2E 加固（P2）
- e2e 標記不可悄悄撤銷：卡片一旦為
e2e: true，去掉該標記的寫入會被拒絕（422）；只有 Owner 授權（非裝置授權）可用不含任何秘密的寫入清除它。 - OTP 參數：密封的 OTP 可以是 Base32 種子（SHA1/6 位/30 秒）或完整
otpauth://totp/...URI；sealed-get --otp遵循其中的 algorithm（SHA1/SHA256/SHA512）、digits（6/8）、period（30/60）。device hosted pair會在終端機（stderr）輸出配對QR 碼。 - 撤銷後重新加密：撤銷裝置會刪除其信封，並把相關卡片標記為
needs_rotation（在 sealed 列表、/v1/sealed/rotation、存取列表和手機重新加密頁面可見）。已送達的明文無法召回：請先在來源端輪換秘密，再在手機上“為所有裝置重新加密”，它只發給目前已批准的裝置並清除標記。 - 手機身分還原：Center 從不儲存手機身分。首次建立時顯示一次性還原碼（32 位元組種子 + 2 位元組校驗的 Base32，每 4 位一組），請抄寫；“用還原碼還原”可還原同一身分。
- 身分輪換：“遷移到新手機金鑰”會生成新身分，並提交由舊金鑰和新金鑰共同簽章的輪換記錄（僅管理員成員可提交，舊金鑰必須已被某裝置信任）。CLI 首次使用時固定批准手機的公鑰（
hosted-device-trust.json），只接受從該根經已驗證輪換鏈可達的簽章者。 - 硬體儲存：手機種子用
flutter_secure_storage最強內建選項儲存：iOS/macOS 鑰匙串passcode（僅本機、不同步、需裝置密碼）；Android Keystore 包裝並要求生物識別或裝置憑證，resetOnError: false。限制：簽章/加密時種子仍需進入應用記憶體（Secure Enclave/StrongBox 不支援 X25519/Ed25519），只保護靜態儲存。 - 透明記錄：Center 維護僅追加、雜湊連結的裝置記錄（配對、批准、身分輪換、撤銷），
GET /v1/devices/log。memories device hosted log --verify校驗鏈、所有簽章，以及記錄是否延續上次驗證的鏈首（hosted-device-log.json）。
手機生物識別與裝置鎖
在單機模式下解鎖資料庫後，可在更多選單中開啟“使用生物識別／裝置鎖解鎖”。開啟時需先透過一次系統驗證；該安全選項也用於代管審核等敏感操作。
- Android：使用系統 BiometricPrompt（指紋／面容），並可回退到裝置 PIN、圖形或密碼。快速解鎖所需的資料庫密碼儲存在 Android Keystore 綁定的金鑰下，該金鑰要求使用者驗證（
setUserAuthenticationRequired），且在新增或刪除指紋／面容後自動失效（setInvalidatedByBiometricEnrollment(true)）。 - iOS：使用 Face ID／Touch ID（可回退到裝置密碼），鑰匙串條目僅在裝置設定了密碼時可用。
- 受保護的操作：解鎖資料庫、顯示或複製憑證明文、使用受保護卡片／生成 OTP、批准配對裝置、批准代管請求、封裝（seal）與重新封裝（re-seal）。
- 生物識別資訊變更：金鑰失效時應用會明確提示，資料庫與資料不會被刪除；用裝置憑證驗證後輸入一次資料庫密碼，即可重新建立金鑰。
- 無生物識別或關閉選項：裝置沒有可用的生物識別／裝置鎖，或選項關閉時，沿用原有的密碼流程。關閉選項會刪除儲存的快速解鎖資訊。
新建內容（手機端）
新建記憶、憑證和代管中心條目共用同一個編輯器：可從檔案匯入（預設以檔名為標題，可修改）；.env 等設定內容自動切換為等寬多行編輯（也可手動切換）；名稱可先留空，儲存時依次從檔名或第一行非空文字推斷，仍為空時才提示輸入。
知識卡片採用全螢幕表單，底部固定儲存按鈕；“編輯內文”開啟共享內文編輯器，可匯入檔案、手寫或掃描。記憶和知識卡片在儲存成功後才關閉，儲存失敗保留草稿供重試，並阻止重複提交。匯入覆蓋已有內文、離開未儲存內容時均需確認。草稿只在記憶體中儲存，背景鎖定後不會還原。單機卡片和代管一般卡片編輯保留標籤、來源、關係及自訂欄位；代管建立只提供目前建立介面接受的中繼資料。
多欄位憑證
一個憑證可以同時儲存多個相互獨立、均可為空的欄位：使用者名稱/帳號、密碼、OTP（otpauth:// URI 或 base32 種子及參數）、API Key、URL、備註，以及自訂欄位（可標記為機密）。密碼、OTP、API Key 和標記為機密的自訂欄位只存放在加密內文中；使用者名稱、URL、備註和非機密自訂欄位可以直接檢視。
memories credential set VAULT [ASSET] --username 我 --url https://example.com --password --otp --field 团队=core --secret-field PIN
memories credential show VAULT ASSET
memories credential get VAULT ASSET --field username
memories credential get VAULT ASSET --field password --reveal
memories credential copy VAULT ASSET --field api_key
memories credential otp VAULT ASSET
memories credential migrate VAULT ASSET
機密值只透過隱藏輸入錄入，不作為命令列參數。舊的單欄位憑證仍可直接讀取：otpauth:// 或標題以 OTP: 開頭的映射為 OTP，帶 HTTP 認證或允許主機的映射為 API Key，其餘映射為密碼。第一次透過 credential set 修改（或執行 credential migrate）時會改寫為結構化格式，舊版本保留在歷史中，不會丟失資料。原有只使用單個機密的功能（HTTP 注入、執行綁定、不帶 --field 的複製）使用“主機密”：密碼優先，其次 API Key、OTP、第一個機密自訂欄位。
多欄位憑證：MCP、代管中心與端到端同步
- MCP
credential_fields（讀權限）只回傳非機密欄位和機密欄位名；credential_reveal（allow_all 授權）需intent: "reveal_plaintext"與理由，逐欄位回傳並稽核。 - 代管中心：端到端（e2e）憑證在中心只儲存描述資訊，機密欄位只存在於裝置密封信封中。
- 已配對裝置：
memories device sealed-get --vault V --card C --field password --reveal、--otp生成驗證碼。 - 手機：新建憑證為分割槽表單（登入資訊、一次性驗證碼、API、更多、自訂欄位），全部可空；複製機密欄位和檢視實時驗證碼（帶倒計時）需系統解鎖驗證。