尚无译文的页面会以英语打开,并标注为英语。
本页由机器从英文原文翻译,内容以英文原文为准。 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 匹配到但有意不呈现的流程:即同一账本中“未展示”的一侧。 |