WebHooks

支持的触发对象

当前 Memory 处理链路中，WebHooks 主要围绕三类资源工作：

Resource	公开含义	典型用途
fact	Facts 处理	清洗或审核从 Message 中抽取的事实。
summary	Summary 处理	调整长期记忆摘要，或同步到用户画像系统。
topic	Topic 处理	审核主题聚合结果，或同步主题摘要。

支持的触发时机

Event	触发时机	是否影响主流程
before_add	写入前触发。	可以修改即将写入的数据。
before_llm	LLM 调用前触发。	只能追加 instruction。
after_llm	LLM 调用后触发。	用于审计和通知，不修改主流程结果。

不同资源支持的事件不同。Facts 支持 before_add、before_llm、after_llm；Summary 支持 before_llm、after_llm、before_add；Topic 支持 before_add。

典型使用场景

数据清洗

在 fact.before_add 阶段过滤或修正 Facts。适合处理敏感信息、格式不一致、字段缺失或业务侧需要统一的实体命名。

LLM 规则注入

在 fact.before_llm 或 summary.before_llm 阶段返回 instruction。GUMem 会把这段 instruction 追加到默认 user prompt 后面，用于补充业务规则、合规要求或质量标准。

before_llm 不允许替换完整 prompt，也不允许修改 system prompt。

审计与监控

在 after_llm 阶段接收 LLM 输出和解析结果，用于日志记录、告警、质量分析或人工审核。这个阶段不修改写入结果。

外部系统同步

在 summary.before_add 或 topic.before_add 阶段接收长期记忆和主题聚合结果。适合同步用户画像、CRM、推荐系统或审计流水。

Webhook 请求格式

GUMem 会向配置的 target_url 发送 POST 请求。

{
  "hook_id": "hook_xxx",
  "hook_name": "Fact quality checker",
  "project_id": "project_1",
  "resource": "fact",
  "event": "before_llm",
  "mode": "sync",
  "triggered_at": "2026-04-24T06:00:00Z",
  "context": {
    "user_id": "user_1",
    "thread_id": "thread_1",
    "message_ids": ["msg_1"]
  },
  "data": {
    "messages": []
  }
}

context 保存用户、线程、消息或 Summary ID 等处理上下文。data 保存当前阶段可见的数据，不同 resource 和 event 下结构不同。

返回格式

如果不需要修改数据，可以返回任意 2xx 响应。

{
  "ok": true
}

如果需要影响主流程，返回 data 对象。

{
  "data": {
    "...": "..."
  }
}

before_llm

before_llm 只能追加 instruction。

{
  "data": {
    "instruction": "Only extract explicitly supported facts. Ignore speculation."
  }
}

GUMem 会把这段 instruction 追加到默认 user prompt 后面。返回完整 prompt 或 system prompt 不会被采用。

before_add

before_add 可以调整即将写入的数据，但返回值必须能通过系统校验。

Facts 写入前可以返回：

{
  "data": {
    "observations": []
  }
}

Summary 写入前可以返回：

{
  "data": {
    "propositions": []
  }
}

Topic 写入前可以返回：

{
  "data": {
    "topics": []
  }
}

这些字段名是接口载荷的一部分。公开概念仍使用 Facts、Summary、Topic 来理解它们。

同步与异步模式

sync 适合需要影响主流程的场景，例如写入前过滤数据、LLM 前追加规则、入库前调整 Summary。

async 适合不影响主流程的场景，例如日志记录、审计同步、指标上报和通知外部系统。

异步 webhook 的返回值不会影响主流程。

失败处理

Webhook 调用失败不会中断主流程。以下情况会被忽略并记录日志：

• 请求超时。
• 目标地址不可达。
• 返回非 2xx。
• 返回 JSON 格式不正确。
• 返回的 data 不是对象。
• 返回的数据无法通过系统校验。

最小接入示例

from fastapi import FastAPI, Request

app = FastAPI()


@app.post("/webhooks/fact-before-llm")
async def fact_before_llm(request: Request):
    payload = await request.json()

    return {
        "data": {
            "instruction": "Prefer durable user preferences and explicit facts."
        }
    }

下一步

阅读 新增记忆 和 查询记忆，了解 WebHooks 所影响的写入和召回链路。