roam_search_by_date
Find Roam Research blocks or pages created or modified within specific date ranges to locate historical content and track changes over time.
Instructions
Search for blocks or pages based on creation or modification dates. Not for daily pages with ordinal date titles.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | Yes | Start date in ISO format (YYYY-MM-DD) | |
| end_date | No | Optional: End date in ISO format (YYYY-MM-DD) | |
| type | Yes | Whether to search by creation date, modification date, or both | |
| scope | Yes | Whether to search blocks, pages | |
| include_content | No | Whether to include the content of matching blocks/pages |
Implementation Reference
- Core handler function that implements the 'roam_search_by_date' tool logic: converts date range to timestamps, fetches all blocks via text search with empty query, filters by date (using placeholder logic), maps and sorts results.async searchByDate(params: { start_date: string; end_date?: string; type: 'created' | 'modified' | 'both'; scope: 'blocks' | 'pages' | 'both'; include_content: boolean; }): Promise<{ success: boolean; matches: Array<{ uid: string; type: string; time: number; content?: string; page_title?: string }>; message: string }> { // Convert dates to timestamps const startTimestamp = new Date(`${params.start_date}T00:00:00`).getTime(); const endTimestamp = params.end_date ? new Date(`${params.end_date}T23:59:59`).getTime() : undefined; // Use text search handler for content-based filtering const handler = new TextSearchHandlerImpl(this.graph, { text: '', // Empty text to match all blocks }); const result = await handler.execute(); // Filter results by date const matches = result.matches .filter(match => { const time = params.type === 'created' ? new Date(match.content || '').getTime() : // Use content date for creation time Date.now(); // Use current time for modification time (simplified) return time >= startTimestamp && (!endTimestamp || time <= endTimestamp); }) .map(match => ({ uid: match.block_uid, type: 'block', time: params.type === 'created' ? new Date(match.content || '').getTime() : Date.now(), ...(params.include_content && { content: match.content }), page_title: match.page_title })); // Sort by time const sortedMatches = matches.sort((a, b) => b.time - a.time); return { success: true, matches: sortedMatches, message: `Found ${sortedMatches.length} matches for the given date range and criteria` }; }
- src/tools/tool-handlers.ts:93-100 (handler)Delegating handler method in ToolHandlers class that forwards the tool call to SearchOperations.searchByDate.async searchByDate(params: { start_date: string; end_date?: string; type: 'created' | 'modified' | 'both'; scope: 'blocks' | 'pages' | 'both'; include_content: boolean; }) { return this.searchOps.searchByDate(params);
- src/tools/schemas.ts:372-404 (schema)Input schema definition for the 'roam_search_by_date' tool, including parameters for date range, type, scope, and content inclusion.[toolName(BASE_TOOL_NAMES.SEARCH_BY_DATE)]: { name: toolName(BASE_TOOL_NAMES.SEARCH_BY_DATE), description: 'Search for blocks or pages based on creation or modification dates. Not for daily pages with ordinal date titles.', inputSchema: { type: 'object', properties: { start_date: { type: 'string', description: 'Start date in ISO format (YYYY-MM-DD)', }, end_date: { type: 'string', description: 'Optional: End date in ISO format (YYYY-MM-DD)', }, type: { type: 'string', enum: ['created', 'modified', 'both'], description: 'Whether to search by creation date, modification date, or both', }, scope: { type: 'string', enum: ['blocks', 'pages', 'both'], description: 'Whether to search blocks, pages', }, include_content: { type: 'boolean', description: 'Whether to include the content of matching blocks/pages', default: true, } }, required: ['start_date', 'type', 'scope'] } },
- src/server/roam-server.ts:292-304 (registration)Tool registration in the MCP server request handler: switch case that handles calls to 'roam_search_by_date' by invoking ToolHandlers.searchByDate and returning JSON result.case BASE_TOOL_NAMES.SEARCH_BY_DATE: { const params = request.params.arguments as { start_date: string; end_date?: string; type: 'created' | 'modified' | 'both'; scope: 'blocks' | 'pages' | 'both'; include_content: boolean; }; const result = await this.toolHandlers.searchByDate(params); return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], }; }
- src/server/roam-server.ts:90-92 (registration)Registers all tools (including 'roam_search_by_date') for listing via MCP ListToolsRequest.mcpServer.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: Object.values(toolSchemas), }));