Apartment38/Agent-Skills

外部记忆提供程序

安装、配置和验证 Hermes Agent 的第三方记忆提供程序。将“已安装”和“在 Hermes 中激活”作为独立的验收标准。

原则

1. 从当前权威文档出发。 加载 hermes-agent 技能，获取提供程序的安装页面及其完整的 Hermes 集成页面。遵循文档推荐的路径；仅在存在实际兼容性约束时使用文档记录的备用方案。
2. 将依赖项放在 Hermes 管理的 venv 之外。 Hermes 更新可能会重建该 venv。优先使用 pipx 或专用的持久化 venv。
3. 在桥接边界匹配 Python ABI。 pipx 环境可能使用比 Hermes 更新的 Python。当涉及原生 wheel 时，将其 site-packages 添加到 Hermes 的 sys.path 是不安全的。当包装器在进程内执行导入时，使用由 Hermes 的 Python 创建的专用 venv。
4. 使用 Hermes CLI 进行配置。 切勿手动编辑 config.yaml；使用 hermes config set 应用设置。
5. 不要禁用共享内存工具集。 在替换遗留文件记忆时，仅禁用提供程序文档中说明的内置文件/配置文件标志。使用 hermes tools disable memory 一刀切也可能隐藏提供程序工具。
6. 考虑提示缓存。 提供程序/工具的更改适用于新初始化的会话。不要修改现有会话的系统提示或工具模式；重启网关，并明确说明正在运行的 TUI 会话必须被替换。

安装工作流

1. 在更改状态前进行审计

记录：

• hermes --version 及 Hermes 的 Python 版本/路径
• 提供程序包的版本和安装环境
• 提供程序安装程序/状态输出
• hermes plugins list --plain --no-bundled
• hermes config get memory.provider
• hermes memory status
• 网关状态

不要从基础包版本推断 [all] 或等效的额外功能。导入或检查提供程序文档中提到的每个能力依赖项。

2. 选择隔离拓扑

• 当提供程序进行进程间通信或 Hermes 发现一个安全的包入口点时，使用 pipx。
• 当 Hermes 在进程内导入提供程序代码且包包含原生扩展时，使用由 Hermes 的 Python 构建的专用 venv。
• 切勿将 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 代理路径

独立的 SDK 冒烟测试是必要但不充分的。通过 Hermes 自己的记忆提供程序加载器加载提供程序，或启动一个新的 Hermes 代理，然后验证：

1. 提供程序的构造和初始化；
2. 提供程序系统提示块处于活动状态；
3. 提供程序工具模式被暴露；
4. 写入一个带有唯一标签的测试记忆；
5. 召回该确切标签；
6. 删除测试记忆；
7. 确认提供程序数据库/路径是预期的 Hermes 存储。

使用断言，如果任何步骤失败，则验证命令失败。报告确切观察到的版本/状态，而不是合理的预期。

常见陷阱

• 单独的 pipx venv 对于进程内导入并非“并存”。 核心和包装器各自可能正常工作，而 Hermes 无法安全地同时导入两者。
• 插件被发现并不意味着插件已启用。 提供程序发现可能成功，而钩子/工具注册仍然需要选择加入。
• CLI 命令不存在并不证明提供程序失败。 Hermes 可以加载提供程序，而安装程序省略了用于 argparse 发现的姊妹 cli.py。分别诊断提供程序和 CLI 路径，然后仅使用经过测试的桥接层进行修复。
• 网关重启不会改造当前会话。 新的网关和 CLI 会话使用该提供程序；旧的 TUI 进程保留其冻结的提示/工具表面。
• 成功的安装命令并不等于完成。 需要验证读取回配置、提供程序处于活动状态以及实际的写入/召回/清理周期。

提供程序参考

• Mnemosyne + Hermes 集成、Python ABI 处理、CLI 桥接层和确定性冒烟测试：references/mnemosyne-hermes.md