尚无译文的页面会以英语打开,并标注为英语。
本页由机器从英文原文翻译,内容以英文原文为准。 Machine-translated from the English page, which is authoritative.
Cursor
Cursor 通过三部分接入 Loom:
| 组成部分 | 提供的内容 | 方式 |
|---|---|---|
| MCP 工具 | Cursor 的 agent 中的 loom_* 工具 |
插件、适用于本地单用户服务器的安装链接,或 loom install --client cursor(MCP 客户端) |
| Skills | loom 和 loom-code skills |
插件,或 npx skills add ClickHouse/loom --skill loom loom-code |
| 对话记录捕获 | 每次对话的各轮内容写入 conversation.append |
sessionEnd hook integrations/cursor/cursor-session-hook.sh |
Cursor 插件包含 MCP 条目以及 loom 和 loom-code skills,不含任何 hook:没有代码分流,也不捕获工具调用、运行或工作记忆;Claude Code 和 Codex 插件则具备这些功能。
插件
仓库根目录下的 .cursor-plugin/ 使该仓库成为一个 Cursor 插件市场,其中只有一个插件 clickhouse-loom:包含 loom MCP 服务器和根目录下的 skills/。该插件未在 Cursor 的市场中上架。它的本地单用户连接和只读记忆搜索已在 Cursor 中测试过。在 Teams 或 Enterprise 套餐上,团队管理员可在 Dashboard → Plugins & MCPs → Add Marketplace → Import from Repo 下添加,地址为 https://github.com/ClickHouse/loom。
该插件只有一个变量:Loom MCP URL。团队管理员在 Cursor 控制台的 Plugins & MCPs 下为所有成员设置它。
| 服务器 | Loom MCP URL | 登录方式 |
|---|---|---|
| 单用户,在每个成员的机器上 | http://localhost:7777/mcp?toolset=coding(默认值) |
无 |
设置了 LOOM_OAUTH_ENABLED=true 的团队服务器 |
https://<your server>/mcp |
浏览器,每人各自登录 |
开启 OAuth 的服务器使用不带参数的 URL,即其受保护资源元数据所指明的资源;默认工具集之外的工具通过 loom_op 运行。该条目不发送 Authorization 头,因此未开启 OAuth 的团队服务器会返回 401。这样的团队应跳过该插件:使用下文的 loom install --client cursor 写入带令牌的条目,并用 npx skills add 添加 skills。
通过浏览器登录的客户端中有 OAuth 的详细说明。
MCP 工具
同一台机器上的单用户服务器无需令牌即可接收 MCP 调用。将 Loom 添加到 Cursor 会在 mcpServers.loom 下添加此条目,使用控制台为 Cursor 提供的 coding 工具集。链接中的 config 就是该条目的 base64 编码:
{ "url": "http://localhost:7777/mcp?toolset=coding" }
该条目指向默认端口 7777;如果使用其他端口,请编辑 ~/.cursor/mcp.json 中的 url。对于其他任何服务器,请连同令牌一起写入该条目:
loom install --client cursor --server-url https://loom.example.com --token "$LOOM_API_KEY"
这会把一个 mcpServers.loom 条目(url 加上 Authorization 请求头)合并到 ~/.cursor/mcp.json 中。之后请重启 Cursor。工具集、agent 标签以及各客户端的文件对照表见 MCP 客户端。
然后从 agent 指令 中添加 .cursor/rules/loom.mdc,让 agent 知道何时检索记忆、保存记忆以及使用代码索引,除非仓库的 AGENTS.md 已经包含该内容块。
对话记录捕获
你需要自行注册一个 hook。cursor-session-hook.sh 会把已结束对话的记录交给 loom ingest-transcript,后者将每一轮对话发送到 conversation.append。只有命名空间开启了对话日志时,这些轮次才会被存储。
安装
- 从 Loom 代码仓库检出目录安装
loomCLI(pip install -e .),或从 git 安装(pip install "git+https://github.com/ClickHouse/loom"),并确保python3在PATH中。 - 将 hook 复制到
~/.cursor/hooks/cursor-session-hook.sh,并赋予可执行权限。 -
在
~/.cursor/hooks.json中注册它。用户级文件中的路径相对于~/.cursor/;项目内的.cursor/hooks.json则从项目根目录解析路径。{ "version": 1, "hooks": { "sessionEnd": [{ "command": "./hooks/cursor-session-hook.sh", "timeout": 150 }] } } -
为 hook 提供环境变量。从 Dock 启动的应用看不到你的 shell 配置文件,因此请把令牌放在
~/.loom/token中(loom mint-token --save会写入该文件),其余变量在hooks.json所指向的包装脚本中设置:#!/usr/bin/env bash export LOOM_BASE_URL=https://loom.example.com LOOM_NAMESPACE=my-namespace exec "$HOME/.cursor/hooks/cursor-session-hook.sh" "$@" -
为该命名空间开启对话日志(控制台“对话”页面上的 Record conversations 开关,或使用
conversation.set_logging)。在此之前,服务器会接受这些轮次,但不会存储任何内容。
| 变量 | 默认值 | 含义 |
|---|---|---|
LOOM_NAMESPACE |
必填 | 对话线程写入的命名空间 |
LOOM_API_KEY |
~/.loom/token |
令牌;CLI 从环境变量中读取,因此它不会出现在命令行上 |
LOOM_BASE_URL |
http://localhost:7777 |
Loom 服务器 |
LOOM_AGENT |
cursor |
对话行上的 agent |
LOOM_BIN |
loom |
要运行的 CLI |
LOOM_CAPTURE_CONVERSATIONS |
true |
设为 false 会使 hook 不执行任何操作 |
LOOM_INGEST_MAX_BYTES |
16777216 |
超过该大小的记录会被跳过,而不是被截断 |
LOOM_INGEST_TIMEOUT |
120 |
CLI 允许运行的秒数(需要 timeout 或 gtimeout);请保持小于 hooks.json 中的超时时间 |
hook 读取的内容
Cursor 会将 hook 作为进程启动,并向其 stdin 写入一个 JSON 对象。hook 只读取其中两个字段,其余忽略:
| 字段 | 用途 |
|---|---|
transcript_path |
记录文件;关闭记录功能时为 null,此时不会发送任何内容 |
conversation_id |
线程 id cursor-<conversation_id>(仅允许 [A-Za-z0-9._:-],最长 128 个字符) |
环境变量 CURSOR_TRANSCRIPT_PATH 是路径的后备来源。如果没有可用的 conversation_id,线程 id 为 cursor- 加上记录路径的哈希值。请注册 sessionEnd;stop 也可以使用,但它会在每个 agent 轮次之后重新发送整份记录。
hook 读取 Cursor 写在 ~/.cursor/projects/<project>/agent-transcripts/ 下的 JSONL:每行一个对象,包含 role 和 message.content(字符串或块列表)。由 {role, content} 组成的 .json 数组,或带有 # user / # assistant 小节的 .md 文件,会被原样传递。其他任何文件都会被跳过,并在 stderr 上输出一条消息。
捕获范围
- 会发送:
user和assistant行的文本,按文件顺序发送。只发送文本块:tool_use块、工具结果、思考内容以及其他所有角色,都会在本机被丢弃。 - 不会发送: hook 输入中的
user_email、workspace_roots或模型字段。写入者就是令牌所对应的身份;这些行只带有agent,不包含任何来自 Cursor 账户的信息。 - 不会脱敏: 轮次文本按原样发送。请不要在要捕获的对话中出现密钥,或者保持该命名空间的日志关闭。
行为
- 从不阻塞 Cursor。 在 hook 模式下,所有结果都以退出码 0 退出,并在 stdout 上输出
{};CLI 的输出写入 stderr。 - Loom 不可达时是安全的。 hook 会记录一行日志并以 0 退出,不会重试。下一次运行会重新发送记录,而
conversation.append会跳过已经写入的轮次(轮次 id)。 - 有界。 hook 输入最多读取 1 MiB,记录最多读取
LOOM_INGEST_MAX_BYTES,CLI 最多运行LOOM_INGEST_TIMEOUT秒。 - 安静。 诊断信息是 stderr 上以
loom-cursor-hook:为前缀的一行,不会包含任何记录文本或令牌。 - 手动模式。
cursor-session-hook.sh <transcript>会摄取单个文件,并以 CLI 的退出码退出(2表示配置错误,3表示记录被跳过,其余情况为 CLI 自身的退出码)。
限制
- 存储的轮次只是一份记录,不是提取来源:不会从中挖掘任何内容。若要从对话中写入记忆,请将其轮次发送到
memory.set_from_messages。 - 转录格式属于 Cursor,Cursor 未公开其文档;格式发生变化时,stderr 上会出现 "no user or assistant text in the transcript"。