> ## Documentation Index
> Fetch the complete documentation index at: https://docs.loom.teamecho.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Schema Templates

> Use preset templates or create custom ones to bootstrap schema structures.

Loom supports **two schema construction modes**:

1. **LLM Auto-Generation** — The CM agent creates schema fields dynamically during `build()` (default)
2. **From Template** — Select a preset template; Loom copies it as a new schema file (`{name}_{YYYYMMDD}_{HHmmss}.json`) and subsequent chats dynamically update it via the CM agent

## Built-in Templates

Loom ships with two built-in templates:

| Template   | Domains                                                  | Description                                                |
| ---------- | -------------------------------------------------------- | ---------------------------------------------------------- |
| `general`  | `user_profile`, `user_interests`, `memory_events`        | Long-term user memory for personalised AI assistants       |
| `roleplay` | `chatbot_settings`, `relationship_schema`, `user_schema` | Character and relationship tracking for roleplay scenarios |

Run `loom init` to export them as editable JSON files:

```bash theme={null}
loom init
# Exports built-in templates to ./templates/ (editable copies)
# Existing files are kept by default; use --force to overwrite
```

## Template Sources & Priority

Templates are loaded from three sources, with later sources overriding earlier ones:

| Priority    | Source            | Directory                                      | Description                                 |
| ----------- | ----------------- | ---------------------------------------------- | ------------------------------------------- |
| 1 (lowest)  | Built-in          | Bundled in code                                | `general` and `roleplay`                    |
| 2           | User (shared)     | `templates_dir` (`./templates/`)               | Project-level templates, version-controlled |
| 3 (highest) | Custom (personal) | `custom_templates_dir` (`./templates/custom/`) | Personal templates, git-ignored             |

If two templates share the same name, the higher-priority source wins.

## Template File Format

Templates use the same JSON format as schema files, with an optional `_meta` key:

```json theme={null}
{
  "_meta": {
    "name": "medical_record",
    "description": "Patient medical record schema"
  },
  "patient_info": {
    "data": {
      "meta": {
        "domain": {"value": "patient_info", "description": "Schema domain: patient_info"}
      },
      "name": {"value": "", "description": "Patient full name"},
      "diagnosis": {"value": "", "description": "Current diagnosis"},
      "medications": {"value": "", "description": "Current medications"},
      "allergies": {"value": "", "description": "Drug allergies"}
    },
    "_mutable": true
  }
}
```

The `_meta.name` field determines the template identifier. The file name can be anything ending in `.json`.

## Using Templates

<Tabs>
  <Tab title="CLI">
    ```bash theme={null}
    # Start server with a template
    loom serve --template general

    # Build with a template
    loom build --template general --input notes.md --session user1
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    loom = Loom(config).from_template("general")
    ```
  </Tab>

  <Tab title="YAML Config">
    ```yaml theme={null}
    # configs/loom.yaml: auto-load on startup
    templates:
      templates_dir: "./templates"
      custom_templates_dir: "./templates/custom"
      schema_template: "general"
    ```
  </Tab>

  <Tab title="OpenClaw Slash Commands">
    ```bash theme={null}
    # List all templates (grouped by source: builtin / user / custom)
    /loom templates

    # Preview a template's domains and fields
    /loom templates show general

    # Create a schema from template and switch to it
    /loom templates use general

    # Create a custom template
    /loom templates create my_template My description
      domain1: field1 | desc1, field2 | desc2

    # Delete a custom template
    /loom templates delete my_template
    ```
  </Tab>
</Tabs>

When you select a template (via CLI, API, or Web UI), Loom **copies** the template into the schemas directory as a new schema file named `{template_name}_{YYYYMMDD}_{HHmmss}.json` and binds the current session to it. Subsequent conversations dynamically update this schema via the CM agent — the template simply provides the starting structure.

## Creating Custom Templates

### Via Web UI

1. Open the Build Schemas modal → switch to **From Template** mode
2. Click **+ New Template** to open the template editor
3. Fill in the template name, description, and fields
4. Click **Save Template** — the file is saved to `./templates/custom/`

### Via File

Place any `.json` file in `./templates/` (shared) or `./templates/custom/` (personal):

```bash theme={null}
# Shared template (version-controlled)
templates/my_template.json

# Personal template (git-ignored)
templates/custom/my_private_template.json
```

### Via API

Save a custom template through the REST API:

```bash theme={null}
curl -X POST http://localhost:8666/api/templates/custom \
  -H "Content-Type: application/json" \
  -d @my_template.json
```

Delete a custom template:

```bash theme={null}
curl -X DELETE http://localhost:8666/api/templates/custom/my_template
```

### Via OpenClaw Slash Command

Create templates directly from the chat using the compact text format:

```
/loom templates create game_character
  character: name, class, level, skills
  story: main_quest, side_quests
  social: friends, guild, reputation
```

Format rules:

* First line: `template_name description` (name allows letters, numbers, `_`, `-`)
* Following lines: `domain_name: field1 | description, field2 | description`
* Fields separated by `,`, field name and description separated by `|`

Or use JSON format:

```
/loom templates create --json {"_meta":{"name":"my_template","description":"..."},...}
```

Delete a custom template:

```
/loom templates delete my_template
```

<Note>
  Only custom templates can be deleted via the API or slash commands. Built-in and shared (user) templates are protected.
</Note>

## Template Resolution

Templates are resolved by name across all three sources. The resolution order (highest priority first):

1. **Custom** templates in `custom_templates_dir` (`./templates/custom/`)
2. **User** templates in `templates_dir` (`./templates/`)
3. **Built-in** templates bundled with Loom

Use the API to view templates grouped by source:

```bash theme={null}
curl http://localhost:8666/api/templates/grouped
```