尚无译文的页面会以英语打开,并标注为英语。
本页由机器从英文原文翻译,内容以英文原文为准。 Machine-translated from the English page, which is authoritative.
自定义提取流水线
memory.set_from_messages 会让对话记录依次经过一组有序的步骤,这些步骤共享同一个状态。请求可以通过 pipeline_steps 替换这组步骤:重新排序或跳过某些步骤,也可以调用由运维人员注册的进程内步骤。本页只介绍步骤列表;提取本身的行为请参阅提取。
pipeline_steps 是 HTTP 请求体字段。它对 MCP 工具 schema 不可见,也不是 Python SDK 中 memory.set_from_messages 辅助函数的参数;请通过 HTTP 或 call(...) 发送。生成的 op 输入类型(sdk/python/loom/ops.py、sdk/typescript/src/generated/ops.ts)包含该字段。
默认流水线
server/memory/app/pipeline.py 中的 DEFAULT_PIPELINE:
| 步骤 | 作用 |
|---|---|
loom.fetch_namespace_categories |
为提取器加载命名空间的标签分类体系。 |
loom.fetch_existing_memories |
取最相近的已有记忆(最多 50 条),展示给提取器。 |
loom.llm_extract |
执行提取调用。 |
loom.drop_recall_echoes |
丢弃复述本会话已获取记忆的事实。 |
loom.drop_session_echoes |
丢弃复述本会话自身 Loom 调用所携带内容的事实。 |
loom.drop_activity_narration |
丢弃对工具活动的叙述,这类内容没有持久的结果。 |
loom.drop_non_durable |
编码会话:丢弃状态快照、日常事务和计划。 |
loom.verify_durable |
编码会话:对剩余事实进行验证。 |
loom.hash_dedup |
丢弃规范哈希已存储的事实。 |
loom.bulk_write |
将 bot 规则(about="agent")归入学习队列,其余通过 memory.bulk_set 写入。 |
编码会话是指 extra_tags 带有编码 agent 来源标签(source:claude-code、source:codex、source:cursor)的对话记录,或轨迹回放。这两个编码步骤对其他对话记录原样放行。
空的 pipeline_steps 会运行上面这组步骤;非空的则严格按顺序运行其中列出的步骤,并共享同一个状态。省略 loom.bulk_write 意味着不会写入任何内容:响应仍会报告提取到的内容。
运行更短的流水线
不使用去重上下文,直接提取并写入,适用于一次性导入已知全新的数据:
curl -s "$LOOM_BASE_URL/v1/memory.set_from_messages" \
-H "Authorization: Bearer $LOOM_API_KEY" -H 'Content-Type: application/json' -d '{
"org": "acme",
"namespace": "support",
"agent": "importer",
"messages": [{ "role": "user", "content": "..." }],
"pipeline_steps": [{ "step_id": "loom.llm_extract" }, { "step_id": "loom.bulk_write" }]
}'
这需要真实的 LLM provider(LOOM_LLM_PROVIDER 及其密钥);默认堆栈中的假 provider 无法提取有意义的事实。
步骤行为
每个描述符的形式为 {"step_id": ..., ...};整个对象会作为配置传给该步骤。
- 每个请求最多 16 个步骤。
hook.*步骤会被拒绝,返回 422VALIDATION_FAILED:服务器不会代表调用方发起任何出站调用。- 未知的步骤 id 会被跳过,并在响应的
pipeline_errors中以unknown_step:<id>报告。 - 失败时放行的步骤。 失败的获取类步骤会将错误记录到
pipeline_errors(例如fetch_existing_failed:<error>),流水线继续运行。 loom.llm_extract失败时中止:提取出错会使请求以 502 终止,因此不会在对话记录得到written=[]的情况下悄悄返回。它的描述符接受{"judge": true}以开启评判关卡;对默认步骤列表,请求上的judge_extraction=true效果相同。- 耗时。 响应的
stage_ms包含每个步骤的墙钟耗时(step.<step_id>)。每个步骤还会在名为pipeline.step的 OpenTelemetry span 中运行,步骤 id 作为其属性。
注册进程内步骤
运维人员在服务器进程启动时导入的代码中注册步骤:
from server.memory.app.pipeline import WorkflowState, register_step
async def spam_filter(state: WorkflowState, config: dict) -> WorkflowState:
state.extracted_facts = [
f for f in state.extracted_facts if "spam" not in str(f.get("value", "")).lower()
]
return state
register_step("operator.spam_filter", spam_filter)
之后请求即可使用 {"step_id": "operator.spam_filter"};描述符中的其他键会作为 config 传入。该步骤在进程内运行,对整个 WorkflowState 拥有读写权限:身份、消息、已有记忆、提取出的事实、计数器。register_step 会替换同一 id 下已有的注册,因此运维人员的步骤也可以替换内置步骤。
替换 loom.bulk_write 的步骤,写入的内容中不得包含 about="agent" 的事实:这些是 bot 的规则,由内置步骤归入学习队列。
警告: 丢弃或改写
extracted_facts的步骤,会改变每个指定它的调用方所存储的内容。放在loom.bulk_write之后的步骤可以在state.written中看到已写入的行,但无法撤销写入。
若要向 Loom 本身添加内置步骤,请在 server/memory/app/pipeline.py 中添加该函数及其 register_step 调用,将其放入 DEFAULT_PIPELINE,并在改动前后各运行一次 make bench-quick:默认步骤列表决定着每一次提取的结果。
限制
- 步骤按顺序执行,不支持分支或并行。
- 默认步骤列表是全局的,不支持按命名空间配置流水线。
- 没有步骤级重试。