# 安装记忆插件
通过记忆插件，将华为云AgentArts记忆库与Hermes、Claude Code、Codex、OpenCode等主流AI智能体框架无缝对接，安装后，Agent 在对话过程中自动将记忆写入AgentArts Memory，并在每轮对话前搜索并注入相关记忆，实现跨会话记忆持久化。
#### 前提条件
- 已创建记忆库，并获取以下信息：
  - **记忆库ID（Space ID）**：在记忆库详情页获取。
  
  - **API Key**：创建记忆库时生成的API Key，用于数据面API认证。
  
  - **区域（Region）**：记忆库所在区域，如cn-southwest-2。
   
- 已安装Python，且版本不低于3.10。
- 已安装agentarts-sdk，版本不低于0.1.5。
  ```
  pip install agentarts-sdk
  ```
  ![](https://support.huaweicloud.com/highcode-agentarts/public_sys-resources/note_3.0-zh-cn.png)
  下载缓慢或超时，可使用华为云镜像源：
  ```
  pip install agentarts-sdk -i https://repo.huaweicloud.com/repository/pypi/simple --trusted-host repo.huaweicloud.com
  ```
  
- 已安装并配置好目标智能体框架（Hermes、Claude Code、Codex或OpenCode）。
 
#### 配置环境变量
安装记忆插件前，需要配置以下环境变量，用于记忆库的认证和访问。
表1环境变量说明 
| 环境变量                           | 说明                              | 是否必填  | 默认值             |
|:---|:---|:---|:---|
| HUAWEICLOUD_SDK_MEMORY_API_KEY | AgentArts记忆库的API Key，用于数据面API认证。 | 是    | -                 |
| AGENTARTS_MEMORY_SPACE_ID     | AgentArts记忆库ID（Space ID）。        | 是   | -              |
| HUAWEICLOUD_SDK_REGION         | 华为云区域名称。                        | 否 | cn-southwest-2 |
   
配置方式：
```
export HUAWEICLOUD_SDK_MEMORY_API_KEY="your-memory-api-key"
export AGENTARTS_MEMORY_SPACE_ID="your-space-id"
export HUAWEICLOUD_SDK_REGION="cn-southwest-2"
```
![](https://support.huaweicloud.com/highcode-agentarts/public_sys-resources/note_3.0-zh-cn.png)
安装插件时若使用交互模式，安装器会自动将环境变量写入Shell RC文件（如\~/.bashrc或\~/.zshrc），下次打开终端无需重新设置。Windows系统通过setx命令写入用户环境变量。
#### 支持的平台
| 平台            | target 名称 | 配置目录（global）                | 配置目录（project） | 是否需要 Node.js |
|:---|:---|:---|:---|:---|
| Codex         | codex        | \~/.codex                   | .codex/          | 是            |
| Claude Code   | claude     | \~/.claude                 | .claude/        | 是            |
| Hermes Agent | hermes      | $HERMES_HOME 或 \~/.hermes | N/A（固定 user 级）  | 否             |
| OpenCode    | opencode    | \~/.config/opencode         | .opencode/    | 是           |
   
Windows下Hermes配置目录为 %LOCALAPPDATA%\\hermes（由 Hermes 安装器设置 HERMES_HOME 环境变量）。
#### 安装记忆插件
1. 安装agentarts-sdk后，使用以下命令为指定智能体框架一键安装记忆插件。 
   ```
   agentarts memory install [hermes|claude|codex|opencode] --global --yes
   ```
   - **--global**：全局安装（写入用户主目录配置）。如不指定，则为项目级安装（写入当前工作目录配置）。
   
   - **--yes**：跳过交互确认，直接安装。
   
   
   
   
2. 安装完成后，重启或重新加载智能体框架，插件即生效。 
   安装器会自动完成以下操作：
   - 复制插件脚本文件到目标框架的插件目录。
   
   - 合并框架配置文件（hooks、MCP servers等），保留已有配置。
   
   - 记录安装信息到\~/.agentarts/installed.json注册表。
   
   
   
   
 
#### 安装示例
**示例 1：自动检测并交互安装**
```
agentarts memory install
```
**示例 2：安装到 Claude Code（全局）**
```
# 先设置环境变量
export AGENTARTS_MEMORY_SPACE_ID="my-space-12345"
export HUAWEICLOUD_SDK_MEMORY_API_KEY="abcdefghijklmnop123456"
export HUAWEICLOUD_SDK_REGION="cn-southwest-2"
# 安装
agentarts memory install claude --global
```
**示例 3：非交互模式安装 Codex（项目级）**
```
agentarts memory install codex --yes
```
--yes 模式下：跳过所有交互提示，凭据从环境变量读取（缺失则使用默认值），范围默认 project。
**示例 4：安装 Hermes 插件**
```
agentarts memory install hermes --global
```
Hermes 固定为 global 级安装，--global 参数可选。
**示例 5：查看已安装的插件**
安装记录存储在 \~/.agentarts/installed.json，可直接查看：
```
cat ~/.agentarts/installed.json
```
#### 卸载记忆插件
如需移除记忆插件，使用以下命令：
```
# 交互式选择要卸载的平台
agentarts memory uninstall
# 直接指定平台
agentarts memory uninstall codex --global --yes
```
卸载操作会：
- 删除插件脚本文件及插件目录。
- 精确剥离配置文件中的插件相关配置（hooks、MCP servers等），保留用户已有其他配置。
- 清理空目录。
- 更新或删除\~/.agentarts/installed.json注册表中的安装记录。
  ![](https://support.huaweicloud.com/highcode-agentarts/public_sys-resources/note_3.0-zh-cn.png)
  卸载不会删除记忆库中已存储的记忆数据。如需删除记忆数据，请在AgentArts控制台删除记忆库。