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 |
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 |
_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
}
}
_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
{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
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 | 声望
- 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":"..."},...}
/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
