查询记忆

查询会话记忆

会话记忆用于召回当前 Session 里的对话 Message，以及由这些 Message 形成的 Facts、Summary 和 Topic。session_id 必须是已创建的 Session，用户身份以 Session 绑定的用户为准。

调用方式

Node

const memory = await session.getMemory({
  query: "which city should be used for Europe or Americas team scheduling"
});

Python

memory = session.get_memory(
    query="which city should be used for Europe or Americas team scheduling",
)

bash

curl -G "http://localhost:8000/api/sessions/session_xxx/context" \
  -H "Authorization: Api-Key your_api_key" \
  --data-urlencode "query=which city should be used for Europe or Americas team scheduling" \
  --data-urlencode "details=false"

返回内容

常见返回字段包括：

字段	说明
project_id	当前 Memory 查询所属的 Project ID。
user_id	当前 Session 绑定的用户 ID。
session_id	当前查询对应的 Session ID。
history	当前 Session 中返回的 Message 列表。
facts	与 query 相关的 Facts。
summary	当前 Session 或用户上下文中可用于本次召回的 Summary。
formatted_context	服务端整理后的最终上下文，适合直接放入 Agent prompt。

如果开启 details，返回结果可能包含更细的来源信息，例如命中的 Message、Facts、Summary 和得分。调试召回时再使用这些字段；正常接入优先使用 formatted_context。

RecallConfig

如果需要调整会话记忆召回范围，可以传入 recall config。

Node

const memory = await session.getMemory({
  query: "which city should be used for Europe or Americas team scheduling",
  details: true,
  recallConfig: {
    MessageRecentLimit: 20,
    MetadataFilters: {
      ping: "pong"
    }
  }
});

Python

memory = session.get_memory(
    query="which city should be used for Europe or Americas team scheduling",
    details=True,
    recall_config={
        "MessageRecentLimit": 20,
        "MetadataFilters": {
            "ping": "pong",
        },
    },
)

bash

curl -X POST "http://localhost:8000/api/sessions/session_xxx/context?query=which city should be used for Europe or Americas team scheduling&details=true" \
  -H "Authorization: Api-Key your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "recall_config": {
      "MessageRecentLimit": 20,
      "MetadataFilters": {
        "ping": "pong"
      }
    }
  }'

参数	公开含义	说明
MessageRecentLimit	近期 Message 数量	控制返回多少条最近 Message。
MetadataFilters	metadata 精确过滤	简单的 metadata KV 字典，用于缩小召回范围。

MetadataFilters 的 key 必须是非空字符串，value 必须是字符串、数字或布尔值。GUMem 会在 Project、用户和 Session 范围内应用这些精确匹配条件。

查询行为记忆

行为记忆用于召回通过 User Actions 或行为 Message 写入的搜索、筛选、点击、收藏、工具调用和业务事件。公开查询入口仍是 Session Memory recall；调用方通过 query 描述当前任务，并用 metadata 过滤需要的行为范围。

调用方式

curl -sS -X POST \
  "https://gumem.asix.inc/api/user/actions/profile/recall" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "YOUR_USER_ID",
    "query": "any query",
    "recall_config": {
      "topk": 10,
      "metadata_filters": {
        "workspace": "docs",
        "ping": "pong"
      }
    }
  }'

返回内容

行为记忆返回的上下文结构与会话记忆一致。区别在于命中的内容通常来自行为 Message 或由行为 Message 抽取出的 Facts、Summary 和 Topic。

字段	说明
short_term_context	当前 Session 中最近或最直接相关的行为 Message。
mid_term_context	与行为 query 相关的 Facts，例如页面访问、筛选、收藏或工具调用结果。
long_term_user_context	从跨 Session 行为中沉淀出的长期用户 Summary。
long_term_session_context	当前 Session 内由行为信号形成的 Summary。
formatted_context	服务端整理后的最终上下文，适合直接放入 Agent prompt。

如果开启 details，返回结果可能包含命中来源、metadata、Facts、Summary 和得分。具体字段以部署版本的 GUMem API 为准。

RecallConfig

行为记忆的召回参数放在 recall_config 中。常用字段是 topk 和 metadata_filters：topk 控制返回数量，metadata_filters 用于缩小行为范围，例如只召回某个 workspace、事件来源、业务对象或埋点标签下的记忆。

参数	公开含义	说明
topk	返回数量	控制最多返回多少条行为记忆。
metadata_filters	metadata 精确过滤	简单的 metadata KV 字典，用于精确过滤行为记忆。

metadata_filters 是简单 KV 字典，例如 { "workspace": "docs", "ping": "pong" }。它只做精确匹配，不表达嵌套查询、范围查询或复杂布尔条件。

查询顺序

长期记忆召回按以下顺序工作：

Topic -> Summary -> Facts -> Message

1. GUMem 根据 query 判断是否需要长期记忆。
2. 如果需要，先召回相关 Topic。
3. 在相关 Topic 下召回 Summary。
4. 如果 Summary 不足，继续补充支撑它的 Facts。
5. 结合当前 Session 的近期 Message，生成最终上下文。

这套顺序让 Agent 不必读取全部历史。Topic 负责缩小范围，Summary 负责提供可直接使用的长期上下文，Facts 负责解释来源和补充证据。

调试召回结果

如果结果不符合预期，优先检查：

• query 是否足够具体。
• 相关 Message 是否已经写入。
• 长期写入是否已经完成 Summary 和 Topic 生成。
• metadata_filters 是否把相关 Memory 过滤掉。
• Session 是否绑定到正确用户。

如果返回为空，Agent 不应假装知道用户偏好。更好的处理方式是向用户询问缺失信息，并在确认后把新的 Message 写回 GUMem。

下一步

阅读 更新记忆 了解用户更正信息时应如何处理。