ClickHouse Loom
为 AI agent 提供共享记忆、文档搜索和代码智能。适用于 Claude Code、Codex、Cursor 以及你自己的 agent。
English · 简体中文 · 日本語 · 한국어 · Português (Brasil) · Español
Loom 的用途 · 基准测试 · 快速开始 · 能力 · 集成 · 文档



Loom 是一个开源、自托管的 MCP 服务器,为你的 agent 提供长期共享记忆:一个 agent 在会话中学到的东西,下一个 agent 或工具就能找到。在带认证的团队部署中,每个 agent 使用一个限定到命名空间和读/写角色的 token。参见共享记忆和被拒绝的访问。
Agent 通过 MCP、HTTP、Python 或 TypeScript 连接。可用 Docker 自托管,或在 Kubernetes 上用 Helm chart 部署;agent 上下文和索引数据存放在 ClickHouse 中,部署时可在首次启动选择 Postgres 用于实时记忆和知识状态。仪表盘把记忆、仓库、任务和运行汇聚到一处。
Loom 的用途
- 在你的编码 agent 之间共享的长期记忆,配合插件在会话开始时加载上下文,并在运行过程中捕获会话。Agent 记忆 · 连接编码 agent
- 通过 Python 或 TypeScript SDK 为 agent 应用提供按用户隔离的记忆。你的第一个 agent
- 一个多用户 MCP 记忆服务器,支持命名空间、角色和 token。多用户模式 · 命名空间与共享
- 为你仓库建立的代码索引,编码 agent 可查询定义、调用方和变更影响。代码索引 · 语言支持与限制
- 与代码关联的记忆,会随代码一起经历重构,在代码变更时被标记,并在 agent 读取或编辑该代码时出现。与代码关联的记忆
- 如下文所测,降低编码 agent 的模型成本。编码 agent 成本
- 带引用的文档搜索(RAG),包括由提取服务转换的 PDF、.docx 和 .pptx 文件。文档搜索
- 多 agent 工作流的共享上下文:共享记忆、任务收件箱和决策。多 agent
- 面向自主 agent 的记忆、召回、审计和擦除。自主 agent
- agent 工作的记录,包括可搜索的对话(开启录制时)、可用于恢复的会话简报、包含目标、结果和模型成本(若提供)的运行记录,以及 PR 和跟踪器历史。运行与 PR 历史
面向软件工厂的记忆。Loom 为实施 agent 和评审 agent 提供跨会话的共享经验、issue 上下文和来源溯源。用 token 限定每个主体的访问范围,在你的应用中等待必需的写入和任务交接,并在评审前用当前源码重新核对与代码关联的经验。同一服务支持多 agent 工作流和自主机器人;编排、测试和审批由你的编排系统负责。提供一个工具并不保证模型会使用它。多 agent 工作流 · 自主 agent 记忆
所有用例,以及何时其他工具更合适:用例。
关于记忆架构选型、数据所有权和运营职责,请阅读为软件工厂选择记忆。
Loom 不是供单个 agent 短期记忆使用的进程内库,也不是 agent 框架。当 Loom 不合适时
实测结果
| 评估 | 使用 Loom | 不使用 Loom | 效率提升 | 范围 |
|---|---|---|---|---|
| 编码智能体回答质量 | 0.84 | 0.78 | 模型成本降低 20% | 24 个问题 × 3 次配对运行 |
| 编码智能体文件定位 | 96.4% | 91.4% | 模型成本降低 21% | 36 个问题 × 10 次配对运行 |
| 记忆 vs 完整历史回答 | 94% | 90% | reader prompt tokens 减少 91% | 100 个配对的 LongMemEval-S 问题 |
两个编码实验环境均在 ClickHouse 代码库上使用 Claude Code(claude-sonnet-5);成本为整个会话的模型账单,不含 Loom 的服务端模型调用、托管和索引。回答质量衡量对已验证答案关键点的覆盖程度,并带有矛盾惩罚。文件定位统计正确文件是否在智能体回答末尾被要求列出的最多三个文件之中。
记忆行使用相同的 gpt-5 reader,比较检索到的记忆与完整对话历史。Token 节省不含记忆构建;94% vs 90% 的准确率差异是描述性的,未经统计学确立。
另外,Loom 的 memory.ask 配置在全部 500 个 LongMemEval-S 问题上取得了 96.6% 的回答准确率。这是一项使用自身配置的回答模型的产品评估,与上述固定 reader 的对比不同。
结果仅针对所测试的工作负载。
协议与可复现工件 · 详细结果 · 在你的工作负载上评估
开始使用
1. 选择你的 Docker 配置
- 个人使用——默认:无需登录,仅限 localhost 访问,并带有一个 dev/local 命名空间。一个人可以连接多个智能体。
- 团队使用:带身份验证的账户和命名空间访问控制。从首次启动起就以多用户模式运行。
两种模式支持相同的 Loom 功能,包括配置的 LLM 和 embeddings。单用户模式不是功能缩减版。你也可以在不删除现有数据的情况下切换已有安装;授予新账户访问现有命名空间的权限。
若想无需安装任何东西直接试用,在 codespace 中打开它:
(它运行什么,谁能访问它)
对于默认的个人安装,需已安装 Docker(在 Windows 上,于 docker 可用的 WSL 2 终端中:开启 WSL 集成的 Docker Desktop,或在发行版中安装的 Docker Engine):
curl -fsSL https://github.com/ClickHouse/loom/releases/latest/download/install.sh -o loom-install.sh && sh loom-install.sh && rm loom-install.sh
从你的主目录或其他只有你能写入的目录运行它。安装程序会启动 Loom 和 ClickHouse,应用迁移并打印仪表盘 URL:http://localhost:7777/;在新安装中,它随后会检查记忆能否保存并读回。在终端中,它还会提议连接它找到的编码智能体(Claude Code、Codex、VS Code),并在新安装中打开仪表盘。镜像包含服务器、workers、仪表盘以及 Python、TypeScript 和 Go 编译器索引器,amd64 上还包括 C++ 索引器;TypeScript 依赖会自动准备。快速开始与固定版本
安装位于 ~/.loom(LOOM_INSTALL_DIR 可选择其他目录):Compose 文件和启动设置位于 ~/.loom/.env。再次运行安装命令会原地升级并保留你的 .env 设置。
保持单用户模式仅限 localhost。如需共享访问,请遵循团队部署指南,包括 TLS。
2. 配置模型与 API 密钥
原版安装无需密钥或网络即可启动。存储、仪表盘、结构化代码索引和语义搜索可用,基于镜像自带的小型本地 embedding 模型;fake LLM 不提供 AI 生成的答案。
| 组件 | 实际使用所需配置 | 未配置时 |
|---|---|---|
| Embeddings | 提供商、embedding 模型、维度与 API 密钥。 | local(CPU 上的 bge-small):语义检索,弱于托管模型。 |
| LLM | 提供商、模型与 API 密钥。 | fake-echo-1:没有有意义的提取、摘要或回答。 |
文章标题:Loom:面向 AI 代理的共享记忆、文档搜索与代码索引
正文: 打开 Settings → Models & keys,选择两个提供商和模型,输入它们的密钥,然后点击 Test & apply。无需重启 Docker;更改嵌入空间会重建现有索引。仪表盘中的嵌入选项均为托管提供商:若要保留本地嵌入并添加 LLM,请改为在 ~/.loom/.env 中设置 LLM 相关行(Models and keys)。
一个 OpenAI API 密钥可以同时承担这两个角色。Claude 需要单独的嵌入提供商。支持 OpenAI、Gemini 以及兼容 OpenAI 的嵌入端点。你的代理的 CLI 登录或订阅不会提供 Loom 的提供商密钥。
更喜欢用环境配置?编辑 ~/.loom/.env,然后重新创建服务器:
docker compose --project-directory "$HOME/.loom" up -d --force-recreate loom
仅设置密钥不会改变已固定的模型(本地嵌入器和模拟 LLM);还需设置提供商和模型。仪表盘中保存的设置优先于 .env。请参阅 models and API keys 获取提供商配置方法和健康检查说明。
其余所有内容都在一个文件中。loom.example.yaml 按区域列出了每个设置及其默认值和作用:ClickHouse 连接、超时与预算、速率限制、工作进程,以及用于开启和关闭功能的 *_enabled 开关。将其中的任意一项设置为 ~/.loom/.env 中的 LOOM_<NAME> 并重新创建服务器;挂载配置文件的部署则可以在该文件的副本中设置它们(how settings are read)。标记为 live 的设置还会在 Loom 运行期间变化:loom settings set <name> <value>,或 Admin → Deployment settings。loom settings list --changed 显示哪些值与默认值不同,以及每个值的来源(runtime settings)。
3. 连接你的代理
如果安装程序已经连接了你的代理,请跳过下面的命令。在运行个人安装的机器上,插件不需要令牌:
# Claude Code
claude plugin marketplace add ClickHouse/loom
claude plugin install loom@loom
# Codex
codex plugin marketplace add ClickHouse/loom
codex plugin add loom@loom
启动一个新会话;第一个会话会连接到 http://localhost:7777。在 Codex 中,以交互方式运行一次 codex 并批准该插件的 hooks;在此之前只有工具可用。告诉代理一些值得保留的内容,然后在下一个会话中询问它。
Cursor 将 Loom 列为插件和 MCP 服务器。对于 Teams 或 Enterprise 计划上的团队市场,团队管理员还可以导入此仓库;其 Cursor 插件会安装 MCP 条目和 Loom 的 skills。在运行个人安装的机器上,下面的按钮会添加本地 MCP 条目,无需令牌:
对于在运行个人安装的机器上使用 VS Code 代理模式的情况,下面的按钮会添加本地 MCP 条目,无需令牌:
对于团队服务器,请向 Claude Code 传递 --config server_url=… --config token=…,或按 connect a coding agent 中所述将 Codex 指向它。在 Settings → Tokens 中创建令牌。Cursor 和其他 MCP 客户端以及 SDK 也在那里有所介绍。
为什么选择 Loom
- 可延续的记忆。跨代理和会话共享决策与发现。每条事实都会记录其作者,版本历史和冲突审查使更正可追溯,命名空间可以回滚到任意时间点。Memory
- 有证据的代码智能。查找定义、调用者、变更影响和相关测试;将代码与提交、拉取请求和问题关联起来。使用源代码位置、完整性信号和分层新鲜度来检查结果。Code index
- 有依据的检索。搜索被允许的记忆、文档、对话和跟踪器记录。答案会引用其来源;低置信度的检索可以放弃回答。Retrieval
- 多代理交接。通过带有租约、重试、审查规则和结果的持久任务收件箱分配工作。你的代理执行工作流;Loom 保留交接。Task queues
- 对代理数据的控制。管理命名空间访问、来源、保留、审计记录和经过验证的擦除。上下文在 ClickHouse 中保持可查询。Security
集成
| 集成 | 连接内容 |
|---|---|
| Claude Code、Codex、Cursor 及其他 MCP 客户端(全部集成) | 在你现有的 agent 工作流中提供记忆与代码智能。 |
| Python、TypeScript、Rust、Go、.NET 和 HTTP | 你自己的 agent 和应用程序。 |
| Langfuse | 请求追踪、模型成本、检索分数和提示词版本归因。 |
| ClickStack / HyperDX | ClickHouse 中的 OpenTelemetry 追踪、日志和指标。 |
Langfuse 和 ClickStack 是可选的集成,不是 Docker 栈中捆绑的服务。
基准测试详情
详细的检索、读取器和代码搜索结果
| 评测 | 结果 |
|---|---|
| LongMemEval-S 证据检索(500 个问题) | 98.6% 的问题在前 30 条记忆中至少包含一个支持会话。 |
| LongMemEval-S 固定 gpt-5 读取器(500 个问题) | 从 top 200 条记忆中取得 92.0% 的答案准确率。 |
| LoCoMo(全部 10 段对话) | 89.6% 的答案准确率;对抗性问题上的正确弃答率为 90.8%。 |
| MemoryAgentBench 事实问题样本(500 个问题) | 99.0% SubEM;生成答案上的 token 重叠 F1 为 95.7%。 |
| 概念性代码搜索(36 个问题) | 金标文件召回率 @5 为 91.2% / @10 为 97.2%;MRR 0.91。 |
| SWE-bench Verified 文件定位(200 个 issue) | 前 10 个结果中包含变更文件的 issue 占比:82%,而 BM25 为 57%;前 5 个中为 76.5%。 |
| Tracker 重复检测(104 对) | 记录中较旧的重复项在 87.5% 的情况下排名第一。 |
这些测量的是不同任务,而不是一个综合分数。SWE-bench 衡量的是文件定位,而不是 issue 解决。结果账本包含评分定义、小样本评测、较弱和负面的发现,以及完整的协议、模型和产物。
方法论 · 覆盖范围与已知差距 · 运行基准测试
文档与贡献
关于共享 agent 上下文、代码智能和带权限的检索,请从文档开始。部署要求见前置条件。
部署 · FAQ · 贡献 · 安全报告 · llms.txt · llms-full.txt
Apache-2.0 · 许可证 · 声明