Decorator API

Functions for parsing and serializing V3 lorebook decorators.

`parseDecorators()`

Parse @@decorator lines from lorebook entry content.

Signature:

function parseDecorators(content: string): ParsedDecorators

Parameters:

Name	Type	Required	Description
`content`	`string`	Yes	Raw entry content with potential decorator lines

Returns: ParsedDecorators — Parsed decorators and cleaned content.

Example:

import { parseDecorators } from '@motioneffector/cards'

const raw = `@@depth 4
@@role system
@@activate_only_after 3
This is the actual entry content.`

const { decorators, content } = parseDecorators(raw)

console.log(decorators)
// [
//   { type: 'depth', value: 4 },
//   { type: 'role', value: 'system' },
//   { type: 'activate_only_after', value: 3 }
// ]

console.log(content)
// "This is the actual entry content."

`serializeDecorators()`

Convert decorator array back to @@syntax and prepend to content.

Signature:

function serializeDecorators(
  decorators: Decorator[],
  content: string
): string

Parameters:

Name	Type	Required	Description
`decorators`	`Decorator[]`	Yes	Decorators to serialize
`content`	`string`	Yes	Entry content to append after decorators

Returns: string — Content string with decorator lines prepended.

Example:

import { serializeDecorators } from '@motioneffector/cards'

const decorators = [
  { type: 'depth', value: 4 },
  { type: 'role', value: 'system' }
]
const content = 'The actual entry content.'

const result = serializeDecorators(decorators, content)
// "@@depth 4\n@@role system\nThe actual entry content."

Types

`ParsedDecorators`

interface ParsedDecorators {
  decorators: Decorator[]
  content: string
}

Property	Type	Description
`decorators`	`Decorator[]`	Parsed decorator objects
`content`	`string`	Content with decorator lines removed

`Decorator`

type Decorator =
  // Activation
  | { type: 'activate' }
  | { type: 'dont_activate' }
  | { type: 'activate_only_after'; value: number }
  | { type: 'activate_only_every'; value: number }
  | { type: 'keep_activate_after_match' }
  | { type: 'dont_activate_after_match' }

  // Position
  | { type: 'depth'; value: number }
  | { type: 'instruct_depth'; value: number }
  | { type: 'reverse_depth'; value: number }
  | { type: 'position'; value: string }
  | { type: 'role'; value: 'assistant' | 'system' | 'user' }

  // Scanning
  | { type: 'scan_depth'; value: number }
  | { type: 'instruct_scan_depth'; value: number }
  | { type: 'is_greeting'; value: number }

  // Matching
  | { type: 'additional_keys'; value: string[] }
  | { type: 'exclude_keys'; value: string[] }
  | { type: 'is_user_icon'; value: string }

  // UI
  | { type: 'ignore_on_max_context' }
  | { type: 'disable_ui_prompt'; value: string }

  // Unknown (forward compatibility)
  | { type: 'unknown'; name: string; value?: string }

Decorator Reference

Decorator	Type	Description
`@@activate`	Activation	Force activation (ignore keys)
`@@dont_activate`	Activation	Force deactivation
`@@activate_only_after N`	Activation	Only after N messages
`@@activate_only_every N`	Activation	Every Nth activation
`@@keep_activate_after_match`	Activation	Stay active once triggered
`@@dont_activate_after_match`	Activation	Deactivate after first trigger
`@@depth N`	Position	Insert at depth N (from end)
`@@instruct_depth N`	Position	Depth in instruct mode
`@@reverse_depth N`	Position	Depth from start
`@@position VALUE`	Position	Named position
`@@role VALUE`	Position	Message role (system/user/assistant)
`@@scan_depth N`	Scanning	How far back to scan for keys
`@@instruct_scan_depth N`	Scanning	Scan depth in instruct mode
`@@is_greeting N`	Scanning	Greeting index
`@@additional_keys K1,K2`	Matching	Extra trigger keys
`@@exclude_keys K1,K2`	Matching	Keys that prevent activation
`@@is_user_icon VALUE`	Matching	User icon trigger
`@@ignore_on_max_context`	UI	Skip when context is full
`@@disable_ui_prompt VALUE`	UI	Disable UI prompt