roam-research-mcp 0.19.0 → 0.20.0

package/README.md

@@ -28,7 +28,7 @@ npm run build
 
 ## Features
 
-The server provides twelve powerful tools for interacting with Roam Research:
+The server provides fourteen powerful tools for interacting with Roam Research:
 
 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
@@ -42,6 +42,8 @@ The server provides twelve powerful tools for interacting with Roam Research:
 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
+13. `roam_search_for_tag`: Search for blocks containing specific tags with optional filtering by nearby tags
+14. `roam_remember`: Store and categorize memories or information with automatic tagging
 
 ## Setup
 
@@ -60,28 +62,14 @@ The server provides twelve powerful tools for interacting with Roam Research:
    ```
    ROAM_API_TOKEN=your-api-token
    ROAM_GRAPH_NAME=your-graph-name
+   MEMORIES_TAG='#[[LLM/Memories]]'
+   PROFILE_PAGE='LLM/Profile' (not yet implemented)
    ```
 
    Option 2: Using MCP settings (Alternative method)
    Add the configuration to your MCP settings file:
 
    - For Cline (`~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`):
-
-   ```json
-   {
-     "mcpServers": {
-       "roam-research": {
-         "command": "node",
-         "args": ["/path/to/roam-research/build/index.js"],
-         "env": {
-           "ROAM_API_TOKEN": "your-api-token",
-           "ROAM_GRAPH_NAME": "your-graph-name"
-         }
-       }
-     }
-   }
-   ```
-
    - For Claude desktop app (`~/Library/Application Support/Claude/claude_desktop_config.json`):
 
    ```json
@@ -92,7 +80,9 @@ The server provides twelve powerful tools for interacting with Roam Research:
          "args": ["/path/to/roam-research/build/index.js"],
          "env": {
            "ROAM_API_TOKEN": "your-api-token",
-           "ROAM_GRAPH_NAME": "your-graph-name"
+           "ROAM_GRAPH_NAME": "your-graph-name",
+           "MEMORIES_TAG": "#[[LLM/Memories]]",
+           "PROFILE_PAGE": "LLM/Profile"
          }
        }
      }
@@ -421,6 +411,86 @@ Returns:
 }
 ```
 
+### Search For Tags
+
+Search for blocks containing specific tags with optional filtering by nearby tags:
+
+```typescript
+use_mcp_tool roam-research roam_search_for_tag {
+  "primary_tag": "Project/Tasks",
+  "page_title_uid": "optional-page-title-or-uid",
+  "near_tag": "optional-secondary-tag",
+  "case_sensitive": true
+}
+```
+
+Features:
+
+- Search for blocks containing specific tags
+- Optional filtering by presence of another tag
+- Page-scoped or graph-wide search
+- Case-sensitive or case-insensitive search
+- Returns block content with page context
+- Efficient tag matching using Datalog queries
+
+Parameters:
+
+- `primary_tag`: The main tag to search for (required)
+- `page_title_uid`: Title or UID of the page to search in (optional)
+- `near_tag`: Another tag to filter results by (optional)
+- `case_sensitive`: Whether to perform case-sensitive search (optional, default: true to match Roam's native behavior)
+
+Returns:
+
+```json
+{
+  "success": true,
+  "matches": [
+    {
+      "block_uid": "matching-block-uid",
+      "content": "Block content containing #[[primary_tag]]",
+      "page_title": "Page containing block"
+    }
+  ],
+  "message": "Found N block(s) referencing \"primary_tag\""
+}
+```
+
+### Remember Information
+
+Store memories or important information with automatic tagging and categorization:
+
+```typescript
+use_mcp_tool roam-research roam_remember {
+  "memory": "Important information to remember",
+  "categories": ["Work", "Project/Alpha"]
+}
+```
+
+Features:
+
+- Store information with #[[LLM/Memories]] tag
+- Add optional category tags for organization
+- Automatically adds to today's daily page
+- Supports multiple categories per memory
+- Easy retrieval using roam_search_for_tag
+- Maintains chronological order of memories
+
+Parameters:
+
+- `memory`: The information to remember (required)
+- `categories`: Optional array of categories to tag the memory with
+
+Returns:
+
+```json
+{
+  "success": true,
+  "block_uid": "created-block-uid",
+  "content": "Memory content with tags"
+}
+```
+
 ### Search By Date
 
 Search for blocks and pages based on creation or modification dates:

package/build/server/roam-server.js

@@ -22,6 +22,7 @@ export class RoamServer {
         }, {
             capabilities: {
                 tools: {
+                    roam_remember: {},
                     roam_add_todo: {},
                     roam_fetch_page_by_title: {},
                     roam_create_page: {},
@@ -57,6 +58,13 @@ export class RoamServer {
         this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
             try {
                 switch (request.params.name) {
+                    case 'roam_remember': {
+                        const { memory, categories } = request.params.arguments;
+                        const result = await this.toolHandlers.remember(memory, categories);
+                        return {
+                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                        };
+                    }
                     case 'roam_fetch_page_by_title': {
                         const { title } = request.params.arguments;
                         const content = await this.toolHandlers.fetchPageByTitle(title);

package/build/tools/schemas.js

@@ -74,7 +74,7 @@ export const toolSchemas = {
     },
     roam_create_outline: {
         name: 'roam_create_output_with_nested_structure',
-        description: 'Create a structured outline or output 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.',
+        description: 'Create a structured outline or output 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.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -146,7 +146,7 @@ export const toolSchemas = {
     },
     roam_search_for_tag: {
         name: 'roam_search_for_tag',
-        description: 'Search for blocks containing a specific tag and optionally filter by blocks that also contain another tag nearby.',
+        description: 'Search for blocks containing a specific tag and optionally filter by blocks that also contain another tag nearby. Example: Use this to search for memories that are tagged with the MEMORIES_TAG.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -414,5 +414,26 @@ export const toolSchemas = {
             },
             required: ['start_date', 'type', 'scope']
         }
+    },
+    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. Use roam_search_for_tag with "LLM/Memories" to find stored memories.\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'
+                },
+                categories: {
+                    type: 'array',
+                    items: {
+                        type: 'string'
+                    },
+                    description: 'Optional categories to tag the memory with (will be converted to Roam tags)'
+                }
+            },
+            required: ['memory']
+        }
     }
 };

package/build/tools/tool-handlers.js

@@ -1096,6 +1096,58 @@ export class ToolHandlers {
             message: `Found ${sortedMatches.length} matches for the given date range and criteria`
         };
     }
+    async remember(memory, categories) {
+        // Get today's date
+        const today = new Date();
+        const dateStr = formatRoamDate(today);
+        // Try to find today's page
+        const findQuery = `[:find ?uid :in $ ?title :where [?e :node/title ?title] [?e :block/uid ?uid]]`;
+        const findResults = await q(this.graph, findQuery, [dateStr]);
+        let pageUid;
+        if (findResults && findResults.length > 0) {
+            pageUid = findResults[0][0];
+        }
+        else {
+            // Create today's page if it doesn't exist
+            const success = await createPage(this.graph, {
+                action: 'create-page',
+                page: { title: dateStr }
+            });
+            if (!success) {
+                throw new McpError(ErrorCode.InternalError, 'Failed to create today\'s page');
+            }
+            // Get the new page's UID
+            const results = await q(this.graph, findQuery, [dateStr]);
+            if (!results || results.length === 0) {
+                throw new McpError(ErrorCode.InternalError, 'Could not find created today\'s page');
+            }
+            pageUid = results[0][0];
+        }
+        // Get memories tag from environment
+        const memoriesTag = process.env.MEMORIES_TAG;
+        if (!memoriesTag) {
+            throw new McpError(ErrorCode.InternalError, 'MEMORIES_TAG environment variable not set');
+        }
+        // Format categories as Roam tags if provided
+        const categoryTags = categories?.map(cat => {
+            // Handle multi-word categories
+            return cat.includes(' ') ? `#[[${cat}]]` : `#${cat}`;
+        }).join(' ') || '';
+        // Create block with memory, memories tag, and optional categories
+        const blockContent = `${memoriesTag} ${memory} ${categoryTags}`.trim();
+        const success = await createBlock(this.graph, {
+            action: 'create-block',
+            location: {
+                "parent-uid": pageUid,
+                "order": "last"
+            },
+            block: { string: blockContent }
+        });
+        if (!success) {
+            throw new McpError(ErrorCode.InternalError, 'Failed to create memory block');
+        }
+        return { success: true };
+    }
     async addTodos(todos) {
         if (!Array.isArray(todos) || todos.length === 0) {
             throw new McpError(ErrorCode.InvalidRequest, 'todos must be a non-empty array');

package/package.json

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