v2.18.0

Features

• roam save --order — Control insertion position of top-level blocks

  • --order first prepends to top of page/parent
  • --order last appends (default, backwards-compatible)
  • --order N inserts at specific 0-indexed position
  • Works with all save modes: text, file, stdin, --todo, --json, --lines

• roam_create_outline order parameter — Same position control for the MCP tool

  • Accepts "first", "last", or integer

Other

• CI workflow bumped to actions/checkout@v5, actions/setup-node@v5, Node.js 22

v2.17.0

What's New

Full Page View (roam_fetch_page_full_view + roam get full)

Mirrors Roam's page view UI — fetches a page's own content plus all linked references with breadcrumb context and children expanded to configurable depth. Includes a max_references safety valve (default 200) to prevent timeouts on heavily-referenced pages. (#15, thanks @quinten-l)

roam get full "Project Notes"          # Full view with backlinks
roam get full "TODO" -n 50             # Cap references at 50

Sub-Pages (roam_get_subpages + roam get subpages)

List pages under a namespace prefix (e.g. "Project/", "Framework/") with optional tag filtering and content inclusion.

roam get subpages "Project"                    # List all Project/* pages
roam get subpages "Framework" --content        # With block content
roam get subpages "Project" --filter-tag active # Only active projects

Refactors

• Extract fetchChildrenByDepth into shared helper used by both block-retrieval and full-page-view

Bug Fixes

• convertToRoamActions now correctly passes through 'first'/'last' order strings
• CLI roam save <file.md> -p <page> no longer ignores the -p flag when input is a file
• Typo fix in roam_add_content schema description

Acknowledgements

Thank you, @quinten-l

v2.16.0 — Bidirectional Block Traversal

What's New

roam_fetch_block_with_children → roam_fetch_block — renamed with bidirectional traversal support.

New: Ancestor Chain Traversal

• New include_ancestors parameter (default: false) returns the ancestor chain from any block up to the page root
• Each ancestor includes UID, content string (or title for page root), and depth
• Uses Datomic :block/parents pull pattern — single API call, no recursion
• Combine with depth: 0 to fetch ancestors only (lightweight alternative to fetching entire page)

CLI

• New -a, --ancestors flag on roam get for ancestor traversal from the command line
• roam get abc123def -a — block + children + ancestors
• roam get abc123def -a -d 0 — ancestors only, no children

Backward Compatible

• Existing depth parameter and children behavior unchanged
• Deprecated fetchBlockWithChildren() method kept as alias
• Default behavior (no include_ancestors) returns identical output to v2.15.x

v2.15.3

Changes

v2.15.3

• Fix: Cheatsheet path resolution for npx/installed environments (#14)
  • getCheatsheetPath() now resolves relative to __dirname instead of process.cwd(), fixing "file not found" errors when the server is invoked via npx or from a global install

v2.15.2

• Fix: Sanitize category/tag inputs to prevent double-hash formatting (##Tag, #[[#Tag]])
• Fix: Docker build — copy .roam/ directory and cheatsheet into builder and release stages

Also included (since v2.13.0)

• v2.15.1: CLI isBlockUid() now requires at least one digit, preventing 9-letter titles from being misidentified as UIDs
• v2.15.0: Cheatsheet v2.2.0 — advanced components section with hidden/undocumented Roam features
• v2.14.0: --lines flag for CLI, enhanced --debug, numbered list threading, structure format

Full changelog: https://github.com/2b3pro/roam-research-mcp/blob/main/CHANGELOG.md

v2.13.0

Features

Markdown Parser Improvements

• Numbered lists — Prefixes (1., 2., etc.) are now stripped from content and parent blocks receive children-view-type: "numbered" for proper Roam rendering
• Horizontal rules — ---, ***, ___ (3+ chars) converted to Roam's native --- format
• Affects: roam_import_markdown, roam_create_outline, roam_create_page with content, CLI roam save

Page Existence Validation

• Batched existence checking — Single Datomic query checks all parent-uids at once (1 API call instead of N), rate-limit friendly
• Daily page auto-creation — Detects MM-DD-YYYY format UIDs and auto-creates missing daily pages before batch execution
• Session-scoped UID cache — Tracks known existing UIDs to avoid redundant API calls within a session
• Clear error messages — Missing non-daily pages return actionable error: "Create them first with roam_create_page"

Testing

• 15 new tests for PageValidator in src/shared/page-validator.test.ts
• 11 new tests for markdown features in src/markdown-utils.test.ts
• All 152 tests passing

Commits

• 88e964e feat(markdown): add numbered list and horizontal rule support
• c9af1cc feat(batch): add page existence validation with daily page auto-creation
• 9919bab test(block-retrieval): fix skipped tests with correct mock setup

v2.10.0

What's New in v2.10.0

Namespace Search for Page Titles

• Added scope: "page_titles" parameter to roam_search_by_text for finding pages by namespace prefix
• Example: searching "Convention/" finds all pages starting with Convention/
• CLI: roam search --namespace "Convention"

---

Changelog Since v2.4.3

v2.10.0 - Namespace Search

• feat(search): Add namespace prefix search for page titles via scope parameter

v2.9.1 - Page Subcommand

• feat(cli/get): Add page subcommand for UID/URL retrieval (roam get page abc123)

v2.9.0 - Heading Hierarchy

• feat(save): Infer heading hierarchy from markdown (H1-H3 preserved)

v2.8.1 - Reliability Fixes

• fix(pages): Improve createPage reliability and fetchPageByTitle array return

v2.8.0 - Per-Graph Memory Tags

• feat(memory): Add per-graph memoriesTag configuration in ROAM_GRAPHS

v2.7.0 - Sort & Group

• feat(cli/get): Add --sort (created/modified/alpha) and --group-by (page/tag) options

v2.6.0 - Advanced Filtering

• feat(cli/get): Add --tag, --text, --any, --negtag, --showall options

v2.5.1 - Block Reference Resolution

• fix(refs): Add recursive block reference resolution logic

v2.5.0 - Write Protection

• feat(config): Use protected flag + ROAM_SYSTEM_WRITE_KEY for write protection

Bug Fixes

• fix(search): roam_search_by_text page filter now works correctly
• fix(cli/get): Markdown code block transformation fixed

Documentation

• LLM-optimized CLI reference added
• README updated with CLI examples and project evolution

Full Changelog: v2.4.3...v2.10.0

v2.4.0 - Multi-Graph Architecture

🚀 Major Release: Multi-Graph Architecture

This release introduces a complete rewrite with multi-graph support, making it easy to work with multiple Roam graphs from a single installation.

✨ Highlights

Multi-Graph Support

• Configure multiple graphs via ROAM_GRAPHS JSON environment variable
• Write protection with write_key for sensitive graphs
• Dynamic graph info prepended to cheatsheet for AI awareness

New CLI Commands

• roam status - Show available graphs and connection status with --ping testing
• roam batch - Execute multiple block operations efficiently in a single API call
• roam rename - Rename pages by title or UID
• roam refs - Find all blocks referencing a page, tag, or block

Enhanced CLI

• Datalog query support in roam search -q
• Smart diff for page updates (preserves block UIDs)
• TODO/DONE workflow improvements
• Heading flag support

⚠️ Breaking Changes

• Environment variable format changed for multi-graph (ROAM_GRAPHS JSON)
• All MCP tools now include graph and write_key parameters
• Some tool behaviors modified for multi-graph support

📦 Installation

npm install -g roam-research-mcp

📚 Documentation

See README and CLI README for full documentation.

---

🤖 Generated with Claude Code

v1.9.1 - Final v1.x Release

Final v1.x Release

This is the last release of the v1.x series before the v2.0 multi-graph architecture.

Features (v1.7.0 - v1.9.1)

• CLI --heading flag for save command
• roam_move_block tool
• Enhanced roam_remember with parent targeting
• --no-daily-page flag for save command
• Parent and JSON options for save command
• TODO/DONE support in get and save commands
• Block reference expansion in CLI

Maintenance

The v1 branch is available for critical fixes. New development continues on main (v2.x).

---

🤖 Generated with Claude Code