A suite of tools for maintaining a discourse graph from Roam!


You could use the Copy Extension button below to individually install this extension. To install, just paste anywhere in your Roam graph and click "Yes, I Know What I'm Doing".

Manual Installation

If the extension doesn't work after using the copy extension button above, try installing manually using the instructions below.

First create a block with the text {{[[roam/js]]}} on any page in your Roam DB. Then, create a single child of this block type three back ticks. A code block should appear. Copy this code and paste it into the child code block in your graph:

var existing = document.getElementById("roamjs-discourse-graph-main");
if (!existing) {
  var extension = document.createElement("script");
  extension.src = "https://roamjs.com/discourse-graph/main.js";
  extension.id = "roamjs-discourse-graph-main";
  extension.async = true;
  extension.type = "text/javascript";

Finally, click "Yes, I Know What I'm Doing".


Discourse graphs are an information model for bodies of knowledge that emphasize discourse moves (such as questions, claims, and evidence), and relations (such as support or opposition).

This information model (theoretically!) has high potential for augmenting individual and collective "research-grade" synthesis (e.g., lit reviews for a dissertation or grant proposal).

Discourse graphs are not a new idea (you can read more about it in this short (academic-focused) write-up), but the potential to use it for everyday research work is! .

This extension instantiates an experimental bet that this information model can be seamlessly integrated into a networked note-taking workflow for literature reviewing and writing, in such a way that authoring a formal discourse graph becomes a byproduct of (and directly enhances) joyful, intrinsically and immediately beneficial tasks like notetaking and outlining and collaboration. This bet is (partially) written up in this essay.


This experimental extension instantiates this bet by providing the following three sets of capabilities in your Roam graph. We briefly summarize them here: click through to the feature sub-pages for more details on [[HowTo]] use them.

Please note! This is an experimental extension under active development. The usual caveats for roam/js extensions apply (backup your graph, if you're nervous, test in a local graph first: although the extension doesn't make any back-end/bulk changes to your graph, so your data shouldn't be affected by the extension's behavior: it moreso automates/smooths some things you might do manually already, and adds new ways to interact with existing data that might be latent in your graph).

I. Seamlessly create a formal discourse graph alongside your informal notes

Discourse graphs are valuable in part because they are formalized. But most of our notes are not! To integrate the possible value of discourse graphs into our own notes, we need a way for them to peacefully co-exist, and for us to gracefully "formalize" parts of our notes into discourse graphs when appropriate.

The extension helps with this by including features that:

  • Author formal discourse nodes alongside your informal notes: The node menu makes it easy to factor parts of your notes into formal nodes of a discourse graph (claims, evidence, etc.). For example, the extension currently includes keyboard shortcuts for quickly "refactoring" notes into claim and evidence notes with appropriate metadata.

    • (refactoring a portion of a reading note into a formal evidence note for later use)

  • Naturally create formal discourse relations between nodes by writing and outlining: The graph grammar feature enables the system to parse formal discourse relation edges (e.g., support, oppose, inform, consistent-with) from user-defined conventions of prose writing and outlining, making it possible for you to write and outline very similarly to how you would normally write/outline for your own thinking, and author edges between nodes in a formal discourse graph as a natural byproduct.

    • (define your own patterns of writing and outlining (or use/fork patterns from other users) that the extension recognizes and translates into formal discourse graph relations; the system shows a preview of how the patterns you describe map to patterns of Roam writing/outlining)

    • (example parse: from informal prose outline on the left to a formal discourse graph on the right that recognizes claim (green) and evidence (pink) typed nodes and support relationships between evidence and claim)

II. Leverage a formal discourse graph to improve your thinking and writing

Discourse graphs can help with synthesis in many ways, such as querying and sorting between claims based on evidentiary support/opposition, or even computing belief scores as a function of support/opposition (as a complement to qualitative reasoning). The extension helps explore how to provide this immediate value.

At the moment, a few proof-of-concept prototype features are implemented, such as:

  • Perform formal graph queries over your discourse graph: The synthesis query component enables users to perform specialized querying based on discourse graph elements and relations (e.g., find all evidence that informs my question, but opposes some claim), and insert elements into your writing or on a playground

  • "Surf" your discourse graph from node to node: The [[discourse-graph/discourse-context]] component provides additional associative trail navigation based on discourse relations like inform/support/oppose. You can think of this as slightly more formalized/focused version of backlinks.

  • Do visual sensemaking and synthesis over your claims and evidence: The playground provides a visuospatial "playground" where you can import discourse graph elements and do visual exploratory sensemaking over your claims and evidence, then export to a Roam page as a rough outline.

III. Leverage a formal discourse graph to improve collaboration with others

Discourse graphs may also be a particularly effective abstraction of your notes to share and collaborate with others. The extension helps explore this value proposition.

At the moment, the following proof-of-concept prototype features are implemented, such as:

  • Export your discourse graph in open, interoperable standard formats to share with others. The extension's export functionality offers the ability to do specialized query/export of (portions/subsets) of your discourse graph to a labeled property graph (for direct import into Neo4j) and/or a markdown bundle of notes. For example, imagine collecting all evidence notes that inform a focal question and sharing that with a collaborator/student that they can immediately try to make sense of and integrate into their own notes and outlines, instead of dumping a giant stack of papers on their desk! Other features are in the pipeline now for in-graph (and later, cross-graph) subscriptions to discourse graphs from collaborators and people with common interests.

  • Subscribe to graph query updates from others: Subscriptions is an #experimental feature that is coming soon! The idea will be to allow users to subscribe to updates to the discourse graph (e.g., new evidence that supports a claim, new claims that inform a question), first in the same graph, and then later, potentially with integrations with [[roam/inter]] or core Roam multiplayer functionality, subscribe to discourse graph updates from other graphs.

This is an ongoing research project, so more features are possible! We invite you to join us in exploring how integrating discourse graphs into networked notebooks like Roam might make us better thinkers, together! Issues are tracked on github (where the code is also open-sourced)

Contact Joel Chan (joelchan@umd.edu or @JoelChan86 on Twitter or in the #discourse-graph channel on the Academia Roamana Discord) for more details!


(Optional) CSS

CSS from here can be used alongside formal node definitions if desired: https://roamresearch.com/#/app/roam-synthesis/page/hf70y5mVU

Make sure to copy both the variables and synthesis blocks


This extension is brought to you by RoamJS! If you are facing any issues reach out to support@roamjs.com or click on the chat button on the bottom right.

If you get value from using this extension, consider sponsoring RoamJS by clicking on the button below!

A special thanks to those who's contributions also helped make this extension possible:

Joel Chan
Joel Chan

Other Extensions