内容
align="center">
<img src="https://img.shields.io/badge/python-10+-blue?style=for-the=python" alt="Python 3.10+">
<img src="https://img.shields.io/badge/protocol-MCP-green?style=for-the-badge" alt="MCP Protocol">
<img src="https://img.shields.io/badge/version-0.4.0-orange?style=for-the-badge" alt="Version 0.4.0">
<img src="https://img.shields.io/badge/license-MIT-lightgrey?style=for-the-badge" alt="MIT License">
</p>
<h1 align="center">🧠 Loom</h1>
<p align="center"><strong>人工智能代理的共享内存 - 任何代理学习的内容都属于整个组织。</strong></p>
<p align="center">只需一次 <code>pip install</code>。粘贴一个 JSON 块。每个代理都随着变得更智能。</p## 快速开始
Desktop
```bash
loom-learn # 一条命令
loom init #配置 → 粘贴到 Claude Desktop
# 重启 Claude Desktop # 完成
```
### Claude Code (CLI)
将以下内容添加到 `~/.claude/settings.json` 或项目的 `.claude/settings.json` 中：
```json
{
"mcpServers": {
"loom": {
"command": "python3",
"args": ["-m", "loom.mcp"],
"env": {
"LOOM_PROJECT_ROOT": "/path/to/your/project"
}
}
}
}
```
然后重启 Claude Code。就这样 - Loom 会在您的第一个工具调用时自动注入上下文。
Loom 免费提供关键词提取功能。要使用 LLM 进行更智能的提取，请将您的 API 密钥添加到 `env` 块中：
```json
"env": {
"LOOM_PROJECT_ROOT": "/your/project/path",
"ANTHROPIC_API_KEY": "sk-ant-..."
}
```
DeepSeek 或 Gemini？只需更换密钥 - Loom 会自动检测提供商。
验证：
```bash
loom doctor # 本地健康检查
loom doctor --preflight # 在重启前验证 MCP 配置
```
---
## Loom 的功能
Loom 是您团队的共享。每个代理都从中读取和写入。当发现约定（convention）时，每个代理都知道。当高级某个模式（pattern）的重要性时，每个新入职员工的代理在第一天就能获得该上下文。
| 功能 | 描述 |
|-----------|-------------|
| **自动学习** | 钩子自动触发 - 无需代理记住调用任何内容 |
| **自动回忆** | 在第一次工具调用时注入相关上下文 - 顶部提醒、领域规则、辅导、组织范围内的知识 |
| **教学** | 显式注入约定 - 代理，教授它，团队| **入职培训 新入职员工的代理已经了解组织 - 23 个内置角色，从后端到支持 |
| **继任**在人员流动中存 在有人离开之前捕获 |
| **辅导**顶级表演者的模式 用上下文放大关键规则其重要性 |
|** | 分级保留衰减 - 永久组织知识永不过期，瞬时模式逐渐消失 |
| **的访问控制（RBAC）** | 五个许可级别，在每个读取路径上强制执行 - 公共、内部密、受限、秘密 |
| **时间线** | 可审计的组织历史记录 - 按领域、项目或所有学习内容 |
| **联合** | 跨项目知识 - 将其他项目的规则引入组织存储 |
| **删除敏感信息** | 在每个写入路径上自动剥离机密 - API 密钥、令牌、凭证、电子邮件、IP 地址从不存储 |
| **私有模式** | `LOOM_PRIVATE_MODE=1` 在保持召回可用的情况下阻止所有内存写入 |
| **云后端** | 通过 Supabase 的 Postgres - `loom cloud setup` 为团队提供共享数据库 |
| **代理模式** | Loom 作为单个 MCP 入口点 - 观察每个转发的工具调用 |
---
## 18 个 MCP 工具
### 学习
| 工具 | 描述 |
|------|-------------|
| `teach` | 直接教授规则 - 自动捕获 |
| `learn` | 从观察中学习 - 自动捕获 |
| `reflect` | 从多个观察中提取模式 |
### 回忆
| 工具 | 描述 |
|------|-------------|
| `recall_relevant` | 自动为当前任务查找上下文 |
| `recall_memory` | 搜索已学习的约定 |
| `session_init` | 预加载上下文 - 自动触发 |
| `observe` | 被动后台捕获 - 自动触发 |
### 团队知识
| 工具 | 描述 |
|------|-------------|
| `onboard` | 为任何角色生成入职包 |
succession` | 捕获离职成员的知识 |
| `amplify` | 在团队中放大辅导 |
| `retain` | 标记规则以永久保留 |
| `set_clearance` | 按规则的访问控制 |
| `timeline` | 查询可审计的组织历史记录 |
| `federate` | 从其他项目导入规则 |
### 实用工具
| 工具 | 描述 |
|------|-------------|
| `export` | 导出规则（markdown、JSON、紧凑） |
| `export_timeline` | 导出完整的组织历史记录 |
| `get_stats` | 按领域、置信度、保留策略获取统计信息 |
| `store_out | 存储 PR 审查结果 |
---
## 双后端
**本地（免费，默认）：** 所有内容存储在 `.loom/` 中 - 具有原子、崩溃安全写入的 JSON 文件。零配置。将 `rules.json` 和 `conventions.md` 提交到 git，以便团队共享约定。
**云（团队）：** `loom cloud setup` 为团队提供一个 Supabase Postgres 数据库。组织中的每个代理都从同一个存储中读取和写入。实时共享内存。
```
免费（JSON）： 云（Postgres）：
loom init loom cloud setup
→ .loom/ 磁盘上 → Supabase 数据库
→ 提交到 git → 团队实时共享
→ 零成本 → 受管控，可扩展
```
---
## Loom 创建的内容
```
your-project/
└── .loom/
├── domains/ # 8 个领域 YAML 配置（编码、样式、架构、过程、测试、安全、文档、常规）
├── rules.json # 学习到的规则，带有置信度得分
├── conventions.md # 人类可读的约定文档
├── timeline.jsonl # 可审计的、追加的组织历史记录
├── retention.json # 永久到瞬时的保留策略
├── archive.json # 存档规则（永不丢失）
├── permissions.json # 按观察的基于角色的访问控制
├── # 基于角色的入职包
├── succession/ # 离职成员知识捕获
└── coaching/ # 辅导放大
```
自动生成 `.loom/.gitignore`，以便敏感文件（令牌、审计日志、权限）永远不会到达 git，而 `rules.json` 和 `conventions.md` 保持可共享。
---
## CLI 参考
```bash
loom init # 为 Claude Desktop 生成配置
loom setup # 与 init 相同
loom doctor # 健康检查 - Python、Loom、存储、LLM、MCP
loom doctor --preflight # 在重启前验证 MCP 配置
loom cloud setup # 为团队提供 Supabase 数据库
loom version # 打印已安装的版本
```
### 配置位置
| 客户端 | 配置文件 |
||
| Claude Desktop | `~/Library/Application Support//claude_desktop` (macOS) |
| Claude Code | `~/.claude/settings.json` 或 `.claude/settings.json` |
| Cursor | `~/.cursor/mcp.json` |
| Codex CLI | `~/.codex/config.toml` 或 `~/.codex/config.json` |
---
## 示例会话
```
[代理开始编码]
第一次工具调用 → 自动触发 session_init：
<!-- LOOM:AUTO_CONTEXT -->
## 🔍 相关约定（来自 Loom）
### ⚡ 顶部提醒
1. 所有公共函数必须具有类型提示（9/10）
2. 所有 I/O 操作都应使用 async/await（8/10）
3. 每个新端点都需要一个测试（9/10）
### 按领域划分
#### coding
- type_safety（9/10）：所有公共函数必须具有类型提示
- error_handling（8/自定义异常类
### 📢 辅导放大
- “使用 async/await 进行所有 I/O 操作” - Sarah Chen（高级工程师）
这很重要，因为同步 导致了 3 次生产事故...
### 🌐 组织范围内的知识
- [api-service] error_handling：始终包含请求 ID
- [shared-infra] process：合并前压缩提交
[代理继续。每次 teach/learn/amplify 自动观察。
会话结束 → 自动刷新将所有观察结果提取到规则中。]
```
---
## 代理模式
将 Loom 运行为客户端连接的**唯一** MCP 服务器。Loom 在内部启动其他 MCP 服务器，转发每个 JSON-RPC 消息，并观察每个转发的工具调用 - 无需教授，无需记住。
```bash
python3 -m loom.mcp --proxy
```
通过 `LOOM_PROXY_TARGETS` 配置服务器以转发（与 MCP 客户端的服务器配置相同）：
```json
{
"mcpServers": {
"loom": {
"command": "python3",
"args": ["-m", "loom.mcp", "--proxy"],
"env": {
"LOOM_PROJECT_ROOT": "/your/project",
"LOOM_PROXY_TARGETS": "{\"github\": {\"command\": \"npx\", \"args\": [\"-y\", \"@modelcontextprotocol/server-github\"], \"env\": {}}}"
}
}
}
}
```
Loom 的 18 种工具以及每个转发的工具都作为一个扁平的工具列表出现。发生崩溃的目标被标记为已死亡并快速失败 - 它永远不会挂起您的会话。
---
## 安全
- **每次写入路径都会进行数据脱敏。** 在任何数据到达存储之前，Loom 都会剥离：Anthropic/OpenAI 样式的密钥（`sk-ant-…`、`sk-proj-…`、`sk-…`）、Stripe（`sk_live_…` 访问密钥和秘密密钥、GitHub/GitLab 令牌（经典和细粒度）、Slack、Google、SendGrid、npm、PyPI、Hugging Face 令牌、JWT、承载令牌、PEM 私钥块、连接字符串密码、通用 `api_key=…` 赋值、电子邮件和 IPv4 地址。
- **在读取时强制执行基于角色的访问控制。** `set_clearance` 限制谁可以看到规则；`recall_memory`、`recall_relevant`、`export`、`timeline` 和 `onboard` 都根据通过 `LOOM_AGENT_ID` / `LOOM_AGENT_ROLE` / `LOOM_AGENT_TEAMS` 设置的代理身份进行过滤。
- **私有模式。** `LOOM_PRIVATE_MODE=1` 在保持召回可用的情况下阻止所有写入工具。
- **崩溃安全存储。** 在咨询文件锁的情况下，原子写入（临时文件 + fsync + 重命名）；损坏的文件被隔离以进行恢复，永远不会被静默丢弃。
发现漏洞？请参阅 [SECURITY.md](SECURITY.md)。
---
## 环境变量
| 变量 | 是否必需 | 默认值 | 描述 |
|----------|----------|---------|-------------|
| `LOOM_PROJECT_ROOT` | 否 | `$PWD` | 创建 `.loom/` 的位置 |
| `LOOM_STORAGE_BACKEND` | 否 | `json`` 或| `LOOM_DATABASE_URL` | 否 | — | Postgres |
| `LOG_STORE` | 否 | `.loom/org-store | 共享的组织范围内存路径 |
|ROPIC_API_KEY` | 否 | — | Anthropic LLM 提取 `LOOM_DEEPSEEK_API_KEY` | — | DeepSeek提取 |
| `GEMINI_API_KEY` | 否 | — | Gemini LLM |
| `LOLM_PROVIDER` | 自动检测 | ``、`deepseek` 或 `gemini` `LOOM_LLM | 否 | 提供 | 覆盖提取 |
| `LO_MODE` | 否 | `0` | `1` 阻止所有内存写入 |
| `LOOM_AGENT_ID` | 否 | `agent` | 基于角色的访问控制检查的身份 |
| `LOOM_AGENT_ROLE` | 否 | `member` | 基于角色的访问控制检查的角色 |
|OM_AGENT_TEAMS 否 | — | 基于角色的访问控制检查的逗号分隔团队 |
| `LOOM_PROXY_TARGETS 否 | — | 代理模式下转发 MCP 服务器的映射 |
|OM_DB_POOL_MIN` | `2 Postgres 连接池最小 |
| `LOOM_DB_POOL_MAX` | `20` | Postgres 连接池最大连接数 |
要求
| 要求 | 原因 |
|-------------|-----|
| 3.10 类型提示语法库改进 |
| **MCP 兼容客户端** | Claude Desktop，Claude Code，Cursor |
| ** API 密钥（可选）** | Anthropic，DeepSeek 或 Gemini。默认情况下免费关键词提取。 |
---
## 故障排除
```bash
loom doctor # 捕获大多数问题 doctor --preflight # 验证完整的 MCP 链
```
预飞行检查：配置文件中的 Python 路径存在，Loom 可导入，MCP 配置是有效的 JSON，存储路径可写入，MCP 模块加载时无错误。所有绿色则退出 0，任何失败时退出 1 并附带特定修复说明。
---
## 贡献
欢迎提交错误报告、功能想法和 PR参阅 [CONTRIBUT](CONTRIBUTING.md)。
```bash
git clone https://github.com/Kaushik-hub306/Loom.git && cd Loom
pip install -e ".[dev]"
python -m pytest # 159 个测试
ruff check loom/ tests/ # lint
mypy loom/ # 类型检查
```
## 许可证
[MIT](LICENSE)
---
<p align="center">
<sub>为希望其 AI 代理在每次交互中变得更智能并且永不遗忘的团队而构建。</sub>
</p>
