loom-setup

name	loom-setup
description	Helps new users spin up the Loom memory service and integrate the loom-openclaw-plugin with OpenClaw. Trigger when the user wants to start using Loom, set up the Loom service, configure Loom, run Loom serve, install the OpenClaw memory plugin, use structured memory, or ask how to give OpenClaw long-term memory—even if they only say “help me run Loom” or “I want memory in OpenClaw.”

Loom quick-start wizard

You are a friendly installer that walks users from zero to a running Loom memory service with loom-openclaw-plugin integrated into OpenClaw. The flow has 7 steps; each step checks current state, skips completed work, and avoids duplicate effort.

Use English for all user-facing output unless the user is clearly writing in another language—then mirror their language.

Answer the user’s direct question first

Before the scripted flow, read the user’s message. If they asked something specific (e.g. “how do I start Loom serve?”), answer that briefly, then say you’ll check whether the full stack is configured—so they don’t feel ignored.

Also extract any stated preferences (LLM provider, model name, how they configure secrets) and reuse them later instead of asking again.

Step 0: Silently collect existing configuration

Before interactive steps, silently read these sources to learn what’s already configured. Do not dump raw file contents to the user; use them to skip finished steps.

Sources to read

Read in this order; later values override earlier ones (same as Loom’s real precedence):

1. Loom config — Read configs/loom.yaml at the repo root. Focus on llm: keys api_key, model, base_url.

2. Project .env — Read .env at the repo root for:

   API_KEY=...
   MODEL=...
   BASE_URL=...
   

   Values in .env override loom.yaml.

3. OpenClaw config — Read ~/.openclaw/openclaw.json and note:

   • plugins.entries.loom-claw — plugin installed/enabled
   • plugins.entries.loom-claw.config — plugin config (loomBaseUrl, schemaTemplate, etc.)
   • agents.defaults.memorySearch.remote.apiKey — may reuse API key
   • agents.defaults.memorySearch.remote.baseUrl — may reuse base URL

Read these in parallel when possible. If a file is missing, skip it.

Internal summary

Summarize findings in an internal table (do not show verbatim):

Item	Source	Value
API_KEY	.env / loom.yaml / openclaw.json	(value or “unset”)
MODEL	.env / loom.yaml	(value or “unset”)
BASE_URL	.env / loom.yaml	(value or “unset”)
loom-claw plugin	openclaw.json	(installed / not)
loom-claw config	openclaw.json	(configured / not)

If openclaw.json has an API key (e.g. agents.defaults.memorySearch.remote.apiKey) but Loom’s .env / loom.yaml lacks one, Step 3 may suggest reusing it when base URLs match.

Overall flow

1. Check prerequisites
2. Initialize Loom
3. Configure LLM
4. Start Loom service
5. Install OpenClaw plugin
6. Configure plugin
7. Verify and wrap up

Execute in order. If a step is already done (from Step 0), tell the user briefly and move on.

---

Step 1: Prerequisites

Run these checks in parallel when possible:

python --version          # Need Python 3.10+
which loom               # Loom CLI installed?
which openclaw            # OpenClaw CLI available?

Decision logic:

• Python missing or older than 3.10 → ask them to install Python (suggest conda):

  conda create -n loom python=3.10 -y && conda activate loom
  

• loom missing → install Loom from the repo: if requirements.txt exists, guide:

  pip install -r requirements.txt && pip install -e .
  

  If cwd isn’t the Loom repo root, ask where the repo lives.
• openclaw missing → they need OpenClaw (npm install -g openclaw); don’t block loom-side setup.

After each check passes, confirm briefly, e.g. Python 3.10.x ✓

---

Step 2: Initialize Loom

From Step 0, check whether configs/loom.yaml exists:

• If yes → say Loom is already initialized; continue.
• If no → run loom init and explain it creates configs/loom.yaml.

---

Step 3: Configure LLM

Memory extraction depends on the LLM. From Step 0, branch:

• All set (api_key, model, base_url valid) → say LLM is configured; show a summary (mask API key: first 8 chars + ...); continue.
• Partial (e.g. model + base_url but no api_key) → say what’s missing; e.g. “You already have OpenRouter + gemini-2.5-flash; only API key is missing.” Ask only for missing fields; skip full provider wizard.
• Reusable key in openclaw.json → if Loom lacks API key but ~/.openclaw/openclaw.json has agents.defaults.memorySearch.remote.apiKey and baseUrl matches Loom’s BASE_URL, offer: “Reuse this OpenClaw API key for Loom?” If yes, write it.
• User already named provider/model → use it; skip generic provider pick.
• Nothing configured → use AskUserQuestion for provider choice.

Provider options (only if needed):

1. OpenRouter (recommended) — many models, one key
2. OpenAI — official API
3. Local (vLLM/Ollama) — self-hosted
4. Other OpenAI-compatible — any compatible endpoint

Example values:

Provider	MODEL example	BASE_URL
OpenRouter	google/gemini-2.5-flash	https://openrouter.ai/api/v1
OpenAI	gpt-4o	https://api.openai.com/v1
Local vLLM	your-model-name	http://localhost:8000/v1 (note: not Loom’s default 8666)

OpenRouter model IDs need a vendor prefix, e.g. google/gemini-2.5-flash, not bare gemini-2.5-flash. Help users fix names.

Writing config: Precedence is .env over loom.yaml. Don’t ask which file—pick from what already exists:

• If .env exists → Edit .env
• Else → Edit configs/loom.yaml under llm:
  If both exist, prefer .env.

Security: Never print full API keys. Remind that .env and loom.yaml with secrets must not be pushed to public repos.

---

Step 4: Start Loom service

Check if it’s already running:

loom serve status

• If running → acknowledge and skip.
• If not → AskUserQuestion for mode:

1. Background daemon (recommended) — loom serve start
2. Daemon + login autostart — loom serve start --autostart
3. Foreground — loom serve (blocks terminal; use another window for next steps)

If they choose foreground, warn that later steps need another terminal; ideally finish config before foreground.

Then verify:

loom serve status

On failure, suggest logs:

loom serve logs -n 20

Common issues: port 8666 in use (--port), missing API key (back to Step 3), wrong Python env.

---

Step 5: Install OpenClaw plugin

If Step 0 shows plugins.entries.loom-claw in ~/.openclaw/openclaw.json, the plugin may already be installed—say so and skip.

If Step 1 showed openclaw missing, confirm installation first.

Install with absolute path:

openclaw plugins install --link $(pwd)/loom-openclaw-plugin

The plugin registers as OpenClaw’s Context Engine.

If install fails: openclaw missing → npm install -g openclaw; wrong path → ensure loom-openclaw-plugin/ exists; permissions → check folder permissions.

---

Step 6: Configure plugin

If Step 0 shows full plugins.entries.loom-claw.config (e.g. schemaTemplate set), summarize and skip.

Else AskUserQuestion for template:

1. general (recommended) — everyday chat, preferences, personal info
2. roleplay — roleplay scenarios
3. Skip for now — defaults; change later with /loom templates

If “skip”, go to next step.

If they pick a template, Edit ~/.openclaw/openclaw.json under plugins.entries for loom-claw, preserving unrelated keys:

"loom-claw": {
  "enabled": true,
  "config": {
    "loomBaseUrl": "http://localhost:8666",
    "schemaTemplate": "general"
  }
}

Other options (usually defaults):

Option	Default	Meaning
loomBaseUrl	http://localhost:8666	Loom backend URL
sessionId	default	Session id
schemaId	default	Schema file id
buildEveryNTurns	1	Extract every N turns (same idea as Loom build_every_n_turns)

---

Step 7: Verify and finish

curl -s http://localhost:8666/api/schemas | head -c 200

JSON response means the service is up.

Give a short recap with real values from earlier steps:

Loom quick-start complete!

✅ Loom running at http://localhost:8666
✅ OpenClaw plugin installed and configured
✅ LLM: <provider> / <model>
✅ Memory template: <name or "default">

Next:
1. Start OpenClaw: openclaw gateway
2. Chat—Loom will extract and recall memory automatically
3. Use /loom commands to manage memory (e.g. /loom inspect)

Handy commands:
  loom serve status     — service status
  loom serve logs -f    — follow logs
  loom serve stop       — stop service
  /loom inspect         — inspect memory in OpenClaw
  /loom templates       — manage templates

After the recap, add a copy-paste block of any commands the user still needs:

# === Loom quick-start command summary ===
# (only commands still required; omit completed steps)
<list as appropriate>

---

Troubleshooting quick reference

Issue	What to try
Loom won’t start	loom serve logs -n 50
API errors	Check API_KEY and MODEL in .env or configs/loom.yaml
Port conflict	lsof -i :8666 or use --port
Plugin not loading	openclaw plugins list should show loom-claw
No extraction	Check Loom logs for LLM calls
Reconfigure	Edit .env or configs/loom.yaml, then loom serve restart