HMS多语言SDK与CLI工具详解：Python、TypeScript、Go、Rust客户端及hms命令行完全指南

HMS（Holographic Memory System）是面向 AI 应用的开源长期记忆系统。为了让开发者在任何技术栈中都能方便地存取记忆，HMS 官方提供了覆盖 Python、TypeScript、Go、Rust 的四种语言SDK，以及功能强大的hms 命令行工具（CLI）。本文带你快速上手：5 分钟搞清各语言客户端的安装与调用方式，掌握 retain（记忆写入）、recall（记忆召回）、reflect（记忆推理）三大核心操作，并学会用 hms CLI 完成日常运维。

一、为什么需要 HMS 多语言 SDK？

HMS 的核心工作流只有三步：

所有 SDK 都基于同一份 OpenAPI 规范自动生成，因此四端能力对齐、版本同步。无论你用 Python 写后端、TypeScript 写前端、Go 写服务，还是 Rust 做高性能组件，都能用一致的 API 风格接入 HMS。

二、四种语言 SDK 速览

💡 四个 SDK 的 API 方法几乎一一对应（retain/recall/reflect/createBank…），学会一种，迁移到另一种只需要几十分钟。

三、Python 客户端：hms-client

3.1 安装 Python 客户端

pip install hms-client

Python 客户端由两层组成：自动生成的底层 API（hms_client_api）+ 人工维护的高层封装类HMS（见 hms_client.py）。每个便捷方法都有异步版本（a前缀，如aretain），在 FastAPI、LangGraph 等异步框架中推荐优先使用异步方法。

3.2 三步完成记忆读写

from hms_client import HMS client = HMS(base_url="http://localhost:8888", api_key="your-api-key") # 1. 写入记忆 client.retain(bank_id="alice", content="Alice 是一名热爱 Rust 的软件工程师") # 2. 语义召回 response = client.recall(bank_id="alice", query="Alice 喜欢什么编程语言？") # 3. 基于记忆生成回答 answer = client.reflect(bank_id="alice", query="我现在的兴趣是什么？")

进阶功能（文档管理、实体浏览、Webhook、文件上传、异步任务跟踪）可通过低层属性访问，例如client.documents.list_documents("alice")、client.operations.get_operation_status(...)，覆盖完整 API 面。

四、TypeScript 客户端：@hms-memory/hms-client

4.1 安装 TypeScript 客户端

npm install @hms-memory/hms-client

4.2 核心调用示例

import { HMSClient } from "@hms-memory/hms-client"; const client = new HMSClient({ baseUrl: "http://localhost:8888", apiKey: "your-api-key" }); // 写入单条记忆 await client.retain("alice", "Alice loves hiking", { context: "Settings conversation", metadata: { source: "chat" }, }); // 批量写入 await client.retainBatch("alice", [{ content: "Alice visited Paris last summer" }], { async: true }); // 语义召回（budget 控制召回深度：low / mid / high） const results = await client.recall("alice", "What are Alice's hobbies?", { budget: "mid" }); // 生成上下文回答 const answer = await client.reflect("alice", "What should I do this weekend?"); console.log(answer.text);

TypeScript 客户端还内置了createBank（创建/更新记忆库）、银行模板（manifest）导入导出等能力，完整类型定义位于 typescript/src/index.ts。

五、Go 客户端：OpenAPI 自动生成

Go 客户端由 OpenAPI Generator 根据 openapi.yaml 生成，适合在 Go 服务中做网关或微服务集成。

import hms "github.com/hms-memory/hms/interface/sdk/go" // 通过 BanksAPI / MemoryAPI 等客户端调用各端点 client := hms.NewAPIClient(cfg) banks, _, err := client.BanksAPI.ListBanks(ctx).Execute()

主要 API 分组（见 go/README.md）：

• BanksAPI：记忆库创建、配置、统计、consolidation 触发
• MemoryAPI：RetainMemories/RecallMemories/Reflect/ 图数据
• DocumentsAPI / EntitiesAPI：文档与实体管理
• OperationsAPI：异步任务查询、取消

服务端 URL 支持 context 注入切换（hms.ContextServerIndex），方便多环境部署。

六、Rust 客户端：hms-client

Rust 客户端在构建期通过 progenitor 从 OpenAPI 规范自动生成，天然与 API schema 保持同步（见 rust/README.md）：

# Cargo.toml 中添加依赖 # hms-client = "0.1.0"

use hms_client::Client; let client = Client::new("http://localhost:8888"); // 语义检索 let results = client.search_memories("alice", &search_request).await?; // 批量写入记忆 client.batch_put_memories("alice", &memory_request).await?;

特点：全异步（tokio + reqwest）、完全类型安全、错误统一由progenitor_client::Error处理。CLI 工具hms正是构建在这个 Rust 客户端之上（依赖声明见 cli/Cargo.toml）。

七、hms 命令行工具完全指南

hms CLI 是官方提供的终端运维工具（Rust 编写，当前版本 0.6.1），支持彩色 Pretty 输出，也支持-o json/-o yaml供脚本消费。命令定义位于 cli/src/main.rs，各子命令实现位于 cli/src/commands/。

7.1 首次配置：configure 与 profile

# 交互式配置 API 地址与密钥 hms configure --api-url http://localhost:8888 --api-key your-api-key # 管理多套命名配置（适合切换 dev / prod 环境） hms profile create prod --api-url https://hms.example.com --api-key xxx hms profile list hms -p prod bank list

配置优先级（由高到低）：

1. 环境变量HMS_API_URL、HMS_API_KEY
2. 命名 profile（-p参数或HMS_PROFILE环境变量）
3. 配置文件~/.hms/config
4. 默认值http://localhost:8888

7.2 记忆库（Bank）管理

hms bank list # 列出所有记忆库 hms bank create alice -n "Alice 的助理" -m "记住她的项目与偏好" hms bank stats alice # 查看记忆统计 hms bank disposition alice # 查看性格/画像 hms bank consolidate alice --wait # 触发记忆整合并等待完成 hms bank export-template alice -o alice.json # 导出模板（配置+心智模型+指令）

7.3 记忆核心操作：retain / recall / reflect

# 写入单条记忆 hms memory retain alice "Alice 是一名热爱 Rust 的软件工程师" # 从文件/目录批量导入（支持递归） hms memory retain-files alice ./notes/ -r --context "工作笔记" # 语义召回：-b 控制思考预算，--tags 按标签过滤 hms memory recall alice "Alice 喜欢什么编程语言？" -b mid # 基于记忆库身份生成回答：--schema 支持 JSON Schema 结构化输出 hms memory reflect alice "我现在的兴趣是什么？" --include-facts # 浏览与清理 hms memory list alice -t world -q rust hms memory history alice <memory_id>

7.4 文档、实体与异步任务

hms document list alice # 查看库内文档 hms entity list alice # 浏览实体 hms operation list alice # 查看异步任务 hms operation cancel alice <op_id> # 取消待处理任务 hms operation retry alice <op_id> # 重试失败任务

7.5 运维与交互式探索

hms health # API 健康检查 hms metrics # Prometheus 指标 hms version # API 版本与特性开关 hms audit list # 审计日志 hms webhook list alice # Webhook 管理 hms explore # 启动 k9s 风格的交互式 TUI（别名 hms tui） hms ui # 启动 Web 控制台

hms explore内置基于 ratatui 的 TUI 界面，可在终端里直接浏览银行、记忆、实体并执行 recall / reflect，是排查记忆数据的利器（实现见 cli/src/commands/explore.rs）。

7.6 构建与冒烟测试

# 构建发布版多平台二进制（见 build.sh） bash interface/cli/build.sh # 对着运行中的 API 服务做冒烟测试 bash interface/cli/smoke-test.sh

八、常见问题：SDK 与 CLI 怎么选？

九、延伸阅读

• 端到端记忆流程说明：docs/hms_end_to_end_flow.md
• 系统架构与多模态指南：docs/system_architecture_and_multimodal.md
• 多模态记忆操作指南：docs/multimodal_memory.md
• 自动记忆演示脚本（一行命令体验 retain + recall 闭环）：scripts/run_memory_demo.sh

🧭 小结：HMS 的四种语言 SDK 均以 OpenAPI 规范为单一事实来源自动生成，API 一致、行为对齐；hms CLI 则把银行管理、记忆读写、异步任务、审计、TUI 探索聚合到一个二进制里。按技术栈选择 SDK、用 CLI 做运维，即可覆盖 HMS 的完整使用场景。