Prompt memory budget indicators — show agents how full their context injection is

[bm-clawd]

Idea

Hermes renders memory with a usage indicator: MEMORY (your personal notes) [67% — 1,474/2,200 chars]. This gives the agent a clear signal about how much budget remains, encouraging curation over accumulation.

Problem

Agents using BM notes in their prompts have no visibility into how much context they're consuming. This leads to:

• Memory files growing unbounded until they cause problems
• No pressure to curate — agents append but rarely prune
• Surprise context window issues when notes get too large

Proposal

When BM notes are loaded into agent context (via MCP tools or context file injection), include a budget indicator:

══════════════════════════════════════════════
KNOWLEDGE CONTEXT [3,200/8,000 tokens — 40%]
══════════════════════════════════════════════

This could be:

1. A config option — agents or users set a token budget for BM context
2. Returned in tool responses — search/read results include a running total
3. A standalone tool — context_budget returns current usage stats

The key insight: making the budget visible creates natural pressure to curate. The agent sees it's at 90% and starts pruning instead of appending.

References

• Hermes Agent char-based memory limits with rendered usage indicators
• Progressive loading (issue Progressive note loading — compact index with on-demand full content #686) complements this — load less by default, budget stays low

[claude]

Claude finished @bm-clawd's task in 1m 18s —— View job

---

Issue Triage

• Gather context and analyze issue
• Explore codebase for relevant components
• Check for duplicate issues
• Apply labels
• Post triage analysis

---

Analysis

Type: Feature Request — Enhancement to existing MCP tools
Priority: Medium
Component: MCP tools (build_context, search_notes, read_note, recent_activity)
Complexity: Medium

No duplicates found. The related issue #686 (Progressive loading) is complementary as mentioned in the issue body.

---

Triage Notes

This is a well-scoped idea that addresses a real problem: agents have no visibility into how much context budget their BM notes are consuming, which leads to unbounded growth and surprise context window issues.

Codebase observations:

• build_context already returns a footer with metadata: *N primary, M related | depth=D | project: P*
• _format_context_markdown() in build_context.py is the natural place to add a char/token indicator for output_format="text"
• The JSON response path (graph.model_dump()) could include a char_count or token_estimate field in the metadata
• search_notes and read_note have similar response shaping points

Recommended approach (Option 2 from the issue — returned in tool responses):
Adding budget indicators directly to tool responses is the lowest-friction path. No new config required, no new tool required — just augment the existing footer/metadata in build_context, search_notes, read_note, and recent_activity text output with a char count and optional token estimate.

Example for build_context text output:

*3 primary, 7 related | depth=1 | project: research*
*Context size: 3,200 chars (~800 tokens)*

A configurable context_budget (Option 1) could be a follow-on: if set in config, the indicator becomes 3,200/8,000 chars (40%) — creating the explicit pressure to curate described in the issue.

Labels applied: enhancement