Loomem

---

Loomem 是面向大模型 Agent 的开源上下文层——一个运行在笔记本电脑上的 Rust 单一二进制程序，通过 MCP 提供服务，为 Claude、ChatGPT、Codex 或任何 MCP 客户端提供完成实际工作所需的事实、决策和历史记录。更换模型，切换工具；你的上下文始终相随。

Loomem 会存储从对话中提取的结构化知识，并通过混合检索将其提供给任何支持 MCP 的客户端（Claude、ChatGPT、Codex、Cursor 以及你自己的 Agent）：

• 混合搜索——BM25（Tantivy）+ 向量嵌入 + 实体图信号，通过加权混合得分进行融合（向量 0.6 / BM25 0.4）。
• 整合——后台工作进程会合并相关事实、解决矛盾，并让过时事实逐渐衰减（“做梦”）。
• 双时态模型——事实同时记录摄取时间和事件时间（valid_from / valid_until），因此“我在 3 月知道什么”和“3 月发生了什么”是不同的查询。
• 实体图——从人员、项目和技术中提取实体，构建包含别名和关系的图，同时用于检索和探索。
• MCP 原生——通过标准 MCP HTTP 传输提供 15 个 memory_* 工具，其中包括面向远程连接器的 OAuth 动态客户端注册。
• 静态加密（可选）——采用字段级 AES-GCM 信封加密，主密钥从环境中读取。

使用 Rust、RocksDB 和 Tantivy 构建。单一二进制程序，无需外部服务。

状态：早期阶段。 该引擎已在个人日常使用中运行一段时间，但公共 API 和存储格式仍可能发生变化。可能存在一些不够完善之处；欢迎提交问题和 PR。

快速开始

从零开始，让 Claude 在不同对话间记住信息，适用于 macOS 或 Linux。每个步骤彼此独立，请按顺序执行。

1. 安装二进制文件（无需 sudo；安装到 ~/.loomem）：

curl -fsSL https://raw.githubusercontent.com/vvooki-sys/loomem/main/install.sh | sh

2. 将 ~/.loomem/bin 添加到 PATH（安装程序也会打印此说明）：

echo 'export PATH="$HOME/.loomem/bin:$PATH"' >> ~/.zshrc   # or ~/.bashrc
exec $SHELL

3. 下载本地嵌入模型（约 113 MB，仅需下载一次）。安装程序不会下载该模型；没有它，服务将拒绝启动：

curl -fsSL https://raw.githubusercontent.com/vvooki-sys/loomem/main/scripts/fetch-embedding-model.sh | sh

4. 设置 LLM 密钥，用于提取、整合和梦境处理，或者接受无密钥模式（参见 常见问题）：

export OPENAI_API_KEY="sk-..."     # or: export LOOMEM_ALLOW_KEYLESS=1

5. 启动服务（配置已预置在 ~/.loomem 中）：

cd ~/.loomem && loomem-server

6. 检查服务是否运行（在另一个终端中）：

curl http://localhost:3030/health
# {"status":"ok","version":"0.5.4"}

安装程序默认使用端口 3030，若该端口已被占用，则会询问是否使用其他端口（设置 LOOMEM_PORT 可跳过提示）。如果选择了其他端口，请在下面的命令中使用该端口。

7. 连接 Claude Code：

claude mcp add --transport http loomem http://localhost:3030/mcp

7b. 想改用 Claude 桌面应用（或 Cowork）？ 它通过 stdio 而非 HTTP 连接本地服务，因此需要在 claude_desktop_config.json 中配置桥接，然后重启 Claude。原生支持，无需 Node（Loomem ≥ v0.2.1）：

{ "mcpServers": { "loomem": { "command": "/absolute/path/to/.loomem/bin/loomem-cli", "args": ["mcp-stdio", "--url", "http://127.0.0.1:3030"] } } }

（任何版本均可使用，但需要 Node："command": "npx", "args": ["-y", "mcp-remote", "http://127.0.0.1:3030/mcp", "--allow-http"]。）有关身份验证和详情，请参阅连接 MCP 客户端。

8. 试试看。 在 Claude 中输入：“记住，我在所有工具中都偏好深色模式。” 然后在一个新的对话中输入：“你知道我的偏好吗？” ——答案将由 Loomem 提供。

其他客户端（claude.ai、ChatGPT、OpenClaw）、TLS／远程访问，以及完整的选项列表，请参见下文和 docs/installation.md。

安装

一行命令（预编译二进制文件，macOS + Linux）

curl -fsSL https://raw.githubusercontent.com/vvooki-sys/loomem/main/install.sh | sh

将 loomem-server、loomem-cli 和 loomem-migrate 安装到 ~/.loomem/bin（无需 sudo），并将配置模板放入 ~/.loomem。使用 LOOMEM_VERSION=v0.2.0 固定版本，使用 LOOMEM_INSTALL_DIR 更改安装位置。归档文件会根据发布页面中的 SHA256SUMS 进行校验。安装程序不会下载本地嵌入模型：请按照快速开始的第 3 步下载。

完整指南——需求、固定版本、手动校验校验和、升级、卸载和故障排查：docs/installation.md。

从源代码构建

git clone https://github.com/vvooki-sys/loomem.git
cd loomem
cp entities.toml.example entities.toml   # personal entity config (gitignored)
(cd loomem-dashboard && npm ci && npm run build)   # dashboard, embedded at compile time
./scripts/fetch-embedding-model.sh                 # local embedding model → ~/.loomem/models
cargo build --release -p loomem-server -p loomem-cli
export OPENAI_API_KEY="sk-..."   # or LOOMEM_ALLOW_KEYLESS=1 to run without a key (see below)
cargo run --release -p loomem-server
# server listens on http://127.0.0.1:3030, data in ./data

需要 Rust（stable）、Node.js（用于仪表板）和 libclang（用于构建 RocksDB）：在 Debian／Ubuntu 上运行 apt install libclang-dev，macOS 上则随 Xcode CLT 一同安装。在 Windows 上，请参阅 INSTALL_WINDOWS.md。

即使跳过某个步骤不会导致构建失败，每一步仍然很重要：不构建仪表板，仪表板就会返回 404；不构建 loomem-cli，Claude 桌面应用就没有 stdio 桥接。本地嵌入模型是必需的：使用默认设置 embedding_provider = "local" 时，无论是否提供 API 密钥，如果没有该模型，服务都会拒绝启动（refusing cloud fallback）。默认配置还启用了由 LLM 支持的提取和梦境处理，因此除非设置 LLM 密钥（export OPENAI_API_KEY=...）或设置 LOOMEM_ALLOW_KEYLESS=1，否则服务拒绝启动。在无密钥模式下，memory_ingest 会返回缺少密钥错误且不存储任何内容；实体提取会关闭，梦境处理会失败；memory_store 和搜索仍可正常使用。

Docker

docker build -t loomem .
export LOOMEM_AUTH_TOKEN=$(openssl rand -hex 32)
export LOOMEM_AT_REST_MASTER_KEY=$(openssl rand -base64 32)
export OPENAI_API_KEY="sk-..."
docker run -p 3030:3030 -v loomem-data:/data \
  -e LOOMEM_AUTH_TOKEN -e LOOMEM_AT_REST_MASTER_KEY -e OPENAI_API_KEY \
  -e LOOMEM_EMBEDDING_PROVIDER=openai -e LOOMEM_EMBEDDING_DIM=1536 loomem

仅在本地（环回地址）运行时，默认关闭身份验证。Docker 镜像绑定到 0.0.0.0，因此服务需要设置 LOOMEM_AUTH_TOKEN（未设置时拒绝启动），并且根据镜像默认设置，需要主密钥来加密静态数据。将密钥作为 Authorization: Bearer <key> 传递。可选择主动关闭这些功能：LOOMEM_ALLOW_UNAUTH=1（无身份验证）和 LOOMEM_AT_REST_EXPECT_ENABLED=0（静态数据以明文存储）——请参阅 docs/SECURITY.md。

镜像不包含本地嵌入模型，因此该命令会将嵌入切换到 OpenAI（LOOMEM_EMBEDDING_PROVIDER=openai、LOOMEM_EMBEDDING_DIM=1536），并传入 OPENAI_API_KEY。存储的文本随后会发送到 OpenAI API。若未设置这些变量，服务将拒绝启动（refusing cloud fallback）。

连接 MCP 客户端

Loomem 通过 /mcp 上的可流式 HTTP 提供 MCP 服务。任何兼容 MCP 的客户端都可以使用；以下是常见客户端的配置示例：

Claude Code

claude mcp add --transport http loomem http://localhost:3030/mcp

Claude 桌面应用（及 Cowork）— 本地 stdio 桥接

Claude 桌面应用（及 Cowork）通过 stdio 连接本地 MCP 服务，而不是通过 HTTP；设置中的“Add custom connector”框仅接受 https:// URL，因此不能在其中粘贴 http://localhost:3030/mcp。你需要将 Loomem 的本地 HTTP 端点桥接到 stdio。将以下任一配置块添加到 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/claude_desktop_config.json；Windows：%APPDATA%\Claude\claude_desktop_config.json），然后完全重启 Claude。

推荐 — 原生桥接，无需 Node（Loomem ≥ v0.2.1；你已安装的 loomem-cli 已包含此功能）：

{
  "mcpServers": {
    "loomem": {
      "command": "/absolute/path/to/.loomem/bin/loomem-cli",
      "args": ["mcp-stdio", "--url", "http://127.0.0.1:3030"]
    }
  }
}

请使用 loomem-cli 的绝对路径（例如 /Users/you/.loomem/bin/loomem-cli）——桌面应用不会继承 shell 的 PATH。如果启用了身份验证，请在 args 中添加 "--token", "<your token>"，或在 "env" 块中设置 LOOMEM_AUTH_TOKEN。

替代方案 — mcp-remote（适用于任何版本，需要 Node 18+ / npx）：

{
  "mcpServers": {
    "loomem": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:3030/mcp", "--allow-http"]
    }
  }
}

由于端点是 localhost 上的纯 HTTP，因此必须使用 --allow-http。若要启用身份验证，请在 args 中追加 "--header", "Authorization: Bearer ${LOOMEM_AUTH_TOKEN}"，并添加 "env": { "LOOMEM_AUTH_TOKEN": "<your token>" }。这两个配置块也适用于其他任何仅支持 stdio 的桌面客户端。（Claude Code 是个例外——它原生支持 HTTP，因此请使用上面的 claude mcp add 配置示例，而不是桥接方案。）

Claude — 远程连接器（HTTPS，托管在其他位置）

若要连接运行在另一台机器上的 Loomem 实例，claude.ai/desktop 的远程连接器使用 HTTPS 通信。请通过启用 TLS 的反向代理（或 Cloudflare Tunnel 之类的隧道）公开你的实例，设置 SERVER_ORIGIN=https://your-domain（此项为必需，确保 OAuth 元数据公布正确的 URL），然后在 Claude 设置中添加连接器，并将其指向 https://your-domain/mcp。Loomem 开箱即支持 OAuth 动态客户端注册（/.well-known/oauth-authorization-server）。

ChatGPT — 自定义连接器

ChatGPT 的自定义连接器需要 HTTPS 和 OAuth（不支持静态 API 密钥）；必须启用开发者模式（Pro/Team/Enterprise 方案）。按上述方法通过 HTTPS 公开服务，然后依次选择：ChatGPT → Settings → Connectors → Add custom connector → 粘贴 https://your-domain/mcp 并完成 OAuth 流程。

OpenClaw

openclaw mcp add loomem --url http://localhost:3030/mcp --transport http \
  --header "Authorization: Bearer $LOOMEM_AUTH_TOKEN"

对于远程 OpenClaw 网关，请将 --url 指向你的 HTTPS 端点。

通用 MCP 客户端配置

{
  "mcpServers": {
    "loomem": {
      "type": "http",
      "url": "http://localhost:3030/mcp",
      "headers": { "Authorization": "Bearer <your LOOMEM_AUTH_TOKEN>" }
    }
  }
}

独立服务注意事项

一个 Loomem 实例可以同时为多个客户端提供服务（例如，在本地运行的 Claude Code、通过 HTTPS 端点连接的 ChatGPT 等）——它们共享相同的上下文。除非前面配置了 TLS + 身份验证，否则请将绑定地址保持为 127.0.0.1；切勿将裸 HTTP 端口暴露到互联网。

架构

                    ┌──────────────────────────────────────────────┐
                    │                loomem-server                 │
 MCP client ──────► │  /mcp (JSON-RPC) ── dispatcher ─┐            │
 HTTP client ─────► │  /v1/* + /api/* ─── handlers ───┤            │
                    └─────────────────────────────────┼────────────┘
                                                      ▼
                    ┌──────────────────────────────────────────────┐
                    │                 loomem-core                  │
                    │  hybrid search (BM25 + vector + graph + RRF) │
                    │  consolidation / decay / dream workers       │
                    │  entity extraction + alias graph             │
                    │  encryption at rest (optional)               │
                    └───────┬───────────────┬──────────────────────┘
                            ▼               ▼
                       RocksDB          Tantivy
                  (chunks, graph,    (full-text index)
                   embeddings)

工作区 crate：loomem-core（引擎）、loomem-server（HTTP/MCP 服务）、loomem-migrate（离线数据库维护）、loomem-cli（命令行客户端）。

文档

• 快速入门
• 配置
• API 参考
• MCP 工具
• 架构
• 部署
• 安全模型
• 备份与恢复

常见问题

Loomem 是什么？ 面向大模型 Agent 的开源上下文层。它使用 Rust 编写，以单个二进制文件的形式运行，基于 RocksDB 和 Tantivy，并通过模型上下文协议（MCP）提供服务。它为 Claude、ChatGPT、Codex 或任何 MCP 客户端提供完成实际工作所需的事实、决策和历史记录——可移植、本地优先，且由你掌控。

Loomem 与 mem0、Zep、Letta 和 cognee 有何不同？ Loomem 以单个 Rust 二进制文件的形式发布，无需外部服务——大多数替代方案都需要单独的向量数据库和／或图数据库。它在上下文所有权和可移植性方面表现突出，可完全自托管并采用本地优先模式，支持使用本地 ONNX 模型离线生成嵌入，并且开箱即用，原生支持 MCP。

Loomem 免费且开源吗？ 是的——采用 Apache-2.0 许可证，可免费自托管。源代码位于此仓库中。

Loomem 是否需要互联网连接或 OpenAI？ 核心功能无需互联网连接。嵌入可通过本地 ONNX 模型在设备上运行，上下文的存储和搜索也完全支持离线使用。只有由大模型支持的步骤（memory_ingest 提取、整合、梦境处理、矛盾检测）需要 OpenAI API 密钥；没有密钥时，这些步骤将不可用，且默认配置仅在设置 LOOMEM_ALLOW_KEYLESS=1 后才能启动，而 memory_store 和搜索仍可正常使用。

哪些大模型客户端可以连接？ 任何支持 MCP 的客户端。Loomem 通过可流式传输的 HTTP 提供 MCP，并为 Claude、Claude Code、ChatGPT、Codex 和 Cursor 提供配置指南，同时支持远程连接器的 OAuth 动态客户端注册。

为什么不直接使用 ChatGPT 或 Claude 的内置记忆？ 内置记忆被锁定在单一供应商的平台中。Loomem 让你的上下文可在所有工具和模型之间移植，由你自托管和掌控，并提供结构化实体图谱和双时间历史记录——这些是单一供应商的功能无法提供的。

作者

Loomem 由 Łukasz Gumowski 创建并维护——[email protected]。

许可证

Apache-2.0。请参阅 LICENSE。