Apartment38/Agent-Skills

外部記憶體提供者

為 Hermes Agent 安裝、設定及驗證第三方記憶體提供者。將「已安裝」和「在 Hermes 中活躍」視為獨立的驗收標準。

原則

1. 從當前官方文件開始。 載入 hermes-agent 技能，並獲取提供者的安裝頁面及其完整的 Hermes 整合頁面。遵循文件推薦的路徑；僅在實際相容性限制要求時使用文件記錄的備用方案。
2. 將相依套件保留在 Hermes 管理的虛擬環境之外。 Hermes 更新可能會重建該虛擬環境。偏好使用 pipx 或專用的持久性虛擬環境。
3. 在橋接邊界匹配 Python ABI。 pipx 環境可能使用比 Hermes 更新的 Python。在涉及原生 wheel 時，將其 site-packages 加入 Hermes 的 sys.path 是不安全的。當包裝器在程序內執行匯入時，請使用 Hermes 的 Python 建立專用虛擬環境。
4. 使用 Hermes CLI 進行設定。 切勿手動編輯 config.yaml；使用 hermes config set 套用設定。
5. 不要停用共享記憶體工具集。 替換舊版檔案記憶體時，僅停用提供者文件所指明的內建檔案/設定檔旗標。全面的 hermes tools disable memory 也可能隱藏提供者工具。
6. 考慮提示快取。 提供者/工具的變更僅適用於新初始化的 session。不要變更現有對話的系統提示或工具 schema；請重新啟動閘道，並清楚說明必須取代已在執行的 TUI session。

安裝工作流程

1. 在變更狀態前進行稽核

記錄：

• hermes --version 及 Hermes 的 Python 版本/路徑
• 提供者套件版本及安裝環境
• 提供者安裝程式/狀態輸出
• hermes plugins list --plain --no-bundled
• hermes config get memory.provider
• hermes memory status
• 閘道狀態

請勿從基礎套件版本推斷 [all] 或等效的 extras。匯入或檢查提供者文件所列出的每個能力相依套件。

2. 選擇隔離拓撲

• 當提供者進行程序外通訊或 Hermes 發現安全的套件進入點時，使用 pipx。
• 當 Hermes 在程序內匯入提供者程式碼且套件包含原生擴充功能時，使用由 Hermes 的 Python 建立的專用虛擬環境。
• 切勿將 importlib.util.find_spec() 視為相容性證明。它在不載入原生程式碼的情況下定位模組。請在將執行提供者的直譯器下執行真實匯入。

3. 安裝提供者與橋接器

安裝完整的要求功能設定檔及其 Hermes 包裝器。如果包裝器附帶安裝程式/狀態命令，請使用它在 $HERMES_HOME/plugins/ 下建立持久性插件橋接器，並驗證其匯入。

當 Hermes 將使用者插件列為選擇加入時，請明確啟用它們：

hermes plugins enable <manifest-name>

提供者選擇和一般插件啟用可能是不同的機制。兩者都需要驗證。

4. 設定而不重複

設定外部提供者，並根據提供者文件的指示停用舊版檔案記憶體，同時保留記憶體工具集：

hermes config set memory.provider <provider>
hermes config set memory.memory_enabled false
hermes config set memory.user_profile_enabled false

使用提供者當前文件記錄的金鑰，而非假設這些是通用的。

5. 重新啟動並驗證

僅在安裝、啟用和設定完成後重新啟動閘道。然後驗證：

• 閘道處於活躍狀態。
• 插件橋接器/狀態顯示已安裝且可匯入。
• 一般插件清單在依賴於鉤子/工具時顯示已啟用。
• hermes memory status 顯示所選提供者已安裝、可用且處於活躍狀態。
• 提供者診斷沒有實際的錯誤/失敗記錄。不要將計數器、測量值、跳過的檢查或未設定的可選覆蓋項誤讀為失敗。

6. 執行 Hermes agent 路徑

獨立的 SDK 冒煙測試是必要但不充分的。透過 Hermes 自己的記憶體提供者載入器載入提供者，或啟動一個全新的 Hermes agent，然後驗證：

1. 提供者建構與初始化；
2. 提供者系統提示區塊處於活躍狀態；
3. 提供者工具 schema 已公開；
4. 寫入一個具有唯一標籤的測試記憶；
5. 回憶該確切標籤；
6. 刪除該測試記憶；
7. 確認提供者資料庫/路徑是預期的 Hermes 儲存庫。

使用斷言，並在任一失敗時使驗證命令失敗。回報確切觀察到的版本/狀態，而非看似合理的預期。

常見陷阱

• 分離的 pipx 虛擬環境並非「並存」於程序內匯入。 核心和包裝器可能各自單獨運作，而 Hermes 卻無法安全地同時匯入兩者。
• 插件被發現並不代表插件已啟用。 提供者發現可能成功，而鉤子/工具註冊仍然是選擇加入的。
• CLI 命令缺失並不代表提供者失敗。 Hermes 可以載入提供者，而安裝程式省略了用於 argparse 發現的同級 cli.py。請獨立診斷提供者和 CLI 路徑，然後僅使用經過測試的橋接器進行修復。
• 閘道重新啟動不會改造當前對話。 新的閘道和 CLI session 使用提供者；舊的 TUI 程序則保留其凍結的提示/工具表面。
• 成功的安裝命令並非完成。 需要唯讀回讀設定、活躍提供者狀態以及真實的寫入/回憶/清理循環。

提供者參考資料

• Mnemosyne + Hermes 整合、Python ABI 處理、CLI 橋接器及確定性冒煙測試：references/mnemosyne-hermes.md