[pull] main from agentscope-ai:main

CONTRIBUTING.md

@@ -266,7 +266,7 @@ The memory module in AgentScope currently supports:
 
 - **In-memory storage**: For lightweight, temporary memory needs
 - **Relational databases via SQLAlchemy**: For persistent, structured data storage
-- **NoSQL databases**: For flexible schema requirements (e.g., Redis)
+- **NoSQL databases**: For flexible schema requirements (e.g., Redis, Tablestore)
 
 **⚠️ Important Notice:**
 

CONTRIBUTING_zh.md

@@ -261,7 +261,7 @@ AgentScope 的记忆模块目前支持：
 
 - **内存存储**：用于轻量级的临时记忆需求
 - **通过 SQLAlchemy 支持关系型数据库**：用于持久化的结构化数据存储
-- **NoSQL 数据库**：用于灵活的模式需求（例如 Redis）
+- **NoSQL 数据库**：用于灵活的模式需求（例如 Redis、表格存储）
 
 **⚠️ 请注意：**
 

docs/tutorial/en/src/task_memory.py

@@ -37,6 +37,8 @@
       - An asynchronous SQLAlchemy-based implementation of memory storage, which supports various databases such as SQLite, PostgreSQL, MySQL, etc.
     * - ``RedisMemory``
       - A Redis-based implementation of memory storage.
+    * - ``TablestoreMemory``
+      - An Alibaba Cloud Tablestore-based implementation of memory storage, enabling persistent and searchable memory across distributed environments.
 
 .. tip:: If you're interested in contributing new memory storage implementations, please refer to the
  `Contribution Guide <https://github.com/agentscope-ai/agentscope/blob/main/CONTRIBUTING.md#types-of-contributions>`_.
@@ -410,6 +412,122 @@ async def redis_memory_example() -> None:
 #         await client.aclose()
 #
 #
+# Tablestore Memory
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# AgentScope also provides a memory implementation based on
+# `Alibaba Cloud Tablestore <https://www.alibabacloud.com/product/tablestore>`_,
+# a fully managed NoSQL database service. ``TablestoreMemory`` enables
+# persistent and searchable memory across distributed environments, with
+# built-in support for multi-user and multi-session isolation.
+#
+# First, install the required packages:
+#
+# .. code-block:: bash
+#
+#     pip install tablestore tablestore-for-agent-memory
+#
+# Then, you can initialize the Tablestore memory as follows:
+#
+# .. code-block:: python
+#    :caption: Tablestore Memory Basic Usage
+#
+#     import asyncio
+#     from agentscope.memory import TablestoreMemory
+#     from agentscope.message import Msg
+#
+#
+#     async def tablestore_memory_example():
+#         # Create the Tablestore memory
+#         memory = TablestoreMemory(
+#             end_point="https://your-instance.cn-hangzhou.ots.aliyuncs.com",
+#             instance_name="your-instance-name",
+#             access_key_id="your-access-key-id",
+#             access_key_secret="your-access-key-secret",
+#             # Optionally specify user_id and session_id
+#             user_id="user_1",
+#             session_id="session_1",
+#         )
+#
+#         # Add a message to the memory
+#         await memory.add(
+#             Msg("Alice", "Generate a report about AgentScope", "user"),
+#         )
+#
+#         # Add a hint message with the mark "hint"
+#         await memory.add(
+#             Msg(
+#                 "system",
+#                 "<system-hint>Create a plan first to collect information and "
+#                 "generate the report step by step.</system-hint>",
+#                 "system",
+#             ),
+#             marks="hint",
+#         )
+#
+#         # Retrieve messages with the mark "hint"
+#         msgs = await memory.get_memory(mark="hint")
+#         for msg in msgs:
+#             print(f"- {msg}")
+#
+#         # Close the Tablestore client connection when done
+#         await memory.close()
+#
+#
+#     asyncio.run(tablestore_memory_example())
+#
+# The ``TablestoreMemory`` can also be used as an async context manager:
+#
+# .. code-block:: python
+#    :caption: Tablestore Memory as Async Context Manager
+#
+#     async with TablestoreMemory(
+#         end_point="https://your-instance.cn-hangzhou.ots.aliyuncs.com",
+#         instance_name="your-instance-name",
+#         access_key_id="your-access-key-id",
+#         access_key_secret="your-access-key-secret",
+#         user_id="user_1",
+#         session_id="session_1",
+#     ) as memory:
+#         await memory.add(
+#             Msg("Alice", "Generate a report about AgentScope", "user"),
+#         )
+#
+#         msgs = await memory.get_memory()
+#         for msg in msgs:
+#             print(f"- {msg}")
+#
+# Similarly, ``TablestoreMemory`` can be used in production environments with FastAPI:
+#
+# .. code-block:: python
+#    :caption: Tablestore Memory in FastAPI
+#
+#     import os
+#     from fastapi import FastAPI
+#     from agentscope.memory import TablestoreMemory
+#     from agentscope.message import Msg
+#
+#
+#     app = FastAPI()
+#
+#
+#     @app.post("/chat_endpoint")
+#     async def chat_endpoint(user_id: str, session_id: str, input: str):
+#         """A chat endpoint using Tablestore memory."""
+#         memory = TablestoreMemory(
+#             end_point=os.environ["TABLESTORE_ENDPOINT"],
+#             instance_name=os.environ["TABLESTORE_INSTANCE_NAME"],
+#             access_key_id=os.environ["TABLESTORE_ACCESS_KEY_ID"],
+#             access_key_secret=os.environ["TABLESTORE_ACCESS_KEY_SECRET"],
+#             user_id=user_id,
+#             session_id=session_id,
+#         )
+#
+#         # Use the memory with your agent
+#         ...
+#
+#         # Close the Tablestore client connection when done
+#         await memory.close()
+#
 #
 # Customizing Memory
 # ~~~~~~~~~~~~~~~~~~~~~~~~

docs/tutorial/zh_CN/src/task_memory.py

@@ -29,6 +29,8 @@
       - 基于异步 SQLAlchemy 的记忆存储实现，支持如 SQLite、PostgreSQL、MySQL 等多种关系数据库。
     * - ``RedisMemory``
       - 基于 Redis 的记忆存储实现。
+    * - ``TablestoreMemory``
+      - 基于阿里云表格存储（Tablestore）的记忆存储实现，支持分布式环境下的持久化和可搜索记忆。
 
 .. tip:: 如果您有兴趣贡献新的记忆存储实现，请参考 `贡献指南 <https://github.com/agentscope-ai/agentscope/blob/main/CONTRIBUTING.md#types-of-contributions>`_。
 
@@ -397,6 +399,121 @@ async def redis_memory_example() -> None:
 #         await client.aclose()
 #
 #
+# 表格存储记忆（Tablestore Memory）
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# AgentScope 还提供了基于
+# `阿里云表格存储（Tablestore） <https://www.aliyun.com/product/ots>`_
+# 的记忆实现。``TablestoreMemory`` 支持分布式环境下的持久化和可搜索记忆，
+# 并内置多用户和多会话隔离。
+#
+# 首先，安装所需的依赖包：
+#
+# .. code-block:: bash
+#
+#     pip install tablestore tablestore-for-agent-memory
+#
+# 然后，可以按如下方式初始化 Tablestore 记忆：
+#
+# .. code-block:: python
+#    :caption: Tablestore 记忆基本用法
+#
+#     import asyncio
+#     from agentscope.memory import TablestoreMemory
+#     from agentscope.message import Msg
+#
+#
+#     async def tablestore_memory_example():
+#         # 创建 Tablestore 记忆
+#         memory = TablestoreMemory(
+#             end_point="https://your-instance.cn-hangzhou.ots.aliyuncs.com",
+#             instance_name="your-instance-name",
+#             access_key_id="your-access-key-id",
+#             access_key_secret="your-access-key-secret",
+#             # 可选地指定 user_id 和 session_id
+#             user_id="user_1",
+#             session_id="session_1",
+#         )
+#
+#         # 向记忆中添加消息
+#         await memory.add(
+#             Msg("Alice", "生成一份关于AgentScope的报告", "user"),
+#         )
+#
+#         # 添加一条带有标记"hint"的提示消息
+#         await memory.add(
+#             Msg(
+#                 "system",
+#                 "<system-hint>首先创建一个计划来收集信息，"
+#                 "然后逐步生成报告。</system-hint>",
+#                 "system",
+#             ),
+#             marks="hint",
+#         )
+#
+#         # 检索带有标记"hint"的消息
+#         msgs = await memory.get_memory(mark="hint")
+#         for msg in msgs:
+#             print(f"- {msg}")
+#
+#         # 完成后关闭 Tablestore 客户端连接
+#         await memory.close()
+#
+#
+#     asyncio.run(tablestore_memory_example())
+#
+# ``TablestoreMemory`` 也可以用作异步上下文管理器：
+#
+# .. code-block:: python
+#    :caption: Tablestore 记忆作为异步上下文管理器
+#
+#     async with TablestoreMemory(
+#         end_point="https://your-instance.cn-hangzhou.ots.aliyuncs.com",
+#         instance_name="your-instance-name",
+#         access_key_id="your-access-key-id",
+#         access_key_secret="your-access-key-secret",
+#         user_id="user_1",
+#         session_id="session_1",
+#     ) as memory:
+#         await memory.add(
+#             Msg("Alice", "生成一份关于AgentScope的报告", "user"),
+#         )
+#
+#         msgs = await memory.get_memory()
+#         for msg in msgs:
+#             print(f"- {msg}")
+#
+# 同样，``TablestoreMemory`` 也可以在生产环境中与 FastAPI 一起使用：
+#
+# .. code-block:: python
+#    :caption: FastAPI 中使用 Tablestore 记忆
+#
+#     import os
+#     from fastapi import FastAPI
+#     from agentscope.memory import TablestoreMemory
+#     from agentscope.message import Msg
+#
+#
+#     app = FastAPI()
+#
+#
+#     @app.post("/chat_endpoint")
+#     async def chat_endpoint(user_id: str, session_id: str, input: str):
+#         """使用 Tablestore 记忆的聊天端点。"""
+#         memory = TablestoreMemory(
+#             end_point=os.environ["TABLESTORE_ENDPOINT"],
+#             instance_name=os.environ["TABLESTORE_INSTANCE_NAME"],
+#             access_key_id=os.environ["TABLESTORE_ACCESS_KEY_ID"],
+#             access_key_secret=os.environ["TABLESTORE_ACCESS_KEY_SECRET"],
+#             user_id=user_id,
+#             session_id=session_id,
+#         )
+#
+#         # 使用记忆与智能体交互
+#         ...
+#
+#         # 完成后关闭 Tablestore 客户端连接
+#         await memory.close()
+#
 #
 # 自定义记忆（Customizing Memory）
 # ~~~~~~~~~~~~~~~~~~~~~~~~

pyproject.toml

@@ -73,6 +73,10 @@ tokens = [
 
 # ------------ Memory ------------
 redis_memory = ["redis"]
+tablestore_memory = [
+    "tablestore-for-agent-memory",
+    "tablestore",
+]
 
 mem0ai = [
     "mem0ai<=1.0.3",
@@ -83,6 +87,7 @@ memory = [
     "agentscope[redis_memory]",
     "agentscope[mem0ai]",
     "agentscope[reme]",
+    "agentscope[tablestore_memory]",
 ]
 
 # ------------ RAG ------------
@@ -171,6 +176,7 @@ dev = [
     # Development tools
     "pre-commit",
     "pytest",
+    "pytest-asyncio",
     "pytest-forked",
     "sphinx-gallery",
     "furo",

src/agentscope/memory/__init__.py

@@ -6,6 +6,7 @@
     InMemoryMemory,
     RedisMemory,
     AsyncSQLAlchemyMemory,
+    TablestoreMemory,
 )
 from ._long_term_memory import (
     LongTermMemoryBase,
@@ -22,6 +23,7 @@
     "InMemoryMemory",
     "RedisMemory",
     "AsyncSQLAlchemyMemory",
+    "TablestoreMemory",
     # Long-term memory
     "LongTermMemoryBase",
     "Mem0LongTermMemory",

src/agentscope/memory/_working_memory/__init__.py

@@ -7,10 +7,12 @@
 from ._in_memory_memory import InMemoryMemory
 from ._redis_memory import RedisMemory
 from ._sqlalchemy_memory import AsyncSQLAlchemyMemory
+from ._tablestore_memory import TablestoreMemory
 
 __all__ = [
     "MemoryBase",
     "InMemoryMemory",
     "RedisMemory",
     "AsyncSQLAlchemyMemory",
+    "TablestoreMemory",
 ]