Enabling Profiling: What It Changes

+15 Mana ✨
Hermes configuration reference(DOCUMENTATION)

Introduction

Profiling is opt-in. You enable it with one config key, and the agent's behavior changes in a few specific ways. Understanding exactly what flips lets you decide whether to turn it on for a given environment.

Key Concepts

  • user_profile_enabled: The config key that toggles the profiling subsystem.
  • Active extraction: With profiling on, the agent considers each turn for profile-worthy facts.
  • Reads vs writes: USER.md is always read if memory_enabled is true. Whether new entries get written is what user_profile_enabled controls.
  • Privacy posture: For shared or sensitive environments, you may want to leave profiling off and seed USER.md by hand.

Real World Context

A contractor uses Hermes on a client laptop they will return in three weeks. Profiling on this machine would write their personal preferences into a USER.md they cannot take with them. They leave user_profile_enabled: false and seed a minimal USER.md by hand for the engagement. On their personal laptop, profiling is on and accumulates over months.

Deep Dive

The full set of memory-related config keys, ordered by what they control:

yaml
memory:
  memory_enabled: true        # master switch for the entire memory subsystem
  user_profile_enabled: true  # whether the agent writes new entries to USER.md
  memory_char_limit: 2200     # capacity of MEMORY.md
  user_char_limit: 1375       # capacity of USER.md
  provider: file              # which backend handles persistence

Three useful states:

  1. Full memory (memory_enabled: true, user_profile_enabled: true): the default. The agent reads both files at session start and proactively writes to both during conversation.
  2. Read-only profile (memory_enabled: true, user_profile_enabled: false): USER.md is loaded into the system prompt as before, but the agent will not add new entries. You curate the profile manually.
  3. Off (memory_enabled: false): the agent neither reads nor writes persistent memory. The session is fully ephemeral.

A subtle but important behavior: turning user_profile_enabled from true to false does not erase USER.md. The file stays on disk and continues to be loaded at session start (as long as memory_enabled is true). The toggle only governs whether new writes happen.

For multi-user setups (e.g., a household Hermes server), you may want a separate profile per user. The standard way to do that is to run Hermes profiles (hermes profile), each with its own HERMES_HOME and thus its own ~/.hermes/memories/ directory. Each profile gets its own USER.md.

Common Pitfalls

  1. Forgetting that profiling reads still happen when writes are off: If you do not want USER.md in the prompt at all, you need memory_enabled: false, not just user_profile_enabled: false.
  2. Leaving profiling on for shared accounts: The agent will happily write profile facts inferred from whichever user happens to be typing. Use profiles or disable writes.

Best Practices

  1. On for personal, off for shared: Default to profiling on for solo use. Default off for shared, client, or temporary environments.
  2. Hand-seed when you turn it on: Even with profiling enabled, the first session is more useful if USER.md already has five solid entries.

Summary

  • memory.user_profile_enabled toggles whether the agent writes new entries to USER.md.
  • Reads of USER.md are governed by memory_enabled, not by the profiling key.
  • Disabling profiling does not erase existing USER.md content.
  • Use Hermes profiles (hermes profile) for multi-user setups where each person needs their own profile.

Code Examples

yaml
# Read-only profile state: keep USER.md in the prompt but stop new writes
memory:
  memory_enabled: true
  user_profile_enabled: false
  provider: file

# Fully ephemeral session: no reads, no writes
memory:
  memory_enabled: false
✓ Completed