Schema Templates

CogOS supports two schema construction modes:

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

Built-in Templates

CogOS 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 cogos init to export them as editable JSON files:

cogos 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:

{
  "_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

CLI
Python
YAML Config
OpenClaw Slash Commands

# Start server with a template
cogos serve --template general

# Build with a template
cogos build --template general --input notes.md --session user1

cogos = CogOS(config).from_template("general")

# configs/cogos.yaml: auto-load on startup
templates:
  templates_dir: "./templates"
  custom_templates_dir: "./templates/custom"
  schema_template: "general"

# List all templates (grouped by source: builtin / user / custom)
/cogos templates

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

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

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

# Delete a custom template
/cogos templates delete my_template

When you select a template (via CLI, API, or Web UI), CogOS 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

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

Via File

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

# 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:

curl -X POST http://localhost:8000/api/templates/custom \
  -H "Content-Type: application/json" \
  -d @my_template.json

Delete a custom template:

curl -X DELETE http://localhost:8000/api/templates/custom/my_template

Via OpenClaw Slash Command

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

/cogos 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:

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

Delete a custom template:

/cogos templates delete my_template

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

Template Resolution

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

Custom templates in custom_templates_dir (./templates/custom/)
User templates in templates_dir (./templates/)
Built-in templates bundled with CogOS

Use the API to view templates grouped by source:

curl http://localhost:8000/api/templates/grouped

​Built-in Templates

​Template Sources & Priority

​Template File Format

​Using Templates

​Creating Custom Templates

​Via Web UI

​Via File

​Via API

​Via OpenClaw Slash Command

​Template Resolution

Built-in Templates

Template Sources & Priority

Template File Format

Using Templates

Creating Custom Templates

Via Web UI

Via File

Via API

Via OpenClaw Slash Command

Template Resolution