搜尋、嵌入向量與檢索增強生成

Memories 支援對已授權的一般記憶與知識卡片進行關鍵字及語意檢索。文件匯入接受 UTF-8 文字與 Markdown，並建立一般加密知識卡片。PDF/DOCX/二進位檔案不會自動擷取；請先轉換為文字，再明確匯入。私密內容、憑證及檔案資產均排除於檢索之外。

快速開始

CLI 與執行中的常駐程式須使用相同的 home/config。升級或變更模型設定後，請重新啟動常駐程式。照常初始化及解鎖後，執行：

memories rag ingest VAULT_ID notes.md --title "Research notes"
memories memory search VAULT_ID "Chinese English keywords"
memories rag search VAULT_ID "keywords" --mode bm25 --match-mode all
memories rag model-install
memories rag index VAULT_ID
memories rag search VAULT_ID "Find similar meaning" --mode vector
memories rag search VAULT_ID "Find evidence" --mode hybrid --limit 8
memories rag status VAULT_ID
memories rag ask VAULT_ID "What does the evidence say?"

rag ask 需要在常駐程式設定中指定生成 URL。若要在不使用嵌入模型的情況下使用詞彙 RAG，請加入 --mode bm25；仍然需要生成 URL。memory_search 維持詞彙搜尋。進階搜尋回傳文件區塊，包含資產／修訂 ID、穩定的區塊雜湊、原始 UTF-8 位元組位移、分數及引用標籤。[S1] 識別單次結果中的來源；一般 memory read 應使用其 id 與 revision 欄位，而非區塊雜湊。

中文 BM25 與區塊

中文及混合語言文字使用 Jieba 斷詞。標題、本文與安全的中繼資料參與 FTS5 BM25 排序，權重為 5/1/2。any（預設）組合關鍵字；all 要求每個查詢詞；phrase 要求原始片語。嚴格的 all/phrase 限制也會篩選向量／混合候選項。查詢會進行跳脫，不會被解讀為任意 FTS 運算子。

文字會在接近句子／段落邊界處分割為最多 768 個 Unicode 字元的區塊，通常重疊 128 個字元。回傳位移對應原始 UTF-8 本文。搜尋限制為請求 100 筆結果、64 個詞彙項目及 1,024 個查詢位元組。基本 memory search 依文件分組區塊；進階 RAG 檢索回傳個別區塊。--cards-only 可縮小檢索範圍。

查詢之間會重用索引。保管庫修改、同步或政策變更會使其快取索引失效；鎖定／重新啟動會清除所有索引與向量。它們不會以明文持久儲存，也不會加入加密同步承載資料。每個快取保管庫的限制為 10,000 個區塊、16 MiB 的來源文字／中繼資料與 32 MiB 的向量；最多快取兩個保管庫。大型資料庫仍受效能文件所述的底層完整狀態持久儲存限制。

程序內的 EmbeddingGemma

預設嵌入後端為 Google 的 EmbeddingGemma 300M Q4，透過原生 ONNX 推論運作。它在 Memories 常駐程式內執行，無須 Ollama、Python 或獨立推論服務。應用程式包含推論引擎，並在建立工作階段前明確停用 ONNX 遙測；應用程式會一次安裝模型／斷詞器檔案（約 209 MiB）：

memories rag model-install

安裝程式下載固定的 onnx-community/embeddinggemma-300m-ONNX 修訂、驗證 SHA-256、支援範圍下載／重試，而且絕不取代現有的不相符檔案。已驗證的現有檔案會重用。預設目錄位於所選 Memories home 下的 models/embeddinggemma。可透過 rag.local_model_dir 指定現有目錄；該目錄必須包含 Q4 ONNX 圖、其外部資料與斷詞器／設定檔。變更模型檔案後，請重新啟動常駐程式。權重另受 Gemma 使用條款與禁止使用政策規範；安裝程式會寫入聲明及上游模型卡。

[rag]
local_model_dir = "./models/embeddinggemma"
local_threads = 4
max_tokens = 2048
# Optional mirror of the exact pinned files:
# model_download_base_url = "https://your-mirror.example/embeddinggemma"

相對模型路徑會以設定檔所在目錄為基準解析。降低 local_threads 可限制 CPU 使用量；max_tokens 限制斷詞器輸入，若低於區塊詞元數，可能截斷長輸入。嵌入向量為 768 維正規化向量。模型使用不同的查詢／文件任務前綴。rag index 預先建立索引；向量／混合檢索也會依需要計算缺少的嵌入向量。步驟之間會檢查五分鐘的操作時間預算；保管庫／模型保持不變且已解鎖時，重試可重用已完成的批次。

客戶提供的模型 URL

Gemini Embedding 是線上 API，並非離線的 EmbeddingGemma 模型。 加入 rag.embedding 可選擇遠端供應商；省略即可維持本機嵌入。請使用完整的操作 URL，並設定服務預期的模型：

[rag.embedding]
protocol = "gemini"
url = "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent"
model = "gemini-embedding-001"
dimensions = 768
api_key_env = "GEMINI_API_KEY"

[rag.generation]
protocol = "gemini"
url = "https://generativelanguage.googleapis.com/v1beta/models/YOUR_MODEL:generateContent"
model = "YOUR_MODEL"
api_key_env = "GEMINI_API_KEY"

在常駐程式環境中設定指定名稱的 API 金鑰環境變數。不要將金鑰值放入 TOML、URL 或命令引數。Gemini 使用 x-goog-api-key；protocol = "compatible" 使用 Bearer 驗證及常見的 {model,input} 嵌入／聊天完成 JSON 格式。相容嵌入回應必須包含具有索引的 data 項目及 embedding 陣列；生成回傳 choices[0].message.content。本機服務的金鑰為選填。遠端 URL 必須使用 HTTPS；HTTP 僅接受回送位址。選填的嵌入 dimensions 會以 Gemini outputDimensionality 或相容的 dimensions 傳送，在收到時檢查，並綁定至向量空間鍵。操作 URL 不接受憑證、查詢字串與片段。

沒有隱含的公開模型端點。設定遠端嵌入 URL 即允許將符合條件的文件區塊傳送至該處。生成僅傳送選取的區塊與問題；已儲存的憑證／私密／檔案內容不會進入此流程。這些設定屬於常駐程式，而非個別 MCP 呼叫。請參閱安全性。

混合搜尋與重新排序

向量模式使用餘弦相似度。混合模式透過倒數排名融合（k=60）合併 BM25 與向量排序。預設輕量重新排序提高詞彙涵蓋率及片語相符的權重。它並不宣稱是經學習的交叉編碼器。有需要時可設定經學習的重新排序服務：

[rag.rerank]
protocol = "compatible"
url = "https://your-reranker.example/rerank"
model = "YOUR_RERANKER"
api_key_env = "RERANK_API_KEY"

請求為 {model, query, documents, top_n}。其回應必須包含 results，每個候選項均須有唯一且有效的 index 與有限的 relevance_score。未知／重複項目會導致失敗，不會默默將錯誤文件重新排序。--no-rerank 會略過兩個選填的重新排序階段。

代理、逾時與重試

[rag.http]
use_env_proxy = true
proxy_url = "http://127.0.0.1:7890"
retries = 2
backoff_ms = 500
connect_timeout_seconds = 10
timeout_seconds = 60
download_timeout_seconds = 900

明確指定的代理優先於環境代理探索。支援 HTTP、HTTPS、SOCKS5 及 SOCKS5h URL。需要驗證的代理值可透過代理環境提供；TOML 代理 URL 不可包含憑證。回送位址的模型／鏡像端點一律直接連線。TLS 驗證保持啟用。

retries 是額外嘗試次數（0-5）。模型 API 連線／讀取失敗、429 及 500/502/503/504 可使用指數退避重試；Retry-After 秒數最多採用 30 秒。驗證／資料驗證錯誤、不安全的重新導向及格式錯誤的模型輸出不會重試。模型 API 重新導向已停用。下載重新導向必須使用 HTTPS，且每個最終檔案均會檢查雜湊。下載逾時是每個檔案的時間預算。重試生成可能增加供應商費用。嘗試之間會重新檢查授權／取消狀態。

回答、引用與 MCP

memory_retrieve 向 MCP 用戶端提供範圍受限的檢索；memory_ask 呼叫已設定的生成服務。兩者均保留授權的保管庫及一般資料限制。它們無法選擇任意端點或存取憑證。僅限裝置的保管庫會拒絕將資料傳送至非回送位址模型端點的操作；本機推論及明確設定的回送位址服務可運作。較舊的 memory_search 與 memory_read 工具仍可使用。隨附的 Memories 技能為 AI 用戶端說明 memory_retrieve 與 memory_ask。升級後，請以 memories inject all --force 取代已安裝的舊技能。

生成將來源文字視為不受信任的資料，且沒有應用程式工具。模型必須回傳結構化回答／引用 JSON，並使用結果中確實存在的引用，例如 [S1]。無效或捏造的 ID 會遭拒絕。沒有證據時，不會呼叫生成服務，結果會標示 insufficient_evidence。引用驗證檢查的是參照，而非每個主張是否受到事實支持；請對照來源檢視重要回答。

鎖定、授權到期／撤銷及來源狀態變更會使進行中的工作失效，並抑制延遲結果。已開始的遠端請求無法收回。本次版本未在行動裝置 FFI 新增模型支援的 RAG 介面；行動裝置的一般搜尋獲得中文／BM25 改善，並可使用 BM25 檢索。