尚无译文的页面会以英语打开,并标注为英语。
此机器翻译生成后,英文原文已更新。请阅读英文页面以获取当前说明。
本页由机器从英文原文翻译,内容以英文原文为准。 Machine-translated from the English page, which is authoritative.
快速入门
本页介绍如何在笔记本电脑上启动 Loom,并通过 HTTP、Python 和 MCP 保存第一条记忆。整个过程不需要 API key,也不需要账号。全新安装的发布版栈使用镜像自带的小型本地模型生成嵌入,因此无需网络,搜索也能返回有意义的结果(升级安装则沿用其 .env 中指定的嵌入器);它的 LLM 是伪造的,所以提取不会产生任何结果,memory.ask 也不会返回答案。检出的代码仓库中的 .env 对两者都使用伪造的提供方。
默认的 Docker 安装是单用户的: 无需登录,仅限本机访问,并使用默认的 dev/local 命名空间。一个人无需启用多用户模式,就可以连接多个 agent。开源版同样支持团队部署,提供经过身份验证的账号和命名空间访问控制;请以多用户模式启动,或参阅部署 → 身份模式。两种模式支持相同的 Loom 功能;无论哪种模式,使用真实的 LLM 和嵌入都需要配置提供方。
前置条件
| 需求 | 用途 |
|---|---|
| 带 compose 插件的 Docker | 运行整个技术栈:ClickHouse 和 Loom 服务器。 |
| Python 3.12 或更高版本 | 仅供贡献者使用的 loom CLI。SDK 支持 3.11 及以上版本。 |
| Node.js 20 或更高版本 | TypeScript SDK(可选)。 |
空闲端口 7777 |
供 Loom 使用。从源码检出进行开发时,还会在 8123 和 9000 上暴露 ClickHouse。 |
jq |
读取第 4 步中 curl 的输出(可选)。 |
1. 启动堆栈
快速路径:使用发布的镜像,无需克隆
前提条件:Docker Desktop,或 Docker Engine 与 Compose 2.20 或更高版本。在 Windows 上,请在能正常使用 docker 的 WSL 2 终端中运行该命令:即为该发行版开启了 WSL 集成的 Docker Desktop,或安装在其中的 Docker Engine。安装程序是一个 POSIX shell 脚本。
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-install.sh,或把它指向另一个文件。下载失败时会以 curl 的错误信息和非零退出码停止;安装失败后,请先解决它报告的问题,再完整地重新运行该命令。安装程序会从最新的 GitHub Release 下载 loom-stack.tar.gz,校验其 SHA-256,把 Compose 和 ClickHouse 配置安装到 ~/.loom 下,拉取匹配的 ghcr.io/clickhouse/loom:X.Y.Z 和 ghcr.io/clickhouse/loom-extractor:X.Y.Z(文档提取服务)镜像,并等待 http://localhost:7777/v1/health 可用。服务器镜像包含 API、worker、迁移,以及位于服务器根路径的已构建 React 控制台;无需安装 Python 或 Node。Python、TypeScript 和 Go 的编译器索引器已包含并启用,在 amd64 上 C++ 索引器(scip-clang)也一样。使用 TypeScript 索引器索引的仓库会自动安装其依赖。两个镜像都支持 Linux amd64 和 arm64,包括 Apple Silicon 上的 Docker Desktop。
Loom 响应之后,安装程序会:
- 检查记忆。 新安装会保存一条测试记忆,读回后将其删除,以此表明写入和读取均正常,并且不会留下有效记忆(其已删除的版本显示在“最近删除”下)。在检查通过后重新运行,或升级时,会跳过这一步。
- 了解是否开启了登录。 开启登录时,它不会连接任何 agent,并说明令牌从哪里获取。
- 提供连接你的编码 agent 的选项。 在终端中,它会对找到的每一个询问:Claude Code 和 Codex 通过它们的插件,VS Code 通过
code --add-mcp。LOOM_CONNECT可替代询问,在没有终端的运行中同样有效,并且只会查看它指名的客户端:取值为claude-code、codex和vscode的逗号分隔列表、all,或单独的none;任何其他值都会使安装停止。没有终端且没有LOOM_CONNECT时,不会查看或更改任何 agent。之前已设置的插件或 MCP 服务器(通过插件、claude mcp add、codex mcp add或loom install)保持原样;对于 Claude Code 插件,安装程序会打印把它指向本次安装的命令。Claude Code 的插件使用 PATH 上的 Node.js 18 或更高版本,因此没有时安装程序不会安装插件,只打印仅用于 MCP 服务器的claude mcp add命令行;Codex 的插件还会通过 nvm 之类的方式查找 Node.js,因此会安装,并在旁边给出codex mcp add命令行。Codex 的插件始终使用http://localhost:7777,所以对于安装在其他地址的情况,它会得到指向其设置页面的链接。在远程会话或 WSL 中不提供 VS Code。LOOM_CONNECT指名的客户端若不在 PATH 上,会被指出。 - 打开控制台:在桌面环境中,对于新安装会打开;
LOOM_NO_OPEN=1可跳过。
在启动 Loom 之前,如果新安装运行在终端中,且 Ollama 在 localhost:11434 上响应,还会询问是否让 Loom 的模型任务(提取,以及启用后的助手)使用它,无需 API 密钥;LOOM_LOCAL_MODELS=ollama 表示回答是,off 表示否(你机器上的模型服务器)。
从 WSL 运行时,这些步骤作用于 WSL 内部:请按连接指南从 Windows 连接在 Windows 上运行的 agent,并在 Windows 浏览器中打开安装程序打印的控制台地址。
在任何步骤按 Ctrl-C 都可以中止运行;agent CLI 为其插件启动的克隆可能仍会在后台完成。
该堆栈运行自己的 ClickHouse 容器。若要使用你已在运行的 ClickHouse,即自管服务器或 ClickHouse Cloud 服务(26.4 或更高版本,并带有 Keeper),请传入它的 URL;URL 中没有密码时,安装程序会询问密码,创建 loom 数据库和一个只读 reader 用户,或者打印需要管理员运行的 SQL(选择 ClickHouse):
curl -fsSL https://github.com/ClickHouse/loom/releases/latest/download/install.sh -o loom-install.sh \
&& sh loom-install.sh --clickhouse https://loom@abc123.us-east-1.aws.clickhouse.cloud:8443 && rm loom-install.sh
每个版本的 install.sh 安装的都是该版本,因此 latest 提供的副本安装最新版本,而下面某个版本自己的 URL 每次都安装该版本。在较新的安装之上,较旧版本的副本会拒绝安装,而不是在较新的数据上启动较旧的 Loom 和 ClickHouse;若要有意降级,请按降级安装程序安装的版本操作。要固定某个版本,请使用它自己的 URL:
curl -fsSL https://github.com/ClickHouse/loom/releases/download/v1.2.3/install.sh -o loom-install.sh && sh loom-install.sh && rm loom-install.sh
若想在启动前检查全部内容,请下载这些文件并核对:
curl -fLO https://github.com/ClickHouse/loom/releases/latest/download/loom-stack.tar.gz
curl -fLO https://github.com/ClickHouse/loom/releases/latest/download/loom-stack.tar.gz.sha256
curl -fL https://github.com/ClickHouse/loom/releases/latest/download/install.sh -o loom-install.sh
sha256sum -c loom-stack.tar.gz.sha256
tar -tzf loom-stack.tar.gz
待输出内容看起来无误后,再从已核对的包中安装:
LOOM_INSTALL_BUNDLE="$PWD/loom-stack.tar.gz" \
LOOM_INSTALL_CHECKSUM="$PWD/loom-stack.tar.gz.sha256" sh loom-install.sh && rm loom-install.sh
传给安装程序的 LOOM_PORT、LOOM_BIND_HOST、LOOM_IMAGE_REPOSITORY、LOOM_EXTRACTOR_IMAGE_REPOSITORY 和 LOOM_CLICKHOUSE_IMAGE 会写入安装目录的 .env,因此之后在该目录中运行的 docker compose 命令以及之后的安装程序运行会使用相同的端口和镜像。非回环地址的 LOOM_BIND_HOST 会把 Loom 发布到本机之外,而在没有 LOOM_PUBLIC_BASE_URL 和登录的情况下,服务器会拒绝以这种方式启动:请使用 LOOM_SKIP_START=1 安装,在 .env 中设置它们(见下文),然后不带 LOOM_SKIP_START=1 再次运行安装命令。
每个版本都运行构建时最新的 ClickHouse 版本,因此对同一个 Loom 版本再次运行安装命令会保留其 ClickHouse;安装较新的 Loom 版本会使它升级,除非 .env 固定了 LOOM_CLICKHOUSE_IMAGE(删除该行即可重新跟随版本发布)。再次运行安装命令会更新受管理的 Compose 和配置文件,并协调容器。它会保留 ~/.loom/.env,为没有提取器 URL 和令牌的文件补上它们,同时保留命名的 Docker 卷。要在不删除数据的情况下停止:
docker compose --project-directory "$HOME/.loom" down
仅在有意进行不可逆的重置时才添加 --volumes。
在 GitHub Codespaces 中试用
仓库的开发容器会在 codespace 中运行最新版本,你的机器上无需任何东西:它用上述安装程序安装 Loom,启动它,并把 Claude Code 连接到它。首次启动会下载约 3 GB 的镜像,需要几分钟。请在创建日志最后几行打印的地址打开控制台(Loom is running in the codespace. Dashboard: https://<codespace name>-7777.app.github.dev,即 Ports 标签页中端口 7777 的转发地址);其上方安装程序给出的 http://127.0.0.1:7777/ 是 codespace 自己的地址。在 codespace 的终端中运行 cd ~ && claude(在检出目录之外,因为其中的说明是针对开发 Loom 本身的),登录,然后说“Remember that I never deploy on Friday”;在新的 claude 会话中,问“When can I deploy?”。
该试用以单用户模式运行,没有登录。在浏览器中,端口 7777 是私有转发的:其地址只响应你的 GitHub 账号。请保持私有:设为公开,或对组织私有,都会把一个没有登录的服务器开放给所有获得共享的人。codespace 内的 agent,例如它的 claude,使用 http://localhost:7777;控制台的连接行给出的是转发地址,而这需要 GitHub 登录,codespace 中的 agent 没有这一登录。在桌面版 VS Code 中打开时,codespace 还会把该端口转发到你笔记本电脑的 localhost:7777,在那里它与本地安装一样对笔记本上的每个程序开放,笔记本上的 agent 也可以访问它;转发需要该本地端口空闲,因此请先停止本地的 Loom。请通过浏览器地址使用控制台:从笔记本的 localhost:7777 页面可以打开,但服务器会拒绝它的请求,所以不显示数据;只有转发地址才是该服务器自己的页面。
安装位于 /workspaces/.loom,因此重建的 codespace 会保留其 .env 和 Compose 项目,不过它的记忆存放在 Docker 卷中,重建时可能不会保留;重建还会在其上运行最新版本的安装程序,把它升级到该版本。这些文档中凡是提到 ~/.loom 或 "$HOME/.loom" 的地方,codespace 使用 /workspaces/.loom。Codespaces 会在端口 7777 一开始监听时就提示打开它;控制台要等创建日志打印“Loom is running in the codespace”之后才会响应。如果日志最后以错误结束,请在 codespace 的终端中运行 sh .devcontainer/start-loom.sh:它会保留首次运行已设置好的内容。
以多用户模式启动
若要全新安装发布镜像,并从首次启动起就带有账户和登录,请先准备堆栈文件,但不启动容器:
curl -fsSL https://github.com/ClickHouse/loom/releases/latest/download/install.sh -o loom-install.sh \
&& LOOM_SKIP_START=1 sh loom-install.sh && rm loom-install.sh
在启动 Docker 之前编辑 ~/.loom/.env。替换现有的身份和认证条目,并添加注册设置:
LOOM_IDENTITY_PROVIDER=trust-network
LOOM_AUTH_REQUIRED=true
LOOM_SELF_SIGNUP=open
保留生成的 COMPOSE_PROJECT_NAME 和 LOOM_JWT_SECRET。然后拉取并启动堆栈(如果使用你自己的 ClickHouse,请先按安装程序所说运行 ch-setup):
docker compose --project-directory "$HOME/.loom" pull
docker compose --project-directory "$HOME/.loom" run --rm loom loom ch-setup # your own ClickHouse only
docker compose --project-directory "$HOME/.loom" up -d
健康检查通过后,打开 http://localhost:7777/ 并注册。SDK 和 MCP 客户端需要令牌;请使用授予你账户的组织和命名空间,而不是下面示例中单用户的 dev/local 默认值。
这启用的是多用户认证,而不是公共网络:堆栈仍然绑定到 localhost。在与团队共享之前,请配置操作员访问和 TLS。同时也要配置真实的模型和 API 密钥;选择多用户模式并不会取代 fake LLM。
对于已在运行的单用户堆栈,请改按切换说明操作;重新创建容器会保留现有的数据卷。
贡献者路径:构建检出的代码
前提条件:Docker Compose 2.34 或更高版本,检出代码中的 compose 文件需要它来每日拉取 ClickHouse。
git clone https://github.com/ClickHouse/loom && cd loom
python3 -m venv .venv && . .venv/bin/activate
pip install -e .
loom up
loom up 做三件事:
- 创建 git 不跟踪的两个文件:由
.env.example生成的.env,以及由其模板生成的deploy/clickhouse-config/named_collections.xml。它从不覆盖这两个文件;对于没有提取器令牌的现有.env,它会补上一个。 - 使用
--build运行开发 compose 堆栈。 - 轮询
http://localhost:7777/v1/health,直到服务器就绪,并打印待处理的迁移数量。超过--timeout(300 秒)后放弃,并给出最后一次的健康响应体和日志行。
首次贡献者启动会构建镜像并应用所有 schema 迁移,因此请预留几分钟。随后 loom up 会打印控制台 URL(http://localhost:7777/)、一个用于保存第一条记忆的 curl 调用和一段 Python 代码片段,以及一行用于接入 Claude Code 的命令。开启认证时,它还会生成一个 writer 令牌,并放入这些片段中。
| 标志 | 作用 |
|---|---|
--rebuild |
代码更改后重新构建。 |
--no-build |
复用缓存的镜像。 |
--open |
打开控制台。 |
--port |
使用另一个 Loom 端口。 |
--env-file |
指向另一个 env 文件。 |
对正在运行的堆栈重新运行 loom up 只会重新检查健康状态。make dev 不经过 CLI 完成同样的事,并运行:
docker compose --env-file .env -f compose.yaml -f dev/docker-compose.dev.yml --profile bundled up -d --build
由于 compose.yaml 排在最前,Compose 会读取仓库根目录的 .env 来进行 ${VAR:-default} 替换;--env-file .env 只是明确说明了这一点。loom down 会停止堆栈并保留其卷。loom down --delete-data 只有在你输入生成的 Compose 项目名之后,才会永久删除这次安装的命名卷;--yes 是非交互式的确认。Makefile 目标的作用相同:make down 保留数据,make down-all 删除数据。
默认 .env 启动的内容
检出代码和发布包的 .env 模板都选择单用户模式。发布包显式设置 LOOM_IDENTITY_PROVIDER=single-user;检出代码将其留空,并从 LOOM_AUTH_REQUIRED=false 推断出相同的模式。
| 设置 | 值 | 效果 |
|---|---|---|
LOOM_AUTH_REQUIRED=false, LOOM_IDENTITY_PROVIDER=single-user (或留空) |
single-user |
无需登录。默认命名空间为 dev/local。SDK 和 MCP 调用不需要令牌。 |
LOOM_LLM_PROVIDER=fake, LOOM_LLM_MODEL=fake-echo-1 |
fake LLM | 提取、实体标记和 memory.ask 的综合回答不产生任何内容。 |
LOOM_EMBEDDING_MODEL=local, LOOM_EMBEDDING_DIM=384 (发布包) |
bge-small | 在 CPU 上进行语义搜索,使用镜像自带的模型文件。 |
LOOM_EMBEDDING_MODEL=fake-ngram-3072, LOOM_EMBEDDING_DIM=3072 (检出代码) |
假嵌入器 | 搜索按字符 n-gram 排序。足以检查接线是否正确,但不能用于召回。 |
两种安装方式都会生成唯一的 COMPOSE_PROJECT_NAME、随机的 JWT 签名密钥、随机的提取器令牌,以及 LOOM_BIND_HOST=127.0.0.1。因此不同的克隆不会悄悄共享 ClickHouse 卷,并且 Loom 和 ClickHouse 只能从这台计算机访问。
要使用真实的提供方,请打开 Settings → Models & keys,选择你的提供方和模型,输入它们的 API 密钥,然后点击 Test & apply。同一个 OpenAI API 密钥可以同时用于 LLM 和嵌入。无需重启 Docker;嵌入的更改会触发经过验证的重建,进度和重试会显示在控制台中。
若改用基于环境变量的部署,请替换 ~/.loom/.env(发布的堆栈)或 .env(检出代码)中的提供方行。仅设置 OPENAI_API_KEY 不会改变任何东西:默认的提供方行显式指定了它们的提供方。从本地或 fake 嵌入器切换走时,会对已存储的内容重新嵌入。
LOOM_EMBEDDING_MODEL=text-embedding-3-large
LOOM_EMBEDDING_DIM=3072
LOOM_LLM_PROVIDER=openai
LOOM_LLM_MODEL=gpt-6-luna
OPENAI_API_KEY=sk-...
对于 Claude、OpenAI、托管嵌入、仅限订阅的客户端以及使用单一 LLM 提供方的部署,请按配置模型和 API 密钥操作。仅在编辑了已发布堆栈的 .env 之后,才用 docker compose --project-directory "$HOME/.loom" up -d --force-recreate loom 来应用它;单纯重启不会重新加载容器的环境变量。高级设置见部署 → 提供方。
检查堆栈
curl -fsS http://localhost:7777/v1/health | jq '{status, fake_embedding, fake_llm, providers_degraded, problems}'
docker compose --project-directory "$HOME/.loom" exec loom loom doctor
- 当 ClickHouse 可访问,并且除
code_tier_failing(某个仓库的代码索引层级失败)之外没有其他问题属于错误时,/v1/health返回status: ok。fake_embedding、fake_llm和providers_degraded说明你处于哪种模式;problems列出每个问题及其修复方法;schema.pending列出尚未应用的迁移。 loom doctor对每项服务器端检查打印一行。--json给出 JSON。对于源码检出堆栈,请运行docker compose --env-file .env -f compose.yaml -f dev/docker-compose.dev.yml exec loom loom doctor。
2. 打开控制台
在 single-user 模式下,http://localhost:7777/ 会直接打开控制台;在多用户模式下,需要先注册或登录。在 single-user 模式下,控制台和 agent 的默认值使用 dev/local(LOOM_DEFAULT_NAMESPACE 可重命名该命名空间)。这是一种便利模式,不是用户隔离边界:任何能够访问该服务器的人都可以访问其数据并进行管理。请仅限 localhost 访问。
如果想改为试用注册功能(trust-network:使用邮箱和密码,第一个认领某个命名空间名称的人会成为该命名空间的管理员),请替换 ~/.loom/.env(发布版部署)或 .env(源码检出部署)中的这些条目:
LOOM_IDENTITY_PROVIDER=trust-network
LOOM_AUTH_REQUIRED=true
LOOM_SELF_SIGNUP=open
如果显式选择了 single-user,仅设置 LOOM_AUTH_REQUIRED=true 是不够的:该模式会保持认证关闭。请保留安装程序生成的 LOOM_JWT_SECRET 和现有的卷,然后重新创建服务器以加载环境变量:
# Released stack:
docker compose --project-directory "$HOME/.loom" up -d --force-recreate loom
# Checkout stack (run from the repository root):
docker compose --env-file .env -f compose.yaml -f dev/docker-compose.dev.yml --profile bundled up -d --force-recreate loom
此后控制台会打开登录页面,页面上有 Sign up 标签页,并且每次 SDK 和 MCP 调用都需要令牌。身份模式请参见身份与命名空间。显式指定 trust-network 也能让非回环的 LOOM_BIND_HOST 在开放注册的情况下启动,因此任何能访问该端口的人都可以注册。在让团队访问服务器之前,请按照部署指南配置运维访问,并参阅 TLS。
3. 获取令牌
在单用户模式下,令牌是可选的。即便如此也建议生成一个,这样在开启认证后,只要脚本指明了自己的 org(或将其留空)、namespace 和 agent,脚本就能继续工作:发送凭据的调用(SDK 在找到凭据时就会这样做,见 Python SDK → 凭据)不会自动补全这三项,而留空的 org 就是令牌自身所属的 org。
- 控制台: Settings → Tokens → New token。默认情况下,令牌可以读取你所属的每个命名空间和仓库(受限仓库只有在你添加后才可读取),但不能读取任何 collection,并且会保存到你当前所在的命名空间。Only what you choose 会把令牌限制在你勾选的命名空间、collection 和仓库内(起初一项也不选);勾选的条目按列出的顺序搜索,你可以用每行的箭头调整顺序,在桌面端也可以拖动该行的拖动手柄。结果页只显示一次令牌,并附带适用于你的 MCP 客户端或脚本的配置方法。
-
CLI,以运维人员身份: 在持有签名密钥的服务器容器内运行:
docker compose --project-directory "$HOME/.loom" exec loom loom mint-token --subject my-bot --org dev --namespaces local --roles writer凡是会离开你本机的令牌,都应加上
--ttl-days 30。loom mint-token --help会列出用于限定范围的选项(--namespace-role、--read-scope、--traffic-class)。
- 自行注册的 bot(仅限信任网络):
loom init --agent nightly-triage --server-url http://localhost:7777会创建命名空间agent-nightly-triage,把一个 writer 令牌保存到~/.loom/token,把 URL 保存到~/.loom/config.json,并输出一个认领码。由一个人在/oauth/agent-claim输入一次该认领码,并设置自己的密码,即可接管所有权。
把令牌保存到 SDK、CLI 和插件会查找的位置:
mkdir -p ~/.loom && (umask 077; printf '%s' "<token>" > ~/.loom/token)
export LOOM_API_KEY="<token>"
声明(claims)、角色和授权的说明见 令牌与授权。
4. 通过 HTTP 写入第一条记忆
每个操作都是一个 POST /v1/<op> 请求,请求体为 JSON。使用安装程序或源码检出得到的全新安装,在保留默认 .env 的情况下是单用户模式:无需令牌,日常的记忆或搜索调用(memory.set、memory.get、memory.search 等)如果没有指定 org 或 namespace,就会在本次安装自己的 org dev 和命名空间 local 中运行,MCP 和控制台使用的也是这一组;没有指定 agent 的 memory.set 会被记录为 agent http,而搜索会读取所有 agent 的记忆。因此下面的调用只需要填写各自的字段(哪些操作适用)。如果不带令牌的调用返回 401 AUTH_INVALID,说明已启用鉴权:请添加 -H "Authorization: Bearer $LOOM_API_KEY",并指定你账户的 org、namespace 和 agent;令牌为空的请求头会被拒绝。
curl -sX POST http://localhost:7777/v1/memory.set -H 'Content-Type: application/json' \
-d '{"memory_key":"deploy_window","value":"Tue and Thu only; never Friday."}'
curl -sX POST http://localhost:7777/v1/memory.get -H 'Content-Type: application/json' \
-d '{"memory_key":"deploy_window"}' | jq '{found, value}'
curl -sX POST http://localhost:7777/v1/memory.search -H 'Content-Type: application/json' \
-d '{"query":"when can we deploy?"}' | jq '.results[0].content_excerpt'
memory.set 的响应包含 memory_id、content_sha256 和 status。memory.get 读回一个键:found 表示该键是否持有有效值,value 是写入时的原值。搜索响应包含 results 和 abstain,后者表示最佳命中是否足够可靠,可以据此作答。搜索会读取该命名空间中所有 agent 的记忆,包括在控制台中添加的记忆;指定 agent 则只读取该 agent 的记忆。GET /v1/operations 会列出所有操作,在 http://localhost:7777/docs 中可以直接在浏览器里试用每个操作。各操作的数据结构见 HTTP API 参考。
5. 用 Python 创建第一条记忆
pip install clickhouse-loom # or, from a clone: pip install ./sdk/python
尚未发布到 PyPI 的版本可从其发布资源安装(从 GitHub Release 安装)。
示例中指定了 org 和 namespace,因此无论是否使用第 3 步中的令牌都可以运行,SDK 在找到令牌时会自动发送。在单用户服务器上,不带令牌的调用可以省略这两项:Agent(agent="quickstart", base_url=...) 同样在 dev/local 中运行。
import asyncio
from loom import Agent
async def main():
async with Agent(
org="dev",
namespace="local",
agent="quickstart", # names the writer in the audit log
base_url="http://localhost:7777",
) as a: # sends a credential it finds; none needed in single-user mode
await a.memory.set("standup_time", "Daily standup is at 9:30.")
row = await a.memory.get("standup_time") # None when the key is unset
print(row["value"] if row else "unset")
for hit in await a.memory.search("when is standup?"):
print(hit.content_excerpt)
asyncio.run(main())
SDK 如何查找服务器和凭据,参见 Python SDK → 凭据。TypeScript SDK 通过 npm install @clickhouse/loom 安装(从克隆安装)。
客户端接口请参阅 Python SDK 和 TypeScript SDK 参考文档。
6. 通过编码 agent 创建第一条记忆
如果安装程序已经连接了你的 agent,请直接跳到本节的最后一段。
对于 Claude Code,请安装 Loom 插件。它在 MCP 工具之上增加了 hook(会话开始时加载上下文,结束时捕获)和 skill:
claude plugin marketplace add ClickHouse/loom
claude plugin install loom@loom
如果服务器是本机上的单用户服务器,请保留默认的服务器 URL,并在 Claude Code 询问插件设置时将令牌留空。
如果不使用插件,可以直接添加 MCP 条目:
claude mcp add --transport http loom "http://localhost:7777/mcp?toolset=coding" -s user
这两种方式都无需你提供令牌,即可连接本机上的单用户服务器。
如果启用了认证,请在 Settings → Tokens 中创建令牌,然后在 Connect 下选择 Claude Code:对话框会显示插件以及 claude mcp add 条目的设置,其中包含该令牌。然后:
- 用对话框中的
config.json代码块,加上该令牌保存记忆所用的命名空间("namespace": "<namespace>"),覆盖~/.loom/config.json:单用户会话留在文件中的org或namespace优先于令牌;如果没有设置,插件会写入该令牌的第一个非*命名空间,否则写入coding。请把你之前设置过的code_repo或agent加回去。 - 保持
LOOM_API_KEY为空(第 3 步可能导出过该变量:unset LOOM_API_KEY),插件的token选项也保持为空,或者将它们设置为新令牌:插件会先读取这两者,再读取该文件(配置)。 - 如果之前添加的
claude mcp add条目没有带令牌,请先将其删除(claude mcp remove loom -s user),再运行对话框中的命令,因为该命令会拒绝已存在的名称。
loom install --client <name> 会为 Claude Desktop、Claude Code、Codex、Cursor、VS Code、Cline、Windsurf 和 Zed 写入 MCP 条目;不带该标志时,它会连接所有找到的客户端。连接编码 agent 介绍了 Codex 和 Cursor。
开始一个新会话,然后说:"记住,我从不在周五部署。" agent 会调用 loom_memory_set。在一个全新的会话中问:"我什么时候可以部署?" agent 会调用 loom_search,并根据存储的事实回答。模型根据工具描述来决定何时保存和搜索,不需要触发词。
7. 在控制台中查看
| 页面 | 显示内容 |
|---|---|
/memories |
命名空间中的记忆,包含写入者和时间。 |
/admin/activity |
审计日志:哪个 agent 在何时写入了哪个键。 |
/admin/usage |
按操作和 agent 统计的成本。 |
其余内容见控制台。
可选:在已发布的栈上为仓库建立索引
在这个栈上,从控制台添加仓库会被拒绝,并返回 SANDBOX_UNAVAILABLE:添加仓库需要仓库任务沙箱,而 Docker 的默认隔离会阻止沙箱运行,所以这个栈没有启用它。只列出你信任的仓库:它们的构建步骤(TypeScript 依赖安装、Go 模块下载、CMake)会在没有沙箱的情况下,在 loom 容器中运行,而该容器的环境中保存着 JWT 密钥和提供方密钥。
LOOM_CODE_REPOS_JSON 是一行内容,以 JSON 数组的形式包含所有仓库(配置条目)。在 ~/.loom/.env 中取消这一行的注释(如果没有就添加),然后编辑它。dev 是单用户栈所使用的组织,也是多用户账户注册时加入的组织(LOOM_SELF_SIGNUP_ORG);如果你修改过它,请在这里以及下面的 --org 中使用你账户所在的组织:
LOOM_CODE_REPOS_JSON=[{"org":"dev","namespace":"code-myrepo","repo":"acme/myrepo","git_branch":"main","public":true}]
- Loom 会根据仓库的构建文件(
go.mod、package.json、pyproject.toml、根目录的CMakeLists.txt等)选择编译器层级的索引器;也可以用scip_producer指定一个(编译器层级)。C/C++ 还需要已配置好的构建目录,没有的话,C/C++ 仓库只会使用解析器层级。 - 对于私有仓库,请添加 GitHub 令牌(在
.env中设置LOOM_CODE_GITHUB_TOKEN,或在条目中设置github_token),并去掉"public":true:该选项适用于在其托管平台上公开的仓库,设置后组织内的任何人都可以在Repositories中立即以读者身份加入索引。请在第一次运行loom code init之前决定好:它会根据public设置命名空间的加入策略,之后再修改public不会改变该策略(维护者可以用code.repo.set_access修改)。
然后重新创建 loom 容器并运行第一次索引:
docker compose --project-directory "$HOME/.loom" up -d --force-recreate loom
docker compose --project-directory "$HOME/.loom" exec loom loom code init --namespace code-myrepo --org dev
docker compose --project-directory "$HOME/.loom" exec loom loom code backfill --namespace code-myrepo --org dev --embed
backfill --embed 在已发布的栈上使用本地 embedder 运行。如果使用的是假 embedder(检出代码中的 .env,或仍然指定 fake-ngram-* 的升级安装),该命令会拒绝并退出;若仍想试用这套配置,请添加 --allow-fake-embedder。之后在 Settings → Models & keys 中选择模型会重新为代码索引生成嵌入;修改 .env 之后则需要单独重新生成嵌入,详见模型与密钥。
在多用户模式下,列出的仓库没有维护者,因此如果没有 "public":true,读者的加入请求会一直等待,没有人可以批准。运行 loom code init 之后,请以运营者身份用容器中签发的令牌为某人授予访问权限:admin 使其成为维护者,此后由其批准读者;viewer 则只允许读取。subject 是该账户注册时使用的命名空间(即其登录名,也是其令牌的 subject);自助注册的电子邮件从未经过验证,所以授予邮箱不会让任何人获得访问权限:
ADMIN_TOKEN=$(docker compose --project-directory "$HOME/.loom" exec -T loom loom mint-token --subject operator --org dev --namespaces code-myrepo --roles admin --ttl-days 1)
curl -s http://localhost:7777/v1/grants.create -H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"org":"dev","namespace":"code-myrepo","subject":"your-namespace","role":"admin"}'
可选:针对文档提问
loom demo
loom demo 会上传本仓库的 AGENTS.md,用 knowledge.ingest 对其进行摄取(由技术栈的参考提取器解析),再用 knowledge.synthesize 针对该文档提问,并打印答案及其引用的分块。使用 fake LLM 时,它会改为打印 knowledge.search 的最佳命中结果。--file 和 --question 可让它处理你自己的文档。
常见问题
| 现象 | 原因与解决方法 |
|---|---|
set_from_messages 没有写入任何事实 |
LLM 是模拟的。请按照模型与密钥配置一个真实的 LLM。 |
| 搜索结果看起来杂乱无序 | 嵌入模型是模拟的(.env 中为 fake-ngram-*)。请按模型与密钥中的说明切换,已存储的内容会被重新嵌入。不要为了更换模型而删除数据卷。 |
开启认证后返回 401 AUTH_INVALID |
没有提供令牌,或令牌由其他 LOOM_JWT_SECRET 签发。请使用获取令牌中的 Compose 命令重新生成。 |
| 控制台返回 503 | 服务器从源码运行(make server),但没有构建前端。请运行 make frontend-build。 |
| 发布版部署无法变为健康状态 | 运行 docker compose --project-directory "$HOME/.loom" logs --tail 100 loom clickhouse。参见故障排查。 |
添加仓库时返回 SANDBOX_UNAVAILABLE |
该部署运行时没有仓库任务沙箱。请通过 LOOM_CODE_REPOS_JSON 为仓库建立索引(为仓库建立索引)。 |
安装程序提示端口 7777 已被占用 |
其他程序或另一个 Loom 正在监听该端口。请停止它,或在 sh loom-install.sh 前加上 LOOM_PORT=7778 重新运行安装命令;.env 会保留该端口。 |
安装程序提示端口 7777 没有响应 |
有程序占用了该端口却不响应,或者 LOOM_BIND_HOST、LOOM_PORT 或防火墙使本机无法访问该端口。 |
安装程序无法检查端口 7777 |
curl 失败,原因见其退出码;请检查 LOOM_BIND_HOST 和 LOOM_PORT。 |
在 WSL 上使用 Docker Desktop 时,安装中止并提示 Ports are not available |
Windows 占用或保留了该端口,而安装程序在 WSL 内的检查无法发现。netsh interface ipv4 show excludedportrange protocol=tcp 会列出保留的端口范围;请在 sh loom-install.sh 前加上位于这些范围之外的 LOOM_PORT,重新运行安装命令。 |
克隆的仓库中端口 8123 或 9000 被占用 |
重新映射 ClickHouse 的主机端口(本地部署)。 |
| 安装程序无法拉取镜像 | 由 Docker 自己访问镜像仓库:如果位于代理之后,请为 Docker 守护进程配置代理设置。 |
下一步
- 评估 Loom:将这次冒烟测试扩展为针对具体工作负载的质量、延迟和成本评估。
- 连接编码 agent:在此技术栈上使用 Claude Code、Codex 或 Cursor。
- 你的第一个 agent:通过 SDK 使用身份、弃答处理、会话、上下文包和运行。
- 部署:为团队运行 Loom。