W
AI-Wiki
CONCEPT

Agent Memory SDK

定义

Agent Memory SDK 是本文提出的一层轻量级存储抽象，放在业务应用与 Tablestore 之间，目的是把底层表结构设计、索引实现、检索方式与调用细节封装起来，让开发者用更统一、接近业务语义的接口完成 AI 场景接入。

它并不是新的 Agent 理论，也不是在重新定义 Memory 或 Knowledge 的概念，而是把已有的存储工程能力整理成 SDK、对象模型、接口与示例代码，降低业务开发复杂度，并提升 AI 场景下的使用体验。

在本文语境中的位置

在本文架构里，Agent Memory SDK 处于业务侧与 Tablestore 之间：

  • 对上，面向聊天、RAG、搜索、画像挖掘等业务逻辑，提供更直接的编程接口。
  • 对下，依托 Tablestore 实现记忆存储与知识检索，但把底层实现细节隐藏起来。
  • 对开发者而言，目标是不需要直接参与数据库接口调用、表设计与索引调优，也能快速写出可运行代码并产出结果。

原文明确强调，这一层的核心价值是“屏蔽下面的实现细节，专注于提升 AI 场景下的使用体验”。

设计目标

轻量化与开发者友好

SDK 的首要目标是轻量化设计，即以尽量少的接入成本提供通用存储能力。原文给出的几个关键词包括：

  • 开发者友好；
  • 抽象通用存储接口；
  • 降低业务开发复杂度；
  • 在技术深度与易用性之间做好平衡。

这里的“平衡”很关键：SDK 不是把底层能力全部暴露给业务方，也不是为了极致简单而牺牲场景能力，而是在可用性和技术深度之间取中间路线。开发者可以先用统一 API 快速接入，若有特殊业务，再参考底层设计进一步定制。

场景驱动

当前 SDK 主要支持两类场景：

  • Memory：面向实时记忆存储；
  • Knowledge：面向长期语义检索。

原文还指出，SDK 不只覆盖“把数据存进去”这一层，还会在场景上继续扩展，例如：

  • Summary 记录；
  • 事实数据提取；
  • 用户画像/标签挖掘。

这说明它不是一个纯粹的 KV 封装，而是希望逐步沉淀可直接用于业务的场景化方案。

业务价值验证

SDK 的另一个目标是帮助用户在不做复杂技术调研的前提下，快速复用成熟方案进行业务价值验证。原文强调，用户可以直接复用业界方案，而不必先完整掌握底层存储实现。

这也是它与单纯存储客户端 SDK 的差别：后者主要解决“能不能调用”，而 Agent Memory SDK 试图进一步解决“能不能快速做出业务验证”。

支持的两大核心场景

1. Memory：实时记忆存储

Memory 在本文中主要承担“回忆”角色，典型能力包括：

  • 情景记录；
  • 情景摘要；
  • 实时数据抽取；
  • 会话上下文管理；
  • 实时状态信息同步。

这一类场景的关键要求是毫秒级响应、高并发，以及对动态 Schema 扩展的支持。SDK 当前最典型的 Memory 用法是会话管理与历史消息存储。

Memory 的对象模型

在示例中，SDK 暴露的核心对象包括：

  • MemoryStore：Memory 场景的统一入口；
  • Session：一次会话；
  • Message：会话中的消息。

示例代码体现出的核心接口包括：

  • put_session：写入会话；
  • update_session：更新会话；
  • put_message：写入消息；
  • list_messages_paginated：分页列出消息。

Memory 示例中的具体使用方式

原文 Python 示例展示了一个典型聊天流程：

  1. 先创建 MemoryStore()；
  2. 创建 Session(user_id="1", session_id="session_id_1")；
  3. 给 session.update_time 赋值微秒级时间戳；
  4. 在 session.metadata 中写入 model_name = "qwen 2.5"；
  5. 调用 memory_store.put_session(session) 写入会话；
  6. 用户发消息时，创建 Message，设置 content 与 metadata["message_type"] = "用户"，然后 put_message；
  7. 用户消息写入后，同时更新 session.update_time 并执行 update_session(session)；
  8. 大模型回复时，再写入新的 Message，但 message_id 必须变化；
  9. 为了让模型理解“再来一个”的上下文，可以用 list_messages_paginated(session_id="session_id_1", page_size=3, metadata_filter=Filters.eq("message_type", "用户")) 查出最近 3 条符合条件的历史消息，再传给模型。

这里能看出 SDK 的一个重要特点：它把业务侧真正常用的实体和操作直接暴露出来，而不是要求开发者自己从底层表结构拼接查询。

Memory 场景的性能与边界

原文给出了比较具体的线上与理论指标：

  • 理论上的写入和查询 QPS 很容易支持到几百万甚至千万级别；
  • 受限于真实业务情况，线上最大查询和写入大约在十几万 QPS 量级；
  • 在单行较大的情况下，写入延时约 1~8ms；
  • 查询延时约 1~4ms；
  • 单 Memory 表最大规模可到 PB 级别；
  • 成本按实际用量计费；
  • 默认提供 3AZ（同城 3 可用区部署）容灾能力。

这些数字说明，SDK 面向的并不是玩具级本地记忆，而是可承载大规模线上会话和消息流量的工程场景。

2. Knowledge：长期语义检索

Knowledge 在本文中主要承担“知识”角色，核心是对知识内容原文、摘要等进行存储与检索，重点能力是语义检索，同时也兼顾规模、性能与成本。

典型业务包括：

  • 知识库 RAG；
  • 多模态搜索；
  • 文档检索；
  • AI 搜索中的召回层。

Knowledge 的对象模型

在示例中，Knowledge 场景暴露的核心对象包括：

  • KnowledgeStore：Knowledge 场景的统一入口；
  • Document：被写入、点查与检索的文档对象。

核心接口包括：

  • put_document：写入文档；
  • get_document：点查文档；
  • vector_search：向量搜索；
  • full_text_search：全文检索。

Knowledge 示例中的具体使用方式

原文示例中，开发者先创建 KnowledgeStore()，再声明一个 Document(document_id="1", tenant_id="user_id_1")，随后设置：

  • document.text = "你好，世界!"；
  • document.embedding = [1.0, 2.5, 3.5, 1.3]；
  • document.metadata["meta_string"] = "hi"；
  • document.metadata["meta_long"] = 123456。

之后可通过 knowledge_store.put_document(document) 写入，并使用 get_document(document_id="1", tenant_id="user_id_1") 做点查。