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