概览
本页由机器从英文原文翻译,内容以英文原文为准。 Machine-translated from the English page, which is authoritative.
Loom 是一个服务器,为 AI agent 存储记忆、文档、对话、实体图谱和代码索引,所有数据以行的形式保存在 ClickHouse 中,并可选用 Postgres 保存实时记忆和知识状态。agent 和用户可以通过 MCP、HTTP、Python 和 TypeScript SDK 以及控制台访问它。Loom 采用 Apache-2.0 许可。本页帮助你判断它是否适合你的场景。
功能介绍
- 持久的记忆。 agent 保存的事实会出现在之后的会话和其他工具中,每个键对应一条声明,并带有历史、来源和有效期。它可以是个人的记忆,也可以由多个 agent 和多人共享。
- 写入时检查。 近似重复的内容会被合并,矛盾会被标记,针对已固定事实的写入会被拒绝。
- 会弃权的搜索。 当没有结果通过针对你的 embedder 校准的阈值时,
memory.search会返回abstain=true和一个原因码。 - 审计与擦除。 每次改变记忆的写入都会留下一条带内容哈希的审计行。
erasure.request以对读取路径所涉及的每张表进行的残留普查作为结束。 - 带历史的代码索引。 为你的仓库提供搜索、符号、调用方、影响分析、带评审评论的 PR 历史以及 bisect 候选项,每个答案都会注明其背后的提交和索引层级。连接跟踪器数据源后,还支持问题跟踪器:重复检查、issue↔PR 关联以及不稳定测试。
记忆和代码索引是同一台服务器上相互独立的两个平面。可以只用其中一个,也可以两个都用。记忆需要一台服务器和一个写入令牌。代码索引还需要添加一个仓库(LOOM_CODE_REPOS_JSON,或者在运行仓库任务沙箱的控制台中使用 Repositories → Add repository),并设置 LOOM_CODE_INGEST_ENABLED=true。Claude Code 和 Codex 插件同时使用两者。
命名空间的定位
- org 是租户。
- 命名空间是 org 内共享和访问控制的单位。一个部署通常包含:每个团队或项目一个命名空间,每个必须保持隔离的机器人一个命名空间,每个人一个
personal-<slug>(首次使用时创建,也是该用户 MCP 客户端的默认命名空间),以及每个已建立索引的分支一个code-<repo>[-<branch>]。 - 命名空间的每个成员都可以读取其中的每一行。
agent记录是谁写入了某一行,它不是边界。user_id/read_scope=own_user用于在同一个机器人的命名空间内区分不同的最终用户。- 访问权限是命名空间上的角色(viewer/writer/admin),由令牌携带,或通过授权添加。
身份与命名空间中有完整的模型说明。
Loom 适用场景
- 你使用多个 AI 工具,希望它们共享你告诉过其中任何一个的内容,并保存在个人命名空间中。
- 多个工具和人员(Claude Code、Codex、Cursor、客服机器人、在控制台操作的人)需要使用同一份记忆。
- 你希望用 SQL 查询 agent 所掌握的信息:事实、trace、成本和审计记录都是 ClickHouse 表。
- 你已经在运行 ClickHouse,或者可以运行。它是 Loom 唯一必需的存储;Postgres 可选,用于存放实时记忆和知识状态。
- 弃答或标出冲突,好过给出自信但错误的回答。
- 你需要历史记录、来源追溯、审计或可验证的删除。
- 编码 agent 需要你的代码仓库的索引。
不适用的场景
| 场景 | 原因 | 可考虑的替代方案 |
|---|---|---|
| 单个 agent、单个进程、短期记忆 | 没有共享需求时,服务器和数据库只是额外开销 | 进程内的记忆库 |
| 热点路径上的亚毫秒级键查找 | 每次读取都是一次数据库查询 | 在自有存储前加一层缓存 |
| 全图分析或长路径查询 | 遍历时每一跳是一次有界查询,最多四跳 | 图存储,数据由 loom entity-export 导入 |
| 需要 agent 框架 | Loom 不运行 agent 循环、提示词或模型 | agent 框架,以 Loom 作为其记忆 |
| 开箱即用的合规保证 | 擦除和审计只是工程层面的基础能力 | 您自己的合规流程,并使用这些基础能力 |
| 在没有备份计划的单节点 ClickHouse OSS 上运行生产环境 | 没有复制或时间点恢复 | ClickHouse Cloud |
| 固定不变的 API | 操作和字段在不同版本之间会变化 | 固定某个版本,并检查 ops.capabilities |
有效期只涉及有效时间(valid_at、valid_to);Loom 记录了什么以及何时记录,都保存在版本历史中,而不是另设第二条时间轴。部分功能需要运维人员手动开启:代码索引、跟踪器来源、OAuth、遥测导出,以及 Langfuse、ClickStack 中的擦除。
每项特性的代价
| 特性 | 机制 | 代价 |
|---|---|---|
| 单一引擎(ClickHouse 为权威数据源) | 向量、词法、图、过滤、审计和擦除都是针对同一批行的 SQL | 每次读取都是一次查询。读取方需要为带版本的行承担 FINAL 的开销。派生行(实体、摘要)会稍后通过 worker 写入。 |
| 弃答而不是给出弱匹配 | 在启动时根据嵌入模型自身的余弦相似度值推导出阈值(LOOM_ADAPTIVE_THRESHOLDS) |
一些较弱但正确的匹配会被拒绝;可以按请求设置 min_similarity 或 floor_mode。 |
| 会变化的事实 | 每次写入时给出合并、重复、冲突和固定(pinned)的判定;仅追加的 loom.memory_versions |
每次写入都要与相邻记忆比较。一条改写的内容可能会在审核队列中等待,直到有人处理。 |
| 可解释的排序 | 带 explain=true 的 memory.search 会逐项列出每个命中的得分;命中结果带有 source_class 和 verified |
当 top_k 超过 15 时,explain 默认关闭,explain=true 会使每个命中更大。 |
| 带访问控制的共享 | 每一行都带有身份元组;令牌和授权携带命名空间角色 | 你需要签发和轮换令牌并授予角色。跨主体泄漏测试套件在 CI 中为每个读取 op 把关。 |
| 可核查的擦除 | 可恢复的 saga,以残留普查结束;外部后端采用失败即关闭的策略 | 擦除是一个多步骤任务。无法确认删除的后端会使 saga 处于 failed 状态,需要人工升级处理。 |
| 带新鲜度的代码答案 | 解析器层级和编译器(SCIP)层级;答案带有 as_of.commit 和过期标记 |
大型仓库的索引需要数小时。编译器层级需要工具链。 |
质量方面的结论需要你自己衡量。仓库附带了基准测试工具,以及已发布数字背后的原始结果(结果)。在依赖某个默认值之前,请在你的部署上使用真实的提供方运行这些检查(运行)。
决策清单
如果右侧一列中有两个或更多答案符合,Loom 很可能不是合适的工具。
| 问题 | 倾向 Loom | 倾向其他方案 |
|---|---|---|
| 是否有两个或更多工具或 agent 需要共享记忆? | 是 | 否,只有一个进程 |
| 你能否运行 ClickHouse 并运维一项服务? | 是 | 否,你需要托管服务 |
| 数据是否必须保留在你自己的基础设施内? | 是 | 无特别要求 |
| 与其给出自信但错误的答案,是否更希望弃答或标记冲突? | 是 | 始终要返回结果 |
| 你是否需要历史记录、来源追溯、审计或可验证的删除? | 是 | 否 |
| 你的热点路径是否是亚毫秒级的键查找? | 否 | 是 |
| 你是否需要整图分析,而不仅是几跳查询? | 否 | 是 |
| 你能否接受版本之间的 API 变更,或者固定在某一版本? | 是 | 否 |
| 你是否愿意为真实的 embedder 和 LLM 付费,并在自己的数据上做基准测试? | 是 | 否 |
前提条件
| 你需要 | 用途 |
|---|---|
| ClickHouse(评估用 OSS,生产用 Cloud) | 所有功能。参见 ClickHouse 要求。 |
| Postgres 16+(可选) | 在 Postgres 记忆权威下保存实时记忆和知识状态,在部署首次启动时选择;除非设置 LOOM_PG_DURABILITY=local,否则需要同步备库(要求)。 |
| Docker 与 Compose 2.20 或更高版本 | 已发布的本地栈(一行命令安装程序;在 Windows 上,从 WSL 2 运行)和服务器镜像。 |
| Python 3.12+ | 仅供贡献者使用的 loom up、服务器开发和运维 CLI 工作。 |
| 嵌入提供方 | 真实检索:OpenAI、Gemini,或已发布栈使用的本地 CPU 嵌入器。 |
| LLM 提供方 | 提取、memory.ask 综合、code.ask:OpenAI 或 Anthropic。 |
| 令牌和命名空间 | 访问权限。参见令牌和授权。 |
| 代码索引 | 对仓库的 Git 访问权限、用于 PR 历史的 LOOM_CODE_GITHUB_TOKEN,以及首次索引所需的时间。 |
下一步
评估 Loom区分了产品冒烟测试和真正的质量评估。快速入门会运行本地栈。部署说明如何为团队运行 Loom。文档地图按阅读顺序列出了每一个页面。