Issue Station
Sign In
Tools hereToolbox

hermes - ✅(Solved) Fix SOUL.md should evolve with usage, not just initialize once [1 pull requests, 1 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
NousResearch/hermes-agent#11919•Fetched 2026-04-18 05:58:15
View on GitHub
Comments
1
Participants
2
Timeline
2
Reactions
1
Author
GongShi5201GongShi5201
Participants
gongli0929gongli0929GongShi5201GongShi5201
Timeline (top)
commented ×1cross-referenced ×1

Root Cause

  • Persona defines HOW the agent thinks and behaves
  • Memory only stores WHAT it learned
  • Without evolving SOUL.md, the agent's behavior doesn't truly change
  • Users who never manually edit SOUL.md get a static persona forever

Fix Action

Fixed

PR fix notes

PR #11931: feat: add SOUL.md support to memory tool for agent persona evolution

Description (problem / solution / changelog)

Summary

Added SOUL.md support to the memory tool, enabling the agent to evolve its persona and behavior rules based on user feedback and discovered issues.

Changes

  • Added SOUL.md as third memory target (alongside MEMORY.md and USER.md)
  • Added read/add/replace/remove actions for SOUL.md
  • Added SOUL_CHAR_LIMIT = 10KB to prevent unbounded growth
  • SOUL.md treated as whole file (not §-delimited entries)
  • Updated MEMORY_SCHEMA with 'soul' target and 'read' action
  • Added behavior evolution guidance in tool description

Motivation

Currently, SOUL.md is only seeded on first run and never updates. The agent stores lessons in MEMORY.md but doesn't evolve its behavior rules. This contradicts the 'self-evolving' claim.

With this change, the agent can:

  • Read current SOUL.md: memory(action='read', target='soul')
  • Add rules: memory(action='add', target='soul', content='new rule')
  • Replace rules: memory(action='replace', target='soul', old_text='old rule', content='new rule')
  • Remove rules: memory(action='remove', target='soul', old_text='rule to remove')

Design Decisions

  1. Whole file approach: SOUL.md is treated as a single document, not §-delimited entries. This preserves the freedom of markdown formatting.

  2. 10KB limit: Prevents unbounded growth while allowing sufficient space for persona definition.

  3. Read action: Added 'read' action for soul target to allow checking current content before modifications.

  4. Behavior guidance: Updated tool description to guide agents on when and how to evolve SOUL.md.

Related Issue

Fixes #11919 - SOUL.md should evolve with usage, not just initialize once

Changed files

  • hermes_constants.py (modified, +11/-5)
  • tools/memory_tool.py (modified, +199/-31)
  • tools/registry.py (modified, +4/-4)
RAW_BUFFERClick to expand / collapse

Problem

SOUL.md is currently only seeded on first run (see default_soul.py). After that, it never updates automatically. This creates a fundamental contradiction: Hermes claims to be a self-evolving AI, but its core persona file remains static.

Current Behavior

  • First run: SOUL.md is created with a default template
  • After that: never updated unless user manually edits
  • Agent stores lessons in MEMORY.md, but doesn't update SOUL.md

Why This Matters

  • Persona defines HOW the agent thinks and behaves
  • Memory only stores WHAT it learned
  • Without evolving SOUL.md, the agent's behavior doesn't truly change
  • Users who never manually edit SOUL.md get a static persona forever

Proposed Solution

  1. Add an evolution mechanism: when agent discovers behavior issues or learns significant lessons, it should propose updating SOUL.md
  2. Keep SOUL.md lean — only core behavioral rules, not verbose
  3. Update SOUL.md AND MEMORY.md when relevant: SOUL for behavior change, MEMORY for lesson recording

Example

User points out agent is guessing context instead of confirming. Current response: store lesson in MEMORY.md. Better response: also add rule to SOUL.md like "When user asks 'why did you respond that way', confirm which response they mean before answering."

This would make the "self-evolving" claim actually true.

extent analysis

TL;DR

Implement an evolution mechanism to update SOUL.md based on agent's learning and behavior issues, ensuring the core persona file evolves over time.

Guidance

  • Identify key events or triggers that should prompt updates to SOUL.md, such as significant lessons learned or behavior issues discovered.
  • Develop a process to propose and apply updates to SOUL.md based on these triggers, ensuring the file remains lean and focused on core behavioral rules.
  • Consider implementing a review or validation step to ensure updates to SOUL.md are accurate and effective before applying them.
  • Explore ways to integrate the update process with the existing MEMORY.md storage, to ensure consistency and completeness of the agent's knowledge and behavior.

Example

# Pseudocode example of updating SOUL.md
def update_soul(lesson):
    # Identify relevant rule or behavior to update
    rule = generate_rule_from_lesson(lesson)
    # Append or modify existing rule in SOUL.md
    with open('SOUL.md', 'a') as f:
        f.write(rule + '\n')
    # Also update MEMORY.md with the lesson
    update_memory(lesson)

Notes

The proposed solution requires careful consideration of how to balance the evolution of SOUL.md with the need to maintain a consistent and effective persona. It may be necessary to implement safeguards or review processes to prevent unintended changes or inconsistencies.

Recommendation

Apply workaround: Implement the proposed evolution mechanism to update SOUL.md based on agent's learning and behavior issues, as this will allow the agent's persona to truly evolve over time and align with the "self-evolving" claim.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#logging issue#authentication issue#prompt issue#agent setup#task chaining

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

hermes - ✅(Solved) Fix SOUL.md should evolve with usage, not just initialize once [1 pull requests, 1 comments, 2 participants]