Loom Memory Plugin for OpenClaw

Structured long-term memory for OpenClaw using loom. Automatically extracts key information from conversations into schema-based memory and injects relevant context back into the model prompt.

Quick Start

1. Install & configure Loom

cd Loom
pip install -e .
loom init          # generates configs/loom.yaml and template files

Open configs/loom.yaml and fill in the llm section (or copy .env.example to .env and edit):

# configs/loom.yaml
llm:
  api_key: "your-api-key"
  model: "google/gemini-2.5-flash"            # any OpenAI-compatible model
  base_url: "https://openrouter.ai/api/v1"    # OpenRouter / OpenAI / local endpoint

Supported providers: OpenAI (https://api.openai.com/v1), OpenRouter (https://openrouter.ai/api/v1), or any OpenAI-compatible endpoint.

2. Start the Loom backend

loom serve                   # foreground (Ctrl+C to stop)
# or
loom serve start             # background daemon (recommended)

The server runs at http://localhost:8666 by default. Use loom serve status to verify.

3. Install OpenClaw (if not already installed)

If you don't have OpenClaw yet, install it first:

# Recommended: one-line installer (auto-detects OS, installs Node if needed)
curl -fsSL https://openclaw.ai/install.sh | bash

# Or via npm / pnpm / bun if you manage Node yourself
npm install -g openclaw@latest
openclaw onboard --install-daemon

Verify the installation:

openclaw --version
openclaw doctor            # check for config issues

See the OpenClaw Install Guide for all install methods (Docker, Nix, from source, etc.).

4. Install the plugin

openclaw plugins install --link /path/to/Loom/loom-openclaw-plugin

5. Start (or restart) OpenClaw

If the Gateway is not running, start it:

openclaw gateway

If the Gateway is already running, restart it to load the new plugin:

openclaw gateway restart

6. Verify

Confirm the plugin is loaded and the Gateway is healthy:

# Check the plugin is registered
openclaw plugins list --enabled

# Inspect plugin details
openclaw plugins inspect loom-claw

# Check Gateway health
openclaw gateway status

Then open a chat and run /loom status — you should see Loom connection info and schema overview. The plugin will automatically extract and recall structured memories each turn.

AI-Assisted Setup

You can let an AI agent handle the entire setup process for you.

Option A: Via any LLM agent (OpenClaw, Telegram, etc.)

Send this prompt to your agent:

Read https://github.com/TeamEcho-AI/Loom/blob/main/skills/loom-setup/SKILL.md and follow it to install and configure Loom for OpenClaw. When done, summarize what you can do.

The agent will fetch the setup guide, then walk you through environment checks, LLM configuration, service startup, plugin installation, and verification step by step.

Option B: Via Claude Code

claude skill install ./skills/loom-setup

Once installed, say “help me run Loom” or “I want to add memory to OpenClaw” and the skill will trigger automatically.

Features

• Auto-extract and auto-recall — the Loom CM agent extracts information from conversations into structured schemas and injects relevant data into the system prompt each turn
• Schema-based memory — organizes knowledge into typed domains and fields rather than flat text, enabling precise recall and structured reasoning
• Multi-schema management — create, switch, backup, and restore independent schema files for different contexts or personas
• Template system — bootstrap schemas from built-in, shared, or custom templates; create and manage templates via slash commands
• Agent tools — 5 registered tools let the LLM inspect, recall, build, forget, and update memory on demand
• Slash commands — full /loom command suite for manual memory management

Prerequisites

Loom backend setup

cd Loom
pip install -e .
loom init

Configure your LLM provider by editing configs/loom.yaml:

llm:
  api_key: "your-api-key"
  model: "google/gemini-2.5-flash"
  base_url: "https://openrouter.ai/api/v1"

Alternatively, copy .env.example to .env and fill in API_KEY, MODEL, BASE_URL. Values in .env override loom.yaml.

Start the server:

loom serve                               # foreground
loom serve start                         # background daemon
loom serve start --autostart             # daemon + auto-start on boot
loom serve status                        # check if running

The backend runs on http://localhost:8666 by default.

OpenClaw installation

If OpenClaw is not yet installed:

curl -fsSL https://openclaw.ai/install.sh | bash

Or install manually via npm:

npm install -g openclaw@latest
openclaw onboard --install-daemon

See the OpenClaw Install Guide for Docker, Nix, and other options.

Installation

openclaw plugins install --link /path/to/Loom/loom-openclaw-plugin

The installer automatically registers the plugin as the active Context Engine. A Gateway restart is required to load the plugin:

# If the Gateway is already running as a service
openclaw gateway restart

# Or start it fresh
openclaw gateway

To configure the context engine slot manually, add to your openclaw.json:

{
  "plugins": {
    "slots": {
      "contextEngine": "loom-claw"
    }
  }
}

Verify installation

# Plugin should appear in the loaded list
openclaw plugins list --enabled

# Detailed plugin info (config schema, status, capabilities)
openclaw plugins inspect loom-claw

# Gateway health check
openclaw gateway status

Once the Gateway is running, open a chat and send /loom status to confirm end-to-end connectivity with the Loom backend.

See OpenClaw Plugin docs for full plugin management commands, and Gateway CLI for service lifecycle.

Configuration

Configure in openclaw.json under plugins.entries.loom-claw.config:

Example openclaw.json:

{
  "plugins": {
    "entries": {
      "loom-claw": {
        "enabled": true,
        "config": {
          "loomBaseUrl": "http://localhost:8666",
          "sessionId": "default",
          "schemaId": "default",
          "schemaTemplate": "general",
          "buildEveryNTurns": 1
        }
      }
    }
  }
}

Slash Commands

The plugin registers the /loom command with the following subcommands:

View & Recall

Memory Management

Schema Files

Template Management

Configuration

Agent Tools

Five tools are registered for the OpenClaw agent to use during conversations:

Creating Custom Templates

You can create custom templates directly from the chat using the compact text format:

/loom templates create game_character RPG character memory
  character: name | character name, class | class, level | level, skills | skills
  story: main_quest | main quest, side_quests | side quests, achievements | achievements
  social: friends | friends, guild | guild, reputation | reputation

Format rules:

• First line: template_name description (name allows letters, numbers, underscores, hyphens)
• Following lines: domain_name: field1 | description, field2 | description
• Fields separated by ,, field name and description separated by |

Alternatively, use JSON format:

/loom templates create --json {"_meta":{"name":"my_template","description":"..."},"domain1":{"data":{...},"_mutable":true}}

Context Engine Lifecycle

Data Flow

User message → OpenClaw agent
                 ↓
           [assemble] → GET /api/schemas/recall-all
                 ↓        → schema data injected into system prompt
           Model generates response
                 ↓
           [afterTurn] → POST /api/build
                           → CM Agent extracts information
                           → Updates schema
                           → Available on next assemble

Data Storage

Loom stores data under the OpenClaw Agent Workspace:

~/.openclaw/workspace/loom/
├── schemas/              # Schema files (shared across sessions)
│   ├── default.json
│   └── backups/          # Auto-created on reset
│       └── default_20260314_180736.json
└── sessions/             # Loom session files
    └── default.json

Configure the paths in configs/loom.yaml:

persistence:
  session_dir: "~/.openclaw/workspace/loom/sessions"
  schemas_dir: "~/.openclaw/workspace/loom/schemas"

Development

# Install dependencies
npm install

# Type check
npm run typecheck

# Run tests
npm test

To develop with a local link:

openclaw plugins install --link /path/to/Loom/loom-openclaw-plugin

Changes to the TypeScript source are picked up on the next gateway restart.

License

MIT