loom

Loom

An LLM agent framework for Go. Create agents from natural language, orchestrate them with workflow patterns, and improve them through pattern-guided learning.

Version: v1.3.0

Quick Start

# 1. Install
git clone https://github.com/teradata-labs/loom && cd loom
./quickstart.sh          # macOS/Linux (handles Go, Buf, patterns)
# .\quickstart.ps1       # Windows (PowerShell)

# 2. Set your LLM provider
export ANTHROPIC_API_KEY="your-key"    # or Bedrock, Ollama, OpenAI, etc.

# 3. Start the server
looms serve              # gRPC :60051, HTTP :5006

# 4. Launch the TUI
loom                     # Opens with Guide agent
loom --thread weaver     # Or go straight to the Weaver

The Weaver is a meta-agent that creates other agents from natural language:

You: Create a Teradata query optimizer that analyzes EXPLAIN plans
Weaver: Analyzing requirements... selecting patterns... activating agent.

API endpoints after looms serve:

• gRPC: localhost:60051 (127 RPCs)
• HTTP/REST: localhost:5006 (with SSE streaming)
• Swagger UI: localhost:5006/swagger-ui
• MCP Apps: localhost:5006/apps/

How It Works

Instead of prompt engineering, Loom uses pattern-guided learning. Domain knowledge is encoded as reusable YAML patterns that agents select and apply based on user intent:

User message → Pattern selection (from 104 patterns) → LLM call with context → Tool execution → Response
     ↑                                                                                             |
     └────────────────────── Learning feedback loop (optional) ────────────────────────────────────┘

Patterns are plain-English YAML files anyone can write. They turn generic LLMs into domain specialists for SQL optimization, data quality, Teradata analytics, code review, and more.

Features

Weaver (Meta-Agent)

Describe what you need; the Weaver builds it:

• Analyzes requirements to determine domain and capabilities
• Selects patterns from the library (104 patterns across 16 domains)
• Generates YAML configuration and activates the agent
• Automatically selects workflow patterns for multi-agent tasks
• /agent-plan mode for guided requirement gathering with skills-based recommendations

Multi-Agent Workflows

9 orchestration patterns defined in proto:

Judge Evaluation System

Multi-judge evaluation with 6 aggregation strategies (weighted-average, all-must-pass, majority-pass, any-pass, min-score, max-score) and 3 execution modes (synchronous, asynchronous, hybrid). Includes DSPy integration for judge optimization.

See Judge CLI Guide.

Learning Agents

Self-improving agents that analyze successes/failures and propose pattern improvements. Three modes: observation, proposal, and auto-apply. Integrates with DSPy for prompt optimization.

See Learning Agent Guide.

Pattern Library

104 YAML patterns across 16 domains, installed to $LOOM_DATA_DIR/patterns/:

Write your own patterns in plain English YAML to make Loom agents into domain experts for your specific use cases.

MCP Integration

Connect any MCP server without code:

looms config set mcp.servers.github.command /path/to/github-mcp
looms config set mcp.servers.github.env.GITHUB_TOKEN "${GITHUB_TOKEN}"
# MCP servers auto-start with: looms serve

4 built-in MCP UI Apps served at /apps/ and as MCP resources (ui:// scheme):

Dynamic App Creation: Agents and MCP clients can create custom dashboards at runtime from a declarative JSON spec with 14 component types (stat cards, charts, tables, heatmaps, DAGs, etc.). Up to 100 dynamic apps, compiled to secure standalone HTML with the Tokyonight Dark theme. See MCP Apps Guide.

Built-in Tools

Graph Memory

Salience-driven graph-backed episodic memory for persistent, cross-session knowledge. Agents automatically build a knowledge graph of entities, relationships, and memories that survives across sessions.

• Entities (mutable nodes) represent people, tools, projects, concepts
• Edges (directed relationships) link entities: USES, WORKS_ON, KNOWS_ABOUT, etc.
• Memories (immutable records) store facts, decisions, preferences, experiences, failures
• Salience scoring with time decay and access boosting ranks memories by importance
• Lineage tracking for corrections (SUPERSEDES) and merges (CONSOLIDATES)
• FTS5 search over memory content, summaries, and tags
• Token-budgeted context injection per turn (default 10% of context window)
• Enabled by default (opt-out) when storage backend supports it

# Agent config
agent:
  memory:
    graph_memory:
      enabled: true              # default when store available
      context_budget_percent: 10 # % of context window
      decay_rate: 0.995          # salience decay per day

See Graph Memory Architecture.

Artifact Management

Session-scoped file storage with SQLite FTS5 full-text search, automatic metadata extraction, soft/hard delete with 30-day recovery, and archive support. See loom artifacts --help.

Skills System

LLM-agnostic activatable behaviors combining prompt injection, tool preferences, and trigger conditions. Skills activate via slash commands (/skill-name), keyword auto-detection, or always-on mode. Includes hot-reload via fsnotify and token budget control. See pkg/skills/.

Per-Role LLM Providers

Assign different LLM providers per operational role (judge, orchestrator, classifier, compressor) with automatic fallback to the main agent LLM. Enables cost optimization by using smaller models for classification while reserving larger models for complex reasoning.

LLM Providers

8 providers, 44 cataloged models with mid-session switching:

TUI

The terminal UI (loom) is built on Bubbletea with a Crush-inspired color theme.

• Guide agent greets you and helps find the right agent for your task
• Slash commands — /clear, /quit, /sessions, /model, /agents, /workflows, /patterns, /help, and more
• Sidebar shows Weaver status, MCP servers, loaded patterns, model info, keyboard hints
• Mid-session model switching with cost transparency
• Multi-agent colors (6 predefined + golden-ratio generation for 50+ agents)
• Streaming with animated progress, tool execution states, cost tracking

Shortcuts: ctrl+e agents | ctrl+w workflows | ctrl+p command palette | ctrl+o sessions | ctrl+n new session

Architecture

┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
│   loom (TUI)     │  │  looms (server)  │  │  loom-mcp        │
│   Interactive     │  │  gRPC + HTTP     │  │  MCP bridge      │
└────────┬─────────┘  └────────┬─────────┘  └────────┬─────────┘
         │                     │                      │
         └─────────────────────┼──────────────────────┘
                               v
┌──────────────────────────────────────────────────────────────┐
│                      Loom Framework                          │
│  ┌─────────────┐ ┌──────────────┐ ┌────────────┐ ┌────────┐ │
│  │ Agent       │ │ Orchestration│ │ Patterns   │ │ Shuttle│ │
│  │ Runtime     │ │ (9 patterns) │ │ (104 YAML) │ │ (tools)│ │
│  └─────────────┘ └──────────────┘ └────────────┘ └────────┘ │
│  ┌─────────────┐ ┌──────────────┐ ┌────────────┐ ┌────────┐ │
│  │ Judges      │ │ Skills       │ │ MCP Apps   │ │ Comms  │ │
│  │ (6 strats)  │ │ (hot-reload) │ │ (4 apps)   │ │ (3-way)│ │
│  └─────────────┘ └──────────────┘ └────────────┘ └────────┘ │
│  ┌─────────────┐                                             │
│  │ Graph Memory│                                             │
│  │ (salience)  │                                             │
│  └─────────────┘                                             │
└──────────────────────────────────────────────────────────────┘
         │                     │                      │
         v                     v                      v
┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
│   Observability  │  │  LLM Providers   │  │  SQLite/FTS5     │
│   (self-contained│  │  (8 providers)   │  │  or PostgreSQL   │
│    + Hawk opt.)  │  │                  │  │  (persistence)   │
└──────────────────┘  └──────────────────┘  └──────────────────┘

Proto is law: All APIs defined in proto/loom/v1/ first. 127 RPCs covering agents, workflows, patterns, sessions, artifacts, MCP, judges, skills, and scheduling. HTTP/REST via gRPC-gateway.

Installation

Quickstart (Recommended)

git clone https://github.com/teradata-labs/loom && cd loom
./quickstart.sh     # macOS/Linux
# .\quickstart.ps1  # Windows

Installs Go, Buf, builds binaries, installs 104 patterns, and configures your LLM provider interactively. See QUICKSTART.md.

Manual

git clone https://github.com/teradata-labs/loom && cd loom
just install        # Builds binaries to ~/.local/bin/, installs patterns

From Source

go install github.com/teradata-labs/loom/cmd/loom@latest
go install github.com/teradata-labs/loom/cmd/looms@latest
just install-patterns   # Patterns required for Weaver

Upgrading

When upgrading to a new version, run just upgrade (build from source) or looms upgrade to migrate the database schema:

# From source: builds new binaries, installs assets, migrates database
just upgrade

# Or run the upgrade command directly
looms upgrade              # Backup + migrate (default)
looms upgrade --dry-run    # Show pending migrations without applying
looms upgrade --backup-only # Create a backup only
looms upgrade --no-backup  # Skip backup (not recommended)
looms upgrade --yes        # Skip confirmation prompt

SQLite databases are backed up automatically before migration (via VACUUM INTO). Backup files are named with a timestamp suffix (e.g., loom.db.backup.20260224T153000). PostgreSQL backends use the same versioned migration system with advisory locks.

# Create a standalone backup at any time
just backup

Package Managers

macOS (Homebrew via teradata-labs/homebrew-tap) and Windows (Chocolatey, winget) packages are published automatically on each release. Scoop manifests are ready in packaging/ but not yet published to a bucket.

Release Verification

Releases are GPG-signed with SLSA provenance starting v1.1.0. See docs/installation/ for verification steps.

Documentation

Contributing

1. Run go test -tags fts5 -race ./... before submitting PRs
2. Follow existing code patterns and proto-first design
3. Add tests for new features
4. See CONTRIBUTING.md

Support

• Issues: github.com/teradata-labs/loom/issues
• Security: security@teradata.com (do not post security issues in GitHub Issues)

Quality

• 3,230 test functions across 342 test files
• All tests run with -race detector; 0 race conditions
• CI: proto lint, golangci-lint, race detection, fuzz tests, gosec, CodeQL, multi-platform build

License

Apache 2.0 - see LICENSE

Built by Teradata Labs