hermes - 💡(How to fix) Fix [Bug]: Bounded memory overflow does not trigger automatic consolidation/retry [1 participants]

Bug Description

Bug description

Built-in bounded memory does not automatically consolidate when it hits the configured char limit, despite the docs saying the agent should consolidate/replace entries to make room.

In practice, when memory / user is full, the memory tool returns an overflow error and stops. There is no synchronous overflow-handling path that triggers consolidation and retries the write.

Steps to reproduce

1. Use built-in memory (no external memory provider required).
2. Fill MEMORY.md close to memory.memory_char_limit (or configure a smaller limit for easier repro).
3. Call the memory tool with action=add and a new durable fact.
4. Observe the tool result:
   • success: false
   • error: Memory at X/Y chars. Adding this entry (...) would exceed the limit. Replace or remove existing entries first.
   • current_entries
   • usage

Expected behavior

Given the docs for bounded, curated memory, I expected one of these behaviors:

• the agent automatically consolidates/replaces/removes existing entries to make room, then retries the add once
• or overflow triggers a dedicated memory-cleanup review path before failing the write

At minimum, the runtime behavior should match the docs more closely.

Actual behavior

Current runtime behavior appears to be:

1. tools/memory_tool.py:MemoryStore.add() calculates new size.
2. If over the limit, it returns the overflow error immediately.
3. No automatic consolidation occurs in the store layer.
4. Background memory review is only driven by memory.nudge_interval turn cadence, not by overflow.
5. The current _MEMORY_REVIEW_PROMPT is weak for this case: it asks whether anything is worth saving, but does not strongly instruct the model to consolidate existing entries when memory is full.

Why this is surprising

From the user side, the feature is described as "bounded, curated memory". But the current implementation behaves more like:

• bounded storage with manual/soft curation
• overflow is surfaced as an error
• cleanup depends on later background review / agent behavior

So a full memory store can fail writes immediately even though the docs imply the agent should proactively make room.

Likely root cause

There seems to be a gap between documentation / intended behavior and actual runtime wiring.

Specifically:

• MemoryStore.add() rejects overflow but has no recovery hook.
• overflow does not trigger a dedicated memory-cleanup review.
• _MEMORY_REVIEW_PROMPT is tuned for opportunistic saving, not overflow-driven consolidation.
• memory.flush_min_turns appears in config, but I could not find active runtime usage for it in the current codebase.

Suggested fix direction

Minimal-risk fix idea:

• Keep MemoryStore.add() as a pure bounded store that returns a structured overflow error.
• In run_agent.py, when a memory tool call with action=add returns the overflow error, trigger a dedicated memory-only overflow cleanup pass (sync or narrowly-scoped background with retry barrier), then retry the original add once.
• Add a dedicated overflow prompt, e.g. _MEMORY_OVERFLOW_REVIEW_PROMPT, that explicitly instructs the reviewer to:
  1. remove stale / low-value entries,
  2. merge overlapping entries,
  3. shorten overlong entries,
  4. retry making room for the new fact.
• If cleanup does not free enough space, return the original overflow error.

This keeps the storage layer simple while making runtime behavior match the docs.

Relevant code locations

• tools/memory_tool.py
• run_agent.py
  • memory nudge interval wiring
  • background review spawning
  • _MEMORY_REVIEW_PROMPT
• website/docs/user-guide/features/memory.md

Version

Observed on:

• Hermes Agent: v0.13.0 (2026.5.7)
• local checkout reports: Update available: 3 commits behind

I have not yet re-tested after running hermes update, so if this is expected for the bug template, I should re-check on latest first.

Config relevant to reproduction

Built-in memory config in my environment:

Steps to Reproduce

Expected Behavior

Actual Behavior

Affected Component

Agent Core (conversation loop, context compression, memory)

Messaging Platform (if gateway-related)

No response

Debug Report

Local debug summary:

- Hermes Agent: `v0.13.0 (2026.5.7)` (`3d4297a5`)
- OS: `Linux 6.12.74+deb13+1-amd64 x86_64`
- Python: `3.11.15`
- OpenAI SDK: `2.32.0`
- Profile: `default`
- Memory provider: `built-in`
- Model at time of observation: `gpt-5.4`
- Provider at time of observation: `longxiadev`

Relevant memory config:
yaml
memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200
  user_char_limit: 1375
  flush_min_turns: 6
  nudge_interval: 10

Operating System

Debian13

Python Version

3.13.5

Hermes Version

v0.13.0 (2026.5.7)

Additional Logs / Traceback (optional)

Root Cause Analysis (optional)

No response

Proposed Fix (optional)

No response

Are you willing to submit a PR for this?

• I'd like to fix this myself and submit a PR