decay

Instructions

Implementation Reference

• nexus_mcp.py:165-169 (schema)

  Tool definition (inputSchema) for the 'decay' tool — a dry-run decay check with no required parameters.

  {
      "name": "decay",
      "description": "Run a dry-run decay check. Calculates Ebbinghaus decay for all memories and reports which would be archived. Does NOT modify any files.",
      "inputSchema": {"type": "object", "properties": {}},
  },

• nexus_mcp.py:299-328 (handler)

  Handler for the 'decay' tool call. Iterates all memory files, computes Ebbinghaus exponential decay based on days since creation and tier-specific decay constants, reports which would decay or be archived. Pure dry-run (no file modification).

  elif name == "decay":
      files = list_memory_files()
      today_epoch = datetime.now().timestamp()
      decay_map = {
          "semantic": 90, "episodic": 30, "procedural": 180,
          "reflection": 60, "working": 7, "core": 999999,
      }
      results_lines = ["Decay check (dry-run):", ""]
      for f in files:
          with open(os.path.join(MEMORY_DIR, f["path"]), encoding="utf-8") as fh:
              text = fh.read()
          created = parse_frontmatter(text, "created") or "2026-05-18"
          try:
              dt = datetime.strptime(created[:10], "%Y-%m-%d")
              days = max(1, (datetime.now() - dt).days)
          except ValueError:
              days = 1
          dc = decay_map.get(f["type"], 30)
          new_s = f["strength"] * math.exp(-days / dc)
          new_s = max(0.05, min(1.0, new_s))
          if abs(new_s - f["strength"]) > 0.01:
              status = ""
              if new_s < 0.2:
                  status = " [WOULD ARCHIVE]"
              elif new_s < 0.4:
                  status = " [DECAYING]"
              results_lines.append(f"  {f['name']}: {f['strength']:.2f} → {new_s:.2f} ({days}d){status}")
      if len(results_lines) == 2:
          results_lines.append("  All memories at expected strength.")
      return {"content": [{"type": "text", "text": "\n".join(results_lines)}]}, None

• nexus_mcp.py:120-170 (registration)

  TOOL_DEFS list registering all tools including 'decay' (line 166-169). Also handle_tools_list at line 172-173 returns these definitions.

  TOOL_DEFS = [
      {
          "name": "search",
          "description": "Search across all memory files by keyword. Returns matching file names, titles, strengths, and context snippets.",
          "inputSchema": {
              "type": "object",
              "properties": {"query": {"type": "string", "description": "Keyword or phrase to search for"}},
              "required": ["query"],
          },
      },
      {
          "name": "stats",
          "description": "Show memory health statistics: file counts per tier, average strength, active/decaying/archived counts.",
          "inputSchema": {"type": "object", "properties": {}},
      },
      {
          "name": "save",
          "description": "Save a new memory to a specified tier. Creates a markdown file with frontmatter. Use for recording new information, preferences, or experiences.",
          "inputSchema": {
              "type": "object",
              "properties": {
                  "tier": {
                      "type": "string",
                      "enum": ["episodic", "semantic", "procedural", "reflection", "working"],
                      "description": "Memory tier: episodic (experiences), semantic (facts/preferences), procedural (workflows), reflection (meta), working (in-session)",
                  },
                  "name": {"type": "string", "description": "Filename slug (no extension, use dashes: my-memory-name)"},
                  "content": {"type": "string", "description": "Full markdown content of the memory (including title heading)"},
                  "tags": {"type": "string", "description": "Comma-separated tags (optional)"},
              },
              "required": ["tier", "name", "content"],
          },
      },
      {
          "name": "touch",
          "description": "Boost a memory's strength (simulate access, counteracts Ebbinghaus decay). Use this when a memory is referenced or found relevant.",
          "inputSchema": {
              "type": "object",
              "properties": {
                  "name": {"type": "string", "description": "Memory filename (with or without .md extension)"},
                  "boost": {"type": "number", "description": "Strength boost amount (default 0.15, max 1.0)"},
              },
              "required": ["name"],
          },
      },
      {
          "name": "decay",
          "description": "Run a dry-run decay check. Calculates Ebbinghaus decay for all memories and reports which would be archived. Does NOT modify any files.",
          "inputSchema": {"type": "object", "properties": {}},
      },
  ]