Loom

Quick Start

Claude Desktop

pip install loom-learn    # one command
loom init                 # prints config → paste into Claude Desktop
# restart Claude Desktop  # done

Claude Code (CLI)

Add to ~/.claude/settings.json or your project's .claude/settings.json:

{
  "mcpServers": {
    "loom": {
      "command": "python3",
      "args": ["-m", "loom.mcp"],
      "env": {
        "LOOM_PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

Then restart Claude Code. That's it — Loom auto-injects context on your first tool call.

Loom works for free with keyword extraction. To use an LLM for smarter extraction, add your API key to the env block:

"env": {
  "LOOM_PROJECT_ROOT": "/your/project/path",
  "ANTHROPIC_API_KEY": "sk-ant-..."
}

DeepSeek or Gemini? Just swap the key — Loom auto-detects the provider.

Verify:

loom doctor              # local health checks
loom doctor --preflight  # validates MCP config before restart

What Loom Does

Loom is your team's shared memory layer. Every agent reads from and writes to the same store. When one agent discovers a convention, every agent knows it. When a senior engineer shares why a pattern matters, every new hire's agent gets that context on day one.

18 MCP Tools

Learning

Recall

Team Knowledge

Utilities

Dual Backend

Local (free, default): Everything stored in .loom/ — JSON files with atomic, crash-safe writes. Zero config. Commit rules.json and conventions.md to git so your team shares conventions.

Cloud (teams): loom cloud setup provisions a Supabase Postgres database. Every agent in your org reads and writes from the same store. Real-time shared memory.

Free (JSON):                        Cloud (Postgres):
loom init                           loom cloud setup
→ .loom/ on disk                    → Supabase database
→ commit to git                     → team shares in real-time
→ zero cost                         → managed, scalable

What Loom Creates

your-project/
└── .loom/
    ├── domains/           # 8 domain YAML configs (coding, style, architecture,
    │                      #   process, testing, security, documentation, general)
    ├── rules.json         # Learned rules with confidence scores
    ├── conventions.md     # Human-readable conventions doc
    ├── timeline.jsonl     # Auditable, append-only org history
    ├── retention.json     # Permanent-to-transient retention policies
    ├── archive.json       # Archived rules (never lost)
    ├── permissions.json   # Per-observation RBAC
    ├── onboarding/        # Role-based onboarding packs
    ├── succession/        # Departing member knowledge capture
    └── coaching/          # Coaching amplifications

A .loom/.gitignore is generated automatically so sensitive files (tokens, audit logs, permissions) never reach git while rules.json and conventions.md stay shareable.

CLI Reference

loom init              # Generate config for Claude Desktop
loom setup             # Same as init
loom doctor            # Health check — Python, Loom, storage, LLM, MCP
loom doctor --preflight # Validate MCP config before restart
loom cloud setup       # Provision Supabase database for team
loom version           # Print the installed version

Config locations

Example Session

[Agent starts coding]

First tool call → auto session_init fires:

<!-- LOOM:AUTO_CONTEXT -->
## 🔍 Relevant Conventions (from Loom)

### ⚡ Top Reminders
1. All public functions must have type hints (9/10)
2. Use async/await for all I/O operations (8/10)
3. Every new endpoint needs a test (9/10)

### By Domain
#### coding
- type_safety (9/10): All public functions must have type hints
- error_handling (8/10): Use custom exception classes

### 📢 Coaching Amplifications
- "Use async/await for all I/O" — Sarah Chen (Staff Eng)
  This is critical because sync I/O caused 3 production incidents...

### 🌐 Org-Wide Knowledge
- [api-service] error_handling: Always include request IDs
- [shared-infra] process: Squash commits before merging

[Agent continues. Every teach/learn/amplify auto-observed.
 Session ends → auto-flush extracts all observations into rules.]

Proxy Mode

Run Loom as the only MCP server your client connects to. Loom spawns your other MCP servers internally, relays every JSON-RPC message, and observes every forwarded tool call — nothing to teach, nothing to remember.

python3 -m loom.mcp --proxy

Configure the servers to forward via LOOM_PROXY_TARGETS (same shape as an MCP client's server config):

{
  "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's 18 tools plus every forwarded tool appear as one flat tool list. A target that crashes is marked dead and fails fast — it never hangs your session.

Security

• Redaction on every write path. Before anything reaches storage, Loom strips: Anthropic/OpenAI–style keys (sk-ant-…, sk-proj-…, sk-…), Stripe (sk_live_…), AWS access + secret keys, GitHub/GitLab tokens (classic and fine-grained), Slack, Google, SendGrid, npm, PyPI, Hugging Face tokens, JWTs, bearer tokens, PEM private-key blocks, connection-string passwords, generic api_key=… assignments, emails, and IPv4 addresses.
• RBAC enforced at read time. set_clearance restricts who sees a rule; recall_memory, recall_relevant, export, timeline, and onboard all filter by the agent identity set via LOOM_AGENT_ID / LOOM_AGENT_ROLE / LOOM_AGENT_TEAMS.
• Private mode. LOOM_PRIVATE_MODE=1 blocks every write tool while read tools keep working.
• Crash-safe storage. Atomic writes (temp file + fsync + rename) under advisory file locks; corrupt files are quarantined for recovery, never silently discarded.

Found a vulnerability? See SECURITY.md.

Environment Variables

Requirements

Troubleshooting

loom doctor              # catches most issues
loom doctor --preflight  # validates full MCP chain

Preflight checks: Python path in config exists, Loom is importable, MCP config is valid JSON, storage path is writable, MCP module loads without errors. Exits 0 on all green, 1 with specific fix instructions on any failure.

Contributing

Bug reports, feature ideas, and PRs are welcome — see CONTRIBUTING.md.

git clone https://github.com/Kaushik-hub306/Loom.git && cd Loom
pip install -e ".[dev]"
python -m pytest          # 159 tests
ruff check loom/ tests/   # lint
mypy loom/                # types

License

MIT