跳转至

尚无译文的页面会以英语打开,并标注为英语。

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

context 操作

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

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

context.fetch

按 key 读回已暂存的结果:可以按字符切片读取(offset/limit),也可以只读取匹配某个正则的行(pattern,配合 context_lines)。

POST /v1/context.fetch · MCP loom_context_fetch · 角色 viewer · 读取 · 未列入 MCP 的 all 工具集

输入字段 类型 默认值 含义
org str 必填 租户(身份元组的第一个元素)。
namespace str 必填 该操作读取或写入的命名空间。
agent str 必填 写入或读取的 agent;'-' 或 '*' 表示在操作允许时匹配任意 agent。
user_id str '-' 该行所属的终端用户;'-' 表示无。
session_id str '-' 该行所属的会话或对话;'-' 表示无。
run_id str '-' 本次调用所属的 agent 运行(任务范围);'-' 表示无。
blob_key str 必填 context.offload 返回的 key。
offset int 0 切片起始的字符偏移量;与 pattern 一起使用时,表示跳过多少个匹配。
limit int 4000 每次调用最多返回的内容字符数(1-64000)。
pattern str '' 正则表达式(RE2 语法,不区分大小写;不支持反向引用和环视)。
context_lines int 0 与 pattern 一起使用时,每个匹配周围显示的上下文行数(0-10);上下文行以 lineno- 编号,匹配行以 lineno: 编号。
输出字段 类型 含义
found bool 当命名空间中没有具有此 key 的有效且未过期的 blob 时为 false。
blob_key str 原样返回输入的 blob_key。
content str 字符切片;使用 pattern 时为以 lineno: text 形式给出的匹配行。
content_type str 与 blob 一起存储的媒体类型。
summary str 与 blob 一起存储的摘要。
total_chars int 整个已存储内容的字符数。
total_lines int 整个已存储内容的行数。
offset int 原样返回输入的 offset。
next_offset int 切片(或匹配列表)已读完时为 -1。
matched_lines int 使用 pattern 时,整个内容中匹配的行数;否则为 0。
expires_at datetime \| None blob 不再可读取的时间;未找到时为 None。

context.offload

将较大的工具结果(日志、页面、diff、查询输出)存放到模型上下文之外。

POST /v1/context.offload · MCP loom_context_offload · 角色 writer · 幂等 · 未列入 MCP 的 all 工具集

输入字段 类型 默认值 含义
org str 必填 租户(身份元组的第一个元素)。
namespace str 必填 该操作读取或写入的命名空间。
agent str 必填 执行写入或读取的 agent;'-' 或 '*' 表示在操作允许时匹配任意 agent。
user_id str '-' 该行所属的最终用户;'-' 表示无。
session_id str '-' 该行所属的会话或对话;'-' 表示无。
run_id str '-' 本次调用所属的 agent 运行(任务范围);'-' 表示无。
content str 必填 要存放的文本;超过 LOOM_CONTEXT_OFFLOAD_MAX_BYTES(UTF-8 字节数)时返回 413。
blob_key str '' 为空表示按内容寻址(blob/<sha256 prefix>):重复存放相同的输出会得到相同的键,且只保存一行。
content_type str 'text/plain' 随内容一起存储并由 context.fetch 返回的媒体类型。
summary str '' 调用方提供的一句话摘要(工具名称及其返回的内容)。
ttl_seconds int 604800 blob 可被获取的时长,单位为秒(1 分钟到 90 天)。
输出字段 类型 含义
blob_key str 用于获取内容的键:即传入的键,或 blob/<sha256 prefix>。
content_bytes int 所存内容的大小,单位为 UTF-8 字节。
content_chars int 所存内容的字符数。
sha256 str 内容的 SHA-256 十六进制摘要。
summary str 与 blob 一起存储的摘要:即传入的摘要,或内容的前 200 个字符。
expires_at datetime blob 不再可被获取的时间。
pointer str 可直接用于在对话记录中代替该内容。

context.pack

一个任务的记忆、决策和流程:在每个任务开始时首先调用它,除非 Loom hook 已经把 Loom 的上下文放入了当前会话。

POST /v1/context.pack · MCP loom_context_pack · 角色 viewer · 读取

输入字段 类型 默认值 含义
org str 必填 租户(身份元组的第一个元素)。
namespace str 必填 该操作读取或写入的命名空间。
agent str 必填 写入或读取的 agent;'-' 或 '*' 表示在操作允许时匹配任意 agent。
user_id str '-' 该 pack 为其读取的用户;"-" 表示在记忆、profile、流程和运行部分读取所有用户,在 stack 和工作记忆部分读取未归属任何用户的行。
session_id str '-' 该 pack 为其读取的会话;"-" 表示在记忆部分读取所有会话,在 stack 和工作记忆部分读取未归属任何会话的行。
run_id str '-' 该调用所属的 agent 运行(任务范围);'-' 表示无。
query str '' 可选的任务或问题,用于选取相关的记忆和文档。
situation str '' 可选的情境描述,用于匹配流程。
procedure_explore_rate float \| None None 流程部分的探索率;None 表示 0(从不探索)。
token_budget int 2000 整个渲染后 pack 的大小上限,以 token 计(每个约 4 个字符);超长的 pack 会被截断,并设置 truncated。
top_k int 5 每个基于搜索的部分请求多少条命中(流程和 stack 的知识层最多为 5)。
read_scope Literal['namespace', 'own_user', 'own_session'] 'namespace' 语义与 memory.search.read_scope 相同;绑定到该操作的 user_id / session_id。
mode Literal['startup', 'task', 'debug', 'handoff'] 'task' 各部分的预算和搜索方案,任何模式都不调用 LLM:startup(快速召回;没有 query 时返回置顶项和最近的记忆),task 和 handoff(均衡),debug(质量优先)。
include_knowledge bool False 添加一个 knowledge 部分,包含匹配的文档分块;需要 query。
include_conversations bool False 添加一个 conversations 部分,包含匹配的历史消息;需要 query。
include_runs bool False 运行清单:该身份最近每个会话一行(日期、运行状态和目标、按类型统计的工具调用及错误、涉及的文件、摘要),最新的在前,共 runs_limit 行。
runs_limit int 12 设置 include_runs 时,运行清单列出多少个最近的会话(1-50)。
include_chunks bool False 为记忆搜索的 reranker 候选池额外加入 20 个最近的候选;没有 reranker 时无效。
section_token_budgets dict[str, int] (自动计算) 按部分名称指定的 token 预算,覆盖该模式的默认值;每个部分至少获得 80 个 token。
block_order list[str] (自动计算) 可选的调用方指定的块顺序。
session_block str '' 调用方自己的会话书签(session:<project>,即插件 Stop hook 的笔记)。
only_sections list[Literal['working_memory', 'memory_stack', 'profile', 'memories', 'procedures', 'decisions', 'knowledge', 'conversations', 'runs', 'namespace_health', 'namespace_guide', 'mentor']] (自动计算) 将 pack 限制为这些部分。
include_decisions bool True 决策类型的命中项不再出现在记忆块中,而是渲染为单独带标签的 部分,其中包含结构化记录(场景、结果、实际结果)。
输出字段 类型 含义
rendered str 作为单一文本的 pack:每个非空部分包在 <name> 标签中,按块顺序排列,并截断到 token_budget。
sections dict[str, str] 按名称给出各部分的正文,按块顺序排列;未渲染出内容的部分不会出现。
blocks list[ContextBlock] 每个非空部分一条:标签、正文、token 估算、引用、来源数量,以及 priority(其在块顺序中的位置)。
section_meta dict[str, dict[str, Any]] 按名称给出各部分的详情:来源数量、引用、是否被截断、大小、token 预算和填充比(高于 1.0 表示被截断)。
section_count int 渲染出内容的部分数量。
truncated bool 当任一部分或整个 pack 被截断到预算时为 True。
token_budget int 输入 token_budget 的回显。
mode str 输入 mode 的回显。
tokens_estimate int 预算压力。
fill_ratio float tokens_estimate / token_budget,保留三位小数。
stable_sections list[str] rendered 开头不依赖 query 或 situation 的连续部分:在该身份的工作记忆、profile 或置顶项变化之前,对它提出的每个问题,这部分字节都相同。
stable_prefix_chars int rendered 中该前缀的字符长度;当第一个部分依赖 query 时为 0。
stable_hash str 稳定前缀的 SHA-256;当 stable_prefix_chars 为 0 时为空。
procedure_keys list[str] pack 呈现给 agent 的流程:即 utility 所需账本中“已展示”的一侧。
procedure_keys_withheld list[str] pack 匹配到但有意不呈现的流程:即同一账本中“未展示”的一侧。