feat(scripts): add memory budget enforcement tool (#256) #266

Timmy · 2026-04-10T01:13:21Z

Timmy commented

2026-04-10 01:13:21 +00:00

Closes #256

Adds scripts/memory_budget.py — a CI-friendly tool for checking and enforcing character budgets on MEMORY.md and USER.md memory files.

Features

Checks MEMORY.md vs memory_char_limit (default 2200 chars)
Checks USER.md vs user_char_limit (default 1375 chars)
Estimates total injection cost (chars / ~4 chars per token)
Alerts when approaching limits (>80% usage)
--report flag for detailed breakdown with progress bars
--verbose flag for per-entry details
--enforce flag trims oldest entries to fit budget
--json flag for machine-readable output (CI integration)
Exit codes: 0=within budget, 1=over budget, 2=trimmed
Suggestions for largest entries when over budget

Design

Uses same entry delimiter (§) and splitting logic as MemoryStore in tools/memory_tool.py
Defaults match the built-in limits: memory_char_limit=2200, user_char_limit=1375
Token estimation uses the same 4-chars-per-token heuristic as agent/model_metadata.py:estimate_tokens_rough()
--enforce trims oldest entries first (front of file) since memory files append new entries at the end
Standalone script with no hermes-agent runtime dependencies — safe for CI

Closes #256 Adds `scripts/memory_budget.py` — a CI-friendly tool for checking and enforcing character budgets on MEMORY.md and USER.md memory files. ### Features - Checks MEMORY.md vs `memory_char_limit` (default 2200 chars) - Checks USER.md vs `user_char_limit` (default 1375 chars) - Estimates total injection cost (chars / ~4 chars per token) - Alerts when approaching limits (>80% usage) - `--report` flag for detailed breakdown with progress bars - `--verbose` flag for per-entry details - `--enforce` flag trims oldest entries to fit budget - `--json` flag for machine-readable output (CI integration) - Exit codes: 0=within budget, 1=over budget, 2=trimmed - Suggestions for largest entries when over budget ### Design - Uses same entry delimiter (`§`) and splitting logic as `MemoryStore` in `tools/memory_tool.py` - Defaults match the built-in limits: memory_char_limit=2200, user_char_limit=1375 - Token estimation uses the same 4-chars-per-token heuristic as `agent/model_metadata.py:estimate_tokens_rough()` - `--enforce` trims oldest entries first (front of file) since memory files append new entries at the end - Standalone script with no hermes-agent runtime dependencies — safe for CI

Timmy added 1 commit 2026-04-10 01:13:21 +00:00

feat(scripts): add memory budget enforcement tool (#256 )

Forge CI / smoke-and-build (pull_request) Successful in 40s

Details

0d92b9ad15

Add scripts/memory_budget.py — a CI-friendly tool for checking and
enforcing character budgets on MEMORY.md and USER.md memory files.

Features:
- Checks MEMORY.md vs memory_char_limit (default 2200)
- Checks USER.md vs user_char_limit (default 1375)
- Estimates total injection cost (chars / ~4 chars per token)
- Alerts when approaching limits (>80% usage)
- --report flag for detailed breakdown with progress bars
- --verbose flag for per-entry details
- --enforce flag trims oldest entries to fit budget
- --json flag for machine-readable output (CI integration)
- Exit codes: 0=within budget, 1=over budget, 2=trimmed
- Suggestions for largest entries when over budget

Relates to #256

Rockachopa reviewed 2026-04-10 03:41:33 +00:00

Rockachopa left a comment

Auto-approved: clean diff, no conflicts, mergeable.

Rockachopa scheduled this pull request to auto merge when all checks succeed 2026-04-10 03:41:34 +00:00

Rockachopa merged commit 2948d010b7 into main

2026-04-10 03:44:03 +00:00

Rockachopa referenced this issue from a commit

2026-04-10 03:44:06 +00:00

Merge pull request #266

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Timmy_Foundation/hermes-agent#266