Skip to main content
Glama

run_decay

Destructive

Runs a memory decay cycle to lower old memories' scores, archive low-score or expired entries, and optionally permanently forget retained archives; MUST items skip score decay but still expire.

Instructions

Run a memory decay cycle: reduces decay_score for old memories and archives memories that fall below the threshold or whose expires_at valid-time bound has passed. MUST memories are exempt from score-based decay, but NOT from expiry — a MUST whose window has closed is a binding instruction that is no longer true. This is not purely reversible: if MEMVAULT_FORGET_AUTO_ENABLED=1, the same run also permanently forgets archived memories older than MEMVAULT_FORGET_RETENTION_DAYS (default 90); otherwise auto-forget is off. Requires agent auth when the agent has a registered key. Returns updated/archived/expired_archived/contradicted/harmful_flagged/auto_forgotten counts.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "run_decay"
  }
}

Input Schema

NameRequiredDescriptionDefault
api_keyNoAPI key for agent authentication (required if agent has a registered key)
agent_idNoID of the requesting agentunknown

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.2/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds material context an agent cannot get from them: MUST memories are exempt from decay yet still expire, and a run is not purely reversible because MEMVAULT_FORGET_AUTO_ENABLED=1 triggers permanent forgetting of archives older than the retention window (default 90 days). It also discloses the auth requirement and return counts.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then progressive disclosure of edge cases (MUST exemption, irreversible auto-forget, auth). Dense but every clause carries information; a slightly lighter sentence structure would make the env-var caveat easier to scan.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive maintenance tool with no output schema, the description covers effects, exemptions, irreversibility conditions, auth, and even summarizes the returned counts. Nothing an agent needs before invoking it is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both `api_key` and `agent_id` are already documented in the schema; the description only restates the auth condition for `api_key` and says nothing about `agent_id`. Baseline 3 applies since the schema carries the parameter burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Run a memory decay cycle') and then enumerates the concrete effects: reducing decay_score, archiving below-threshold memories, and archiving expired valid-time bounds. The scope is unmistakable and separable from siblings like run_dedup or run_promote, even though no sibling is named.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the conditions the tool acts on (score threshold, expired `expires_at`, MUST exemption) and its prerequisite (agent auth when a key is registered), but never says when an agent should invoke it or when another maintenance tool would be the better choice. Usage is implied by 'decay cycle' rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.