roam-research-mcp 0.23.1 → 0.24.2

package/README.md

@@ -30,6 +30,16 @@ npm run build
 
 The server provides powerful tools for interacting with Roam Research:
 
+- Environment variable handling with .env support
+- Comprehensive input validation
+- Case-insensitive page title matching
+- Recursive block reference resolution
+- Markdown parsing and conversion
+- Daily page integration
+- Detailed debug logging
+- Efficient batch operations
+- Hierarchical outline creation
+
 1. `roam_fetch_page_by_title`: Fetch and read a page's content by title, recursively resolving block references up to 4 levels deep
 2. `roam_create_page`: Create new pages with optional content
 3. `roam_create_block`: Create new blocks in a page (defaults to today's daily page)
@@ -38,7 +48,7 @@ The server provides powerful tools for interacting with Roam Research:
 6. `roam_create_outline`: Create hierarchical outlines with proper nesting and structure
 7. `roam_search_block_refs`: Search for block references within pages or across the graph
 8. `roam_search_hierarchy`: Navigate and search through block parent-child relationships
-9. `find_pages_modified_today`: Find all pages that have been modified since midnight today
+9. `roam_find_pages_modified_today`: Find all pages that have been modified since midnight today
 10. `roam_search_by_text`: Search for blocks containing specific text across all pages or within a specific page
 11. `roam_update_block`: Update block content with direct text or pattern-based transformations
 12. `roam_search_by_date`: Search for blocks and pages based on creation or modification dates
@@ -545,7 +555,7 @@ Returns:
 Find all pages that have been modified since midnight today:
 
 ```typescript
-use_mcp_tool roam-research find_pages_modified_today {}
+use_mcp_tool roam-research roam_find_pages_modified_today {}
 ```
 
 Features:
@@ -717,25 +727,39 @@ Each error response includes:
 
 ## Development
 
-The server is built with TypeScript and includes:
+### Building
 
-- Environment variable handling with .env support
-- Comprehensive input validation
-- Case-insensitive page title matching
-- Recursive block reference resolution
-- Markdown parsing and conversion
-- Daily page integration
-- Detailed debug logging
-- Efficient batch operations
-- Hierarchical outline creation
+To build the server:
+
+```bash
+npm install
+npm run build
+```
+
+This will:
+
+1. Install all required dependencies
+2. Compile TypeScript to JavaScript
+3. Make the output file executable
+
+You can also use `npm run watch` during development to automatically recompile when files change.
+
+### Testing with MCP Inspector
+
+The MCP Inspector is a tool that helps test and debug MCP servers. To test the server:
+
+```bash
+# Inspect with npx:
+npx @modelcontextprotocol/inspector node build/index.js
+```
 
-To modify or extend the server:
+This will:
 
-1. Clone the repository
-2. Install dependencies with `npm install`
-3. Make changes to the source files
-4. Build with `npm run build`
-5. Test locally by configuring environment variables
+1. Start the server in inspector mode
+2. Provide an interactive interface to:
+   - List available tools and resources
+   - Execute tools with custom parameters
+   - View tool responses and error handling
 
 ## License
 

package/build/search/block-ref-search.js

@@ -1,6 +1,7 @@
 import { q } from '@roam-research/roam-api-sdk';
 import { BaseSearchHandler } from './types.js';
 import { SearchUtils } from './utils.js';
+import { resolveRefs } from '../tools/helpers/refs.js';
 export class BlockRefSearchHandler extends BaseSearchHandler {
     params;
     constructor(graph, params) {
@@ -63,10 +64,15 @@ export class BlockRefSearchHandler extends BaseSearchHandler {
                 queryParams = [];
             }
         }
-        const results = await q(this.graph, queryStr, queryParams);
+        const rawResults = await q(this.graph, queryStr, queryParams);
+        // Resolve block references in content
+        const resolvedResults = await Promise.all(rawResults.map(async ([uid, content, pageTitle]) => {
+            const resolvedContent = await resolveRefs(this.graph, content);
+            return [uid, resolvedContent, pageTitle];
+        }));
         const searchDescription = block_uid
             ? `referencing block ((${block_uid}))`
             : 'containing block references';
-        return SearchUtils.formatSearchResults(results, searchDescription, !targetPageUid);
+        return SearchUtils.formatSearchResults(resolvedResults, searchDescription, !targetPageUid);
     }
 }

package/build/search/hierarchy-search.js

@@ -1,6 +1,7 @@
 import { q } from '@roam-research/roam-api-sdk';
 import { BaseSearchHandler } from './types.js';
 import { SearchUtils } from './utils.js';
+import { resolveRefs } from '../tools/helpers/refs.js';
 export class HierarchySearchHandler extends BaseSearchHandler {
     params;
     constructor(graph, params) {
@@ -85,13 +86,16 @@ export class HierarchySearchHandler extends BaseSearchHandler {
                 queryParams = [ancestorRule, child_uid];
             }
         }
-        const results = await q(this.graph, queryStr, queryParams);
-        // Format results to include depth information
-        const matches = results.map(([uid, content, pageTitle, depth]) => ({
-            block_uid: uid,
-            content,
-            depth: depth || 1,
-            ...(pageTitle && { page_title: pageTitle })
+        const rawResults = await q(this.graph, queryStr, queryParams);
+        // Resolve block references and format results to include depth information
+        const matches = await Promise.all(rawResults.map(async ([uid, content, pageTitle, depth]) => {
+            const resolvedContent = await resolveRefs(this.graph, content);
+            return {
+                block_uid: uid,
+                content: resolvedContent,
+                depth: depth || 1,
+                ...(pageTitle && { page_title: pageTitle })
+            };
         }));
         const searchDescription = parent_uid
             ? `descendants of block ${parent_uid}`

package/build/search/status-search.js

@@ -1,6 +1,7 @@
 import { q } from '@roam-research/roam-api-sdk';
 import { BaseSearchHandler } from './types.js';
 import { SearchUtils } from './utils.js';
+import { resolveRefs } from '../tools/helpers/refs.js';
 export class StatusSearchHandler extends BaseSearchHandler {
     params;
     constructor(graph, params) {
@@ -37,7 +38,12 @@ export class StatusSearchHandler extends BaseSearchHandler {
                          [(clojure.string/includes? ?block-str (str "{{[[" ?status "]]}}"))]]`;
             queryParams = [status];
         }
-        const results = await q(this.graph, queryStr, queryParams);
-        return SearchUtils.formatSearchResults(results, `with status ${status}`, !targetPageUid);
+        const rawResults = await q(this.graph, queryStr, queryParams);
+        // Resolve block references in content
+        const resolvedResults = await Promise.all(rawResults.map(async ([uid, content, pageTitle]) => {
+            const resolvedContent = await resolveRefs(this.graph, content);
+            return [uid, resolvedContent, pageTitle];
+        }));
+        return SearchUtils.formatSearchResults(resolvedResults, `with status ${status}`, !targetPageUid);
     }
 }

package/build/search/tag-search.js

@@ -1,6 +1,7 @@
 import { q } from '@roam-research/roam-api-sdk';
 import { BaseSearchHandler } from './types.js';
 import { SearchUtils } from './utils.js';
+import { resolveRefs } from '../tools/helpers/refs.js';
 export class TagSearchHandler extends BaseSearchHandler {
     params;
     constructor(graph, params) {
@@ -28,8 +29,13 @@ export class TagSearchHandler extends BaseSearchHandler {
                       [?b :block/page ?p]
                       [?p :node/title ?page-title]]`;
         const queryParams = [primary_tag];
-        const results = await q(this.graph, queryStr, queryParams);
+        const rawResults = await q(this.graph, queryStr, queryParams);
+        // Resolve block references in content
+        const resolvedResults = await Promise.all(rawResults.map(async ([uid, content, pageTitle]) => {
+            const resolvedContent = await resolveRefs(this.graph, content);
+            return [uid, resolvedContent, pageTitle];
+        }));
         const searchDescription = `referencing "${primary_tag}"`;
-        return SearchUtils.formatSearchResults(results, searchDescription, !targetPageUid);
+        return SearchUtils.formatSearchResults(resolvedResults, searchDescription, !targetPageUid);
     }
 }

package/build/search/text-search.js

@@ -1,6 +1,7 @@
 import { q } from '@roam-research/roam-api-sdk';
 import { BaseSearchHandler } from './types.js';
 import { SearchUtils } from './utils.js';
+import { resolveRefs } from '../tools/helpers/refs.js';
 export class TextSearchHandler extends BaseSearchHandler {
     params;
     constructor(graph, params) {
@@ -24,8 +25,13 @@ export class TextSearchHandler extends BaseSearchHandler {
                       [?b :block/page ?p]
                       [?p :node/title ?page-title]]`;
         const queryParams = [text];
-        const results = await q(this.graph, queryStr, queryParams);
+        const rawResults = await q(this.graph, queryStr, queryParams);
+        // Resolve block references in content
+        const resolvedResults = await Promise.all(rawResults.map(async ([uid, content, pageTitle]) => {
+            const resolvedContent = await resolveRefs(this.graph, content);
+            return [uid, resolvedContent, pageTitle];
+        }));
         const searchDescription = `containing "${text}"`;
-        return SearchUtils.formatSearchResults(results, searchDescription, !targetPageUid);
+        return SearchUtils.formatSearchResults(resolvedResults, searchDescription, !targetPageUid);
     }
 }

package/build/server/roam-server.js

@@ -17,7 +17,7 @@ export class RoamServer {
         this.toolHandlers = new ToolHandlers(this.graph);
         this.server = new Server({
             name: 'roam-research',
-            version: '0.17.0',
+            version: '0.24.2',
         }, {
             capabilities: {
                 tools: {
@@ -33,7 +33,7 @@ export class RoamServer {
                     roam_search_by_status: {},
                     roam_search_block_refs: {},
                     roam_search_hierarchy: {},
-                    find_pages_modified_today: {},
+                    roam_find_pages_modified_today: {},
                     roam_search_by_text: {},
                     roam_update_block: {},
                     roam_update_blocks: {},
@@ -136,7 +136,7 @@ export class RoamServer {
                             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
                         };
                     }
-                    case 'find_pages_modified_today': {
+                    case 'roam_find_pages_modified_today': {
                         const result = await this.toolHandlers.findPagesModifiedToday();
                         return {
                             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
@@ -173,7 +173,8 @@ export class RoamServer {
                         };
                     }
                     case 'roam_recall': {
-                        const result = await this.toolHandlers.recall();
+                        const { sort_by = 'newest', filter_tag } = request.params.arguments;
+                        const result = await this.toolHandlers.recall(sort_by, filter_tag);
                         return {
                             content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
                         };

package/build/tools/operations/memory.js

@@ -66,7 +66,7 @@ export class MemoryOperations {
         }
         return { success: true };
     }
-    async recall() {
+    async recall(sort_by = 'newest', filter_tag) {
         // Get memories tag from environment
         var memoriesTag = process.env.MEMORIES_TAG;
         if (!memoriesTag) {
@@ -76,27 +76,73 @@ export class MemoryOperations {
         const tagText = memoriesTag
             .replace(/^#/, '') // Remove leading #
             .replace(/^\[\[/, '').replace(/\]\]$/, ''); // Remove [[ and ]]
-        // Get results from tag search
-        const tagResults = await this.searchOps.searchForTag(tagText);
-        // Get blocks from the memories page
-        const pageQuery = `[:find ?string
-                       :in $ ?title
-                       :where [?p :node/title ?title]
-                              [?b :block/page ?p]
-                              [?b :block/string ?string]]`;
-        const pageResults = await q(this.graph, pageQuery, [tagText]);
-        // Combine both sets of results and remove the memories tag
-        const allMemories = [
-            ...tagResults.matches.map((match) => match.content),
-            ...pageResults.map(([content]) => content)
-        ].map(content => content.replace(`${memoriesTag} `, ''));
-        // Resolve any block references in the combined memories
-        const resolvedMemories = await Promise.all(allMemories.map(async (content) => resolveRefs(this.graph, content)));
-        // Remove duplicates
-        const uniqueMemories = [...new Set(resolvedMemories)];
-        return {
-            success: true,
-            memories: uniqueMemories
-        };
+        try {
+            // Get page blocks using query to access actual block content
+            const ancestorRule = `[
+        [ (ancestor ?b ?a)
+          [?a :block/children ?b] ]
+        [ (ancestor ?b ?a)
+          [?parent :block/children ?b]
+          (ancestor ?parent ?a) ]
+      ]`;
+            // Query to find all blocks on the page
+            const pageQuery = `[:find ?string ?time
+                         :in $ % ?title
+                         :where 
+                         [?page :node/title ?title]
+                         [?block :block/string ?string]
+                         [?block :create/time ?time]
+                         (ancestor ?block ?page)]`;
+            // Execute query
+            const pageResults = await q(this.graph, pageQuery, [ancestorRule, tagText]);
+            // Process page blocks with sorting
+            let pageMemories = pageResults
+                .sort(([_, aTime], [__, bTime]) => sort_by === 'newest' ? bTime - aTime : aTime - bTime)
+                .map(([content]) => content);
+            // Get tagged blocks from across the graph
+            const tagResults = await this.searchOps.searchForTag(tagText);
+            // Process tagged blocks with sorting
+            let taggedMemories = tagResults.matches
+                .sort((a, b) => {
+                const aTime = a.block_uid ? parseInt(a.block_uid.split('-')[0], 16) : 0;
+                const bTime = b.block_uid ? parseInt(b.block_uid.split('-')[0], 16) : 0;
+                return sort_by === 'newest' ? bTime - aTime : aTime - bTime;
+            })
+                .map(match => match.content);
+            // Resolve any block references in both sets
+            const resolvedPageMemories = await Promise.all(pageMemories.map(async (content) => resolveRefs(this.graph, content)));
+            const resolvedTaggedMemories = await Promise.all(taggedMemories.map(async (content) => resolveRefs(this.graph, content)));
+            // Combine both sets and remove duplicates while preserving order
+            let uniqueMemories = [
+                ...resolvedPageMemories,
+                ...resolvedTaggedMemories
+            ].filter((memory, index, self) => self.indexOf(memory) === index);
+            // Format filter tag with exact Roam tag syntax
+            const filterTagFormatted = filter_tag ?
+                (filter_tag.includes(' ') ? `#[[${filter_tag}]]` : `#${filter_tag}`) : null;
+            // Filter by exact tag match if provided
+            if (filterTagFormatted) {
+                uniqueMemories = uniqueMemories.filter(memory => memory.includes(filterTagFormatted));
+            }
+            // Format memories tag for removal and clean up memories tag
+            const memoriesTagFormatted = tagText.includes(' ') || tagText.includes('/') ? `#[[${tagText}]]` : `#${tagText}`;
+            uniqueMemories = uniqueMemories.map(memory => memory.replace(memoriesTagFormatted, '').trim());
+            // return {
+            //   success: true,
+            //   memories: [
+            //     `memoriesTag = ${memoriesTag}`,
+            //     `filter_tag = ${filter_tag}`,
+            //     `filterTagFormatted = ${filterTagFormatted}`,
+            //     `memoriesTagFormatted = ${memoriesTagFormatted}`,
+            //   ]
+            // }
+            return {
+                success: true,
+                memories: uniqueMemories
+            };
+        }
+        catch (error) {
+            throw new McpError(ErrorCode.InternalError, `Failed to recall memories: ${error.message}`);
+        }
     }
 }

package/build/tools/operations/pages.js

@@ -8,7 +8,7 @@ export class PageOperations {
     constructor(graph) {
         this.graph = graph;
     }
-    async findPagesModifiedToday() {
+    async findPagesModifiedToday(num_pages = 10) {
         // Define ancestor rule for traversing block hierarchy
         const ancestorRule = `[
       [ (ancestor ?b ?a)
@@ -28,7 +28,8 @@ export class PageOperations {
           [?page :node/title ?title]
           (ancestor ?block ?page)
           [?block :edit/time ?time]
-          [(> ?time ?start_of_day)]]`, [startOfDay.getTime(), ancestorRule]);
+          [(> ?time ?start_of_day)]]
+          :limit ${num_pages}`, [startOfDay.getTime(), ancestorRule]);
             if (!results || results.length === 0) {
                 return {
                     success: true,
@@ -87,7 +88,7 @@ export class PageOperations {
                     // Use import_nested_markdown functionality
                     const convertedContent = convertToRoamMarkdown(content);
                     const nodes = parseMarkdown(convertedContent);
-                    const actions = convertToRoamActions(nodes, pageUid, 'last');
+                    const actions = convertToRoamActions(nodes, pageUid, 'first');
                     const result = await batchActions(this.graph, {
                         action: 'batch-actions',
                         actions

package/build/tools/operations/search/handlers.js

@@ -1,4 +1,4 @@
-import { TagSearchHandler, BlockRefSearchHandler, HierarchySearchHandler, TextSearchHandler, DatomicSearchHandler } from '../../../search/index.js';
+import { TagSearchHandler, BlockRefSearchHandler, HierarchySearchHandler, TextSearchHandler, DatomicSearchHandler, StatusSearchHandler } from '../../../search/index.js';
 // Base class for all search handlers
 export class BaseSearchHandler {
     graph;
@@ -54,6 +54,18 @@ export class TextSearchHandlerImpl extends BaseSearchHandler {
         return handler.execute();
     }
 }
+// Status search handler
+export class StatusSearchHandlerImpl extends BaseSearchHandler {
+    params;
+    constructor(graph, params) {
+        super(graph);
+        this.params = params;
+    }
+    async execute() {
+        const handler = new StatusSearchHandler(this.graph, this.params);
+        return handler.execute();
+    }
+}
 // Datomic query handler
 export class DatomicSearchHandlerImpl extends BaseSearchHandler {
     params;

package/build/tools/operations/search/index.js

@@ -1,12 +1,12 @@
-import { TagSearchHandlerImpl, BlockRefSearchHandlerImpl, HierarchySearchHandlerImpl, TextSearchHandlerImpl } from './handlers.js';
+import { TagSearchHandlerImpl, BlockRefSearchHandlerImpl, HierarchySearchHandlerImpl, TextSearchHandlerImpl, StatusSearchHandlerImpl } from './handlers.js';
 export class SearchOperations {
     graph;
     constructor(graph) {
         this.graph = graph;
     }
     async searchByStatus(status, page_title_uid, include, exclude) {
-        const handler = new TagSearchHandlerImpl(this.graph, {
-            primary_tag: `{{[[${status}]]}}`,
+        const handler = new StatusSearchHandlerImpl(this.graph, {
+            status,
             page_title_uid,
         });
         const result = await handler.execute();
@@ -14,7 +14,7 @@ export class SearchOperations {
         let matches = result.matches;
         if (include) {
             const includeTerms = include.split(',').map(term => term.trim());
-            matches = matches.filter(match => {
+            matches = matches.filter((match) => {
                 const matchContent = match.content;
                 const matchTitle = match.page_title;
                 const terms = includeTerms;
@@ -24,7 +24,7 @@ export class SearchOperations {
         }
         if (exclude) {
             const excludeTerms = exclude.split(',').map(term => term.trim());
-            matches = matches.filter(match => {
+            matches = matches.filter((match) => {
                 const matchContent = match.content;
                 const matchTitle = match.page_title;
                 const terms = excludeTerms;

package/build/tools/schemas.js

@@ -34,7 +34,7 @@ export const toolSchemas = {
     },
     roam_create_page: {
         name: 'roam_create_page',
-        description: 'Create a new standalone page in Roam from markdown with given title. Best for hierarchical content, reference materials, markdown tables, and topics that deserve their own namespace. Optional initial content will be properly nested as blocks.',
+        description: 'Create a new standalone page in Roam with optional content using markdown-style formatting. The nesting structure is inferred from markdown indentation (spaces). Best for:\n- Creating foundational concept pages that other pages will link to/from\n- Establishing new topic areas that need their own namespace\n- Setting up reference materials or documentation\n- Making permanent collections of information.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -44,7 +44,7 @@ export const toolSchemas = {
                 },
                 content: {
                     type: 'string',
-                    description: 'Initial content for the page (optional)',
+                    description: 'Initial content for the page (optional). Each line becomes a separate block. Indentation (using spaces or tabs) determines the nesting level of each block.',
                 },
             },
             required: ['title'],
@@ -74,7 +74,7 @@ export const toolSchemas = {
     },
     roam_create_outline: {
         name: 'roam_create_outline',
-        description: 'Create a structured outline with nested structure in Roam from an array of items with explicit levels. Can be added on a specific page or under a specific block. Ideal for saving a conversation with an LLM response, research, or organizing thoughts.',
+        description: 'Add a structured outline to an existing page or block (by title text or uid), with customizable nesting levels. Best for:\n- Adding supplementary structured content to existing pages\n- Creating temporary or working outlines (meeting notes, brainstorms)\n- Organizing thoughts or research under a specific topic\n- Breaking down subtopics or components of a larger concept',
         inputSchema: {
             type: 'object',
             properties: {
@@ -88,7 +88,7 @@ export const toolSchemas = {
                 },
                 outline: {
                     type: 'array',
-                    description: 'Array of outline items with block text and level',
+                    description: 'Array of outline items with block text and explicit nesting level',
                     items: {
                         type: 'object',
                         properties: {
@@ -243,13 +243,19 @@ export const toolSchemas = {
             ]
         }
     },
-    find_pages_modified_today: {
-        name: 'find_pages_modified_today',
-        description: 'Find all pages that have been modified today (since midnight).',
+    roam_find_pages_modified_today: {
+        name: 'roam_find_pages_modified_today',
+        description: 'Find pages that have been modified today (since midnight), with limit.',
         inputSchema: {
             type: 'object',
-            properties: {},
-            required: []
+            properties: {
+                num_pages: {
+                    type: 'integer',
+                    description: 'Number of result pages to retrieve (default: 10)',
+                    default: 10
+                },
+            },
+            required: ['num_pages']
         }
     },
     roam_search_by_text: {
@@ -399,13 +405,13 @@ export const toolSchemas = {
     },
     roam_remember: {
         name: 'roam_remember',
-        description: 'Add a memory or piece of information to remember, stored on the daily page with #[[LLM/Memories]] tag and optional categories. \nNOTE on Roam-flavored markdown: For direct linking: use [[link]] syntax. For aliased linking, use [alias]([[link]]) syntax. Do not concatenate words in links/hashtags - correct: #[[multiple words]] #self-esteem (for typically hyphenated words).',
+        description: 'Add a memory or piece of information to remember, stored on the daily page with MEMORIES_TAG tag and optional categories. \nNOTE on Roam-flavored markdown: For direct linking: use [[link]] syntax. For aliased linking, use [alias]([[link]]) syntax. Do not concatenate words in links/hashtags - correct: #[[multiple words]] #self-esteem (for typically hyphenated words).',
         inputSchema: {
             type: 'object',
             properties: {
                 memory: {
                     type: 'string',
-                    description: 'The memory or information to remember'
+                    description: 'The memory detail or information to remember'
                 },
                 categories: {
                     type: 'array',
@@ -420,16 +426,26 @@ export const toolSchemas = {
     },
     roam_recall: {
         name: 'roam_recall',
-        description: 'Retrieve all stored memories by searching for blocks tagged with MEMORIES_TAG and content from the page with the same name. Returns a combined, deduplicated list of memories.',
+        description: 'Retrieve all stored memories on page titled MEMORIES_TAG, or tagged block content with the same name. Returns a combined, deduplicated list of memories. Optionally filter blcoks with a specified tag and sort by creation date.',
         inputSchema: {
             type: 'object',
-            properties: {},
-            required: []
+            properties: {
+                sort_by: {
+                    type: 'string',
+                    description: 'Sort order for memories based on creation date',
+                    enum: ['newest', 'oldest'],
+                    default: 'newest'
+                },
+                filter_tag: {
+                    type: 'string',
+                    description: 'Include only memories with a specific filter tag. For single word tags use format "tag", for multi-word tags use format "tag word" (without brackets)'
+                }
+            }
         }
     },
     roam_datomic_query: {
         name: 'roam_datomic_query',
-        description: 'Execute a custom Datomic query on the Roam graph beyond the available search tools. This provides direct access to Roam\'s query engine for advanced data retrieval. Note: The Roam graph is case-sensitive.\nA list of some of Roam\'s data model Namespaces and Attributes: ancestor (descendants), attrs (lookup), block (children, heading, open, order, page, parents, props, refs, string, text-align, uid), children (view-type), create (email, time), descendant (ancestors), edit (email, seen-by, time), entity (attrs), log (id), node (title), page (uid, title), refs (text).\nPredicates (clojure.string/includes?, clojure.string/starts-with?, clojure.string/ends-with?, <, >, <=, >=, =, not=, !=).\nAggregates (distinct, count, sum, max, min, avg).\nTips: Use :block/parents for all ancestor levels, :block/children for direct descendants only; combine clojure.string for complex matching, use distinct to deduplicate, leverage Pull patterns for hierarchies, handle case-sensitivity carefully, and chain ancestry rules for multi-level queries.',
+        description: 'Execute a custom Datomic query on the Roam graph beyond the available search tools. This provides direct access to Roam\'s query engine for advanced data retrieval. Note: Roam graph is case-sensitive.\nList of some of Roam\'s data model Namespaces and Attributes: ancestor (descendants), attrs (lookup), block (children, heading, open, order, page, parents, props, refs, string, text-align, uid), children (view-type), create (email, time), descendant (ancestors), edit (email, seen-by, time), entity (attrs), log (id), node (title), page (uid, title), refs (text).\nPredicates (clojure.string/includes?, clojure.string/starts-with?, clojure.string/ends-with?, <, >, <=, >=, =, not=, !=).\nAggregates (distinct, count, sum, max, min, avg, limit).\nTips: Use :block/parents for all ancestor levels, :block/children for direct descendants only; combine clojure.string for complex matching, use distinct to deduplicate, leverage Pull patterns for hierarchies, handle case-sensitivity carefully, and chain ancestry rules for multi-level queries.',
         inputSchema: {
             type: 'object',
             properties: {

package/build/tools/tool-handlers.js

@@ -23,8 +23,8 @@ export class ToolHandlers {
         this.outlineOps = new OutlineOperations(graph);
     }
     // Page Operations
-    async findPagesModifiedToday() {
-        return this.pageOps.findPagesModifiedToday();
+    async findPagesModifiedToday(num_pages = 10) {
+        return this.pageOps.findPagesModifiedToday(num_pages);
     }
     async createPage(title, content) {
         return this.pageOps.createPage(title, content);
@@ -70,8 +70,8 @@ export class ToolHandlers {
     async remember(memory, categories) {
         return this.memoryOps.remember(memory, categories);
     }
-    async recall() {
-        return this.memoryOps.recall();
+    async recall(sort_by = 'newest', filter_tag) {
+        return this.memoryOps.recall(sort_by, filter_tag);
     }
     // Todo Operations
     async addTodos(todos) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roam-research-mcp",
-  "version": "0.23.1",
+  "version": "0.24.2",
   "description": "A Model Context Protocol (MCP) server for Roam Research API integration",
   "private": false,
   "repository": {