Package com.tnsai.annotations

Annotation Interface Ephemeral

@Documented @Retention(RUNTIME) @Target(METHOD) public @interface Ephemeral
Marks an action as producing ephemeral outputs that should not accumulate in context.

When an action is marked as ephemeral, only the last N results are kept in the conversation history. Older results are automatically removed to prevent context explosion from large tool outputs (e.g., browser DOM, screenshots).

Problem Solved

Some tools produce large outputs (DOM trees, screenshots, API responses) that quickly fill up the LLM context window. This annotation ensures only recent outputs are kept, enabling long-running sessions.

Usage


 @ActionSpec(type = ActionType.LLM, description = "Get browser state")
 @Ephemeral(keepLast = 3)  // Keep only last 3 results
 public BrowserState getBrowserState() {
     return new BrowserState(dom, screenshot, cookies);
 }

 // Context behavior:
 // Call 1: Result #1 kept
 // Call 2: Result #1, #2 kept
 // Call 3: Result #1, #2, #3 kept
 // Call 4: Result #2, #3, #4 kept (Result #1 removed)
 // Call 5: Result #3, #4, #5 kept (Result #2 removed)

When to Use

  • Browser automation - DOM snapshots, screenshots
  • File operations - Large file contents
  • API calls - Verbose JSON responses
  • Database queries - Large result sets
  • Any tool producing outputs larger than ~1000 tokens

Comparison with Memory Strategies

Feature@EphemeralSlidingWindowMemory
ScopePer-actionAll messages
GranularityTool-specificGlobal
Use caseLarge tool outputsGeneral context limit
Author:
TnsAI Team
See Also:
  • invalid reference 
    EphemeralContextManager

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    int
    keepLast
    Number of most recent results to keep in context.
    boolean
    keepSummary
    Whether to keep a summary of removed results.
    String
    summaryTemplate
    Custom summary template for removed results.

  • Element Details

    • keepLast

      int keepLast
      Number of most recent results to keep in context.

      When the action is called more times than this value, older results are removed from the conversation history.

      Recommended values:

      • 1 - For very large outputs (screenshots)
      • 3 - For medium outputs (DOM, API responses)
      • 5 - For smaller outputs (status checks)
      Returns:
      number of results to keep (default: 3)
      Default:
      3

    • keepSummary

      boolean keepSummary
      Whether to keep a summary of removed results.

      When enabled, removed results are replaced with a brief summary like "[Previous 5 getBrowserState results omitted]".

      Returns:
      true to keep summary placeholder (default: true)
      Default:
      true

    • summaryTemplate

      String summaryTemplate
      Custom summary template for removed results.

      Placeholders:

      • {count} - Number of removed results
      • {action} - Action name
      Returns:
      summary template (default: "[Previous {count} {action} results omitted]")
      Default:
      "[Previous {count} {action} results omitted]"