Memories

原始碼儲存庫：https://github.com/mbcc2006/memories。CLI 是 memories，中繼服務是 memories-relay，原生程式庫是 memories_ffi。

由用戶端持有的加密記憶、私密檔案與憑證，提供 Rust CLI、Android/iOS 用戶端、本機 MCP 伺服器，以及僅使用記憶體的 WebSocket 中繼服務。

開發版本，格式版本 1。 本儲存庫包含可執行程式碼與安全回歸測試，尚未接受獨立的密碼學或應用程式安全審查。保證、信任邊界與目前限制請參閱 SECURITY.md。

各部分如何協作

在獨立使用模式下，Memories 在每部裝置上維護加密的本機資料儲存區。您可以儲存可搜尋的知識、在用戶端之間攜帶 AI 角色，或透過明確授權使用私密檔案與機密。雲端儲存保存密文；中繼服務僅連接在線上的對等端。兩者都無法取代已授權的用戶端。

行動應用程式也提供 Center（您自行架設的伺服器）與 SaaS（https://memories.ivjn.us）模式。這些模式使用獨立的託管資料儲存區，其營運者可以讀取內容。選擇或切換模式不會上傳、移動或合併既有的本機資料庫。請參閱行動裝置模式。

Memories Web 連接至您既有的託管 Center，讓您在瀏覽器中管理記憶、卡片與檔案。新版 Center 也會在 /app/ 提供此介面。存取權杖、允許的來源與支援操作請參閱 Web 用戶端指南。託管 SaaS API 位於 https://memories.ivjn.us；請使用該服務簽發的成員權杖。

unlock 啟用資料儲存區中的一般授權作業。memories sudo 為私密內容、檔案、憑證及敏感管理作業加入短效工作階段；它不會授予作業系統管理員權限，也不會繞過保管庫權限。一般限定保管庫範圍的 MCP 授權，是獨立且有限的 AI 能力，不是終端機的 sudo 權限。無人值守存取 是另一項必須主動啟用的唯讀能力，可能揭露私密內容與機密值。

從這裡開始

開發相關資訊請參閱儲存庫指南、架構與驗證結果。

簡體中文：產品說明、使用說明、技術文件。

產品介紹網站：website/，提供靜態英文／中文網站與 Cloudflare Pages 部署說明。

建置與執行

安裝 Rust 1.88 或更新版本，以及平台 C 工具鏈（SQLite 由原始碼編譯）。

cargo build --workspace --locked
cargo test --workspace --locked
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo install --path crates/cli --locked

在另一個終端機啟動 memories daemon。它僅服務目前的作業系統使用者，在 Windows 上使用具名管道，在 Linux/macOS 上使用 Unix 通訊端。以 --home PATH 或 MEMORIES_HOME 指定專用資料目錄；預設為作業系統應用程式資料目錄。不要將 --home 指向既有的一般用途資料夾：其權限會被收緊以保護本機服務。

本機快速入門

安裝 memories 並啟動背景服務後，使用第二個互動式終端機。建立全新的獨立資料儲存區時：

memories init --name laptop
memories vault create Personal
memories vault list

建立名為 notes.md 的 UTF-8 檔案，寫入包含「project」的簡短筆記。將下方 VAULT_ID 替換為 vault create 或 vault list 回傳的 id，然後執行：

memories memory put VAULT_ID --title "Project notes" --input notes.md
memories memory search VAULT_ID "project"
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 忽略大小寫。如同一般搜尋排除私密內容，私密文件、衝突版本、卡片、檔案與憑證均不包含在內。沒有符合項目時不產生輸出。

將 ASSET_ID 替換為已儲存筆記的 id。FROM_REVISION 使用 history 回傳的 revision 欄位；差異比較會將該修訂版本與目前的最新版本比較：

memories memory read VAULT_ID ASSET_ID
memories memory history VAULT_ID ASSET_ID
memories memory diff VAULT_ID ASSET_ID FROM_REVISION
memories lock
memories unlock

後續使用時，請執行 unlock，而不是 init。若新裝置要加入既有身分，請先配對，再建立任何保管庫。使用自訂資料儲存區時，背景服務與每個用戶端命令都必須傳入相同的 --home PATH。

使用 memories --help 查看任務，再透過 memories memory --help 或 memories memory put --help 查看細節。加入 --lang zh 取得中文說明，例如 memories --lang zh memory put --help。說明命令不需要背景服務。

密碼從互動式終端機讀取，不會回顯。沒有密碼參數或密碼環境變數。本機與備份密碼沒有應用程式層級的長度限制，也允許空白輸入；仍須進行密碼確認與驗證。命令輸出具有版本資訊的 JSON；失敗命令回傳非零結束狀態。裝置公開金鑰與指紋刻意保持可見；一般命令不會輸出私密金鑰與憑證值。明確啟用的無人值守憑證讀取屬於例外，詳見無人值守 CLI/MCP。

遠端背景服務（HTTP/WebSocket／中繼 RPC）

可選的權杖驗證 HTTP/WebSocket 監聽與 WSS 中繼 RPC，使用與本機 IPC 相同、具有訊框的 service::Request 協定（桌面解鎖／sudo 後功能完整；行動裝置 Share 保留 FFI 拒絕清單）。使用 memories daemon --listen http://127.0.0.1:7900（HTTPS/WSS 可選用 --tls-cert／--tls-key）。RPC 在主機的資料儲存區執行操作，不會同步本機副本。監聽／用戶端旗標、殘餘風險及行動裝置 Share 請參閱遠端背景服務。

可選的授權 Center 可以禁止本機自行初始化授權，並向端點分發註冊／MCP 授權票證。memories-center --data DIR 另可執行完整的託管保管庫：具有 mode = "saas" Center 設定項目的背景服務由它控制，營運者可以遠端解鎖，成員則在 Center 管理。

授權鏈

保管庫角色為 Owner（擁有者）、Admin（管理員）、Editor（編輯者）與 Reader（讀者）。只有 Admin 或 Owner 可以簽發或委派授權；簽發需要解鎖保管庫，但不需要終端機提升權限，核准角色請求則需要提升權限。授權受到簽發者角色（以及任何上層授權）的限制，受授權者不得持有更高角色，center-admin 也不得成為受授權者。委派深度最多為 2。省略範圍表示 read，而非 allow_all。權限請求送至所有符合資格的核准者，或指定的 --approver 成員；任何人都不得決定自己的請求。核准不回傳權杖：請求者必須領取一次（memories request claim、memories center request claim、MCP request_claim 或 POST /v1/requests/{id}/claim）。限制為每位請求者在每個保管庫最多 20 個待處理請求、每個保管庫最多 200 個（Center 回傳 HTTP 429）、待處理 TTL 為 7 天、保留 30 天，且背景服務及託管 Center 各最多有 10,000 個有效授權。memories access list VAULT 按層級列出成員、裝置、待處理及已核准但未領取的請求；memories grant list VAULT 列出授權。移除成員會連帶撤銷其授權（依成員世代）；授權僅以雜湊形式持久化，稽核日誌採雜湊鏈（Center：DIR/audit.jsonl）。請參閱授權。

角色聊天（memories persona chat send|list|history|mark-read）會觸發 chat_message 自動化掛鉤；傳入的自動化 Webhook 也可透過 memories-relay 的 POST /v1/persona/{room}/{vault}/{persona}/automation/trigger 存取（參閱角色、遠端背景服務）。

Linux 建置與封裝

在 Debian/Ubuntu（包括 WSL2 中的 Ubuntu）安裝 Rust 1.88+ 與原生建置相依項目：

sudo apt-get update
sudo apt-get install -y build-essential pkg-config libssl-dev python3 git
bash scripts/build-linux.sh
# Optional development build:
bash scripts/build-linux.sh --debug

此指令稿為主機 GNU 目標建置 Rust 工作區：x86_64 或 aarch64。發布版輸出位於 target/<host-target>/release/（或設定的 Cargo 目標目錄）；偵錯輸出使用 debug/。不需要 Flutter SDK。Linux 支援 CLI、背景服務、中繼服務、FFI 程式庫與 memories webui；原生系統匣目前僅支援 Windows/macOS。

從乾淨且已提交的工作副本建立 Linux 發布封裝：

bash scripts/package-linux.sh

這會重新建置發布版二進位檔，並將 .tar.gz、BUILD-INFO.json、SHA256SUMS 與範例設定寫入 dist/vVERSION-linux-ARCH/。封裝包含 memories、memories-relay、libmemories_ffi.so、C 標頭、文件與授權條款，並保留執行權限。不覆寫既有輸出目錄。手動 Build desktop packages（建置桌面套件） 工作流程也會建置並上傳 Linux x86_64 套件。

這些是原生 GNU/Linux 建置，不是靜態或交叉編譯的二進位檔。使用相容的 glibc/OpenSSL 執行環境；請在預計支援的最舊發行版上建置。系統 TLS 需要 ca-certificates，在桌面瀏覽器開啟儀表板需要 xdg-utils。憑證剪貼簿複製另需 wl-clipboard（Wayland）或 xclip（X11）。模型權重須透過 memories rag model-install 另行安裝。

設定

執行 memories config init 建立 TOML 設定，使用 memories config path 查找位置，並以 memories config show 檢視生效設定。發布版包含 memories.example.toml，提供儲存目錄、中繼與桌面選項。使用 --config PATH 或 MEMORIES_CONFIG 選擇另一個檔案。優先順序為 CLI 選項、環境變數、設定檔、預設值。請參閱設定指南。

桌面系統匣與狀態儀表板

Windows 上，按兩下解壓縮發布目錄中的 memories-tray.exe。macOS 上，開啟封裝的 Memories.app，或使用命令列：

memories tray
memories webui

系統匣／選單列顯示背景服務與保管庫狀態，可開啟本機 WebUI 並啟動背景服務。儀表板顯示鎖定狀態、資料庫數量、連線數與雲端同步佇列，不顯示儲存內容。--home 選擇與 CLI 相同的資料儲存區；--no-open 在啟動時不開啟瀏覽器。照常透過 CLI 初始化／解鎖。行為與封裝方式請參閱桌面指南。

語言

行動用戶端與 CLI 支援英文（en）、簡體中文（zh）、日文（ja）、德文（de）與法文（fr）。行動語言選單可在鎖定畫面與資料庫中使用。預設跟隨系統，手動選擇會在重新啟動後保留。

memories --lang zh --help
memories cloud login --lang ja --help
memories --lang de status
memories language zh       # Remember this language
memories language          # Show saved and effective language
memories language system   # Follow the system again

CLI 語言依序採用 --lang、MEMORIES_LANG、已儲存的語言偏好，再採用 LC_ALL、LC_MESSAGES 或 LANG 中第一個非空值。偏好依 --home／MEMORIES_HOME 分別儲存，不需要背景服務。Windows 上若這些變數都未設定，也會使用作業系統語言。不支援的地區設定回退為英文；接受 fr_FR.UTF-8 與 zh-CN 等環境值。命令、選項名稱、JSON 欄位、錯誤代碼與確認詞 USE、APPROVE 維持不變。使用者內容不翻譯。沒有譯文的低階診斷保留原始細節，搭配在地化的錯誤摘要。維護方式請參閱在地化指南。

短 ID

CLI、MCP 與行動請求使用無前綴的短十六進位 ID，通常為六個字元（例如 0b0668）。ID 不代表型別或分類，也沒有前綴或底線。直接將 vault list、card list、card search 或歷程回傳的 ID 用於對應命令。長 UUID、完整修訂雜湊與有前綴的 ID 都會被拒絕；沒有長 ID 輸出選項。

既有的八字元 ID 仍有效。前綴發生碰撞時，自動以兩字元為單位延長，最多 16 個字元；有歧義的輸入會被拒絕。這不會縮短裝置金鑰或安全指紋。

memories card list eb7abf
memories card search eb7abf "claude relay"
memories card read eb7abf 0b0668

ID 在每個命令參數的範圍內解析。碰撞會使回傳 ID 增加兩個字元，最多 16 個；有歧義時輸入失敗，不會自行選擇物件。碰撞後請重新列出或搜尋。已刪除資產仍保留在碰撞索引中。短 ID 是參照，不是授權：解鎖、sudo、保管庫權限與 MCP 授權仍然適用。

已簽署儲存紀錄保留原始識別碼，不進行遷移。憑證、公開金鑰、驗證指紋、稽核紀錄與加密傳輸封套均不會縮短或改寫。

檢索與 RAG

一般搜尋現在會對中文分詞，並支援多個關鍵字。其 BM25 索引快取於記憶體，在內容／政策變更時失效，鎖定時清除。進階檢索加入區塊位移、向量分數、混合排名融合、輕量重排序，以及透過設定 URL 選用學習式重排序。憑證與私密內容仍排除在外。

memories rag ingest VAULT_ID notes.md --title "Research notes"
memories rag search VAULT_ID "Chinese and English keywords" --mode bm25
memories rag model-install
memories rag index VAULT_ID
memories rag search VAULT_ID "What does this document mean?" --mode hybrid
memories rag ask VAULT_ID "Summarize the evidence"

內建 CPU 推論引擎在 Memories 處理程序中執行 EmbeddingGemma；不需要 Ollama 或其他推論應用程式。模型檔案為公開資料，可透過 model-install 安裝一次，或在 rag.local_model_dir 提供。Gemini Embedding 是另一個線上 API。遠端嵌入、生成及可選重排序的 URL 由使用者自行選擇設定。可設定 HTTP(S)/SOCKS 代理、逾時與有限次重試。請參閱 RAG 指南。

私密檔案與憑證

sudo 是內部授權工作階段，不是作業系統管理員存取權限。它使用相同的本機密碼。提升權限最長持續 15 分鐘，閒置五分鐘後到期，範圍限定於終端機的父處理程序。鎖定或重新啟動服務會清除它。一般解鎖在閒置 15 分鐘後到期。

memories sudo
memories file import VAULT_ID document.pdf
memories file export VAULT_ID FILE_ID exported.pdf
memories file exec VAULT_ID FILE_ID -- caddy run --config "{file}" --adapter caddyfile
memories credential add VAULT_ID "API token"
memories credential import VAULT_ID "SSH identity" existing-private-key
memories credential generate VAULT_ID "laptop ssh"
memories credential generate VAULT_ID "laptop ssh" --algorithm rsa --bits 4096
memories credential generate VAULT_ID "db ca" --kind tls-ca --algorithm rsa --subject memories-ca
memories credential generate VAULT_ID "db server" --kind tls --ca CA_ID --algorithm rsa --name db.example.test
memories credential public VAULT_ID KEY_ID
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
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
memories credential allow-host VAULT_ID CREDENTIAL_ID api.example.com
memories credential http VAULT_ID CREDENTIAL_ID https://api.example.com/status
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 open mysql --vault VAULT_ID --credential CREDENTIAL_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 open postgres --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 mysql --vault VAULT_ID --credential CREDENTIAL_ID --host db.example.test --user app --database appdb --no-tls
memories remote run SESSION_ID -- uname -a
memories remote run SESSION_ID --op query -- SELECT 1
memories remote propose SESSION_ID -- uname -a
memories remote approve TICKET_ID
memories remote exec TICKET_ID
memories remote close SESSION_ID
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 CREDENTIAL_ID --host db.example.test --user app --database appdb
memories proxy list
memories proxy stop PROXY_ID

使用已儲存設定檔執行程式

memories file exec VAULT_ID FILE_ID -- PROGRAM ARGS... 讀取已授權檔案，將程式參數中每個 {file} 替換為暫存檔案的絕對路徑。在 -- 前使用 --revision REVISION 選擇歷史版本。所需解鎖、保管庫存取與終端機 memories sudo 權限與匯出檔案相同。遠端／託管背景服務可提供檔案；程式始終在 CLI 所在電腦，以 CLI 使用者帳號執行。

memories sudo
memories file import VAULT_ID ./Caddyfile
# Use the returned file ID. Caddy 2 Caddyfile syntax needs an explicit adapter.
memories file exec VAULT_ID FILE_ID -- caddy run --config "{file}" --adapter caddyfile

子處理程序繼承工作目錄、環境與標準串流；直接回傳其結束代碼，不包裝 JSON 成功封套。不會插入 Shell，也沒有五分鐘執行限制。請在前景執行程式。暫存目錄／檔案僅擁有者可存取（Unix 0700/0600；Windows 使用者 ACL），子處理程序結束或啟動失敗後即移除。Windows 上的 Ctrl+C/Ctrl+Break 與 Unix 上的 SIGINT/SIGTERM/SIGHUP 會觸發關閉，等待十秒後才終止直接子處理程序並清理。Unix 訊號會轉送給子處理程序；Windows 主控台事件會傳至共用該主控台的處理程序。

這會在子處理程序存活期間匯出明文。請信任程式與其外掛：其輸出不會遮蔽。鎖定／撤銷無法收回已交付的副本或停止子處理程序。強制終止 Memories、斷電或關閉 Windows 主控台可能遺留暫存檔；刪除不等於安全抹除。脫離的後代處理程序不受管理。每次呼叫使用一份名為 config 的固定檔案快照；不會自動更新、重新載入、展開範本或匯入相關檔案。相對路徑依目標程式規則處理，因此外部引入檔案／憑證應使用絕對路徑；若程式原本依檔名推斷格式，請明確指定格式。

憑證處理程序注入

憑證 memories run 處理程序注入使用標準輸入；--env 則允許明確選用環境變數。必須確認程式 SHA-256 指紋，或透過 --approve-digest 提供。子處理程序的兩個輸出串流均會被抑制。然而，接收程式仍可複製或傳送憑證，必須值得信任。執行綁定將一個憑證固定至一個程式指紋，讓程式開發代理無須您的終端機 sudo 工作階段即可使用。credential bind gh（sudo，輸入 USE）從 PATH 解析 gh、記錄 SHA-256，並將綁定僅儲存在此裝置的加密狀態；它不會同步，還原時會清除。綁定在 --hours 後到期（預設 8，最多 720），且僅在資料庫解鎖時有效。run --binding gh -- ARGS 會在目前目錄執行程式，將憑證放入所選環境變數，並轉送輸出，同時將每次出現的憑證替換為 [REDACTED]（--suppress-output 改為捨棄輸出），以程式結束代碼結束。--deny WORDS 拒絕非旗標參數依序包含指定詞語的命令；--ask WORDS 使掛鉤在執行前詢問。對 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 會在 Claude Code 使用者設定中加入 PreToolUse 掛鉤（先顯示設定項目並要求輸入 APPROVE）。Claude Code 即將在 Bash 或 PowerShell 執行 gh ... 時，掛鉤將該命令詞改寫為 memories run --binding gh --，其餘命令列保持不變。在 $( )、反引號、sh -c、xargs 等包裝中執行的 gh 會被拒絕並說明原因；heredoc 本文及作為參數的替換（例如 --body "$(cat <<'EOF' ... EOF)"）則允許。管線或重新導向的輸入透過 --stdin 轉送（最多 16 MiB）。程式在背景服務的環境執行，因此拒絕 NAME=value gh ... 前綴；請改用程式旗標。Shell 在執行時展開的參數（$var、萬用字元）無法與規則比對，因此掛鉤會先詢問。只有整個命令完全由綁定執行組成時，掛鉤才直接核准；若也執行其他程式或寫入檔案，仍適用 Claude Code 的一般確認。若綁定程式遺留的後代仍持有管道，導致背景工作執行緒持續讀取，這些執行緒的數量受到限制；遺留數量過多時，拒絕後續綁定執行。Claude Code 自己的拒絕與詢問權限規則仍適用，但可能看到改寫後命令，因此敏感子命令應保留在綁定規則中。綁定程式在服務鎖之外執行，所以長時間的 gh run watch 不會阻塞其他用戶端；五分鐘限制仍適用。

HTTPS 介面僅透過 HTTPS/443 將 Bearer 權杖傳送至已設定主機，不跟隨重新導向或繼承代理設定，且只回傳狀態碼，避免在回應本文反射憑證。背景服務管理的 SSH、FTP、TCP、MySQL、Redis 與 PostgreSQL 工作階段將機密留在服務中。每個指令先提出、以 APPROVE 核准，然後在實際工作階段執行一次。remote run 完成全部三步；指令稿可用 remote propose（排入票證）、remote approve（sudo、單次使用）與 remote exec（同一提升權限呼叫者）分開執行。SSH 接受密碼憑證、匯入的 OpenSSH 私密金鑰（credential import）或在保管庫內產生的金鑰（credential generate）。產生操作不會輸出私密金鑰；credential public 僅回傳 SSH 公開金鑰或 TLS 憑證。可選擇附加第二個 OpenSSH 憑證項目（--certificate）。SSH 也需要由 remote probe 取得並固定的主機金鑰指紋。MySQL、Redis 與 PostgreSQL 預設使用 TLS，並驗證主機名稱。Redis 與 PostgreSQL 使用 rustls 和 webpki 根憑證；MySQL 使用平台 TLS 程式庫。--tls-ca 從保管庫憑證加入已儲存的 PEM CA；它與全域 --ca-file PATH（MEMORIES_CA_FILE）不同，後者為背景服務／中繼 WSS 及對外 HTTPS／資料庫用戶端加入檔案系統 PEM CA 憑證組。請在建立連線的處理程序設定這些選項（由背景服務執行的上游操作，須在啟動背景服務時設定）。全域 --insecure 略過憑證與主機名稱驗證，但不停用 TLS：危險，僅供開發／自簽憑證使用；優先使用 --ca-file。伺服器端 --tls-cert／--tls-key 不變。請參閱用戶端 TLS 範例。傳入 --no-tls 可停用資料庫 TLS。MCP 不能使用此途徑。檔案操作使用 FTP；已核准 SSH 工作階段僅接受 exec。

保護 Wiki 文件中的機密

在應用程式開啟記憶／卡片選單，選擇 Protect secret in document（保護文件中的機密）（中文：替換資料中的金鑰）。為參照命名（例如 API_KEY），然後透過隱藏輸入輸入精確機密值並授權操作。該文件本文中所有完全符合的內容會變為 {{secret:API_KEY}}；機密值以加密憑證儲存。一般讀取、搜尋與 MCP 只能看到參照。

在文件或憑證選單選擇 Copy secret（複製機密）（複製金鑰）。文件若有多個參照，先選擇標籤。確認並授權後，將目前的值複製至系統剪貼簿，不顯示內容。

CLI 提供相同操作（使用 list 或 search 回傳的短 ID）：

memories sudo
memories memory protect-secret VAULT_ID DOCUMENT_ID API_KEY
# For a knowledge card, use: 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

替換命令會提示輸入機密；不要將機密放在參數或參照名稱中。標籤接受 1-64 個 ASCII 字母、數字、底線或連字號，且必須尚未用於該文件。複製文件參照必須指定 --label，即使僅有一個參照。複製只回傳複製狀態（"copied": true）。Windows 使用原生剪貼簿，macOS 使用 pbcopy，Linux 需要 wl-copy（Wayland）或 xclip（X11）。受保護的帳號／權杖／env／OTP 卡片也可直接複製；OTP 複製回傳種子，而非一次性代碼。

替換只影響目前文件本文。舊的簽署版本、備份、其他文件與共用副本仍保留先前內容；請向提供者撤銷或輪替已暴露金鑰。剪貼簿內容在鎖定後仍存在，可能被其他應用程式或作業系統剪貼簿歷程讀取。使用後請清除。此功能不會自動發現機密或輪替金鑰。同步含有機密參照的文件前，請更新所有用戶端。拒絕條件、編輯與憑證更新、平台需求及剪貼簿疑難排解請參閱完整指南。

無密碼 SSH 與資料庫代理

memories proxy start 通過終端機 sudo 與憑證主機允許清單檢查後，開啟 127.0.0.1 監聽器。它回傳 id、listen 位址與可直接使用的 command。在背景服務所在電腦的代理終端機執行該命令；不會回傳已儲存密碼或私密金鑰。上游帳號、主機與初始資料庫由啟動代理的參數選定。代理授權該帳號的命令，無須逐一核准命令。

memories sudo
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

先用 credential allow-host VAULT_ID CREDENTIAL_ID HOSTNAME 授權憑證目的地主機。提供 --host-key 前，須透過可信管道驗證 remote probe 取得的 SSH 指紋。SSH 代理轉送 exec、shell、PTY 與子系統請求；上游主機金鑰維持固定。本機 SSH 主機金鑰為短暫金鑰，因此回傳命令僅對本機端點停用主機金鑰持久化。

資料庫上游預設使用已驗證的 TLS，可選 --tls-ca CA_ID。本機資料庫這一段連線為明文回送。PostgreSQL 支援 SCRAM-SHA-256、MD5 與密碼驗證。MySQL 支援 mysql_native_password 與 caching_sha2_password；完整 SHA-256 密碼驗證需要 TLS。尚未實作 PostgreSQL 取消／啟動選項轉送與 MySQL 壓縮。本機登入名稱與初始資料庫請求不會覆寫已設定的上游帳號／資料庫。

任何能連上本機連接埠的處理程序，都能使用其已授權的遠端帳號。請讓連接埠僅限本機使用。鎖定、自動保管庫閒置鎖定、proxy stop 及背景服務關閉，都會關閉監聽器與既有連線。代理即使持續使用，也會在 30 分鐘後到期；最多四個代理，每個代理最多 16 個連線。MCP 不能啟動、列出或停止代理；使用者啟動代理後，AI 代理使用一般終端機用戶端。

擷取密碼與命令輸出

memories catch（亦為 memories credential catch）擷取 UTF-8 機密，並以加密憑證儲存。先在同一終端機執行 memories sudo。未指定來源旗標時，如同 credential add，會提示隱藏輸入：

memories sudo
memories catch VAULT_ID "Database password"

使用 --stdin 接收管線或重新導向檔案。這些範例可在 Windows CMD 使用；secret-tool 代表您自行提供、會輸出機密值的程式：

secret-tool.exe | memories catch VAULT_ID "Database password" --stdin --regex "password=([^\r\n]+)"
memories catch VAULT_ID "API token" --stdin --json-pointer /token < response.json
memories catch VAULT_ID "API token" --exec secret-tool.exe --json-pointer /token -- issue --format json

--exec PROGRAM -- ARGS... 直接啟動指定程式並擷取標準輸出。它會關閉子處理程序的標準輸入並抑制標準錯誤。CMD 指令稿使用 --exec cmd.exe -- /d /c script.cmd；Shell 運算子需要明確選擇 Shell。此模式不支援需要終端機的互動式外部程式；請改用隱藏輸入或非互動式輸出命令。

未指定選取器時，擷取保留完整文字，只移除末尾一個 LF/CRLF。正規表示式必須恰好符合一次；若有單一擷取群組，儲存該群組，沒有群組則儲存整個符合內容。其他分組請用 (?:...)。--json-pointer 選取 JSON 字串（例如 /credentials/password）；不能與 --regex 併用。JSON 物件的索引鍵必須唯一，包括巢狀物件與跳脫後等價的鍵，例如 password 與 pass\u0077ord。空值、無效 UTF-8、有歧義的符合項目、重複索引鍵及失敗命令都會被拒絕，不儲存。使用 --id CREDENTIAL_ID 替換憑證。

輸入上限為 1 MiB。命令在 30 秒後逾時；需要時可將 --timeout 設為 1-300 秒。逾時或輸出過多時，擷取會終止直接子處理程序；它不提供整棵處理程序樹的隔離。管線標準輸入等待 EOF，沒有逾時。成功輸出包含憑證 ID，絕不包含擷取值。透過 memories run 或授權 HTTP 操作使用憑證。不要將真實機密放在命令參數、正規表示式模式或標題中。擷取不會清除來源檔案、Shell 歷程或來源程式產生的日誌。

裝置、成員與同步

雲端帳號授權

在此裝置使用您自行註冊的 OAuth 應用程式授權 OneDrive 或 Google Drive。登入前，啟動目前的背景服務、解鎖資料庫，並在同一終端機執行 sudo：

memories 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 logout onedrive

登入會開啟瀏覽器，使用 PKCE/state 驗證本機回呼。權杖儲存在加密的裝置本機狀態中，排除於備份／裝置交換之外。狀態不會輸出權杖。登出移除本機授權；提供者端的同意須另外管理。memories cloud sync 更新權杖後，透過已連接的 OneDrive 或 Google Drive 應用程式資料夾上傳與下載不可變密文物件。行動裝置提供雲端連線與前景同步控制；必須註冊原生 OAuth 用戶端。請參閱行動雲端設定。

提供者註冊、重新導向 URI、--no-browser、到期與疑難排解請參閱 docs/cloud-authorization.md。

裝置配對與保管庫傳輸

以新裝置自己的密碼初始化，然後執行：

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 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 device revoke VAULT_ID DEVICE_PUBLIC_KEY

擁有者管理管理員與所有權；管理員管理一般成員；編輯者寫入資產；讀者讀取並使用資產。裝置撤銷依保管庫分別執行，請套用至每個受影響保管庫。切勿假設移除成員會抹除其既有副本。

加密檔案交換無須中繼服務：

memories sync export VAULT_ID RECIPIENT_DEVICE_PUBLIC_KEY packet.json
memories sync import packet.json

若要在線上傳輸，請在 TLS 反向代理後執行 memories-relay，並用 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

中繼服務不會替離線裝置排隊保存封包。傳送成功表示封包已交給中繼服務，不代表對等端已驗證／匯入；接收端會另行回報匯入成功。sync export/import 與中繼 sync send/receive 是明確執行的完整保管庫傳輸，不是自動增量雲端同步。cloud sync PROVIDER 則透過持久化雲端佇列交換不可變密文物件；真實帳號驗證仍待完成。中繼 RPC 又是另一種方式：它呼叫遠端背景服務，不將其保管庫匯入用戶端資料儲存區。使用者持有的永遠在線用戶端可保存副本，但它是可信端點，而非不受信任的儲存伺服器。

每次建立／更新都會在保管庫 DAG 寫入新的簽署修訂版本（記憶、知識／Brain 卡片、受保護卡片中繼資料、檔案與憑證）。使用 memory history／card history／file history 列出修訂版本（revision、時間戳記、作者、最新版本、摘要）。以 read --revision 取得修訂版本，並用 memory diff／card diff／file diff 比較（對標題、結構化中繼資料與本文產生統一格式文字差異；檔案差異省略二進位內容；憑證機密本文絕不回傳）。修訂版本隨保管庫無限期保留，不自動修剪。並行資產編輯會保留為多個最新版本。用 memory history 檢閱後，再明確執行 memory put --id ASSET_ID --resolve。先前未知的舊世代變更進入 sync quarantine；sync reapply 會簽署目前世代的新修訂版本。分歧的權限鏈一律拒絕授權。在兩個分支都有效的擁有者可檢閱後執行 sync resolve-policy VAULT_ID packet.json --keep-local，再分發已簽署的解決結果。涉及不相容所有權移轉的衝突仍會被阻擋，不授予任一方單方面控制權。

稽核與復原

memories audit VAULT_ID --verify
memories sudo
memories audit VAULT_ID
memories backup offline-backup.memories

備份使用獨立密碼。請在裝置之外保存一份副本。復原時，以新的 --home 啟動背景服務，再執行：

memories --home NEW_DIRECTORY restore offline-backup.memories --name replacement
memories --home NEW_DIRECTORY sudo
memories --home NEW_DIRECTORY archive list

復原會建立獨立保管庫，包含目前資產與保留的衝突最新版本。它不會恢復過時的共用保管庫權限。原始版本、刪除標記與已簽署稽核紀錄保留在加密、唯讀的復原封存中（archive history、archive read、archive audit）。請透過目前已授權成員重新加入正在使用的共用保管庫。一般介面與封存介面都不能輸出歷史憑證值。

AI 用戶端技能注入

安裝內附的 memories 技能，讓 AI 用戶端了解如何搜尋、檢索與儲存 Memories 知識，依已授權文件回答，以及使用已授權憑證操作：

memories inject all --dry-run
memories inject all
memories inject codex
memories inject opencode claude
memories inject all --project /path/to/project

預設為使用者範圍安裝。--project DIRECTORY 僅安裝至既有專案目錄（目前目錄使用 --project .）。claude 目標為 Claude Code，也接受 claude-code 別名。

~ 是作業系統使用者的家目錄，包括 Windows 的 %USERPROFILE%。OpenCode 依序採用 OPENCODE_CONFIG_DIR、絕對路徑 XDG_CONFIG_HOME 加上 opencode，再採用上述預設位置。Claude Code 採用 CLAUDE_CONFIG_DIR。Codex 使用文件規定的 .agents/skills 位置，與 CODEX_HOME 無關。專案安裝忽略這些全域覆寫設定。OpenCode 也會探索相容 Claude／agent 的技能目錄；使用多個用戶端時，請讓所有位置的 memories 技能內容一致，避免定義衝突。

安裝離線進行，不需要背景服務或已初始化的資料儲存區。只寫入內附技能，不讀取／匯出保管庫內容、不建立授權，也不修改 MCP／用戶端設定。--home／MEMORIES_HOME 為一般操作選擇 Memories 資料儲存區，而非技能目的地；安裝不會嵌入該路徑。使用非預設資料儲存區時，請在用戶端環境或 MCP 命令設定相同主目錄。

內容相同的既有檔案保持原狀。不同的 SKILL.md，包括先前 Memories 版本留下的舊技能，會被拒絕，除非傳入 --force；此選項僅替換該檔案，保留同層其他檔案。即使使用 --force，作為連結的技能檔案／目錄仍會被拒絕。寫入前會檢查所有目標的衝突，並以不可分割的方式發布每個檔案。若後續檔案系統 I/O 失敗，較早的目標可能已安裝；請修正錯誤後重新執行。--dry-run 執行相同檢查，回報計畫路徑／操作，不寫入任何內容；使用 --dry-run --force 預覽替換。

確保 memories 位於用戶端 PATH。若未立即探索到技能，請開啟新的用戶端工作階段。在 Codex 呼叫 $memories；Claude Code 呼叫 /memories；OpenCode 則要求載入 memories 技能。本機技能安裝不會將帳號層級技能安裝至 Claude Desktop/Cowork 或雲端工作階段。有可用的既有 MCP 連線時，技能會使用它；請依下方說明另行設定。

探索慣例：Codex、OpenCode、Claude Code。

產生 AGENTS.md／角色技能

撰寫專案 AGENTS.md（或 Cursor/Codex 形式的技能目錄），說明如何操作 Memories：保管庫、卡片、角色／世界／物件、歷程／差異與遠端背景服務基礎。可選擇嵌入角色核心概覽：

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 預覽計畫但不寫入。

memories inject 仍是獨立的離線安裝程式，用於將內附通用技能安裝至 Codex／OpenCode／Claude Code 路徑。

用戶端 CLI 預設值

非機密預設值存於 Memories 主目錄（MEMORIES_HOME／--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

明確指定的旗標永遠優先。接受保管庫／資產的角色子命令，會以預設值補上省略的位置參數（world-get、thing、append-event 等）。persona import 仍須在技能路徑前明確提供保管庫 ID（clap 位置參數順序）。

本機 MCP

本節說明一般限定保管庫範圍的 MCP 授權。另一個需主動啟用的無人值守伺服器具有更廣的讀取邊界。

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

授權是本機持有人能力，寫入檔案而非輸出。請保護該檔案。授權預設為讀取；一般內容寫入使用 --scope read_write，包含刪除則用 --scope read_write_delete。--write 是相容簡寫，等同 --scope read_write。這些範圍不授予私密內容、檔案、憑證或 sudo。將 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，以及角色卡片列出的角色工具。workflow_card 建立步驟工作流程、檢查清單範本或從範本複製的任務；workflow_update 編輯檢查清單欄位或推進步驟；兩者都需要寫入範圍。workflow_read 與 workflow_list 可使用讀取權限。每次呼叫包含已授權保管庫 ID。memory_retrieve 回傳附引用的文件區塊，預設模式為本機 BM25；vector 與 hybrid 使用背景服務設定的嵌入提供者。設定生成 URL 後，memory_ask 依據這些來源回答，並拒絕未出現在檢索證據中的引用。請參閱檢索與 RAG。私密記憶、檔案、憑證存取、處理程序執行與保管庫成員變更均排除在外。授權簽發、列出、撤銷與權限請求是獨立 MCP 工具，不繼承 sudo。鎖定會移除記憶體內授權；未到期授權在解鎖後恢復。MCP 協定：2024-11-05。MCP 讀取不解析機密參照。目前 card_write 工具無法更新含機密參照的卡片，因為不會保留其對應關係；請透過 CLI 或行動應用程式編輯這些卡片。

無人值守桌面 CLI/MCP

明確註冊需要輸入 ENABLE 表示同意，並在設定時以密碼解鎖／sudo 一次。請明確選擇 windows-dpapi、macos-keychain、linux-secret-service 或保護較弱的 owner-file 後端，然後簽發限定保管庫範圍的用戶端檔案。用 unattended ... --client-file PATH 或 mcp serve-unattended --client-file PATH 選取該檔案。這些用戶端能讀取一般／私密內容、原始檔案、歷程與明確請求的憑證明文，但不能修改資產或繼承 sudo。

背景服務啟動時只載入金鑰，不取得一般環境授權。手動 lock 會持久禁止無人值守存取，直到以密碼授權執行 unattended resume；revoke 移除一個授權，disable 移除全部無人值守權限。Center 管理的資料儲存區、遠端傳輸與行動裝置均不能使用。一般 MCP 不受影響。憑證 base64 是編碼，不是加密：AI 用戶端或其日誌可能保留機密。請參閱設定、位元組範圍讀取與安全限制。

知識卡片與受保護卡片

所有知識卡片支援卡片型別與自訂欄位：筆記、聯絡人、連結、程式碼片段、檢查清單、事件與憑證，以及可重用保管庫範本。欄位有順序並會驗證；敏感值維持遮蔽，除非透過已驗證授權明確揭露。使用 memories type、memories card field，或 Flutter 與受限桌面卡片編輯器。

卡片支援標籤、來源、可選別名（alias）、筆記／備註（notes/remark）、類別（category）、有向關聯與反向連結。一般卡片內容與安全帳號摘要可在本機搜尋；一般私密卡片讀取需要 sudo，並排除於一般搜尋與 MCP 之外。獨立的無人值守權限可讀取範圍內私密卡片。建立／更新時使用 --alias、--notes 與 --category。card list（亦為頂層 memories list／memories ls）可省略保管庫 ID，以掃描所有可存取保管庫（每筆結果包含 vault）。--type knowledge|brain|persona|workflow|account|env|token|totp|hotp|otp 按 summary.type 篩選（knowledge 是一般 Wiki／知識卡片；brain 是具摘要與型別連結的結構化知識；otp 表示 totp+hotp）；--otp 是 --type otp 的簡寫。--category NAME 篩選；--group-by-category 將輸出分組。有設定別名、備註與類別時，列表會顯示它們。

memories card put VAULT_ID --title "An idea" --input notes.md --tag design --alias "Design note" --notes "from workshop" --category design
memories card list VAULT_ID
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 --type account
memories card list VAULT_ID --category design
memories card list VAULT_ID --group-by-category
memories card brain VAULT_ID --title "Alice" --abstract "Product lead bridging design and eng" \
  --link CARD_A=reports-to --link "OTHER_VAULT/CARD_B=collaborates|shared roadmap" \
  --alias "Alice" --notes "org chart" --category people
memories card brain VAULT_ID --id BRAIN_ID --title "Alice" --abstract "Updated abstract" --link CARD_B=partner
memories card link 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 unlink VAULT_ID CARD_A CARD_B --relation supports
memories card delete VAULT_ID CARD_ID

card delete（如同 memory delete）從目前檢視移除卡片；簽署歷程保留先前修訂版本。刪除私密或受保護卡片需要 sudo。

Brain 卡片儲存明文 abstract（在保管庫權限內可搜尋，不是受保護機密）及可跨保管庫的具型別連結 { vault?, card, role?, note? }。--link 值含 | 或空格時，請以引號包住整個值，避免 Shell 將其解讀為管線。summary.type 為 brain，並包含 link_count。有權限時，列表／圖譜／讀取解析連結標題與型別，將遺失或未授權目標標記為 broken（不連帶刪除）。搜尋索引標題、摘要、連結角色／備註與同保管庫公開目標摘要，絕不索引機密。同保管庫 Brain 連結也會出現在 card graph。

角色卡片（summary.type = persona）儲存跨產品身分核心，包含連結的封存資產、用於本地日期／時段推理（隔日／早課晚課）的 IANA timezone、世界領域（place／pose／look／帶自由 JSON 屬性的通用 things／帳本／天氣／骰子／轉盤／排程），以及帶 UTC 與本地時間戳記的僅附加行為事件。請參閱 docs/persona.md。使用 memories persona import VAULT_ID ./xiaoya-persona --timezone Asia/Shanghai 匯入；以 memories persona world-set 更新世界狀態。

工作流程卡片（summary.type = workflow）在卡片修訂版本上保存依序步驟，每步為 pending、active、done 或 skipped，另有整體狀態；memories card workflow VAULT --title Release --step "Write notes" --step Ship 建立卡片，memories card workflow-update VAULT ASSET --advance 推進步驟，memories card list --type workflow 列出卡片。

使用 memories card workflow VAULT --template --assignee NAME --summary OVERVIEW --goal GOAL 建立檢查清單範本（summary.type 保持 workflow，設定欄位 template 為 true），以 memories card list --type workflow --template 列出，並以 memories card workflow VAULT --template TEMPLATE 複製為任務工作流程；可使用 --workflow WORKFLOW 連結另一張工作流程卡片，以及 --archive MEMORY 封存記憶。

一般有向連結（card link）參照同保管庫卡片。圖譜省略已刪除、衝突及未授權節點與其相連的邊。參照保留於加密歷程。復原會保留無歧義資產的 ID，讓關聯與憑證參照在復原後的獨立保管庫繼續有效；衝突資產的參照可能需要修復。行動裝置顯示向外連結、反向連結與可平移／縮放圖譜（畫布最多 24 個節點，但可從完整圖譜選取並查看關聯列表）。

受保護卡片在同一交易中儲存中繼資料與獨立憑證：

網站登入資料通常批次匯入，而非逐一輸入；請參閱匯入與匯出網站登入資料。

memories sudo
memories card account VAULT_ID --title "Example mail" --email user@example.test --smtp smtp.example.test
memories card env VAULT_ID ./app.env --title "Application config"
memories card token VAULT_ID --title "API session" --host api.example.test
memories card token VAULT_ID --title "Browser session" --host app.example.test --cookie
memories card request VAULT_ID TOKEN_CARD_ID https://api.example.test/session
memories card otp VAULT_ID --title "Example OTP" --issuer Example --account user@example.test
memories card otp VAULT_ID --title "Example HOTP" --issuer Example --account user@example.test --hotp --counter 0
memories card otp-import VAULT_ID --title "Imported OTP" --alias "Work 2FA" --notes "laptop" --category otp 'otpauth://totp/Example:user@example.test?secret=GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ&issuer=Example'
memories card otp-import VAULT_ID --image ./ga-export.png --title "GA import" --category otp
memories card otp-code VAULT_ID OTP_CARD_ID

OTP 標題可保留匯入時的 issuer / account 形式，--alias 與 --notes 則分別儲存顯示名稱與備註；--category 在 card list 中將它們分組。

密碼、權杖、Cookie 與 OTP 種子使用隱藏終端機輸入，絕不放在命令參數中。Bearer 模式輸入原始 JWT，Cookie 模式輸入 name=value; other=value。帳號 SMTP 預設為 SSL 連接埠 465；這只記錄設定，不傳送郵件。加入 --id CARD_ID 替換受保護卡片的中繼資料與機密；憑證 ID 與卡片連結會保留。憑證 ID 是參照，不是機密值。一般卡片寫入不能替換受保護參照。

dotenv 匯入器遮蔽所有值，包括空值／非機密值，絕不索引值或註解。它接受每行一個 KEY=value、可選 export、空白行與註解。拒絕重複索引鍵與多行引號值。不展開變數，也不執行檔案。原始來源檔案仍留在原處；匯入不變更其權限，也不抹除檔案。自由格式卡片標題／備註不是自動機密偵測系統。

HTTPS 介接器在用戶端注入 Authorization: Bearer ... 或 Cookie: ...。它需要 sudo、精確核准主機、HTTPS 連接埠 443 與 GET/POST。重新導向與環境代理停用；僅回傳狀態，抑制回應本文／標頭以防機密反射輸出。這是授權請求介接器，不是通用轉送代理或瀏覽器 Cookie 儲存區。尚未實作 Cookie 到期、JWT 更新與自動登入。

TOTP 支援 SHA-1/SHA-256/SHA-512（--algorithm）、6/8 位數（--digits）與 30/60 秒週期（--period）。HOTP 使用相同演算法與位數，搭配 --hotp 與初始 --counter（每次 otp-code 後遞增）。以 otp-import 匯入 Google Key URI（otpauth://totp/... 或 otpauth://hotp/...）、Google Authenticator 遷移 URI（otpauth-migration://offline?data=...），或透過 --image 匯入 QR 圖片（以純 Rust rqrr 解碼）。TOTP/HOTP 類型取自 URI 或遷移紀錄。省略類型時，有 counter 則選 HOTP，其他帳號均為 TOTP。遷移資料可能建立多張卡片；--title 作為單一卡片標題或批次前綴。otp-code 在 sudo 後回傳短效代碼並稽核產生動作，但不將代碼儲存於稽核紀錄；HOTP 回應包含下一個計數器。搜尋與 MCP 絕不產生代碼或回傳種子。行動裝置隱藏到期代碼，鎖定／進入背景時關閉對話框。TOTP 需要裝置時鐘準確。行動裝置不使用相機掃描 OTP QR 碼；請用 CLI --image 或貼上 otpauth://／遷移 URI。託管裝置配對有獨立相機流程；請參閱 Center。

行動裝置提供 Protected card（受保護卡片）、Import .env（匯入 .env） 與 Import logins (CSV)（匯入登入資料 CSV） 操作。帳號／憑證基本資訊直接出現在搜尋結果與卡片詳情。權杖與 OTP 卡片提供 Authorized request（授權請求） 與 Generate OTP（產生 OTP） 選單操作。一般卡片編輯保留受保護中繼資料；目前機密替換使用 CLI。

匯入與匯出網站登入資料

網站登入資料存於 login 受保護卡片，並批次移動。匯入與匯出需要 memories sudo 與可寫入角色。

memories sudo
# Browser CSV (Chrome/Edge/Brave or Firefox about:logins); the header is detected.
memories login import VAULT_ID --from chrome passwords.csv
memories login import VAULT_ID --from firefox firefox-logins.csv --with-notes
# Read a Firefox profile directly (modern key4.db; prompts for any primary password).
memories login import VAULT_ID --from firefox-profile "/path/to/Profiles/xxxx.default"
# Windows Credential Manager generic credentials (Windows only).
memories login import VAULT_ID --from windows --filter github
memories login import VAULT_ID --from windows --all
# A previous encrypted export.
memories login import VAULT_ID --from memories logins.mlx

# Export: portable encrypted file (recommended) or a browser-compatible 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，會輸出警告，寫入僅擁有者可存取且必須尚不存在的檔案，防止試算表公式注入，使用後應刪除。僅限裝置的保管庫不能匯出。

僅限裝置的設定

memories local-python
memories local-python --program /path/to/python
memories vault list
memories card search LOCAL_VAULT_ID Python

此操作以隔離模式執行所選 Python 直譯器，記錄版本與執行檔目錄，不收集環境變數。每次呼叫在加密的 This device（此裝置） 保管庫中記錄新的觀測，帶有 local_only: true。整個保管庫排除於裝置授權封裝與匯出備份之外；成員邀請、同步匯出／匯入與政策同步都會被拒絕。它仍可在此裝置搜尋，並在鎖定／重新啟動後保留，但匯出備份復原刻意不還原它。可在此保管庫建立知識卡片，記錄其他本機設定。裝置配對仍要求目的地沒有既有保管庫；請先配對，再建立本機設定觀測。

交換卡片前請升級所有參與用戶端：舊用戶端不理解新的 card 類型與受保護中繼資料。

行動裝置

第一次啟動時選擇 Standalone（獨立模式）、Center 或 SaaS。Standalone 使用加密本機資料庫。Center 要求輸入託管伺服器 URL 與成員權杖；SaaS 使用 https://memories.ivjn.us，並要求成員權杖。託管模式不需要建立或解鎖本機資料庫。之後可用主工具列的 Switch mode（切換模式） 變更；既有資料仍留在原資料儲存區。連線步驟、可用功能、授權、編輯與疑難排解請參閱行動指南，或中文使用指南。

建置與驗證行動用戶端

使用 Flutter 3.44.2（CI 版本）、JDK 17+、Android SDK/NDK 與 cargo install cargo-ndk --locked。此工作副本使用 NDK 28.2.13676358 及 SDK 平台 35、36、37.0 建置（Flutter SDK 與外掛選擇其編譯平台）。建置前接受 Android SDK 授權條款。讓 PATH 可找到 flutter，並使用 rustup target add 安裝 aarch64-linux-android 與 x86_64-linux-android Rust 目標。

.\scripts\build-android.ps1 -Apk

這會建置 ARM64/x86_64 原生程式庫，並產生偵錯 APK：mobile/build/app/outputs/flutter-apk/app-debug.apk。不包含發布簽署憑證。macOS 配合 Xcode 使用 bash scripts/build-ios.sh，然後以自己的開發團隊簽署與執行應用程式。iOS 靜態程式庫會強制連結，以保留 Dart FFI 符號。

建置原生程式庫後，從 mobile 在已連接裝置或模擬器上執行實際行動 ABI 冒煙測試：

flutter test integration_test/native_smoke_test.dart -d DEVICE_ID

此測試使用暫存資料庫，透過 Rust FFI 檢查加密儲存、授權、拒絕憑證讀取、稽核驗證及鎖定／解鎖。之後請重新建置一般 APK，因為 Flutter 整合測試會以測試執行器替換偵錯 APK 入口。

Standalone 模式下，行動用戶端透過 C FFI 使用相同 Rust 服務，提供本機全文搜尋、檔案選擇器、裝置／成員核准檔案、線上中繼傳輸、歷程與稽核檢視。由 Keychain/Keystore 保護的本機因子補強密碼。進入背景會清除授權並關閉內容對話框；Android 阻擋螢幕擷取，iOS 遮蔽應用程式切換器快照。此版本未啟用背景同步。

Center 與 SaaS 透過 FFI 使用 Rust 託管用戶端，支援請求核准、知識瀏覽、伺服器端搜尋、詳情、編輯、刪除與裝置配對。操作依權杖範圍執行；結構化／密封卡片須使用專用編輯器。進入背景會關閉託管工作階段；返回時使用 Reconnect saved session（重新連接已儲存工作階段） 或重新輸入權杖。選擇工作流程前請參閱模式比較。

原始碼儲存庫

實作與驗證細節請參閱 docs/architecture.md 及 docs/validation.md。OneDrive/Google Drive 儲存與同步設計記錄於 docs/cloud-storage-design.md。CLI 授權與 cloud sync 已實作；提供者傳輸已使用本機測試資料測試，未使用真實帳號。行動登入／同步控制使用 AppAuth 與共用 Rust 工作程序；真實授權同意與平台驗證仍是發布門檻。