message_reload_ops.md

jupytext	formats text_representation md:myst extension format_name format_version jupytext_version .md myst 0.13 1.11.5
kernelspec	display_name language name Python 3 python python3

Message Reload Ops

GrepOp

Purpose

Provides a text search capability for locating specific content within offloaded files by pattern matching. This operation enables case-insensitive search within a single file, making it easy to find specific lines in tool messages or compressed groups.

Functionality

• Searches for literal text patterns (case-insensitive) within a single file
• Limits result count to avoid overwhelming output (default: 50 matches)
• Returns matching lines with file path, line number, and content
• Ideal for locating specific content within known offloaded files

Parameters

• file_path (string, required):

  • The path to the file to search in
  • Can be an absolute or relative path
  • Must be a valid file path (not a directory)
  • Examples:
    • /workspace/context_store/tool_call_123.txt
    • ./context_store/compressed_group_0.json

• pattern (string, required):

  • The text pattern to search for in the file
  • Search is case-insensitive
  • Searched as a literal string (special regex characters are escaped)
  • Examples: "stored in", "error message", "function_name"

• limit (number, optional, default: 50):

  • Maximum number of matching lines to return
  • Stops searching after reaching the limit
  • Useful for large files to avoid token overflow
  • Example: 100 returns at most 100 matching lines

Return Value

The operation returns search results with matching lines:

• Each match is formatted as: file_path:line_number:line_content
• Returns up to limit matches
• If no matches found, returns a message indicating no matches
• Each match shows the complete line containing the pattern

Example: Searching for "error" in /workspace/context_store/tool_call_123.txt with limit 50 returns matching lines like:

/workspace/context_store/tool_call_123.txt:45:Error: Connection timeout
/workspace/context_store/tool_call_123.txt:78:Warning: Retrying after error

ReadFileOp

Purpose

Reads and returns the content of offloaded files, enabling on-demand access to compacted tool messages and compressed conversation history. Supports efficient pagination for handling large files.

Functionality

• Reads file content from specified path (absolute or relative)
• Supports pagination with offset and limit for reading specific line ranges
• Uses efficient sed command for line-based reading
• Works with text files
• Essential for retrieving full content of compacted tool messages
• Enables access to original message groups before compression

Parameters

• file_path (string, required):

  • The path to the file to read
  • Can be absolute or relative path
  • Path will be expanded and resolved automatically
  • Examples:
    • /workspace/context_store/tool_call_123.txt
    • ./context_store/compressed_group_0.json
    • ~/context_store/message.txt

• offset (number, required but has default):

  • The 0-based line number to start reading from
  • If not provided or 0, starts from the beginning of the file
  • Used in combination with limit for pagination
  • Example: 0 starts from the first line, 100 starts from line 100

• limit (number, required but has default):

  • Maximum number of lines to read from the offset
  • If not provided, defaults to 1,000,000 (reads to end of file)
  • Used with offset to implement pagination
  • Example: 100 reads up to 100 lines from the offset

Return Value

The operation returns the file content as a string:

• Content of the specified line range (from offset to offset + limit)
• Lines are returned without trailing newlines
• Empty string if the specified range is beyond the file's content
• Error message if file not found or cannot be read

Example: Reading /workspace/context_store/tool_call_123.txt with offset=0 and limit=100 returns the first 100 lines of the file.

Usage Pattern: Combining Grep and ReadFile

For a complete working example of how to use these operations in practice, please refer to: test_agentic_retrieve_op.py

This test file demonstrates:

• How to configure the system prompt to guide AI in using Grep and ReadFile operations
• Real-world usage scenarios with message offload and reload
• Proper parameter settings for AgenticRetrieveOp with working memory
• Best practices for combining these operations in a retrieval workflow