roam-research-mcp 2.23.0 → 2.25.0

package/README.md

@@ -18,6 +18,34 @@ What started as an backend for AI agents evolved into a full-featured **Standalo
 
 Whether you want to give Claude superpowers over your knowledge base or just want a robust CLI for your own scripts, this project has you covered.
 
+![Before and after: copy-pasting notes into Roam by hand, versus Claude and your terminal reading and writing the graph directly — install with npm i -g roam-research-mcp, then `roam save "idea"` or pipe with `echo "Buy milk" | roam save --todo`](./roam-research-mcp-sketchnote.png)
+
+## How this differs from Roam's official MCP server
+
+Roam Research ships its own MCP server and CLI ([`@roam-research/roam-mcp`](https://github.com/Roam-Research/roam-tools)). It is a good tool, and this project is not trying to replace it. **They talk to two different Roam APIs, which is the difference everything else follows from.**
+
+|                    | **This project**                                                       | **Official `@roam-research/roam-mcp`**                          |
+| ------------------ | ---------------------------------------------------------------------- | --------------------------------------------------------------- |
+| Talks to           | Roam's **backend REST API** (graph token + graph name)                 | Roam **Desktop's local HTTP API**                                |
+| Needs Roam running | No — works headless                                                    | Yes, the desktop app must be open (it deep-links to launch it)   |
+| Where it can run   | Anywhere: laptop, server, container, CI                                | The machine running Roam Desktop                                 |
+| Shared daemon      | Yes — `roam server` runs one HTTP daemon for every client              | Per-client stdio                                                 |
+| Multi-graph        | `ROAM_GRAPHS` env var, with `write_key` protection for chosen graphs   | `~/.roam-tools.json`, one token per graph                        |
+| Web-only graphs    | Works                                                                  | Desktop only                                                     |
+
+**Reach for the official server when** you want Roam's own supported path, or you need things only the running app can do: controlling the Desktop UI (open a page, read the current selection, drive the sidebar), semantic/embeddings search, link suggestions, file upload, comments, or invoking tools that Roam extensions register.
+
+**Reach for this one when** Roam isn't running or isn't installed — a server, a container, a cron job, a CI step. Or when you want the extras this project has grown: a full standalone CLI with stdin piping, a shared HTTP daemon with optional bearer auth, smart page diffing that preserves block UIDs (and therefore your block references), batch operations with UID placeholders for building nested structures in one call, and agent memory tools.
+
+One deliberate omission: **there is no page-delete tool here.** Roam has no undo that can reverse a bulk API deletion. The official server does offer `delete_page`; this project takes the more conservative line.
+
+### They interoperate
+
+The two servers share conventions on purpose, so running both costs you nothing:
+
+- **`[[roam/agent guidelines]]`** — both read the same page for your conventions. Write them once; both honour them. See [Agent guidelines](#agent-guidelines-per-graph).
+- **`#.rm-hide` / `#.rm-private`** — both withhold tagged blocks from AI-facing content. Tag once, hidden from both. See [Hiding content from the AI](#hiding-content-from-the-ai).
+
 ## Standalone CLI: `roam`
 
 The `roam` CLI lets you interact with your graph directly from the terminal. It supports **standard input (stdin) piping** for all content creation and retrieval commands, making it perfect for automation workflows.
@@ -133,14 +161,24 @@ This is distinct from `CUSTOM_INSTRUCTIONS_PATH`, and the two compose:
 | To change it | edit the file, restart the server | edit the page |
 | Answers | how to write Roam markdown | how *this user* wants *this graph* handled |
 
-Configure per graph, or disable with `false`:
+**Just create the page.** With no configuration at all, `roam_get_guidelines` reads `[[roam/agent guidelines]]` — the same title Roam's own server reads, so writing it once makes both honour it. Creating a page with that exact namespaced title is the opt-in; nothing is read from the graph unless an agent explicitly calls the tool.
+
+If the page doesn't exist, the tool returns `exists: false` rather than failing, so it is always safe to call.
+
+Each graph can point at a different page, or turn it off:
 
 ```bash
-ROAM_GRAPHS='{"personal": {"token": "...", "graph": "...", "guidelinesPage": "roam/agent guidelines"}, "work": {"token": "...", "graph": "...", "guidelinesPage": false}}'
-ROAM_GUIDELINES_PAGE='roam/agent guidelines'   # fallback when a graph sets none
+ROAM_GRAPHS='{
+  "personal": {"token": "...", "graph": "..."},
+  "work":     {"token": "...", "graph": "...", "guidelinesPage": "work/agent rules"},
+  "private":  {"token": "...", "graph": "...", "guidelinesPage": false}
+}'
+ROAM_GUIDELINES_PAGE='team/agent guidelines'   # change the default for every graph
 ```
 
-If no such page exists the tool returns `exists: false` rather than failing, so it is safe to call unconditionally. Results are cached for 30 seconds — an edit to the page takes effect without a restart. A starter template lives at [`.roam/agent-guidelines.template.md`](.roam/agent-guidelines.template.md).
+Resolution order is **per-graph `guidelinesPage` → `ROAM_GUIDELINES_PAGE` → `roam/agent guidelines`**. Above: `personal` uses the env override, `work` uses its own page, and `private` has guidelines off entirely. **Only an explicit `false` disables it** — an unset value never does.
+
+Results are cached for 30 seconds — an edit to the page takes effect without a restart. A starter template lives at [`.roam/agent-guidelines.template.md`](.roam/agent-guidelines.template.md).
 
 Note that guidelines are read through the normal page path, so blocks tagged `#.rm-hide` / `#.rm-private` are withheld from them too — see below.
 

package/build/config/graph-registry.js

@@ -9,6 +9,7 @@
  */
 import { initializeGraph } from '@roam-research/roam-api-sdk';
 import { RoamError } from '../shared/errors.js';
+import { DEFAULT_GUIDELINES_PAGE } from '../tools/operations/guidelines.js';
 /** List of tool names that perform write operations */
 export const WRITE_OPERATIONS = [
     'roam_create_page',
@@ -70,8 +71,21 @@ export class GraphRegistry {
         return config?.memoriesTag ?? process.env.ROAM_MEMORIES_TAG ?? 'Memories';
     }
     /**
-     * Page holding a graph's agent conventions, or null when disabled.
-     * Same precedence as memoriesTag: per-graph config > env var > default.
+     * Page holding a graph's agent conventions, or null when explicitly disabled.
+     *
+     * Precedence: per-graph config > ROAM_GUIDELINES_PAGE env var >
+     * "roam/agent guidelines" (the shared convention).
+     *
+     * Reading the conventional title by default is deliberate. It is the same
+     * page Roam's own MCP server reads unconditionally, so writing it once makes
+     * both servers honour it — which is the entire point of a convention, and it
+     * stops working the moment it needs private configuration. Creating a page
+     * with that exact namespaced title IS the opt-in; nobody makes one by
+     * accident. And nothing here reads the graph unprompted: the lookup only
+     * happens when an agent explicitly calls roam_get_guidelines, so the tool
+     * call is already the consent.
+     *
+     * Set `guidelinesPage: false` to turn it off for a graph.
      */
     getGuidelinesPage(key) {
         const resolvedKey = key ?? this.defaultKey;
@@ -79,7 +93,7 @@ export class GraphRegistry {
         if (config?.guidelinesPage === false) {
             return null;
         }
-        return config?.guidelinesPage ?? process.env.ROAM_GUIDELINES_PAGE ?? 'roam/agent guidelines';
+        return config?.guidelinesPage ?? process.env.ROAM_GUIDELINES_PAGE ?? DEFAULT_GUIDELINES_PAGE;
     }
     /**
      * Get an initialized Graph instance, creating it lazily if needed

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

@@ -67,11 +67,25 @@ describe('GraphRegistry', () => {
 });
 describe('getGuidelinesPage', () => {
     const make = (configs, def = 'personal') => new GraphRegistry(configs, def);
-    it('defaults to the shared roam/agent guidelines convention', () => {
+    it('reads the shared convention when a graph configures nothing', () => {
+        // Creating a page with that exact namespaced title IS the opt-in, and it is
+        // the same title Roam's own server reads — so one page serves both.
         delete process.env.ROAM_GUIDELINES_PAGE;
         const r = make({ personal: { token: 't', graph: 'g' } });
         expect(r.getGuidelinesPage('personal')).toBe('roam/agent guidelines');
     });
+    it('requires an explicit false to turn off — nothing else disables it', () => {
+        delete process.env.ROAM_GUIDELINES_PAGE;
+        const off = make({ personal: { token: 't', graph: 'g', guidelinesPage: false } });
+        expect(off.getGuidelinesPage('personal')).toBeNull();
+    });
+    it('false on one graph beats the env fallback', () => {
+        process.env.ROAM_GUIDELINES_PAGE = 'env/page';
+        const r = make({ personal: { token: 't', graph: 'p' }, work: { token: 't', graph: 'g', guidelinesPage: false } });
+        expect(r.getGuidelinesPage('work')).toBeNull();
+        expect(r.getGuidelinesPage('personal')).toBe('env/page');
+        delete process.env.ROAM_GUIDELINES_PAGE;
+    });
     it('prefers per-graph config over the env var', () => {
         process.env.ROAM_GUIDELINES_PAGE = 'env/page';
         const r = make({ work: { token: 't', graph: 'g', guidelinesPage: 'work/rules' } }, 'work');

package/build/tools/operations/block-retrieval.js

@@ -2,6 +2,7 @@ import { q } from '@roam-research/roam-api-sdk';
 import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
 import { resolveBlockRefs } from '../helpers/refs.js';
 import { fetchChildrenByDepth } from '../helpers/fetch-children.js';
+import { pruneHiddenBlocks, isHiddenBlockString } from '../helpers/hidden.js';
 export class BlockRetrievalOperations {
     constructor(graph) {
         this.graph = graph;
@@ -24,12 +25,17 @@ export class BlockRetrievalOperations {
             }
             const [rootString, rootOrder, rootHeading] = rootBlockResults[0];
             const childrenMap = await fetchChildrenByDepth(this.graph, [block_uid], depth);
+            // A block the user tagged #.rm-hide / #.rm-private is withheld outright,
+            // as is anything nested under it — same rule as the page read paths.
+            if (isHiddenBlockString(rootString)) {
+                return null;
+            }
             const rootBlock = {
                 uid: block_uid,
                 string: rootString,
                 order: rootOrder,
                 heading: rootHeading || undefined,
-                children: childrenMap[block_uid] || [],
+                children: pruneHiddenBlocks(childrenMap[block_uid] || []),
             };
             // Fetch ancestors if requested
             if (include_ancestors) {

package/build/tools/operations/full-page-view.js

@@ -3,6 +3,7 @@ import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
 import { getPageUid as getPageUidHelper } from '../helpers/page-resolution.js';
 import { resolveRefs } from '../helpers/refs.js';
 import { fetchChildrenByDepth } from '../helpers/fetch-children.js';
+import { collectHiddenUids, pruneHiddenBlocks, isHiddenBlockString } from '../helpers/hidden.js';
 export class FullPageViewOperations {
     constructor(graph, pageOps) {
         this.graph = graph;
@@ -21,12 +22,20 @@ export class FullPageViewOperations {
         const refResults = await this.fetchReferringBlocks(title);
         // Deduplicate by block_uid, then cap at max_references
         const seenUids = new Set();
-        const allUniqueRefs = refResults.filter(r => {
+        const dedupedRefs = refResults.filter(r => {
             if (seenUids.has(r.block_uid))
                 return false;
             seenUids.add(r.block_uid);
             return true;
         });
+        // Backlinks come from other pages, so the page's own prune (pageBlocks
+        // above, already filtered by fetchPageByUid) does not cover them. A
+        // referring block may itself be tagged, or sit under a tagged parent
+        // elsewhere — hence the UID closure rather than a text check alone.
+        // Filtered BEFORE the max_references cap so truncation counts what the
+        // caller can actually see.
+        const hiddenUids = await collectHiddenUids(this.graph);
+        const allUniqueRefs = dedupedRefs.filter(r => !hiddenUids.has(r.block_uid) && !isHiddenBlockString(r.block_str));
         const truncated = allUniqueRefs.length > max_references;
         const uniqueRefs = truncated ? allUniqueRefs.slice(0, max_references) : allUniqueRefs;
         const refBlockUids = uniqueRefs.map(r => r.block_uid);
@@ -89,7 +98,8 @@ export class FullPageViewOperations {
                 uid: ref.block_uid,
                 string: resolvedRefStrings.get(ref.block_uid) || ref.block_str,
                 order: 0,
-                children: childrenMap[ref.block_uid] || []
+                // Children of a visible backlink can still contain tagged subtrees.
+                children: pruneHiddenBlocks(childrenMap[ref.block_uid] || [])
             };
             groupMap.get(key).references.push({
                 breadcrumbs: breadcrumbsMap[ref.block_uid] || [],

package/build/tools/operations/guidelines.js

@@ -1,18 +1,20 @@
 /**
  * Per-graph agent guidelines.
  *
- * A page in the graph — `[[roam/agent guidelines]]` by default — holding the
- * user's own conventions: how they tag, how they name pages, what to never do.
+ * A page in the graph — conventionally `[[roam/agent guidelines]]` — holding
+ * the user's own conventions: how they tag, how they name pages, what to never do.
  * This is the same page Roam's official MCP server reads, so a user writes their
  * conventions once and both servers honour them.
  *
  * Distinct from the markdown cheatsheet, which is Roam *syntax* plus this
  * server's mechanics and lives in a file. Guidelines are per-graph, live-edited
  * from inside Roam, and answer "how does this user want their graph handled".
+ *
+ * Read by default; set `guidelinesPage: false` on a graph to disable it there.
  */
 import { PageOperations } from './pages.js';
 import { formatRoamDate } from '../../utils/helpers.js';
-/** Default page title, matching Roam's own convention. */
+/** The shared convention, read by default and by Roam's own MCP server. */
 export const DEFAULT_GUIDELINES_PAGE = 'roam/agent guidelines';
 /**
  * Short TTL: the point of a page over a config file is that an edit takes

package/build/tools/operations/guidelines.test.js

@@ -14,7 +14,7 @@ describe('GuidelinesOperations', () => {
     it('returns the page content when the page exists', async () => {
         getPageUid.mockResolvedValue('abc123456');
         fetchPageByTitle.mockResolvedValue('- H2: Tagging Philosophy');
-        const res = await new GuidelinesOperations(newGraph()).getGuidelines();
+        const res = await new GuidelinesOperations(newGraph(), DEFAULT_GUIDELINES_PAGE).getGuidelines();
         expect(res.exists).toBe(true);
         expect(res.page).toBe(DEFAULT_GUIDELINES_PAGE);
         expect(res.guidelines).toBe('- H2: Tagging Philosophy');
@@ -22,7 +22,7 @@ describe('GuidelinesOperations', () => {
     });
     it('reports absence rather than failing when no page has been created', async () => {
         getPageUid.mockResolvedValue(null);
-        const res = await new GuidelinesOperations(newGraph()).getGuidelines();
+        const res = await new GuidelinesOperations(newGraph(), DEFAULT_GUIDELINES_PAGE).getGuidelines();
         expect(res.exists).toBe(false);
         expect(res.guidelines).toBeNull();
         expect(res.nextSteps).toMatch(/no user conventions/i);
@@ -35,6 +35,13 @@ describe('GuidelinesOperations', () => {
         expect(res.page).toBe('work/agent rules');
         expect(getPageUid).toHaveBeenCalledWith('work/agent rules');
     });
+    it('defaults to the shared convention with no page configured', async () => {
+        getPageUid.mockResolvedValue('abc123456');
+        fetchPageByTitle.mockResolvedValue('rules');
+        const res = await new GuidelinesOperations(newGraph()).getGuidelines();
+        expect(res.page).toBe(DEFAULT_GUIDELINES_PAGE);
+        expect(getPageUid).toHaveBeenCalledWith(DEFAULT_GUIDELINES_PAGE);
+    });
     it('reports guidelines as disabled without touching the graph', async () => {
         const res = await new GuidelinesOperations(newGraph(), null).getGuidelines();
         expect(res.page).toBeNull();
@@ -44,27 +51,27 @@ describe('GuidelinesOperations', () => {
     });
     it('fails open — a lookup error never breaks the tool the agent wanted', async () => {
         getPageUid.mockRejectedValue(new Error('network down'));
-        const res = await new GuidelinesOperations(newGraph()).getGuidelines();
+        const res = await new GuidelinesOperations(newGraph(), DEFAULT_GUIDELINES_PAGE).getGuidelines();
         expect(res.exists).toBe(false);
         expect(res.guidelines).toBeNull();
         expect(res.nextSteps).toMatch(/network down/);
     });
     it('always reports today in Roam ordinal date format', async () => {
         getPageUid.mockResolvedValue(null);
-        const res = await new GuidelinesOperations(newGraph()).getGuidelines();
+        const res = await new GuidelinesOperations(newGraph(), DEFAULT_GUIDELINES_PAGE).getGuidelines();
         expect(res.todaysDailyNote).toMatch(/^[A-Z][a-z]+ \d{1,2}(st|nd|rd|th), \d{4}$/);
     });
     it('tells the agent not to re-orient, so it does not refetch every call', async () => {
         getPageUid.mockResolvedValue('abc123456');
         fetchPageByTitle.mockResolvedValue('rules');
-        const res = await new GuidelinesOperations(newGraph()).getGuidelines();
+        const res = await new GuidelinesOperations(newGraph(), DEFAULT_GUIDELINES_PAGE).getGuidelines();
         expect(res.nextSteps).toMatch(/do not call this tool again/i);
         expect(res.nextSteps).toMatch(/reads as well as writes/i);
     });
     it('caches within the TTL so a burst of calls costs one fetch', async () => {
         getPageUid.mockResolvedValue('abc123456');
         fetchPageByTitle.mockResolvedValue('rules');
-        const ops = new GuidelinesOperations(newGraph());
+        const ops = new GuidelinesOperations(newGraph(), DEFAULT_GUIDELINES_PAGE);
         await ops.getGuidelines();
         await ops.getGuidelines();
         await ops.getGuidelines();
@@ -73,7 +80,7 @@ describe('GuidelinesOperations', () => {
     it('refetches after the cache is cleared', async () => {
         getPageUid.mockResolvedValue('abc123456');
         fetchPageByTitle.mockResolvedValue('rules');
-        const ops = new GuidelinesOperations(newGraph());
+        const ops = new GuidelinesOperations(newGraph(), DEFAULT_GUIDELINES_PAGE);
         await ops.getGuidelines();
         ops.clearCache();
         await ops.getGuidelines();
@@ -82,8 +89,8 @@ describe('GuidelinesOperations', () => {
     it('keeps separate graphs separate', async () => {
         getPageUid.mockResolvedValue('abc123456');
         fetchPageByTitle.mockResolvedValue('rules');
-        await new GuidelinesOperations(newGraph()).getGuidelines();
-        await new GuidelinesOperations(newGraph()).getGuidelines();
+        await new GuidelinesOperations(newGraph(), DEFAULT_GUIDELINES_PAGE).getGuidelines();
+        await new GuidelinesOperations(newGraph(), DEFAULT_GUIDELINES_PAGE).getGuidelines();
         expect(getPageUid).toHaveBeenCalledTimes(2);
     });
 });

package/build/tools/operations/memory.js

@@ -1,6 +1,7 @@
 import { q } from '@roam-research/roam-api-sdk';
 import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
 import { generateBlockUid } from '../../markdown-utils.js';
+import { collectHiddenUids, isHiddenBlockString } from '../helpers/hidden.js';
 import { ANCESTOR_RULE } from '../../search/ancestor-rule.js';
 import { sanitizeTagName } from '../../utils/helpers.js';
 import { resolveRefs } from '../helpers/refs.js';
@@ -92,17 +93,26 @@ export class MemoryOperations {
             .replace(/^\[\[/, '').replace(/\]\]$/, ''); // Remove [[ and ]]
         try {
             // Query to find all blocks on the page
-            const pageQuery = `[:find ?string ?time
+            // ?uid is selected so hidden blocks can be filtered by the UID closure
+            // below — a text check alone would miss blocks nested under a tagged
+            // parent, which carry no tag of their own.
+            const pageQuery = `[:find ?string ?time ?uid
                          :in $ % ?title
                          :where
                          [?page :node/title ?title]
                          [?block :block/string ?string]
+                         [?block :block/uid ?uid]
                          [?block :create/time ?time]
                          (ancestor ?block ?page)]`;
             // Execute query
             const pageResults = await q(this.graph, pageQuery, [ANCESTOR_RULE, tagText]);
+            // Withhold anything the user tagged #.rm-hide / #.rm-private. The tagged
+            // half of recall (searchForTag below) is already filtered by
+            // SearchOperations; this is the page half.
+            const hiddenUids = await collectHiddenUids(this.graph);
             // Process page blocks with sorting
             let pageMemories = pageResults
+                .filter(([content, , uid]) => !hiddenUids.has(uid) && !isHiddenBlockString(content))
                 .sort(([_, aTime], [__, bTime]) => sort_by === 'newest' ? bTime - aTime : aTime - bTime)
                 .map(([content]) => content);
             // Get tagged blocks from across the graph

package/build/tools/operations/pages.js

@@ -501,10 +501,27 @@ export class PageOperations {
             });
         };
         sortBlocks(rootBlocks);
+        // Withhold #.rm-hide / #.rm-private subtrees before ANY format renders
+        // them. This function builds its own tree rather than reusing
+        // fetchPageByUid, so it needs its own prune — that duplication is exactly
+        // how this path shipped unfiltered the first time.
+        const visibleRoots = pruneHiddenBlocks(rootBlocks);
+        // Collect from the PRUNED tree, not by filtering allBlocks: pruning copies
+        // any node that has children, so the originals are no longer the objects
+        // rendered below, and the markdown branch mutates these in place.
+        const visibleBlocks = [];
+        const collectVisible = (bs) => {
+            for (const b of bs) {
+                visibleBlocks.push(b);
+                if (b.children.length > 0)
+                    collectVisible(b.children);
+            }
+        };
+        collectVisible(visibleRoots);
         if (format === 'raw') {
             // Resolve structured references for raw JSON output
-            await resolveBlockRefs(this.graph, allBlocks, 2);
-            return JSON.stringify(rootBlocks);
+            await resolveBlockRefs(this.graph, visibleBlocks, 2);
+            return JSON.stringify(visibleRoots);
         }
         if (format === 'structure') {
             const flattenBlocks = (blocks, depth, parentUid) => {
@@ -532,7 +549,7 @@ export class PageOperations {
                 }
                 return result;
             };
-            const structureBlocks = flattenBlocks(rootBlocks, 0, uid);
+            const structureBlocks = flattenBlocks(visibleRoots, 0, uid);
             return JSON.stringify({
                 page_uid: uid,
                 title: title,
@@ -541,7 +558,7 @@ export class PageOperations {
             });
         }
         // For markdown, resolve references inline
-        await Promise.all(allBlocks.map(async (b) => {
+        await Promise.all(visibleBlocks.map(async (b) => {
             b.string = await resolveRefs(this.graph, b.string);
         }));
         // Convert to markdown with proper nesting
@@ -567,7 +584,7 @@ export class PageOperations {
             })
                 .join('\n');
         };
-        return `# ${title}\n\n${toMarkdown(rootBlocks)}`;
+        return `# ${title}\n\n${toMarkdown(visibleRoots)}`;
     }
     /**
      * Update an existing page with new markdown content using smart diff.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roam-research-mcp",
-  "version": "2.23.0",
+  "version": "2.25.0",
   "description": "MCP server and CLI for Roam Research",
   "private": false,
   "repository": {