roam-research-mcp 2.24.0 → 2.25.0

package/README.md

@@ -161,22 +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 |
 
-**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.
+**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.
 
-Each graph can point at a different page:
+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"},
+  "personal": {"token": "...", "graph": "..."},
   "work":     {"token": "...", "graph": "...", "guidelinesPage": "work/agent rules"},
-  "archive":  {"token": "...", "graph": "..."}
+  "private":  {"token": "...", "graph": "...", "guidelinesPage": false}
 }'
-ROAM_GUIDELINES_PAGE='roam/agent guidelines'   # fallback for graphs that name none
+ROAM_GUIDELINES_PAGE='team/agent guidelines'   # change the default for every graph
 ```
 
-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.
+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.
 
-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).
+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,15 +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.
+     * Page holding a graph's agent conventions, or null when explicitly disabled.
      *
-     * Precedence: per-graph config > ROAM_GUIDELINES_PAGE env var > **disabled**.
+     * Precedence: per-graph config > ROAM_GUIDELINES_PAGE env var >
+     * "roam/agent guidelines" (the shared convention).
      *
-     * 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.
+     * 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;
@@ -86,7 +93,7 @@ export class GraphRegistry {
         if (config?.guidelinesPage === false) {
             return null;
         }
-        return config?.guidelinesPage ?? process.env.ROAM_GUIDELINES_PAGE ?? null;
+        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,10 +67,24 @@ describe('GraphRegistry', () => {
 });
 describe('getGuidelinesPage', () => {
     const make = (configs, def = 'personal') => new GraphRegistry(configs, def);
-    it('is disabled when a graph configures nothing — opt-in, not opt-out', () => {
+    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')).toBeNull();
+        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';

package/build/tools/operations/guidelines.js

@@ -10,14 +10,11 @@
  * 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.
+ * Read by default; set `guidelinesPage: false` on a graph to disable it there.
  */
 import { PageOperations } from './pages.js';
 import { formatRoamDate } from '../../utils/helpers.js';
-/** The conventional page title, matching Roam's own server. Not applied
- * automatically — a graph must opt in via `guidelinesPage` or
- * ROAM_GUIDELINES_PAGE. */
+/** 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
@@ -30,7 +27,7 @@ export class GuidelinesOperations {
     /**
      * @param guidelinesPage Page title to read, or null when disabled for this graph.
      */
-    constructor(graph, guidelinesPage = null) {
+    constructor(graph, guidelinesPage = DEFAULT_GUIDELINES_PAGE) {
         this.graph = graph;
         this.guidelinesPage = guidelinesPage;
         this.pageOps = new PageOperations(graph);

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

@@ -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();

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 } from './operations/guidelines.js';
+import { GuidelinesOperations, DEFAULT_GUIDELINES_PAGE } 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 = null) {
+    constructor(graph, memoriesTag = 'Memories', guidelinesPage = DEFAULT_GUIDELINES_PAGE) {
         this.graph = graph;
         this.cachedCheatsheet = null;
         this.pageOps = new PageOperations(graph);

package/package.json

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