feat(memory): 集成 Hy-Memory 长期记忆服务

README.md

@@ -497,7 +497,7 @@ This group helps you:
 Recommended first:
 
 - Session: [examples/session_service_with_in_memory](./examples/session_service_with_in_memory/README.md) / [examples/session_service_with_redis](./examples/session_service_with_redis/README.md) / [examples/session_service_with_sql](./examples/session_service_with_sql/README.md) / [examples/session_summarizer](./examples/session_summarizer/README.md) / [examples/session_state](./examples/session_state/README.md)
-- Memory: [examples/memory_service_with_in_memory](./examples/memory_service_with_in_memory/README.md) / [examples/memory_service_with_redis](./examples/memory_service_with_redis/README.md) / [examples/memory_service_with_sql](./examples/memory_service_with_sql/README.md) / [examples/memory_service_with_mem0](./examples/memory_service_with_mem0/README.md) / [examples/memory_service_with_mempalace](./examples/memory_service_with_mempalace/README.md)
+- Memory: [examples/memory_service_with_in_memory](./examples/memory_service_with_in_memory/README.md) / [examples/memory_service_with_redis](./examples/memory_service_with_redis/README.md) / [examples/memory_service_with_sql](./examples/memory_service_with_sql/README.md) / [examples/memory_service_with_mem0](./examples/memory_service_with_mem0/README.md) / [examples/memory_service_with_mempalace](./examples/memory_service_with_mempalace/README.md) / [examples/memory_service_with_hy_memory](./examples/memory_service_with_hy_memory/README.md)
 - Knowledge: [examples/knowledge_with_documentloader](./examples/knowledge_with_documentloader/README.md) / [examples/knowledge_with_vectorstore](./examples/knowledge_with_vectorstore/README.md) / [examples/knowledge_with_rag_agent](./examples/knowledge_with_rag_agent/README.md) / [examples/knowledge_with_searchtool_rag_agent](./examples/knowledge_with_searchtool_rag_agent/README.md) / [examples/knowledge_with_prompt_template](./examples/knowledge_with_prompt_template/README.md) / [examples/knowledge_with_custom_components](./examples/knowledge_with_custom_components/README.md)
 
 Related docs:

docs/mkdocs/en/memory.md

@@ -30,6 +30,7 @@ Based on the implementation in [trpc_agent_sdk/memory/](../../../trpc_agent_sdk/
 - **SqlMemoryService**: Stored in the `mem_events` table in MySQL/PostgreSQL
 - **MempalaceMemoryService**: Stored as MemPalace drawers in a local ChromaDB-backed palace
 - **TencentDBMemoryService**: Sent to TencentDB Agent Memory as L0 conversations and asynchronously extracted memories
+- **HyMemoryService**: Uses the Hy-Memory SDK for Chat, Working, and Coding memory
 
 **Code Example**:
 ```python
@@ -167,6 +168,108 @@ _session_events = {
 
 ---
 
+## HyMemoryService
+
+`HyMemoryService` adapts the
+[Hy-Memory](https://github.com/Tencent-Hunyuan/Hy-Memory) SDK to the framework
+`MemoryService` interface. The Runner incrementally stores new Events after
+each turn, while `load_memory` and `preload_memory` continue to recall through
+the common `search_memory()` interface.
+
+Install the optional dependency:
+
+```bash
+pip install "trpc-agent-py[hy-memory]"
+```
+
+By default, Hy-Memory reads its LLM, embedding, and storage configuration from
+environment variables:
+
+```bash
+MEMORY_MODE=pro
+MEMORY_LLM_MODEL=your-memory-model
+MEMORY_LLM_API_KEY=your-memory-model-api-key
+MEMORY_LLM_BASE_URL=https://your-memory-model-endpoint/v1
+MEMORY_EMBEDDER_MODEL=your-embedding-model
+MEMORY_EMBEDDER_API_KEY=your-embedding-api-key
+MEMORY_EMBEDDER_BASE_URL=https://your-embedding-endpoint/v1
+MEMORY_EMBEDDING_DIMS=1024
+```
+
+Create the service:
+
+```python
+from trpc_agent_sdk.memory import HyMemoryService
+from trpc_agent_sdk.memory import HyMemoryServiceConfig
+
+memory_service = HyMemoryService(
+    HyMemoryServiceConfig(
+        enabled=True,
+        mode="pro",
+        scene="chat",
+        source="my-agent",
+    )
+)
+
+runner = Runner(
+    app_name="my_app",
+    agent=agent,
+    session_service=session_service,
+    memory_service=memory_service,
+)
+```
+
+`scene` defaults to `chat`, matching the default `search_mode="default"` and
+avoiding an additional routing decision for general conversational memory.
+Automatic write classification is enabled only when `scene=None` is set
+explicitly. In that case, also use `search_mode="agentic"` so recall follows
+the same automatic routing strategy.
+
+Three scenes are supported:
+
+- `chat`: User preferences, profiles, and general cross-session memory.
+- `working`: Facts and reusable experiences from documents, research, office
+  tasks, and other productivity workflows.
+- `coding`: Coding, debugging, testing, and build tasks, optionally with
+  version-evolution context.
+- `None`: Hy-Memory classifies writes containing tool traces; plain text uses
+  the Chat pipeline directly. Set `search_mode="agentic"` to classify the
+  scene during recall as well; a single query with the default
+  `search_mode="default"` searches Chat memory only.
+
+Working and Coding writes require tool-call traces. The adapter preserves
+framework `FunctionCall` and `FunctionResponse` Events as OpenAI-format
+`tool_calls` and `role="tool"` messages. Hy-Memory falls back to Chat when no
+tool trace is present.
+
+You can also set `scene`, `workspace_id`, and `branch` per request:
+
+```python
+from trpc_agent_sdk.context import AgentContext
+from trpc_agent_sdk.memory import set_hy_memory_options
+
+agent_context = AgentContext()
+set_hy_memory_options(
+    agent_context,
+    {
+        "scene": "coding",
+        "workspace_id": "github.com/example/service",
+        "branch": "fix/timeout",
+    },
+)
+```
+
+Use the same `scene`, `workspace_id`, and `branch` for writes and searches.
+`branch` is effective only when `workspace_id` is set. Framework TTL does not
+delete Hy-Memory data; configure retention in Hy-Memory itself.
+
+See the complete
+[Hy-Memory example](../../../examples/memory_service_with_hy_memory/README.md)
+and the
+[Hy-Memory usage guide](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/docs/usage.md).
+
+---
+
 ## MemoryService Implementations
 
 trpc-agent provides multiple `MemoryService` implementations, allowing you to choose the appropriate storage backend based on your scenario:

docs/mkdocs/zh/memory.md

@@ -29,6 +29,7 @@
 - **RedisMemoryService**：存储在 Redis List 中（JSON 格式）
 - **SqlMemoryService**：存储在 MySQL/PostgreSQL 的 `mem_events` 表中
 - **TencentDBMemoryService**：写入 TencentDB Agent Memory L0 对话，并由服务端异步提取长期记忆
+- **HyMemoryService**：通过 Hy-Memory SDK 提供 Chat、Working 和 Coding 三类记忆
 
 **代码示例**：
 ```python
@@ -164,6 +165,101 @@ _session_events = {
 
 ---
 
+## HyMemoryService
+
+`HyMemoryService` 将
+[Hy-Memory](https://github.com/Tencent-Hunyuan/Hy-Memory) SDK 适配到
+框架的 `MemoryService` 接口。Runner 每轮结束后自动增量写入新 Event；
+`load_memory` 和 `preload_memory` 仍通过统一的 `search_memory()` 接口召回。
+
+安装可选依赖：
+
+```bash
+pip install "trpc-agent-py[hy-memory]"
+```
+
+Hy-Memory 默认从环境变量读取 LLM、Embedding 和存储配置：
+
+```bash
+MEMORY_MODE=pro
+MEMORY_LLM_MODEL=your-memory-model
+MEMORY_LLM_API_KEY=your-memory-model-api-key
+MEMORY_LLM_BASE_URL=https://your-memory-model-endpoint/v1
+MEMORY_EMBEDDER_MODEL=your-embedding-model
+MEMORY_EMBEDDER_API_KEY=your-embedding-api-key
+MEMORY_EMBEDDER_BASE_URL=https://your-embedding-endpoint/v1
+MEMORY_EMBEDDING_DIMS=1024
+```
+
+创建服务：
+
+```python
+from trpc_agent_sdk.memory import HyMemoryService
+from trpc_agent_sdk.memory import HyMemoryServiceConfig
+
+memory_service = HyMemoryService(
+    HyMemoryServiceConfig(
+        enabled=True,
+        mode="pro",
+        scene="chat",
+        source="my-agent",
+    )
+)
+
+runner = Runner(
+    app_name="my_app",
+    agent=agent,
+    session_service=session_service,
+    memory_service=memory_service,
+)
+```
+
+`scene` 默认为 `chat`，与默认的 `search_mode="default"` 保持一致，适合无需
+额外路由判断的通用对话记忆。只有显式设置 `scene=None` 时，才会启用
+Hy-Memory 自动写入分类；此时建议同时设置 `search_mode="agentic"`，确保检索
+使用相同的自动路由策略。
+
+支持三种 Scene：
+
+- `chat`：用户偏好、画像和一般跨会话记忆。
+- `working`：文档、研究、办公和其他生产力任务的事实与经验。
+- `coding`：编码、调试、测试和构建任务，并可维护版本演进上下文。
+- `None`：写入包含工具轨迹时由 Hy-Memory 判断 Scene；普通文本直接走 Chat。
+  自动判断检索 Scene 时还需设置 `search_mode="agentic"`；默认
+  `search_mode="default"` 的单查询固定检索 Chat。
+
+Working/Coding 写入需要工具调用轨迹。适配器会将框架 Event 中的
+`FunctionCall`、`FunctionResponse` 保留为 OpenAI 格式的 `tool_calls` 和
+`role="tool"` 消息。没有工具轨迹时，Hy-Memory 会回退到 Chat 链路。
+
+`scene`、`workspace_id` 和 `branch` 也可以按请求设置：
+
+```python
+from trpc_agent_sdk.context import AgentContext
+from trpc_agent_sdk.memory import set_hy_memory_options
+
+agent_context = AgentContext()
+set_hy_memory_options(
+    agent_context,
+    {
+        "scene": "coding",
+        "workspace_id": "github.com/example/service",
+        "branch": "fix/timeout",
+    },
+)
+```
+
+写入和检索应使用相同的 `scene`、`workspace_id` 和 `branch`。`branch` 只有在
+设置了 `workspace_id` 时生效。框架 TTL 不会自动删除 Hy-Memory 数据，保留策略
+应在 Hy-Memory 中配置。
+
+完整示例：
+[examples/memory_service_with_hy_memory](../../../examples/memory_service_with_hy_memory/README.md)。
+更多 SDK 配置参见
+[Hy-Memory 使用指南](https://github.com/Tencent-Hunyuan/Hy-Memory/blob/main/docs/usage.md)。
+
+---
+
 ## 基本 MemoryService 实现
 
 trpc-agent 内置提供了三种 `MemoryService` 实现，方便根据场景选择合适的存储后端：

examples/memory_service_with_hy_memory/.env.example

@@ -0,0 +1,30 @@
+# Agent model
+TRPC_AGENT_API_KEY=your-agent-model-api-key
+TRPC_AGENT_BASE_URL=https://your-agent-model-endpoint/v1
+TRPC_AGENT_MODEL_NAME=your-agent-model
+
+# Hy-Memory extraction model (OpenAI-compatible)
+MEMORY_MODE=pro
+# Reuse the Agent model. Replace these values when Memory uses another model.
+MEMORY_LLM_API_KEY=${TRPC_AGENT_API_KEY}
+MEMORY_LLM_BASE_URL=${TRPC_AGENT_BASE_URL}
+MEMORY_LLM_MODEL=${TRPC_AGENT_MODEL_NAME}
+
+# Custom remote BGE-M3 embedding service
+BGE_M3_EMBEDDING_ENDPOINT=http://aigc_component.woa.com/embeddings/bge/embeddings/batch
+X_CLIENT_SSID=your-client-ssid
+X_HOST_KEY_ACCESS=your-host-key-access
+MEMORY_EMBEDDING_DIMS=1024
+# Optional request controls:
+# BGE_M3_MAX_RETRIES=2
+# BGE_M3_RETRY_DELAY=2
+# BGE_M3_TIMEOUT=60
+
+# Adapter routing. Use chat for this example.
+HY_MEMORY_SCENE=chat
+# Leave unset to generate a fresh user on each run. Set a fixed value to test
+# persistence across separate process runs.
+# HY_MEMORY_DEMO_USER_ID=demo-user
+# Required only for working/coding isolation:
+# HY_MEMORY_WORKSPACE_ID=github.com/example/service
+# HY_MEMORY_BRANCH=main