Skip to main content

Schema File Location

Place your trait schema in config/traits/ and reference it in your configuration:
{
  "traits": {
    "schemaPath": "./config/traits/my-schema.traits.json"
  }
}

Schema Format

{
  "traits": [
    {
      "key": "trait_name",
      "label": "Human Readable Name",
      "description": "What this trait represents",
      "valueType": "string",
      "category": "category_name",
      "extraction": {
        "enabled": true,
        "promptSnippet": "Extraction hint for the LLM",
        "confidenceThreshold": 0.5
      },
      "injection": {
        "enabled": true,
        "template": "User prefers {{value}}.",
        "priority": 5
      }
    }
  ]
}

Value Types

Free-form text value.
{
  "key": "name",
  "valueType": "string"
}
Extracted value: "Alex"

Extraction Settings

promptSnippet

A hint added to the extraction prompt to help the LLM understand what to look for:
{
  "key": "communication_style",
  "extraction": {
    "promptSnippet": "Assess if user prefers formal, casual, technical, or simple communication based on their language and requests"
  }
}

confidenceThreshold

Minimum confidence score required to store the trait:
ThresholdUse Case
0.9High-stakes traits (name, PII)
0.7Important preferences
0.5General traits (default)
0.3Experimental/weak signals

Injection Settings

template

Format string for injecting the trait into prompts. Use {{value}} placeholder:
{
  "key": "name",
  "injection": {
    "template": "The user's name is {{value}}. Address them by name when appropriate."
  }
}
For array values:
{
  "key": "interests",
  "injection": {
    "template": "User is interested in: {{value}}"
  }
}
// Renders as: "User is interested in: Python, ML, DevOps"

priority

Higher priority traits appear earlier in the injected context:
PriorityTypical Traits
10Name, language
8-9Communication style
5-7Expertise, preferences
1-4Interests, goals

Full Example

{
  "traits": [
    {
      "key": "role",
      "label": "Professional Role",
      "description": "User's job title or professional role",
      "valueType": "string",
      "category": "identity",
      "extraction": {
        "enabled": true,
        "promptSnippet": "Extract job title, role, or profession if mentioned",
        "confidenceThreshold": 0.8
      },
      "injection": {
        "enabled": true,
        "template": "User works as a {{value}}.",
        "priority": 8
      }
    },
    {
      "key": "tech_stack",
      "label": "Technology Stack",
      "description": "Technologies and tools the user works with",
      "valueType": "array",
      "category": "context",
      "extraction": {
        "enabled": true,
        "promptSnippet": "Identify programming languages, frameworks, and tools mentioned",
        "confidenceThreshold": 0.6
      },
      "injection": {
        "enabled": true,
        "template": "User's tech stack includes: {{value}}",
        "priority": 6
      }
    }
  ]
}