πŸ“š node [[agora protocol]]

What follows is Agora Protocol in a nutshell: https://twitter.com/flancian/status/1437079533253976066 .

Self: flancia.org/go/agora-protocol

See also: flancia.org/agora (motivation and TLDR), flancia.org/go/agora (early stage implementation), flancia.org/go/agora-roadmap (roadmap)

By: [[D. W.]], [[Flancian]], your name here!

[[Meta, and a note to contributors]] 1

[[Background]] 1

[[Wikilinks]] 2

[[Backlinks]] 2

[[Block references]] 2

[[Multi-user experience]] 2

[[Proposal]] 2

[[Concepts]] 3

[[Multinodes, or constructive conflict handling]] 3

[[Other clients]] 3

[[Data format]] 3

[[Go links]] 4

[[Contexts]] 4

[[Open questions]] 4

[[Possible Applications]] 4

Meta, and a note to contributors

  • Agora is just a working code name; it is a recurrent label that one of the authors has been using as a placeholder for a set of concurrent, only occasionally convergent ideas. Please feel free to propose a different name, or indeed to ignore the name overall.
  • This document will probably make use of unresolved [[wikilinks]] both for the purpose of demonstrating the concept and labelling entities. Eventually this text is expected to move into a reference Agora, and such links will resolve.
  • I tried keeping Background to about one page and Proposal to about one page. Unsure if this is the right proportion/format at all. Open to any and all feedback :)


The Agora is an annotation layer for the internet based on a loosely coupled socially maintained [[distributed knowledge graph]] based on [[wikilinks]] and back references.

Some conventions may be emerging in a new batch of personal knowledge management tools


, or amenable to them; for the duration of this document, we'll refer to these tools as Roam-like. These systems have caught on over more legacy apps such as Evernote, because associations can be created in a mesh or graph style between concepts and notes instead of relying on folders and more traditionally hierarchical organizational approaches.

This document seeks to explore common ground and propose a way towards a protocol for cross-tool distributed collaboration including aspects like interop, federation, etc.


The ubiquity of [[wikilinks]] is a notable innovation over the previous batch of Personal Knowledge Management tools. The [[wikilink]] convention is in wide use not only in wikis proper, but also in all Roam-likes.

At their core, they allow a user to quickly make a relative "wiki-style link" between a note in one place and a note or concept in another. Typically the user will employ a wiki-like convention to begin-- for instance, typing "[["-- at which point an increasingly constrained set of options will be offered in real time as the user continues typing, against a set of notes or concepts that have already been created in their personal knowledge graph.

As of the time of writing, all Roam-likes support [[wikilinks]] with optimistic resolution


; following a non-existent [[wikilink]] triggers a new note creation. This encourages link-driven writing and enables users to easily create stub pointers to entries to be filled in later.


Backlinks are core to the note taking and navigation experience in Roam-likes. They are the main innovation over most common Wiki tools previously in widespread use.

Backlinks are usually implemented as a list of incoming edges to the currently focused node.

Block references

Block references are critical to some, but not all, of Roam-likes; notably Roam Research and Athens Research support them. Block references are an instance of block-level transclusion.

Obsidian, Foam and other players either don't support References at all or support only limited forms (e.g. Obsidian can transclude sections only). It is unclear whether this should be a core feature of a protocol aiming to federate between tools.

Multi-user experience

At the time of writing Roam is the only tool with an established multi-user (a.k.a. "multiplayer") experience being developed.


We propose to develop Agora, a protocol that

  1. Enables interop between Roam-likes and the rest of the participating internet, in particular the [[fediverse]] and the [[semantic web]].
  2. Offers a common interface for tools targeting Roam-like databases as knowledge graph backends.


An Agora hostsa collection of interlinked gardens # 3. Each garden is an instance of a personal knowledge graph such as that produced by any Roam-like targeting a database. For the purpose of this document, assume that distinct users A, B and C all publish their digital gardens in an Agora.

Multinodes, or constructive conflict handling

Whereas in a Garden each node id is expected to be unique, in an Agora conflicts are desired and enable multinoding # 4_._Assume users A and B have nodes in their gardens with a given id, for example Stoa.

Multinoding results in the following behaviour:

  • When a user of the Agora (not necessarily A or B) visits a [[Stoa]], both A and B's nodes will resolve, and be shown one after the other.
  • When user C creates a new node in [[Stoa]], they are made aware of A and B's node (it is shown as related context).

Other clients

One of the most common uses of tools such as Hypothesis is for users to create annotations which are then imported into a wiki-note application for other purposes.

An obvious affordance would be for folks to directly reference their or other's knowledge graphs in their own annotation bodies. Both the Hypothesis app and others in this category are often using a flavor of markdown as the editor syntax, so the applications are already conceptually similar to each other.

Annotation tools could connect to an Agora of the user's choosing so that while an annotation was being created, a direct reference to a concept node could be created inline. The editor would need to be able to query the remote knowledge graph in real time such that candidate concepts could be presented as the user types, just like in a native client. One could imagine this kind of capability becoming social, if some knowledge graphs were exposed publicly and one could query across them and choose amongst them. In this way, if the Hypothesis note were to be exported to another systemβ€” including the remote knowledge app itselfβ€” the direct reference to the graph would automatically work.

Data format

Most Roam-likes, with the notable exception of Roam, store their data as plain Markdown files. This makes their databases amenable to being hosted in common version control systems.

With the exception of block references, Roam notes can be exported to this format in a lossless way.

The Agora v0.5 reference implementation makes use of this data format and is based on git subtrees. This makes it so that each participating user can host their gardens independently, and rely on the Agora exclusively for Agora-enabled flows (such as multinoding and publishing).


To be written. See [[distributed knowledge graph]].

Open questions

  • Should [[wikilink]] resolution collapse or maintain plurals and other common variations? Same for go links.

Possible Applications

Go links

Note [[go links]] and [[wikilinks]] have synergies. Go links can be seen as HTTP 302 as a service; they can provide both simple social bookmarking (letting users easily claim "URL space") and be seen as a social knowledge graph client. Making clients resolve also resolve [[wikilinks]] to [[go links]] as published by participating domains (perhaps those in a list controlled by the user, or those of their "friends") would allow users to crowdsource interesting targets.

Wikilinks everywhere

See: anagora.org/go/wikilinks-everywhere.

[[1]]Roam Research; Athens Research; Obsidian; Foam; Notion.

[[2]] Or as Ward Cunningham said: "When you reach the edge of your knowledge, create a new Wiki Page" (h/t Gyuri Lajos for the quotation).

[[3]] The term comes from digital garden, as exposed in https://joelhooks.com/digital-garden.

[[4]] Noding is borrowed from everything2.com, which successfully explored a similar setup.

  • #push [[agora protocol]]
    • (Push can be used for writing child blocks to a remote context, as if broadcasting to a [[pubsub]] topic.)
    • a [[protocol]].
      • Based on lightweight conventions conducive to [[knowledge federation]] of supported [[data formats]] as described below.
      • [[plain text]] as layer 0 (bootstrapping).
        • What the literate world already runs on: just plain old human language in full [[unicode]].
        • Note that indented bulleted lists are efficient while encoding trees, [[heterarchies]].
      • [[wikilinks]], #hashtags and other link conventions and annotation as part of layer 1.
      • Layer 2 being defined, the same as refinements to other layers, as [[extensions]].
        • If you are a member of an Agora, you can propose extensions to Agora Protocol by contributing to [[Agora RFCs]].
        • This should be sufficient to bootstrap a [[governance layer]] defined by each [[Agora]].
        • #pull [[agora rfcs]]
        • (Pull instructs an Agora to incorporate a remote context into the current context, e.g. [[transclude]] or provision below.)
  • how to determine scope for a #push (open problem in an Agora, beyond [[agora protocol]] limited implementation)
β₯… node [[agora-paper]] pulled by user


By default, this paper will be built around the following:


In this [[paper]] we describe an Agora, a [[social knowledge graph]] provisioned and maintained by a self-governing community as a commons.

The Agora [[knowledge graph]] can be defined as a hypergraph A with a set of k nodes N (entities an Agora knows about) integrated out of subnodes SN_0 .. SN_k containing subedges SE_0 .. SE_k, aggregating into edges E_0 .. E_k (semantic links between entities inferred out of known subnodes). Edges are annotated implicitly by link context and explicitly via the use of [[agora protocol]], which is extensible and tries to build on existing conventions in the [[personal knowledge management]] space.

An Agora differs from other projects in the personal knowledge space in a few ways: whereas a personal knowledge graph usually contains resources authored or collected by a single person, and a wiki usually contains resources produced by a group, an Agora contains, integrates and interlinks both personal and group resources. Whereas links in a personal knowledge graph or wiki usually have a single target, Agora links fan out by default and can be thought of as mapping to sets of resources. This is consistent with the general design principle of facilitating storage and retrieval of entity-mapped information towards removing friction from cooperation.

Building on the general principles above and a [[free software]]1 reference implementation of the underlying protocols and data, we model and detail how to implement a distributed system that provisions social knowledge services ethically and sustainably, upholding [[data sovereignty]] principles. We then analyze some of the potential applications of such a system. Finally, we shortly explore future work and social implications assuming that the Agora is run as a [[confederated]] system for the [[public good]].


As per [[agora pkm chapter]] by default?


  1. The provided [[reference Agora]] tries to remain tool, format and platform agnostic, building on general conventions common to many tools and platforms in the knowledge space for ease of integration and maximal inclusivity2 and diversity3. ↩

β₯… node [[agora-pkm-chapter]] pulled by user
β₯… node [[knowledge-commons]] pulled by user

knowledge commons

"the mutualization of productive knowledge"

The term "knowledge commons" refers to information, data, and content that is collectively owned and managed by a community of users, particularly over the Internet.

– Knowledge commons - Wikipedia

Examples of knowledge commons

The knowledge commons is a model for a number of domains, including Open Educational Resources such as the MIT OpenCourseWare, free digital media such as Wikipedia,[4] Creative Commons –licensed art, open-source research,[5] and open scientific collections such as the Public Library of Science or the Science Commons, free software and Open Design.[6][7]

– Knowledge commons - Wikipedia

Knowledge commoning

Once again, the promise of a knowledge commons is best made evident in the disagreements and difficulties in determining who and how it should be managed

– [[Undoing Optimization: Civic Action in Smart Cities]]

Knowledge commons is a misnomer bcos there is no such thing as knowledge. (!!)

What there IS/ARE is/are practices of knowing, communicating and organising.

So a 'knowledge commons' is a commons of literacy and (collective) labour power, thro which commoners are able to capably understand and organise their practical life as a commons, in a world of commons. It's a cultural commons.

– [[Mike Hales]] https://social.coop/@mike_hales/107430510590782176


πŸ“– stoas
β₯± context