roam-research-mcp 2.4.3 → 2.13.0

package/build/cli/commands/refs.js

@@ -91,6 +91,8 @@ Examples:
 
   # Block references
   roam refs "((abc123def))"               # Blocks embedding this block
+
+JSON output fields: uid, content, page
 `)
         .action(async (identifier, options) => {
         try {

package/build/cli/commands/save.js

@@ -27,6 +27,55 @@ function flattenNodes(nodes, baseLevel = 1) {
     }
     return result;
 }
+/**
+ * Infer hierarchy from heading levels when all blocks are at the same level.
+ * This handles prose-style markdown where headings (# ## ###) define structure
+ * without explicit indentation.
+ *
+ * Example: "# Title\n## Chapter\nContent" becomes:
+ *   - Title (level 1, H1)
+ *     - Chapter (level 2, H2)
+ *       - Content (level 3)
+ */
+function adjustLevelsForHeadingHierarchy(blocks) {
+    if (blocks.length === 0)
+        return blocks;
+    // Only apply heading-based adjustment when:
+    // 1. All blocks are at the same level (no indentation-based hierarchy)
+    // 2. There are headings present
+    const allSameLevel = blocks.every(b => b.level === blocks[0].level);
+    const hasHeadings = blocks.some(b => b.heading);
+    if (!allSameLevel || !hasHeadings) {
+        // Indentation-based hierarchy exists, preserve it
+        return blocks;
+    }
+    const result = [];
+    // Track heading stack: each entry is { headingLevel: 1|2|3, adjustedLevel: number }
+    const headingStack = [];
+    for (const block of blocks) {
+        if (block.heading) {
+            // Pop headings of same or lower priority (higher h-number)
+            while (headingStack.length > 0 &&
+                headingStack[headingStack.length - 1].headingLevel >= block.heading) {
+                headingStack.pop();
+            }
+            // New heading level is one deeper than parent heading (or 1 if no parent)
+            const adjustedLevel = headingStack.length > 0
+                ? headingStack[headingStack.length - 1].adjustedLevel + 1
+                : 1;
+            headingStack.push({ headingLevel: block.heading, adjustedLevel });
+            result.push({ ...block, level: adjustedLevel });
+        }
+        else {
+            // Content: nest under current heading context
+            const adjustedLevel = headingStack.length > 0
+                ? headingStack[headingStack.length - 1].adjustedLevel + 1
+                : 1;
+            result.push({ ...block, level: adjustedLevel });
+        }
+    }
+    return result;
+}
 /**
  * Check if a string looks like a Roam block UID (9 alphanumeric chars with _ or -)
  */
@@ -56,6 +105,8 @@ async function findOrCreatePage(graph, title) {
         action: 'create-page',
         page: { title }
     });
+    // Small delay for new page to be fully available as parent in Roam
+    await new Promise(resolve => setTimeout(resolve, 400));
     const results = await q(graph, findQuery, [title]);
     if (!results || results.length === 0) {
         throw new Error(`Could not find created page: ${title}`);
@@ -137,6 +188,7 @@ export function createSaveCommand() {
         .option('-c, --categories <tags>', 'Comma-separated tags appended to first block')
         .option('-t, --todo [text]', 'Add TODO item(s) to daily page. Accepts inline text or stdin')
         .option('--json', 'Force JSON array format: [{text, level, heading?}, ...]')
+        .option('--flatten', 'Disable heading hierarchy inference (all blocks at root level)')
         .option('-g, --graph <name>', 'Target graph key (multi-graph mode)')
         .option('--write-key <key>', 'Write confirmation key (non-default graphs)')
         .option('--debug', 'Show debug information')
@@ -258,7 +310,9 @@ JSON format (--json):
             else if (isFile || content.includes('\n')) {
                 // Multi-line content: parse as markdown
                 const nodes = parseMarkdown(content);
-                contentBlocks = flattenNodes(nodes);
+                const flattened = flattenNodes(nodes);
+                // Apply heading hierarchy unless --flatten is specified
+                contentBlocks = options.flatten ? flattened : adjustLevelsForHeadingHierarchy(flattened);
             }
             else {
                 // Single line text: detect heading syntax and strip hashes
@@ -298,6 +352,7 @@ JSON format (--json):
                 printDebug('Input', input || 'stdin');
                 printDebug('Is file', isFile);
                 printDebug('Is JSON', isJson);
+                printDebug('Flatten mode', options.flatten || false);
                 printDebug('Graph', options.graph || 'default');
                 printDebug('Content blocks', contentBlocks.length);
                 printDebug('Parent UID', parentUid || 'none');

package/build/cli/commands/search.js

@@ -42,12 +42,17 @@ export function createSearchCommand() {
         .option('--inputs <json>', 'JSON array of inputs for Datalog query')
         .option('--regex <pattern>', 'Client-side regex filter on Datalog results')
         .option('--regex-flags <flags>', 'Regex flags (e.g., "i" for case-insensitive)')
+        .option('--namespace <prefix>', 'Search for pages by namespace prefix (e.g., "Convention" finds "Convention/*")')
         .addHelpText('after', `
 Examples:
   # Text search
   roam search "meeting notes"               # Find blocks containing text
   roam search api integration               # Multiple terms (AND logic)
 
+  # Namespace search (find pages by title prefix)
+  roam search --namespace Convention        # Find all Convention/* pages
+  roam search --namespace "Convention/"     # Same (trailing slash optional)
+
   # Stdin search
   echo "urgent project" | roam search       # Pipe terms
   roam get today | roam search TODO         # Search within output
@@ -58,6 +63,15 @@ Examples:
 
   # Datalog queries (advanced)
   roam search -q '[:find ?uid ?s :where [?b :block/uid ?uid] [?b :block/string ?s]]' --regex "meeting"
+
+  # Chaining with jq
+  roam search TODO --json | jq '.[].block_uid'
+
+Output format:
+  Markdown: Flat results with UIDs and content (no hierarchy).
+  JSON:     [{ block_uid, content, page_title }] or [{ page_uid, page_title }] for namespace
+
+Note: For hierarchical output with children, use 'roam get --tag/--text' instead.
 `)
         .action(async (terms, options) => {
         try {
@@ -81,6 +95,37 @@ Examples:
                 printDebug('Options', options);
             }
             const searchOps = new SearchOperations(graph);
+            // Namespace search mode (search page titles by prefix)
+            if (options.namespace) {
+                const result = await searchOps.searchByText({
+                    text: options.namespace,
+                    scope: 'page_titles'
+                });
+                if (!result.success) {
+                    exitWithError(result.message || 'Namespace search failed');
+                }
+                let matches = result.matches.slice(0, limit);
+                if (options.json) {
+                    // For JSON output, return page_uid and page_title
+                    const jsonMatches = matches.map(m => ({
+                        page_uid: m.block_uid,
+                        page_title: m.page_title
+                    }));
+                    console.log(JSON.stringify(jsonMatches, null, 2));
+                }
+                else {
+                    if (matches.length === 0) {
+                        console.log('No pages found.');
+                    }
+                    else {
+                        console.log(`Found ${result.matches.length} page(s)${result.matches.length > limit ? ` (showing first ${limit})` : ''}:\n`);
+                        for (const match of matches) {
+                            console.log(`- ${match.page_title} (${match.block_uid})`);
+                        }
+                    }
+                }
+                return;
+            }
             // Datalog query mode (bypasses other search options)
             if (options.query) {
                 // Parse inputs if provided

package/build/cli/commands/status.js

@@ -25,6 +25,8 @@ Examples:
 
   # JSON output for scripting
   roam status --json
+
+JSON output fields: { version, graphs: [{ name, default, protected, connected?, error? }] }
 `)
         .action(async (options) => {
         try {
@@ -34,15 +36,12 @@ Examples:
             for (const key of graphKeys) {
                 const config = registry.getConfig(key);
                 const isDefault = key === registry.defaultKey;
-                const isProtected = !!config.write_key;
+                const isProtected = !!config.protected;
                 const status = {
                     name: key,
                     default: isDefault,
                     protected: isProtected,
                 };
-                if (isProtected) {
-                    status.writeKey = config.write_key;
-                }
                 if (options.ping) {
                     try {
                         const graph = registry.getGraph(key);

package/build/cli/utils/graph.js

@@ -28,9 +28,13 @@ export function resolveGraph(options, isWriteOp = false) {
         const graphKey = options.graph ?? reg.defaultKey;
         if (!reg.isWriteAllowed(graphKey, options.writeKey)) {
             const config = reg.getConfig(graphKey);
-            if (config?.write_key) {
+            if (config?.protected) {
+                const systemWriteKey = process.env.ROAM_SYSTEM_WRITE_KEY;
+                if (!systemWriteKey) {
+                    throw new Error(`Write to protected graph "${graphKey}" failed: ROAM_SYSTEM_WRITE_KEY not configured.`);
+                }
                 throw new Error(`Write to "${graphKey}" graph requires --write-key confirmation.\n` +
-                    `Use: --write-key "${config.write_key}"`);
+                    `Use: --write-key "${systemWriteKey}"`);
             }
         }
     }

package/build/cli/utils/output.js

@@ -66,10 +66,9 @@ export function formatSearchResults(results, options) {
         return 'No results found.';
     }
     let output = `Found ${results.length} result(s):\n\n`;
-    results.forEach((result, index) => {
-        const pageInfo = result.page_title ? ` (${result.page_title})` : '';
-        output += `[${index + 1}] ${result.block_uid}${pageInfo}\n`;
-        output += `    ${result.content}\n\n`;
+    results.forEach((result) => {
+        const pageInfo = result.page_title ? ` — [[${result.page_title}]]` : '';
+        output += `[${result.block_uid}] ${result.content}${pageInfo}\n`;
     });
     return output.trim();
 }
@@ -102,7 +101,31 @@ export function formatTodoOutput(results, status, options) {
                 .replace(/\{\{TODO\}\}\s*/g, '')
                 .replace(/\{\{\[\[DONE\]\]\}\}\s*/g, '')
                 .replace(/\{\{DONE\}\}\s*/g, '');
-            output += `- [${status === 'DONE' ? 'x' : ' '}] ${cleanContent} (${item.block_uid})\n`;
+            output += `[${item.block_uid}] [${status === 'DONE' ? 'x' : ' '}] ${cleanContent}\n`;
+        }
+    }
+    return output.trim();
+}
+/**
+ * Format grouped search results for output
+ */
+export function formatGroupedOutput(grouped, options) {
+    if (options.json) {
+        return JSON.stringify(grouped, null, 2);
+    }
+    const { groups, meta } = grouped;
+    const groupKeys = Object.keys(groups);
+    if (groupKeys.length === 0) {
+        return 'No results found.';
+    }
+    let output = `Found ${meta.total} item(s) in ${meta.groups_count} group(s):\n`;
+    for (const groupName of groupKeys) {
+        const items = groups[groupName];
+        output += `\n## ${groupName}\n`;
+        for (const item of items) {
+            // Format: [uid] content with optional page reference
+            const pageRef = item.page_title ? ` — [[${item.page_title}]]` : '';
+            output += `[${item.block_uid}] ${item.content}${pageRef}\n`;
         }
     }
     return output.trim();

package/build/cli/utils/sort-group.js

@@ -0,0 +1,110 @@
+/**
+ * Sort search results by a specified field and direction
+ */
+export function sortResults(matches, options) {
+    const { field, direction } = options;
+    const multiplier = direction === 'asc' ? 1 : -1;
+    return [...matches].sort((a, b) => {
+        let comparison = 0;
+        switch (field) {
+            case 'created':
+                comparison = (a.created || 0) - (b.created || 0);
+                break;
+            case 'modified':
+                comparison = (a.modified || 0) - (b.modified || 0);
+                break;
+            case 'page':
+                comparison = (a.page_title || '').localeCompare(b.page_title || '');
+                break;
+        }
+        return comparison * multiplier;
+    });
+}
+/**
+ * Group search results by page title
+ */
+export function groupByPage(matches) {
+    const groups = {};
+    for (const match of matches) {
+        const key = match.page_title || '(No Page)';
+        if (!groups[key]) {
+            groups[key] = [];
+        }
+        groups[key].push(match);
+    }
+    return {
+        groups,
+        meta: {
+            total: matches.length,
+            groups_count: Object.keys(groups).length
+        }
+    };
+}
+/**
+ * Group search results by tag
+ * Matches are grouped by the most specific matching subtag of the search tag
+ * Each match appears only once, under its most specific matching tag
+ */
+export function groupByTag(matches, searchTag) {
+    const groups = {};
+    const normalizedSearchTag = normalizeTagName(searchTag);
+    for (const match of matches) {
+        const tags = match.tags || [];
+        // Find the most specific matching tag (longest path that starts with searchTag)
+        let bestTag = searchTag; // Default to the search tag itself
+        let bestLength = 0;
+        for (const tag of tags) {
+            const normalizedTag = normalizeTagName(tag);
+            // Check if this tag matches or is a subtag of the search tag
+            if (normalizedTag === normalizedSearchTag ||
+                normalizedTag.startsWith(normalizedSearchTag + '/')) {
+                if (normalizedTag.length > bestLength) {
+                    bestTag = tag;
+                    bestLength = normalizedTag.length;
+                }
+            }
+        }
+        // Group under the best matching tag
+        if (!groups[bestTag]) {
+            groups[bestTag] = [];
+        }
+        groups[bestTag].push(match);
+    }
+    // Sort groups by tag name for consistent output
+    const sortedGroups = {};
+    const sortedKeys = Object.keys(groups).sort();
+    for (const key of sortedKeys) {
+        sortedGroups[key] = groups[key];
+    }
+    return {
+        groups: sortedGroups,
+        meta: {
+            total: matches.length,
+            groups_count: Object.keys(sortedGroups).length
+        }
+    };
+}
+/**
+ * Group results by specified field
+ */
+export function groupResults(matches, options) {
+    switch (options.by) {
+        case 'page':
+            return groupByPage(matches);
+        case 'tag':
+            return groupByTag(matches, options.searchTag || '');
+    }
+}
+/**
+ * Normalize tag name for comparison (lowercase, trim whitespace)
+ */
+function normalizeTagName(tag) {
+    return tag.toLowerCase().trim();
+}
+/**
+ * Get default sort direction for a field
+ */
+export function getDefaultDirection(field) {
+    // Dates default to descending (newest first), alphabetical to ascending
+    return field === 'page' ? 'asc' : 'desc';
+}

package/build/config/graph-registry.js

@@ -4,7 +4,7 @@
  * Supports:
  * - Multiple graph configurations via ROAM_GRAPHS env var
  * - Backwards compatibility with single graph via ROAM_API_TOKEN/ROAM_GRAPH_NAME
- * - Write protection for non-default graphs via write_key confirmation
+ * - Write protection via protected: true flag + ROAM_SYSTEM_WRITE_KEY env var
  * - Lazy graph initialization (connects only when first accessed)
  */
 import { initializeGraph } from '@roam-research/roam-api-sdk';
@@ -54,6 +54,21 @@ export class GraphRegistry {
     getAvailableGraphs() {
         return Array.from(this.configs.keys());
     }
+    /**
+     * Get the memories tag for a graph
+     * Priority: graph config > ROAM_MEMORIES_TAG env var > "Memories"
+     * Returns null if explicitly disabled (memoriesTag: false)
+     */
+    getMemoriesTag(key) {
+        const resolvedKey = key ?? this.defaultKey;
+        const config = this.configs.get(resolvedKey);
+        // If explicitly disabled, return null
+        if (config?.memoriesTag === false) {
+            return null;
+        }
+        // Priority: per-graph config > env var > default
+        return config?.memoriesTag ?? process.env.ROAM_MEMORIES_TAG ?? 'Memories';
+    }
     /**
      * Get an initialized Graph instance, creating it lazily if needed
      * @param key - Graph key from config. Defaults to defaultKey if not specified.
@@ -84,8 +99,8 @@ export class GraphRegistry {
      * Rules:
      * - Writes to default graph are always allowed
      * - Writes to non-default graphs require:
-     *   - If write_key is configured: must provide matching write_key
-     *   - If no write_key configured: writes are allowed
+     *   - If protected: true, must provide matching ROAM_SYSTEM_WRITE_KEY
+     *   - If not protected: writes are allowed
      */
     isWriteAllowed(graphKey, providedWriteKey) {
         const resolvedKey = graphKey ?? this.defaultKey;
@@ -97,12 +112,13 @@ export class GraphRegistry {
         if (!config) {
             return false; // Unknown graph
         }
-        // If no write_key is configured, allow writes
-        if (!config.write_key) {
+        // If graph is not protected, allow writes
+        if (!config.protected) {
             return true;
         }
-        // Check if provided key matches
-        return providedWriteKey === config.write_key;
+        // Check if provided key matches ROAM_SYSTEM_WRITE_KEY
+        const systemWriteKey = process.env.ROAM_SYSTEM_WRITE_KEY;
+        return !!systemWriteKey && providedWriteKey === systemWriteKey;
     }
     /**
      * Validate write access and return an informative error if denied
@@ -117,9 +133,13 @@ export class GraphRegistry {
             if (!config) {
                 throw new McpError(ErrorCode.InvalidParams, `Unknown graph: "${resolvedKey}". Available graphs: ${this.getAvailableGraphs().join(', ')}`);
             }
+            const systemWriteKey = process.env.ROAM_SYSTEM_WRITE_KEY;
+            if (!systemWriteKey) {
+                throw new McpError(ErrorCode.InvalidParams, `Write to protected graph "${resolvedKey}" failed: ROAM_SYSTEM_WRITE_KEY not configured.`);
+            }
             // Provide informative error with the required key
             throw new McpError(ErrorCode.InvalidParams, `Write to "${resolvedKey}" graph requires write_key confirmation.\n` +
-                `Provide write_key: "${config.write_key}" to proceed.`);
+                `Provide write_key: "${systemWriteKey}" to proceed.`);
         }
     }
     /**
@@ -151,15 +171,13 @@ export class GraphRegistry {
         for (const key of graphKeys) {
             const config = this.configs.get(key);
             const isDefault = key === this.defaultKey;
-            const isProtected = !!config.write_key;
+            const isProtected = !!config.protected;
             const defaultCol = isDefault ? '✓' : '';
-            const protectedCol = isProtected
-                ? `Yes (requires \`write_key: "${config.write_key}"\`)`
-                : 'No';
+            const protectedCol = isProtected ? 'Yes' : 'No';
             lines.push(`| ${key} | ${defaultCol} | ${protectedCol} |`);
         }
         lines.push('');
-        lines.push('> **Note:** Write operations to protected graphs require the `write_key` parameter.');
+        lines.push('> **Note:** Write operations to protected graphs require the `write_key` parameter. The key will be shown in the error message if omitted.');
         lines.push('');
         lines.push('---');
         lines.push('');

package/build/config/graph-registry.test.js

@@ -1,6 +1,43 @@
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, afterEach } from 'vitest';
 import { GraphRegistry } from './graph-registry.js';
 describe('GraphRegistry', () => {
+    describe('getMemoriesTag', () => {
+        const originalEnv = process.env.ROAM_MEMORIES_TAG;
+        afterEach(() => {
+            // Restore original env
+            if (originalEnv !== undefined) {
+                process.env.ROAM_MEMORIES_TAG = originalEnv;
+            }
+            else {
+                delete process.env.ROAM_MEMORIES_TAG;
+            }
+        });
+        it('returns per-graph memoriesTag when configured', () => {
+            const registry = new GraphRegistry({
+                personal: { token: 't1', graph: 'g1', memoriesTag: '#PersonalMemories' },
+                system: { token: 't2', graph: 'g2', memoriesTag: '#[[PAI/Memories]]' },
+            }, 'personal');
+            expect(registry.getMemoriesTag('personal')).toBe('#PersonalMemories');
+            expect(registry.getMemoriesTag('system')).toBe('#[[PAI/Memories]]');
+        });
+        it('falls back to ROAM_MEMORIES_TAG env var when not configured per-graph', () => {
+            process.env.ROAM_MEMORIES_TAG = '#EnvMemories';
+            const registry = new GraphRegistry({ default: { token: 't', graph: 'g' } }, 'default');
+            expect(registry.getMemoriesTag()).toBe('#EnvMemories');
+        });
+        it('falls back to "Memories" when neither per-graph nor env configured', () => {
+            delete process.env.ROAM_MEMORIES_TAG;
+            const registry = new GraphRegistry({ default: { token: 't', graph: 'g' } }, 'default');
+            expect(registry.getMemoriesTag()).toBe('Memories');
+        });
+        it('uses default graph when key not specified', () => {
+            const registry = new GraphRegistry({
+                personal: { token: 't1', graph: 'g1', memoriesTag: '#Personal' },
+                work: { token: 't2', graph: 'g2', memoriesTag: '#Work' },
+            }, 'personal');
+            expect(registry.getMemoriesTag()).toBe('#Personal');
+        });
+    });
     describe('getGraphInfoMarkdown', () => {
         it('returns empty string for single-graph mode with default key', () => {
             const registry = new GraphRegistry({ default: { token: 'token', graph: 'graph' } }, 'default');
@@ -9,21 +46,21 @@ describe('GraphRegistry', () => {
         it('returns markdown table for multi-graph mode', () => {
             const registry = new GraphRegistry({
                 personal: { token: 'token1', graph: 'personal-graph' },
-                work: { token: 'token2', graph: 'work-graph', write_key: 'confirm' },
+                work: { token: 'token2', graph: 'work-graph', protected: true },
             }, 'personal');
             const markdown = registry.getGraphInfoMarkdown();
             expect(markdown).toContain('## Available Graphs');
             expect(markdown).toContain('| personal | ✓ | No |');
-            expect(markdown).toContain('| work |  | Yes (requires `write_key: "confirm"`) |');
+            expect(markdown).toContain('| work |  | Yes |');
             expect(markdown).toContain('> **Note:** Write operations to protected graphs');
         });
         it('shows write protection for default graph if configured', () => {
             const registry = new GraphRegistry({
-                main: { token: 'token1', graph: 'main-graph', write_key: 'secret' },
+                main: { token: 'token1', graph: 'main-graph', protected: true },
                 backup: { token: 'token2', graph: 'backup-graph' },
             }, 'main');
             const markdown = registry.getGraphInfoMarkdown();
-            expect(markdown).toContain('| main | ✓ | Yes (requires `write_key: "secret"`) |');
+            expect(markdown).toContain('| main | ✓ | Yes |');
             expect(markdown).toContain('| backup |  | No |');
         });
     });