roam-research-mcp 2.23.0 → 2.24.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,22 @@ 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`:
+**Opt-in.** A graph with no `guidelinesPage` and no `ROAM_GUIDELINES_PAGE` fallback has guidelines **disabled** — the tool reports that and never touches the graph. Nothing is read until you name a page, so a graph that happens to contain a similarly-titled page won't start feeding it to agents.
+
+Each graph can point at a different page:
 
 ```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": "...", "guidelinesPage": "roam/agent guidelines"},
+  "work":     {"token": "...", "graph": "...", "guidelinesPage": "work/agent rules"},
+  "archive":  {"token": "...", "graph": "..."}
+}'
+ROAM_GUIDELINES_PAGE='roam/agent guidelines'   # fallback for graphs that name none
 ```
 
-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` → disabled**. Setting `guidelinesPage: false` disables it for one graph even when the env fallback is set. In the example above, `archive` uses the fallback; without that env var it would be disabled.
+
+If the named page doesn't exist 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).
 
 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

@@ -71,7 +71,14 @@ export class GraphRegistry {
     }
     /**
      * Page holding a graph's agent conventions, or null when disabled.
-     * Same precedence as memoriesTag: per-graph config > env var > default.
+     *
+     * Precedence: per-graph config > ROAM_GUIDELINES_PAGE env var > **disabled**.
+     *
+     * Unlike memoriesTag this is opt-in: a graph with no `guidelinesPage` and no
+     * env fallback returns null rather than silently reading a conventional page
+     * title. Reading a page nobody asked us to read is a surprise, and a graph
+     * that happens to contain a similarly-named page should not start feeding it
+     * to agents.
      */
     getGuidelinesPage(key) {
         const resolvedKey = key ?? this.defaultKey;
@@ -79,7 +86,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 ?? null;
     }
     /**
      * Get an initialized Graph instance, creating it lazily if needed

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

@@ -67,10 +67,10 @@ describe('GraphRegistry', () => {
 });
 describe('getGuidelinesPage', () => {
     const make = (configs, def = 'personal') => new GraphRegistry(configs, def);
-    it('defaults to the shared roam/agent guidelines convention', () => {
+    it('is disabled when a graph configures nothing — opt-in, not opt-out', () => {
         delete process.env.ROAM_GUIDELINES_PAGE;
         const r = make({ personal: { token: 't', graph: 'g' } });
-        expect(r.getGuidelinesPage('personal')).toBe('roam/agent guidelines');
+        expect(r.getGuidelinesPage('personal')).toBeNull();
     });
     it('prefers per-graph config over the env var', () => {
         process.env.ROAM_GUIDELINES_PAGE = 'env/page';

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,23 @@
 /**
  * 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".
+ *
+ * Opt-in: a graph must name its page via `guidelinesPage` or ROAM_GUIDELINES_PAGE.
+ * With neither set the tool reports disabled and never touches the graph.
  */
 import { PageOperations } from './pages.js';
 import { formatRoamDate } from '../../utils/helpers.js';
-/** Default page title, matching Roam's own convention. */
+/** The conventional page title, matching Roam's own server. Not applied
+ * automatically — a graph must opt in via `guidelinesPage` or
+ * ROAM_GUIDELINES_PAGE. */
 export const DEFAULT_GUIDELINES_PAGE = 'roam/agent guidelines';
 /**
  * Short TTL: the point of a page over a config file is that an edit takes
@@ -25,7 +30,7 @@ export class GuidelinesOperations {
     /**
      * @param guidelinesPage Page title to read, or null when disabled for this graph.
      */
-    constructor(graph, guidelinesPage = DEFAULT_GUIDELINES_PAGE) {
+    constructor(graph, guidelinesPage = null) {
         this.graph = graph;
         this.guidelinesPage = guidelinesPage;
         this.pageOps = new PageOperations(graph);

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);
@@ -44,27 +44,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 +73,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 +82,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/build/tools/tool-handlers.js

@@ -9,12 +9,12 @@ import { MemoryOperations } from './operations/memory.js';
 import { TodoOperations } from './operations/todos.js';
 import { OutlineOperations } from './operations/outline.js';
 import { BatchOperations } from './operations/batch.js';
-import { GuidelinesOperations, DEFAULT_GUIDELINES_PAGE } from './operations/guidelines.js';
+import { GuidelinesOperations } from './operations/guidelines.js';
 import { TableOperations } from './operations/table.js';
 import { DatomicSearchHandlerImpl } from './operations/search/handlers.js';
 import { FullPageViewOperations } from './operations/full-page-view.js';
 export class ToolHandlers {
-    constructor(graph, memoriesTag = 'Memories', guidelinesPage = DEFAULT_GUIDELINES_PAGE) {
+    constructor(graph, memoriesTag = 'Memories', guidelinesPage = null) {
         this.graph = graph;
         this.cachedCheatsheet = null;
         this.pageOps = new PageOperations(graph);

package/package.json

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