跳到内容
ClickHouse Loom
Esc
↑↓导航↵打开⌘J预览
本页内容

conversation 操作

conversation 操作

本页由机器从英文原文翻译,内容以英文原文为准。 Machine-translated from the English page, which is authoritative.

每个 conversation.* 操作接受和返回的确切字段。

每个操作都是 HTTP 上的 POST /v1/<op>,同时也是 MCP 工具 loom_<op>。身份字段(org、namespace、agent、user_id、session_id)会在传输层能够提供时,从令牌和 MCP 会话中填充;对于单用户服务器上不带令牌的 HTTP 调用,除 code.* 和 tracker.*(它们保留各自平面的 org)之外,所有操作的 org 都取该安装的 org,而部分操作的命名空间和 agent 也会如此填充;参见身份与命名空间。操作索引说明了 role、kind 以及 MCP 的 all 列表。未知的输入字段仍会被处理,并在 ignored_args 中列出。

conversation.append

向线程记录一轮对话(角色 + 内容)。

POST /v1/conversation.append · MCP loom_conversation_append · role writer · 幂等

输入字段 类型 默认值 含义
org str 必填 租户(身份元组的第一个元素)。
namespace str 必填 该操作读取或写入的命名空间。
agent str 必填 执行写入或读取的 agent;在操作允许的情况下,'-' 或 '*' 表示任意 agent。
thread_id str 必填 要追加到的线程;无需事先创建。
msg_id str '' 可选;省略时由服务器派生内容哈希
role Literal['user', 'assistant', 'system', 'tool'] 必填 发言者:user、assistant、system 或 tool。
content str 必填 消息文本,按原样存储;user 或 assistant 的轮次还会被嵌入以供 conversation.search 使用,除非其文本被判定为高。
reasoning str '' 模型在这一轮的推理内容,与 content 一并存储;为空表示没有。
user_id str '-' 该行所属的最终用户;'-' 表示没有。
run_id str '-' 此次调用所属的 agent 运行(任务范围);'-' 表示没有。
metadata dict[str, Any] (计算得出) 存储在消息上的自由格式 JSON;可通过 get 和 list 读回。
tokens int 0 调用方上报的该消息的 token 数,按给定值存储;0 表示未上报。
输出字段 类型 含义
msg_id str 消息 id:传入的 id,或服务器派生的内容哈希。
ts datetime 本次调用的服务器时间;消息写入时的时间戳。
stored bool 当记录功能关闭,或该轮次在嵌入进行期间被删除时为 False。
reason Literal['', 'duplicate', 'logging_disabled', 'deleted'] “”(已写入)、“duplicate”(该 msg_id 已写入;stored=True)、“logging_disabled” 或 “deleted”(stored=False)。

conversation.compact

将旧的对话轮次总结为一条带嵌入向量的 system 轮次,并将原始轮次标记为已删除(tombstone)。

POST /v1/conversation.compact · MCP loom_conversation_compact · 角色 writer · 幂等 · 已审计 · 不在 MCP all 工具集中列出

输入字段 类型 默认值 含义
org str 必填 租户(身份元组的第一个元素)。
namespace str 必填 该操作读取或写入的命名空间。
agent str 必填 执行写入或读取的 agent;'-' 或 '*' 表示在该操作允许的情况下可为任意 agent。
thread_id str 必填 要压缩的线程。
keep_recent int 10 最新的这么多条消息保持原文;更早的消息会被总结,数量以摘要器的提示词能容纳为限。
min_to_compact int 4 如果在最后 keep_recent 条之前的新轮次少于该值,则跳过;之前的摘要不计入。
输出字段 类型 含义
compacted bool 写入了摘要并将原始消息标记为已删除时为 True;否则由 reason 说明原因。
messages_summarized int 摘要替换了多少条较早的消息,不含之前的摘要;未压缩时为 0。
summary_msg_id str 合成的 system 摘要消息的 id;未压缩时为空。
tokens_in int 摘要器 LLM 调用所用的提示词 token 数;未发起调用时为 0。
tokens_out int 摘要的补全 token 数;未发起调用时为 0。
reason str compacted=False 的原因:nothing-to-compact、below-min-to-compact、already-compacted、summarizer-empty、embed-failed(嵌入器恢复响应后重试)、summary-high-sensitivity(不要重试:同一窗口会得到相同的摘要)。

conversation.create

创建一个线程容器。

POST /v1/conversation.create · MCP loom_conversation_create · 角色 writer · 幂等 · 不在 MCP all 工具集中列出

输入字段 类型 默认值 含义
org str 必填 租户(身份元组的第一个元素)。
namespace str 必填 该操作读取或写入的命名空间。
agent str 必填 执行写入或读取的 agent;'-' 或 '*' 表示在操作允许时匹配任意 agent。
thread_id str 必填 调用方为该线程指定的 id;使用相同 id 重新创建会替换其标题、元数据和 run_id。
title str '' 在线程列表中显示的标题;为空表示无标题。
metadata dict[str, Any] (自动计算) 存储在线程行上的自由格式 JSON;conversation.get 会返回它。
run_id str '-' 该调用所属的 agent 运行(任务范围);'-' 表示无。
user_id str '-' 该行所属的最终用户;'-' 表示无。
输出字段 类型 含义
thread_id str 原样返回输入的 thread_id。
created_at datetime 本次调用写入线程行的时间。

conversation.delete

软删除一个会话线程:包括它的消息、线程行,以及没有被其他 agent 持有的 embedding。

POST /v1/conversation.delete · MCP loom_conversation_delete · 角色 admin · 幂等 · 有审计 · 不在 MCP all 工具集中列出

输入字段 类型 默认值 含义
org str 必填 租户(身份元组的第一个元素)。
namespace str 必填 该操作读取或写入的命名空间。
agent str 必填 写入或读取的 agent;'-' 或 '*' 表示在操作允许的情况下匹配任意 agent。
thread_id str 必填 要软删除的线程。
confirm_thread_id str 必填 必须与 thread_id 相同,否则调用会返回 400 并且不会删除任何内容。
输出字段 类型 含义
tombstoned_at datetime 标记在每个受影响行上的墓碑时间。
thread_id str 输入 thread_id 的回显。
rows_affected dict[str, int] {table_name: 被标记墓碑的行数};对于 loom.conversation_embeddings,按轮次计数(无论有多少个 embedding 模型持有该轮次,每个轮次只计一行)。
total int 各表 rows_affected 之和。

conversation.get

按 id 获取单个线程:线程元数据,以及可选的消息。

POST /v1/conversation.get · MCP loom_conversation_get · 角色 viewer · 读取 · 未列入 MCP all 工具集

输入字段 类型 默认值 含义
org str 必填 租户(身份元组的第一个元素)。
namespace str 必填 该操作读取或写入的命名空间。
agent str 必填 “” 或 “-” 表示读取线程中所有 agent 的轮次(两个 agent 都记录过一次的轮次),适用于只有 id 的调用方,与 conversation.search 对 “” 和 “-” 的读取方式相同;其他任何值只读取该 agent 的轮次。
thread_id str 必填 要获取的线程。
include_messages bool False 默认关闭:元数据查询只需两次点读。
limit int 100 设置 include_messages 时最多返回的消息数(1-1000)。
offset int 0 从 order 起算的一端开始要跳过的消息数。
order Literal['asc', 'desc'] 'asc' 页面从线程的哪一端开始计数。
输出字段 类型 含义
found bool 当线程既没有线程行也没有任何有效消息时为 False。
thread_id str 输入 thread_id 的回显。
title str 来自 conversation.create 或 update 的标题;未设置时为空。
metadata dict[str, Any] 线程元数据 JSON;未设置时为 {},标题生成器写入的 title_refused 标记除外。
run_id str 该调用所属的 agent 运行(任务范围);无则为 '-'。
user_id str 该行所属的终端用户;无则为 '-'。
agent str 线程的所有者(其线程行的 agent);对于仅由追加构建的线程,为所读消息中最近的写入者,因此未设置 include_messages 时为空。
created_at datetime | None 线程行首次写入的时间;对于仅由追加构建的线程为 None。
updated_at datetime | None 线程行最近一次变更的时间;对于仅由追加构建的线程为 None。
msg_count int 线程中有效(未被墓碑标记)的消息数,即使不返回消息也会返回。
messages list[_ConversationEntry] 仅当 include_messages=True 时填充;使用简单的 limit/offset 切片(基于游标的分页遍历应使用 conversation.list)。
next_cursor str | None 当 order="asc" 时,为本页之后轮次的 conversation.list 游标;当本页已到末尾或 order 为 desc 时为 None。

conversation.list

枚举某个 agent / 命名空间下已存储的对话线程。

POST /v1/conversation.list · MCP loom_conversation_list · 角色 viewer · 读取 · 未列入 MCP all 工具集

输入字段 类型 默认值 含义
org str 必填 租户(身份元组的第一个元素)。
namespace str 必填 该操作读取或写入的命名空间。
agent str 必填 “” 或 “-” 表示读取线程中所有 agent 的轮次(两个 agent 都记录过一次的轮次),适用于只有线程 id 的调用方,与 conversation.search 对 “” 和 “-” 的处理相同;其他任何值则只读取该 agent 的轮次。
thread_id str 必填 要分页浏览的线程,按消息从旧到新排列。
run_id str | None None 可选过滤条件;None 或 “-” 表示所有运行
limit int 100 每页最多返回的消息数(1-1000)。
cursor str | None None 不透明的 (ts, msg_id)
输出字段 类型 含义
rows list[_ConversationEntry] 按时间顺序排列的一页消息。
next_cursor str | None 作为 cursor 传入即可获取下一页;已是最后一页时为 None。

conversation.list_saved_messages

按保存时间由新到旧分页列出用户保存的消息,不带查询:在输入任何内容之前,“已保存”面板显示的就是这个首屏视图。

POST /v1/conversation.list_saved_messages · MCP loom_conversation_list_saved_messages · 角色 viewer · 读操作 · 不在 MCP all 工具集中

输入字段 类型 默认值 含义
org str 必填 租户(身份元组的第一个元素)。
namespace str 必填 该操作读取或写入的命名空间。
agent str 必填 写入或读取的 agent;在操作允许的情况下,'-' 或 '*' 表示任意 agent。
user_id str 必填 仅列出该用户保存的消息。
conversation_id str | None None 可选:仅列出从某一个对话中保存的消息。
limit int 50 每页最多返回的消息数(1-200)。
cursor str | None None 不透明值;传入上一页的 next_cursor。
fields list[str] | None None 调用方要读取的输出字段(按行模型解析的白名单;未知名称会返回 422);不设置则返回全部字段。
输出字段 类型 含义
rows list[_SavedMessageHit] 当前页,最近保存的在前。
next_cursor str | None 作为 cursor 传入以获取下一页;已是最后一页时为 None。

conversation.save_message

保存用户选中用于搜索的一条聊天消息,无论该命名空间是否记录对话记录。

POST /v1/conversation.save_message · MCP loom_conversation_save_message · 角色 writer · 幂等 · 不在 MCP all 工具集中列出

输入字段 类型 默认值 含义
org str 必填 租户(身份元组的第一个元素)。
namespace str 必填 该操作读取或写入的命名空间。
agent str 必填 写入或读取的 agent;'-' 或 '*' 表示在操作允许时匹配任意 agent。
conversation_id str 必填 客户端的对话 id;它在 Loom 中仍作为线程 id。
message_id str 必填 客户端的稳定消息 id。
role Literal['user', 'assistant'] 必填 只有可选择的 user 和 assistant 消息会被嵌入。
content str 必填 消息文本;当对话记录中已有该消息时会被忽略。
user_id str 必填 所有者是配对搜索操作中的硬性过滤条件。
输出字段 类型 含义
conversation_id str
message_id str
indexed bool 当该轮消息已保存并且拥有已保存搜索可排序的向量时为 True:包括新写入、重新保存(完成上次中断的保存所遗留的部分),以及现已标记为已保存的对话记录消息。
reason Literal['', 'duplicate', 'owner_mismatch', 'deleted', 'unsupported_role', 'embed_failed', 'high_sensitivity'] “duplicate”:已保存,未做任何更改。“owner_mismatch”:已存储的消息属于其他用户。“deleted”:已存储的消息已被标记删除。“unsupported_role”:已存储的消息是 system 或 tool 消息,不会被嵌入。…
ts datetime 已存储消息的时间戳;被拒绝时为拒绝发生的时间。

conversation.saved_status

一次调用即可查询用户在某个会话中保存了哪些消息:聊天客户端在打开会话时,会据此绘制每条消息的保存状态。

POST /v1/conversation.saved_status · MCP loom_conversation_saved_status · 角色 viewer · 读取 · 未列入 MCP all 工具集

输入字段 类型 默认值 含义
org str 必填 租户(身份元组的第一个元素)。
namespace str 必填 该操作读取或写入的命名空间。
agent str 必填 写入或读取的 agent;'-' 或 '*' 表示在操作允许的情况下匹配任意 agent。
user_id str 必填 该行所属的终端用户;'-' 表示无。
conversation_id str 必填 消息所属的会话;消息 id 在会话内唯一。
message_ids list[str] 必填 要检查的消息(1-500 条)。
输出字段 类型 含义
saved list[str] message_ids 中该用户已保存的子集,顺序与请求一致。

conversation.search

按与 query 的嵌入相似度对对话消息排序。

POST /v1/conversation.search · MCP loom_conversation_search · 角色 viewer · 读取 · 未列入 MCP all 工具集

输入字段 类型 默认值 含义
org str 必填 租户(身份元组的第一个元素)。
namespace str 必填 该操作读取或写入的命名空间。
agent str 必填 “*” 或 “-” 搜索所有 agent 的对话轮次;其他任何值只搜索该 agent 的对话轮次。
query str 必填 与消息内容匹配的文本,按嵌入相似度匹配;嵌入器不可用时按子串匹配。
thread_id str | None None 可选:限定在某一个线程内
run_id str | None None 可选:按 run_id 过滤;None 或 “-” 表示所有运行
role Literal['user', 'assistant', 'system', 'tool'] | None None 按发言者过滤;除压缩摘要外的 system 轮次以及 tool 轮次不会被嵌入,因此只能通过子串回退匹配到。
user_id str | None None 可选的所有者过滤;None 或 “-” 表示所有用户。
top_k int 20 最多返回这么多条命中结果(1-200)。
namespace_scope Literal['this', 'all_mine'] 'all_mine' “all_mine” 还会读取调用者自己的命名空间,最多读取 memory_search_fanout_max_namespaces 个,与 knowledge.search 相同。
输出字段 类型 含义
hits list[_ConversationHit] 匹配的消息,相似度最高的在前;没有任何消息达到相似度下限时为空;使用子串回退时,按最新的在前排列,且没有下限。
namespaces_skipped list[str] 调用者的命名空间中,all_mine 搜索因达到 memory_search_fanout_max_namespaces 上限而未读取的命名空间;按名称指定其中一个即可搜索它。

conversation.search_saved_messages

仅对某个用户通过 conversation.save_message 保存的消息进行混合搜索,而不是搜索整个对话记录。

POST /v1/conversation.search_saved_messages · MCP loom_conversation_search_saved_messages · 角色 viewer · 读取 · 未列入 MCP all 工具集

输入字段 类型 默认值 含义
org str 必填 租户(身份元组的第一个元素)。
namespace str 必填 该操作读取或写入的命名空间。
agent str 必填 写入或读取的 agent;'-' 或 '*' 表示在操作允许时匹配任意 agent。
user_id str 必填 该行所属的终端用户;'-' 表示无。
query str 必填
conversation_id str | None None
role Literal['user', 'assistant'] | None None
top_k int 20
search_mode Literal['hybrid', 'semantic', 'lexical'] 'hybrid' hybrid:向量检索与针对每条消息全文的 BM25 检索,通过倒数排名融合;semantic:仅向量检索;lexical:仅 BM25 检索。
lexical_weight float 1.0 融合中 BM25 检索的权重(hybrid 模式);1.0 表示权重相等。
输出字段 类型 含义
hits list[_SavedMessageHit]

conversation.set_logging

切换此命名空间是否记录对话记录。

POST /v1/conversation.set_logging · MCP loom_conversation_set_logging · 角色 admin · 幂等 · 已审计 · 未列入 MCP all 工具集

输入字段 类型 默认值 含义
org str 必填 租户(身份元组的第一个元素)。
namespace str 必填 该操作读取或写入的命名空间。
enabled bool 必填 为 True 时在此命名空间中记录对话记录;为 False 时 append 不存储任何内容。
输出字段 类型 含义
namespace str 该操作读取或写入的命名空间。
enabled bool 当前生效的日志记录开关状态。

conversation.threads

按时间倒序列出命名空间中最近的对话线程。

POST /v1/conversation.threads · MCP loom_conversation_threads · 角色 viewer · 读取

输入字段 类型 默认值 含义
org str 必填 租户(身份元组的第一个元素)。
namespace str 必填 该操作读取或写入的命名空间。
agent str '*' “*” 或 “-” 列出所有 agent 的线程
window_days int 30 只返回在最近这么多天内有有效消息的线程(1-365)。
limit int 30 最多返回这么多个线程(1-200)。
offset int 0 在返回当前页之前要跳过的线程数(0-100,000);默认 0,即第一页。
fields list[str] | None None 调用方要读取的输出字段(白名单,按行模型解析;未知名称会返回 422);未设置时返回所有字段。
输出字段 类型 含义
threads list[ConversationThreadSummary] 线程列表,按最近活跃时间倒序,每个线程带有消息数和最后一条消息的摘录。

conversation.unsave_message

从用户的已保存消息搜索中撤回一条消息。

POST /v1/conversation.unsave_message · MCP loom_conversation_unsave_message · 角色 writer · 幂等 · 未列入 MCP all 工具集

输入字段 类型 默认值 含义
org str 必填 租户(身份元组的第一个元素)。
namespace str 必填 该操作读取或写入的命名空间。
agent str 必填 执行写入或读取的 agent;'-' 或 '*' 表示在操作允许的情况下可为任意 agent。
conversation_id str 必填 客户端的会话 ID,与传给 conversation.save_message 的相同。
message_id str 必填 客户端的消息 ID,与传给 conversation.save_message 的相同。
user_id str 必填 仅撤回该用户的已保存记录。
输出字段 类型 含义
conversation_id str
message_id str
found bool 当该用户不存在已保存记录时为 False:从未保存、已被撤回,或由其他用户保存(不会予以确认)。
removed bool 当该轮对话本身被移除时为 True:该命名空间不记录对话记录,因此这条记录只是因为保存操作才存在。
ts datetime

conversation.update

更新单个会话线程的标题、元数据或 run_id。

POST /v1/conversation.update · MCP loom_conversation_update · 角色 writer · 幂等 · 不在 MCP all 工具集中列出

输入字段 类型 默认值 含义
org str 必填 租户(身份元组的第一个元素)。
namespace str 必填 该操作读取或写入的命名空间。
agent str 必填 执行写入或读取的 agent;在操作允许时,'-' 或 '*' 表示任意 agent。
thread_id str 必填 要更新的线程;线程不存在时返回 updated=False。
title str | None None 如果三个字段都未提供,处理程序会返回 400(空操作说明调用方有错误)。
metadata dict[str, Any] | None None 新的元数据 JSON,整体替换旧对象;为 None 时保持不变。
run_id str | None None 线程的新 run;为 None 或 “-” 时保持不变,为 “” 时将其与所属 run 分离。
输出字段 类型 含义
updated bool 当线程没有对应的线程行(从未创建)时为 False,此时不会写入任何内容。
thread_id str 输入 thread_id 的回显。
updated_at datetime | None 线程新的 updated_at;未更新任何内容时为 None。

这个页面有帮助吗?