GitHub Issue Draft

Repo: openclaw/openclaw Title: Add absolute-token trigger for compaction (independent of model context window)

Submit with:

gh issue create \
  --repo openclaw/openclaw \
  --title "Add absolute-token trigger for compaction (independent of model context window)" \
  --body-file /Users/home/.openclaw/workspace/agents/nuntia/drafts/gh-issue-absolute-compaction-threshold.md

Body

Problem

agents.defaults.compaction.memoryFlush.softThresholdTokens is described as the trigger threshold for pre-compaction memory flush, but it's actually distance to the model's context limit, not an absolute usage count.

This means:

1. The same setting behaves very differently across models. On Opus (200k window), softThresholdTokens: 50000 fires at ~150k tokens used. On a 1M-context model, it fires at ~950k tokens used. On a 32k model, it fires almost immediately.
2. Users who want "compact when conversation hits N tokens" have to manually compute window - N per model and update it whenever they change models.
3. The field name and short description ("Compaction Memory Flush Soft Threshold") strongly imply absolute behavior, leading to incorrect mental models. (Confirmed firsthand: I configured softThresholdTokens: 50000 expecting compaction at 50k used, then sat at 190k tokens with no compaction firing.)

Proposed solution

Add a sibling field:

"memoryFlush": {
  "enabled": true,
  "softThresholdTokens": 50000,        // existing: distance-from-limit
  "absoluteThresholdTokens": 75000,    // new: absolute usage trigger
  "forceFlushTranscriptBytes": "2mb"
}

Semantics:

• If both are set, whichever fires first wins (consistent with forceFlushTranscriptBytes).
• absoluteThresholdTokens is model-independent and survives model switches.
• Default unset (undefined), preserving current behavior.

Why this matters

• Cost control on long-context models. On Opus, sitting at 190k uncompacted means every turn re-sends 190k tokens of context. Even with prompt caching, this is expensive and degrades reasoning quality. An absolute trigger lets users set "I never want a session above 75k" regardless of model.
• Multi-agent / multi-model setups. When a user runs Opus, Sonnet, Haiku, and a non-Anthropic model concurrently with shared agents.defaults, a per-model relative threshold is wrong for at least one of them.
• Predictable behavior. Users tune for cost and quality, not "how close am I to OOM."

Alternatives considered

• Per-model overrides (current workaround): functional but brittle and surprising.
• Use maxHistoryShare: caps post-compaction retention, doesn't control trigger timing.
• Documentation-only fix: would help, but the actual user need is an absolute trigger.

Affected paths

• Schema: agents.defaults.compaction.memoryFlush
• Compaction trigger logic (wherever softThresholdTokens is currently evaluated)
• Per-agent compaction overrides (same field on the per-agent path)

Willing to PR?

I'm a user, not a contributor (yet) — happy to test or iterate on the spec if a maintainer scopes the change. If the team prefers to keep softThresholdTokens and just add absoluteThresholdTokens alongside, that's the smallest viable change.

Environment

• OpenClaw 2026.4.29 (a448042)
• macOS Darwin 25.4.0 arm64
• Primary model: anthropic/claude-opus-4-7