ClickHouse Loom
为 AI 编码智能体提供自托管的共享长期记忆、文档检索与代码索引服务。
- Star 数
- ★ 172
- 最近更新
- 今天
- License
- Apache-2.0
- 主语言
- Python
- FA 评分
- 68/100 · 存在缺口
30 秒速览
- 可在哪里用
- 通用 · 跨平台Codex · Claude Code
- 开始前需要
- 典型场景
- 使用 Claude Code 或 Codex 的开发者,希望上一个会话中的决定和发现能在下一个会话中被自动读取。
- 主要局限
- 部署需要 Docker(或 Kubernetes + Helm)并运行 ClickHouse,团队模式还涉及账户、令牌与 TLS 配置,运维成本高于纯库方案。
- 官网
- clickhouse.github.io/loom ↗ 来自 GitHub 仓库设置
- 维护状态
- 近 30 天有提交最近提交 2026-11-20最新版本 v1.3.0(2026-11-20)近 7 天每天 +22.6 ★
- 源码审查
- 68/100 · 存在缺口
这个 Agent 能做什么,适合哪些场景?
Loom 是 ClickHouse 开源的、可自托管的 MCP 服务器,为编码智能体和自有应用提供跨会话共享的长期记忆。智能体可以通过 MCP、HTTP、Python 或 TypeScript SDK 接入,Claude Code、Codex、Cursor 与 VS Code 还可以使用官方插件在会话开始时加载上下文并在运行中回写。记忆会指向其涉及的文件与符号,并在智能体修改这些位置时被重新唤起;代码索引支持查找定义、调用方和变更影响。数据存放在 ClickHouse 中,也可在首次启动时选择 Postgres 承载实时记忆与知识状态,并通过 Docker 或 Helm Chart 在 Kubernetes 上部署。它适合需要多智能体共享上下文、可审计记忆和带引用的文档检索(RAG)的团队,而不是单进程内短期记忆的库。
Loom 以 MCP 服务器形式运行,同时暴露 HTTP 接口与 Python、TypeScript SDK。它接收并存储智能体写入的记忆(每条记录作者、版本历史,并支持冲突审查与命名空间回滚),并为仓库建立代码索引,回答定义、调用方、变更影响与相关测试等问题,结果会标注版本、源码位置与完整性。文档检索支持 PDF、.docx、.pptx 等格式,由抽取服务转换后入库,答案会引用来源,低置信度时可以放弃回答。它还能通过带租约、重试与评审规则的任务收件箱协调多智能体交接,并在开启录制时保存可检索的会话、会话摘要、运行目标与模型成本、PR 与跟踪系统历史。仪表盘把记忆、仓库、任务和运行集中展示。
- 使用 Claude Code 或 Codex 的开发者,希望上一个会话中的决定和发现能在下一个会话中被自动读取。
- 需要让多个智能体协作完成任务的团队,用任务收件箱分配工作并保留交接记录。
- 为自有智能体应用按用户构建长期记忆的开发者,通过 Python 或 TypeScript SDK 接入。
- 需要跨仓库查询定义、调用方与变更影响,以便评估改动风险的工程团队。
- 搭建带引用来源的内部文档问答(RAG)系统,并处理 PDF、Word、PPT 文件的知识管理场景。
- 需要为智能体数据提供命名空间权限、审计记录与可验证删除的合规团队。
安装与配置要点
摘自下方的安装和使用说明,以项目 README 的最新说明为准。
- 端口
7777- 环境变量
LOOM_INSTALL_DIR- 配置文件
~/.loom~/.loom/.envloom.example.yaml- 安装说明涉及
- Windows · WSL · Docker
如何安装或部署这个 Agent?
默认个人安装方式,需要已安装 Docker(Windows 用户在可运行 docker 的 WSL 2 终端中执行):
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、执行迁移并打印仪表盘地址 http://localhost:7777/ ;安装目录为 ~/.loom(可用 LOOM_INSTALL_DIR 指定其他目录)。重复执行该命令可原地升级并保留 .env 设置。
也可使用 Helm Chart 部署到 Kubernetes,或在 GitHub Codespaces 中试用。默认安装无需密钥即可启动:结构化代码索引与语义检索可用(使用镜像内置的本地嵌入模型),但 LLM 默认为 fake-echo-1,不会产生真实摘要或回答。
如何使用这个 Agent?
启动后在仪表盘的 Settings → Models & keys 中选择嵌入与 LLM 提供商和模型、填写 API 密钥,再点击 Test & apply,无需重启 Docker。也可编辑 ~/.loom/.env 后重建服务:
docker compose --project-directory "$HOME/.loom" up -d --force-recreate loom连接 Claude Code 与 Codex 插件(个人安装在同一台机器上无需令牌):
claude plugin marketplace add ClickHouse/loom
claude plugin install loom@loom
codex plugin marketplace add ClickHouse/loom
codex plugin add loom@loom开始新会话后,插件会连接 http://localhost:7777。Cursor 与 VS Code 可通过文档中提供的本地 MCP 安装链接添加 http://localhost:7777/mcp 条目。团队服务器需向插件传入 --config server_url=… --config token=…,令牌在 Settings → Tokens 中创建。所有配置项列于 loom.example.yaml,可在 ~/.loom/.env 中以 LOOM_<NAME> 形式设置。
这个 Agent 有哪些优点和局限?
- 记忆与代码位置绑定:记忆会指向其涉及的文件和符号,并在智能体编辑这些位置时重新浮现。
- README 公布了成体系的评测结果,例如编码智能体文件定位 96.4% 对比 91.4%,模型成本降低 21%,并附协议与可复现工件。
- 真正自托管:服务、仪表盘与索引数据位于你自己的 ClickHouse 中,可选择 Postgres 承载实时记忆,支持命名空间权限、审计与可验证删除。
- 接入面广:MCP、HTTP、Python/TypeScript SDK,以及 Claude Code、Codex、Cursor、VS Code 的官方插件与一键链接。
- 除了记忆与代码索引,还包含带引用的文档检索(PDF/docx/pptx)、多智能体任务收件箱与会话/运行记录。
- 部署需要 Docker(或 Kubernetes + Helm)并运行 ClickHouse,团队模式还涉及账户、令牌与 TLS 配置,运维成本高于纯库方案。
- 想要有意义的抽取、摘要和回答必须自行配置嵌入与 LLM 提供商及 API 密钥;默认的
fake-echo-1不产生真实答案,Claude 还需另配嵌入提供商。 - 本地默认嵌入模型为 bge-small(CPU),README 明确说明效果弱于托管模型,更换嵌入空间会触发索引重建。
- 评测结果由作者自测且针对特定工作负载,README 也指出部分对比(如 94% 对比 90%)只是描述性、未达统计显著。
- README 说明它不适用于单智能体的短期进程内记忆,也不提供智能体框架能力。
这个 Agent 与同类方案有什么区别?
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| ClickHouse Loom 当前 | 68 · 存在缺口 | — | ★ 172 | 今天 | Python | Codex · Claude Code |
| RepoBrain 代码库智能问答引擎 | 54 · 缺口较多 | Agent 插件 / 技能免费 + 模型费 | ★ 1.4k | 9 天前 | Python | Codex · Claude Code |
| OpenMemory 认知记忆引擎 | 65 · 存在缺口 | 代码库 / SDK免费 + 模型费 | ★ 4.6k | 11 天前 | TypeScript | Claude Code · OpenAI API |
| LLMSlim 上下文与记忆工具 | 70 · 存在缺口 | MCP 服务器免费 + 模型费 | ★ 27 | 1 天前 | Python | Codex · Claude Code |
FollowAgents 如何评估这个 Agent?
查看各维度的扣分理由
least_privilege:安全文档给出按 org/namespace 的行级隔离、按角色授权的 op、限流与 read_scope 上限,属于充分设计;但默认单用户模式关闭鉴权、localhost 绑定,且 MCP 工具集暴露面较大,故扣至 2。user_confirmation:安装脚本会询问是否连接 Claude Code/Codex/VS Code,bench 技能要求付费运行前先征得同意,删除/部署等不可逆操作要求先问;但部分 hook 自动捕获会话,故非满分。data_flow_transparency:README 与配置文档明确说明数据存于 ClickHouse、可选 Postgres、模型与密钥配置、Langfuse/ClickStack 为可选集成;但未逐项列出 MCP 工具向外部模型发送的内容,扣 1。sensitive_data_handling:有敏感度检测、high 行不嵌入、prompt fencing、审计哈希链与擦除 saga,证据充分;但依赖部署方正确配置密钥,且默认 dev 密钥存在,扣 1。dependency_security:仅见 PyPI/npm 徽章与镜像拉取,未见锁文件、SBOM 或依赖审计证据,扣至 1。external_effects:安装脚本会拉取镜像、启动容器、可能修改 agent 配置,属外部副作用,虽有确认与回滚说明,但证据有限,扣至 1。rollback:支持原地升级、命名空间回滚到任意时间点、down 不删数据、旧版本安装器拒绝降级,证据较好;但未覆盖所有破坏性操作,扣 1。source_attribution:记忆记录 actor、source_class、verification,检索结果带 as_of 与引用,证据充分;但部分为断言,扣 1。
self_consistency:README、quickstart、AGENTS.md 与技能文件对单用户/多用户、默认 fake LLM 与本地嵌入的描述一致;但技能文件 loom/SKILL.md 在样本中被截断,无法核对全部声明,扣 1。dependency_availability:依赖 Docker、ClickHouse、可选 Postgres、Node 18+、Python 3.12+,文档列出前置条件;但未见版本锁定与离线可用性证据,扣至 1。failure_messages:文档描述健康检查、安装失败重跑、abstain/not_covered/stale 等失败语义,证据较好;但未展示具体错误码清单,扣 1。
audience_and_scenarios:覆盖个人、团队、多 agent、SDK、文档检索、代码索引等多种场景,并明确“何时不适用”,证据充分。capability_boundaries:明确说明不是进程内库、不是 agent 框架,技能中区分 code.* 与 memory.* 用途,边界清晰。trigger_precision:技能 frontmatter 有 WHEN 触发条件与 LOOM_BASE_URL/.loom 标记,但触发依赖环境变量与索引状态,存在误触发/漏触发可能,扣 1。environment_fit:支持 Docker、K8s Helm、Codespaces、WSL、多平台镜像;但要求 Docker 与端口 7777,环境适配非全覆盖,扣 1。
information_architecture:README 结构清晰,docs 分层(getting-started/operations/architecture/benchmarks),AGENTS.md 给出仓库地图,证据充分。install_notes:安装步骤详尽,含校验和验证、固定版本、升级与降级说明,证据充分。naming_stability:插件与技能版本 1.2.0 一致,但存在 loom 与 loom-code-skill 两个插件及同名技能,命名易混淆,扣 1。examples_and_faq:有 quickstart 示例与 FAQ 链接,但样本中未见 FAQ 正文与更多示例,扣 1。known_limitations:README 与 benchmark 文档承认小样本、非统计显著、索引滞后等局限,证据较好;但部分局限散落,扣 1。license:Apache-2.0,LICENSE 与 NOTICE 均提及,证据充分。versioning_changelog:有版本号与配置默认值变更表,但未见完整 CHANGELOG,扣 1。maintenance_responsibility:发布者为 ClickHouse 但未经验证,SECURITY.md 与 CONTRIBUTING.md 存在,维护责任部分明确,扣 1。
output_usability:MCP 工具返回带引用、as_of、abstain 的结构化结果,技能指导先路由后读取,可用性较好;但依赖正确配置模型与索引,扣 1。marginal_value:基准显示成本降低与定位提升,但为特定工作负载、样本有限,边际价值证据中等,扣 1。cost_benefit:需自托管 ClickHouse 与可选模型 API 成本,README 承认未计入服务端模型调用与托管成本,成本收益证据不完整,扣 1。
claim_traceability:基准声明指向 docs/benchmarks/results.md 与协议,配置项指向 catalog.py,可追溯性较好;但部分 README 数字未在样本中给出原始数据,扣 1。cross_source_corroboration:README、quickstart、security 文档与技能文件相互印证,但样本不含测试与结果账本正文,扣 1。fact_inference_separation:README 区分“描述性非统计显著”与实测结果,bench 技能要求先证明处理生效再读分数,分离较好;但部分性能声明仍为产品自评,扣 1。
- 默认单用户模式关闭鉴权并绑定 localhost,若改为对外绑定需自行配置 TLS 与鉴权,否则存在暴露风险。
- 安装脚本从网络下载并执行,虽校验 SHA-256,但仍建议在可写且可信目录运行并预先检查。
- 依赖 Docker、ClickHouse 与可选模型 API,未配置真实模型时 LLM 为 fake,抽取与问答无实际效果。
- 基准结果为特定工作负载、样本有限,部分差异被作者自述为非统计显著,不应外推。
- 发布者身份未经验证,生产采用前应独立核实来源与供应链。
- 插件与技能存在 loom 与 loom-code-skill 同名混淆,安装时需注意不要重复安装。
最近版本
来自该项目 GitHub Releases 的最新发布记录,说明为上游原文摘录,未经本站改写或测试。
-
发布说明摘录
What's Changed * The TypeScript SDK trims slashes from server URLs and the memory store's key prefix in linear time by @zlareb1 in https://github.com/ClickHouse/loom/pull/564 * The recall key's stray-link check compares the key file's name as text by @zlareb1 in https://github.com/ClickHouse/loom/pull/566 * The bundle budget builds through Vite's API, with no shell by @zlareb1 in https://github.com/ClickHouse/loom/pull/567 * Leading SQL comments are skipped in linear time by @zlareb1 in https://github.com/ClickHouse/loom/pull/565 …在 GitHub 查看 ↗ -
发布说明摘录
New Feature - The reference extractor reads Parquet files: each file becomes a table whose rows are searchable passages cited by row, and a typed dataset. (#269) - knowledge.query calculates over the datasets ingested files become: a typed plan of filters, joins, groups and aggregates (or the rows themselves) runs over every row of the live snapshots, and the result carries a receipt naming each snapshot it read. (#278) …在 GitHub 查看 ↗
常见问题
不配置任何模型密钥能直接用吗?
fake-echo-1,不会生成有意义的抽取、摘要或回答,需要真实能力必须配置提供商与密钥。个人模式和团队模式有什么区别?
dev/local 命名空间,一个人可连接多个智能体;团队模式提供认证账户与命名空间访问控制。README 强调两种模式功能一致,单用户不是精简版,已有安装也可在不删数据的前提下切换。数据和上下文存在哪里?
它和智能体框架或记忆库是什么关系?
多智能体协作如何落地?
ClickHouse Loom 用哪个端口?
ClickHouse Loom 官网是什么?
ClickHouse Loom 开源吗?
ClickHouse Loom 安全吗?
ClickHouse Loom 还在维护吗?
ClickHouse Loom 是谁开发的?
谢谢反馈,我们会据此改进页面。