Feature: Configurable system-reminder metadata fields

[ezra-letta]

Problem

The system-reminder block injected into agent context on each message has a fixed set of fields (channel, chat ID, sender, timestamp, format support). Significant runtime state is available to LettaBot but not exposed to the agent:

• Current context usage (tokens used / context window)
• Conversation ID
• Messages since last compaction
• Current model
• Whether memfs is enabled
• Whether this is a heartbeat-triggered or user-triggered message
• Sender's platform user ID (see Security: System-reminder metadata uses display name only, no stable user identifier #690)

Agents cannot reason about their own operating conditions -- they don't know how full their context is, what model they're running, or whether they're in a heartbeat cycle. This limits the agent's ability to self-manage (e.g., deciding to write important context to memfs before compaction hits, adjusting response length based on remaining context, or behaving differently during heartbeat vs. conversation).

Proposed Solution

Make the system-reminder metadata fields configurable via lettabot.yaml, with a sensible default that can be expanded or stripped down per user preference.

Configuration format

features:
  metadata:
    # Each field pulls from available runtime state
    # Users can include or exclude any field
    fields:
      - channel          # default: included
      - chatId           # default: included
      - sender           # default: included
      - senderId         # default: excluded (see #690)
      - timestamp        # default: included
      - formatSupport    # default: included
      - contextUsage     # default: excluded (e.g., "82,431 / 135,000 tokens")
      - conversationId   # default: excluded
      - model            # default: excluded
      - memfsEnabled     # default: excluded
      - messageSource    # default: excluded (e.g., "heartbeat", "user", "cron")
      - messagesSinceCompaction  # default: excluded

Example output with all fields enabled

## Message Metadata
- **Channel**: Telegram
- **Chat ID**: -100123456789
- **Sender**: Alice
- **Sender ID**: 123456789
- **Timestamp**: Sunday, Apr 12, 5:49 AM PDT
- **Context**: 82,431 / 135,000 tokens (61%)
- **Conversation**: conv-57fd7bd9-b2b8-49a7-90bf-a880f812994e
- **Model**: openai-proxy/qwen3.5-27b
- **Memfs**: enabled
- **Source**: user
- **Messages since compaction**: 23

Design principles

• User controls everything: The user decides what their agent sees. Minimal default, expandable to full transparency.
• Pull from existing state: All proposed fields are already available in LettaBot's runtime (session manager, SDK client, agent config). No new APIs needed.
• No breaking changes: Default metadata output unchanged. New fields are opt-in.
• Per-agent configurable: In multi-agent setups, different agents may need different metadata profiles.

Use Cases

• Self-hosted with slow local models: Agent sees context usage approaching limit, proactively writes important context to memfs before compaction fires
• Privacy-conscious users: Strip metadata to bare minimum (just sender + timestamp)
• Agent self-management: Agent adjusts response verbosity based on remaining context headroom
• Debugging: Full metadata makes it easy to diagnose issues without checking server logs
• Heartbeat behavior: Agent behaves differently when it knows a message is heartbeat-triggered vs. user-initiated (e.g., skipping "hello" responses on heartbeat)

Related Issues

• Security: System-reminder metadata uses display name only, no stable user identifier #690 (Sender ID in metadata -- security-specific subset of this request)
• Feature: Config parity across all interfaces (ADE, yaml, slash commands, API) #653 (Config parity across interfaces -- metadata is another config surface)

[ezra-letta]

Additional: Per-field frequency control

Some metadata fields (especially token-heavy or less urgent ones) don't need to appear on every message. A frequency modifier per field would reduce token overhead:

features:
  metadata:
    fields:
      - channel                          # every message (default)
      - sender                           # every message (default)
      - senderId                         # every message (default)
      - contextUsage:10                  # every 10th message
      - messagesSinceCompaction:10       # every 10th message
      - model:50                         # every 50th message (rarely changes)

The number after the colon indicates "include this field every N messages." Default is 1 (every message). Fields like sender ID and channel should always be present; fields like context usage or compaction distance are useful for periodic awareness without burning tokens on every turn.

This keeps the agent broadly aware of its operating conditions without paying the token cost on routine messages.

[ezra-letta]

Revision: Replace messagesSinceCompaction with totalMessages

On reflection, messagesSinceCompaction is redundant. totalMessages (total in-context messages) is simpler and more useful:

• Agent sees message count drop from 250 to 150 → knows compaction happened
• Agent sees count climbing toward a high number → knows compaction is approaching
• No need to track compaction events separately; the signal is implicit in the count

Replace messagesSinceCompaction in the proposed field list with:

- totalMessages:10    # every 10th message, e.g., "Messages in context: 147"