Feat/tencent db

.github/workflows/release.yml

@@ -26,7 +26,7 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           pip install -r requirements-test.txt
-          pip install build twine flake8 yapf
+          python -m pip install --upgrade build "twine>=7.0.0" flake8 yapf
 
       - name: Validate tag version
         run: |

docs/mkdocs/en/memory.md

@@ -29,6 +29,7 @@ Based on the implementation in [trpc_agent_sdk/memory/](../../../trpc_agent_sdk/
 - **RedisMemoryService**: Stored in a Redis List (JSON format)
 - **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
 
 **Code Example**:
 ```python
@@ -55,7 +56,7 @@ async def store_session(self, session: Session, agent_context: Optional[AgentCon
 
 **Function**: Searches for related historical memories based on query keywords.
 
-**Search Method**: Built-in InMemory/Redis/SQL services use **keyword matching**; semantic memory services such as MemPalace and Mem0 use vector / semantic retrieval.
+**Search Method**: Built-in InMemory/Redis/SQL services use **keyword matching**; semantic memory services such as TencentDB Agent Memory, MemPalace, and Mem0 use extracted or vector / semantic retrieval.
 
 **Implementation Logic** (using `InMemoryMemoryService` as an example):
 ```python
@@ -587,6 +588,60 @@ python3 run_agent.py
 
 ---
 
+## Integrating TencentDB Agent Memory
+
+`TencentDBMemoryService` connects the framework to a
+[TencentDB Agent Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
+V3 gateway. After each completed turn, the framework incrementally sends new
+text events to `/v3/conversation/add`. An Agent equipped with
+`load_memory_tool` searches extracted L1 atomic memories through
+`/v3/atomic/search`.
+
+```python
+from trpc_agent_sdk.memory.tencentdb_memory_service import (
+    TencentDBMemoryService,
+    TencentDBMemoryServiceConfig,
+)
+from trpc_agent_sdk.tools import load_memory_tool
+
+memory_service = TencentDBMemoryService(
+    TencentDBMemoryServiceConfig(
+        enabled=True,
+        endpoint="http://127.0.0.1:8420",
+        api_key="local",
+        service_id="memory-service-id",
+        team_id="team-id",
+        agent_id="assistant-id",
+    )
+)
+
+# Add load_memory_tool to LlmAgent.tools and pass memory_service to Runner.
+```
+
+Isolation is mapped as follows:
+
+- `service_id` is sent in the `x-tdai-service-id` header.
+- `team_id` and `agent_id` come from the service configuration.
+- `user_id` comes from the framework session/search key.
+- `session_id` is sent only when writing L0 conversations; searches omit it
+  to support cross-session recall for the same user.
+
+Operational notes:
+
+- L1 extraction is asynchronous, so a memory may not be searchable immediately
+  after a successful write.
+- Successfully accepted event IDs are checkpointed in process. Delivery is
+  at-least-once across restarts.
+- TencentDB Agent Memory controls retention; framework TTL settings do not
+  apply to this service.
+- Deploy the V3 gateway and extraction pipeline before using the integration.
+
+See the
+[complete runnable example](../../../examples/memory_service_with_tencentdb/README.md)
+for environment variables and a cross-session demonstration.
+
+---
+
 ## Integrating Mem0
 
 ### What is Mem0?

docs/mkdocs/zh/memory.md

@@ -28,6 +28,7 @@
 - **InMemoryMemoryService**：存储在进程内存的字典中
 - **RedisMemoryService**：存储在 Redis List 中（JSON 格式）
 - **SqlMemoryService**：存储在 MySQL/PostgreSQL 的 `mem_events` 表中
+- **TencentDBMemoryService**：写入 TencentDB Agent Memory L0 对话，并由服务端异步提取长期记忆
 
 **代码示例**：
 ```python
@@ -54,7 +55,7 @@ async def store_session(self, session: Session, agent_context: Optional[AgentCon
 
 **功能**：根据查询关键词搜索相关的历史记忆。
 
-**搜索方式**：**关键词匹配**（非语义搜索）
+**搜索方式**：InMemory/Redis/SQL 使用**关键词匹配**；TencentDB Agent Memory 等扩展服务可提供记忆提取或语义检索。
 
 **实现逻辑**（以 `InMemoryMemoryService` 为例）：
 ```python
@@ -541,6 +542,54 @@ python3 run_agent.py
 
 ## 扩展 MemoryService 实现
 
+### 集成 TencentDB Agent Memory
+
+`TencentDBMemoryService` 用于对接
+[TencentDB Agent Memory](https://github.com/TencentCloud/TencentDB-Agent-Memory)
+V3 网关。每轮对话结束后，框架会将新增文本事件增量写入
+`/v3/conversation/add`；配置了 `load_memory_tool` 的 Agent 会通过
+`/v3/atomic/search` 检索异步提取出的 L1 原子记忆。
+
+```python
+from trpc_agent_sdk.memory.tencentdb_memory_service import (
+    TencentDBMemoryService,
+    TencentDBMemoryServiceConfig,
+)
+from trpc_agent_sdk.tools import load_memory_tool
+
+memory_service = TencentDBMemoryService(
+    TencentDBMemoryServiceConfig(
+        enabled=True,
+        endpoint="http://127.0.0.1:8420",
+        api_key="local",
+        service_id="memory-service-id",
+        team_id="team-id",
+        agent_id="assistant-id",
+    )
+)
+
+# 将 load_memory_tool 加入 LlmAgent.tools，并把 memory_service 传给 Runner。
+```
+
+隔离字段映射如下：
+
+- `service_id` 通过 `x-tdai-service-id` 请求头传递。
+- `team_id` 和 `agent_id` 来自服务配置。
+- `user_id` 来自框架 Session 或搜索 key。
+- `session_id` 仅在写入 L0 对话时传递；搜索时不传，以支持同一用户跨会话召回。
+
+使用时需要注意：
+
+- L1 记忆提取是异步的，写入成功后不保证立即可以搜索到。
+- 进程内会记录已成功写入的事件 ID；进程重启后采用至少一次投递语义。
+- 记忆保留策略由 TencentDB Agent Memory 管理，框架 TTL 配置不适用于该服务。
+- 使用前需要部署 V3 网关和记忆提取流水线。
+
+环境变量和跨会话运行流程见
+[完整示例](../../../examples/memory_service_with_tencentdb/README.md)。
+
+---
+
 ### 集成 Mempalace
 
 #### 什么是 Mempalace？

examples/memory_service_with_tencentdb/.env

@@ -0,0 +1,15 @@
+# LLM configuration
+TRPC_AGENT_API_KEY=your-llm-api-key
+TRPC_AGENT_BASE_URL=https://your-llm-endpoint
+TRPC_AGENT_MODEL_NAME=your-model-name
+
+# TencentDB Agent Memory V3 gateway
+TENCENTDB_MEMORY_ENDPOINT=http://127.0.0.1:8420
+TENCENTDB_MEMORY_API_KEY=local
+TENCENTDB_MEMORY_SERVICE_ID=your-memory-service-id
+TENCENTDB_MEMORY_TEAM_ID=your-team-id
+TENCENTDB_MEMORY_AGENT_ID=weather-assistant
+
+# L1 extraction is asynchronous. Increase this for slower deployments.
+TENCENTDB_MEMORY_PIPELINE_WAIT_SECONDS=5
+MEMORY_PROMPT_MODE=chat

examples/memory_service_with_tencentdb/.env.local

@@ -0,0 +1,15 @@
+# LLM configuration
+TRPC_AGENT_API_KEY=your-llm-api-key
+TRPC_AGENT_BASE_URL=https://your-llm-endpoint
+TRPC_AGENT_MODEL_NAME=your-model-name
+
+# TencentDB Agent Memory V3 gateway
+TENCENTDB_MEMORY_ENDPOINT=http://127.0.0.1:8420
+TENCENTDB_MEMORY_API_KEY=local
+TENCENTDB_MEMORY_SERVICE_ID=your-memory-service-id
+TENCENTDB_MEMORY_TEAM_ID=your-team-id
+TENCENTDB_MEMORY_AGENT_ID=weather-assistant
+
+# L1 extraction is asynchronous. Increase this for slower deployments.
+TENCENTDB_MEMORY_PIPELINE_WAIT_SECONDS=5
+MEMORY_PROMPT_MODE=chat

examples/memory_service_with_tencentdb/.env.remote

@@ -0,0 +1,19 @@
+# 示例 Agent 使用的 LLM，与 Memory 实例凭证无关
+TRPC_AGENT_API_KEY=sk-******************
+TRPC_AGENT_BASE_URL=http://******************
+TRPC_AGENT_MODEL_NAME=******************
+
+# 腾讯云控制台提供的完整 Gateway 地址，必须包含 https://
+TENCENTDB_MEMORY_ENDPOINT=https://******************
+
+# 腾讯云控制台提供的 Gateway API Key，不是 sk-mem-* User Key
+TENCENTDB_MEMORY_API_KEY=******************
+
+# 腾讯云 Memory 实例 ID，例如 mem-xxxxxxxx
+TENCENTDB_MEMORY_SERVICE_ID=mem-*******
+
+# 在该实例中创建的真实 Team 和 Agent ID
+TENCENTDB_MEMORY_TEAM_ID=team-*******
+TENCENTDB_MEMORY_AGENT_ID=agt-*******
+
+TENCENTDB_MEMORY_PIPELINE_WAIT_SECONDS=15