企业官网建设流程全解析

TencentDB Agent Memory与容器编排：Kubernetes部署最佳实践

【免费下载链接】TencentDB-Agent-MemoryTencentDB Agent Memory is a team-level memory hub for AI Agents — turning conversations, docs, and code into four reusable memory assets (Chat Memory, Skill, LLM-Wiki, Code-Graph) that are governed, shared, and equipped across agents and frameworks.项目地址: https://gitcode.com/GitHub_Trending/te/TencentDB-Agent-Memory

TencentDB Agent Memory是团队级AI Agent记忆中枢，能将对话、文档和代码转化为四种可重用的记忆资产（Chat Memory、Skill、LLM-Wiki、Code-Graph），实现跨Agent和框架的治理、共享与装备。本文将详细介绍如何在Kubernetes环境中部署TencentDB Agent Memory，帮助新手用户快速掌握容器化部署的最佳实践。

1. 容器化部署基础：Docker镜像构建与运行

在进行Kubernetes部署之前，首先需要了解TencentDB Agent Memory的Docker容器化方案。项目提供了一体化的Docker镜像，预装Hermes Agent + TDAI Memory插件，单容器即可同时运行两个服务，只需配置一个API Key即可启用Hermes对话 + 四层记忆系统。

1.1 Docker镜像构建

可以通过以下命令构建Docker镜像，该过程不依赖项目源码，在任意目录均可执行：

docker build -f Dockerfile.hermes -t hermes-memory .

1.2 Docker容器运行

构建完成后，使用以下命令运行容器，实现后台常驻，Gateway会自动启动：

docker run -d \ --name hermes-memory \ --restart unless-stopped \ -p 8420:8420 \ -e MODEL_API_KEY="your-api-key" \ -e MODEL_BASE_URL="https://api.lkeap.cloud.tencent.com/v1" \ -e MODEL_NAME="deepseek-v3.2" \ -e MODEL_PROVIDER="custom" \ -v hermes_data:/opt/data \ hermes-memory

镜像内置了腾讯云DeepSeek-V3.2的默认值，如果使用该模型，MODEL_BASE_URL/MODEL_NAME/MODEL_PROVIDER可以省略，只传MODEL_API_KEY即可。

1.3 容器内部架构

容器内部架构如下，Hermes Agent（Python）通过HTTP与TDAI Memory Gateway（Node.js，监听:8420）通信，实现记忆功能：

┌──────────────────────────────────────────────────────┐ │ 容器内部 │ │ │ │ ┌──────────────────────┐ ┌─────────────────────┐ │ │ │ Hermes Agent │ │ TDAI Memory │ │ │ │ (Python) │───▶│ Gateway (Node.js) │ │ │ │ │HTTP│ :8420 │ │ │ │ memory_tencentdb │ │ │ │ │ │ plugin (内置) │ │ SQLite 本地存储 │ │ │ └──────────────────────┘ └─────────────────────┘ │ │ │ │ 统一模型配置（Hermes + TDAI 共用一套 MODEL_* 变量） │ └──────────────────────────────────────────────────────┘

2. TencentDB Agent Memory记忆系统架构

TencentDB Agent Memory的核心在于其四层记忆系统，了解这一架构有助于在Kubernetes部署时进行合理的资源配置和性能优化。

该记忆金字塔从下到上分为L0 Raw Log、L1 Atomic Memory、L2 Scene Block和L3 Persona四个层级：

• L0 Raw Log：全量保留原始对话与事件流，确保原始信息不丢失，提供证据兜底。
• L1 Atomic Memory：自动提取事实、偏好、约束、状态，从语音中稳定抽出关键信息。
• L2 Scene Block：按项目/主题/工作流场景聚类，带上文召回，减少单场误用。
• L3 Persona：稳定的用户偏好与服务方式画像，让Agent按用户习惯协作。

这一结构实现了从碎片对话到结构事实，再到场景认知，最终形成服务画像的完整过程，为AI Agent提供了强大的记忆支持。

3. Kubernetes部署准备：环境变量与数据持久化

在Kubernetes中部署TencentDB Agent Memory，需要对环境变量和数据持久化进行合理配置，以确保服务的稳定运行和数据安全。

3.1 环境变量配置

TencentDB Agent Memory的环境变量主要分为统一模型配置和服务配置两类。

统一模型配置（Hermes + TDAI 共用）

用户只需配置上述MODEL_*变量，容器启动时会自动同步到Hermes（config.yaml+.env）和Gateway（TDAI_LLM_*环境变量）。

服务配置

3.2 数据持久化方案

所有数据存储在/opt/datavolume中，结构如下：

/opt/data/ ├── tdai-memory/ # TDAI 记忆数据 (SQLite + 场景文件) │ ├── memories.sqlite # L0/L1 数据 │ ├── scene_blocks/ # L2 场景文件 │ ├── persona.md # L3 用户画像 │ └── checkpoint.json # Pipeline 状态 ├── sessions/ # Hermes 会话记录 ├── skills/ # Hermes 技能 ├── config.yaml # Hermes 配置（启动时自动生成） ├── .env # 环境变量（启动时自动生成） └── gateway.log # Gateway 日志

在Kubernetes中，建议使用PersistentVolume（PV）和PersistentVolumeClaim（PVC）来实现数据的持久化存储，确保数据在Pod重启或迁移时不丢失。

4. Kubernetes部署最佳实践：Deployment与Service配置

虽然项目中没有直接提供Kubernetes配置文件，但我们可以基于Docker部署方案，构建Kubernetes的Deployment和Service配置。

4.1 Deployment配置

以下是一个基本的Deployment配置示例，包含了环境变量设置、数据持久化和资源限制：

apiVersion: apps/v1 kind: Deployment metadata: name: tencentdb-agent-memory labels: app: tencentdb-agent-memory spec: replicas: 1 selector: matchLabels: app: tencentdb-agent-memory template: metadata: labels: app: tencentdb-agent-memory spec: containers: - name: hermes-memory image: hermes-memory:latest ports: - containerPort: 8420 env: - name: MODEL_API_KEY valueFrom: secretKeyRef: name: llm-api-secrets key: model-api-key - name: MODEL_BASE_URL value: "https://api.lkeap.cloud.tencent.com/v1" - name: MODEL_NAME value: "deepseek-v3.2" - name: MODEL_PROVIDER value: "custom" - name: TDAI_GATEWAY_PORT value: "8420" - name: TDAI_GATEWAY_HOST value: "0.0.0.0" volumeMounts: - name: hermes-data mountPath: /opt/data resources: requests: memory: "512Mi" cpu: "500m" limits: memory: "2Gi" cpu: "1000m" volumes: - name: hermes-data persistentVolumeClaim: claimName: hermes-data-pvc

4.2 Service配置

为了使Deployment中的Pod能够被集群内部或外部访问，需要配置Service：

apiVersion: v1 kind: Service metadata: name: tencentdb-agent-memory-service spec: selector: app: tencentdb-agent-memory ports: - port: 8420 targetPort: 8420 type: ClusterIP

如果需要从集群外部访问，可以将Service类型改为NodePort或LoadBalancer，并配置相应的端口映射。

5. 部署验证与故障排查

部署完成后，需要进行验证以确保服务正常运行，并掌握基本的故障排查方法。

5.1 部署验证

可以通过以下方法验证部署是否成功：

1. 检查Pod状态：

kubectl get pods

2. 验证Gateway健康状态：

kubectl exec -it <pod-name> -- curl -s http://localhost:8420/health | python3 -m json.tool

3. 进入Hermes对话：

kubectl exec -it <pod-name> -- hermes

5.2 故障排查

常见的故障排查方法包括：

1. 查看Gateway日志：

kubectl exec -it <pod-name> -- cat /opt/data/tdai-memory/gateway.log

2. 查看生成的Hermes配置：

kubectl exec -it <pod-name> -- cat /opt/data/config.yaml

3. 查看环境变量同步结果：

kubectl exec -it <pod-name> -- env | grep -E '(MODEL_|TDAI_LLM_)'

4. 进入容器调试：

kubectl exec -it <pod-name> -- bash

6. 总结与最佳实践建议

通过本文的介绍，我们了解了TencentDB Agent Memory的Docker容器化方案，并基于此构建了Kubernetes部署配置。以下是一些最佳实践建议：

1. 资源配置：根据实际使用情况调整CPU和内存资源限制，确保服务性能。
2. 数据备份：定期备份PersistentVolume中的数据，防止数据丢失。
3. 安全配置：使用Secret管理敏感信息如API Key，避免明文存储。
4. 监控配置：结合Prometheus和Grafana等工具，对服务进行监控，及时发现和解决问题。
5. 版本管理：定期更新镜像版本，获取最新功能和安全修复。

TencentDB Agent Memory的容器化部署使得在Kubernetes环境中管理和扩展AI Agent记忆系统变得更加简单高效，希望本文的最佳实践能帮助您顺利完成部署并充分利用其强大功能。

【免费下载链接】TencentDB-Agent-MemoryTencentDB Agent Memory is a team-level memory hub for AI Agents — turning conversations, docs, and code into four reusable memory assets (Chat Memory, Skill, LLM-Wiki, Code-Graph) that are governed, shared, and equipped across agents and frameworks.项目地址: https://gitcode.com/GitHub_Trending/te/TencentDB-Agent-Memory