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 :)

Background

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

1

, 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.

Wikilinks

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

2

; 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

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.

Proposal

We propose to develop Agora, a protocol that

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

Concepts

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).

Contexts

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.

📜 stoa-test/agora-protocol.md (contribution by @agora) ☆ 📎 ≡

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 :)

Background

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

1

, 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.

Wikilinks

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

2

; 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

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.

Proposal

We propose to develop Agora, a protocol that

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

Concepts

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).

Contexts

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.

📜 agora protocol.md (contribution by @flancian) ☆ 📎 ️🔗 ✍️ ≡

a [[protocol]].
- A series of conventions that sentient beings can agree to follow while trying to communicate optimally for the [[common good]].
  - A series of explicit assertions.
  - Announced customarily in [[schelling points]].
  - Extended through [[agora rfcs]].
  - With such a [[protocol]] we can build ([[provision]]?) a common [[pattern language]] and bootstrap a global [[knowledge commons]].
    - An [[Agora]] is a [[repository]] of [[patterns]].
- A [[flancian]] uses [[Agora Protocol]] to try to define their [[intents]] publicly and cooperate with others optionally for the benefit of beings, but all aspects of Agora and Flancia are meant to be fully optional.
  - I am a [[Flancian]] and this Agora contains my [[manifesto]].
a [[document]].
- #go https://docs.google.com/document/d/1JdaC_9J0uYFNFp7g7x4VNtMxJSZQsE2MQkOMmydLCCc/edit
- Trying to [[bootstrap]] the above [[protocol]].
- Plus a roadmap for a [[platform]] or federated [[network]] making use of it.
- #pull [[agora paper]].
- In [[an agora]], [[agora protocol]] is meant to enable people to exchange [[resources]] mapping to [[patterns]] in a (by default) free global [[commons]], which I also call the Agora for short.
  - This Agora is a [[knowledge commons]] but seeks to enable [[communities]] to bootstrap a physical [[commons]] to provision for their needs as well.
- [[meta]]
  - I started with [[google docs]] in 2019/2020 and then I tried moving to [[hedgedoc]] but actually I think I might just go back to the [[google doc]]. It’s just a rich experience, and several potential collaborators already use it (they left comments).
  - Update (2022): revamping now ocassionally while writing [[agora pkg chapter]], but it may be that the source of truth becomes [[agora paper]].
a social [[convention]].
- A list of social [[conventions]] and [[assertions]].
  - Focusing on improving the ability to communicate with each other with good intent.
  - [[text based]] to begin with.
  - This means you can use it anywhere you can write down text by default.
  - Using this basic quality, we can make use of [[adversarial interoperability]] as we want to.
  - [[agora protocol]] can be used everywhere.
    - It is already used in [[wikis]]. You might as well call it [[wiki protocol]] used in new contexts.
    - You already use it in [[digital gardens]].
    - You can use it in [[books]].
      - Books written today with Markdown u[[git]]
    - In [[email]].
    - In [[chat]] and [[social networks]].
      - -> [[agora plan]]
    - [[Around the web]] in general.
      - -> [[agora ext]]
- This [[Agora]], resolved by default using common [[Agora endpoints]] at https://anagora.org , welcomes all [[people]] and [[formats]] a priori.
- This [[Agora]] welcomes all groups except [[fascists]] and the [[violent]].
- It is the opinion of this Agora that the use of [[agora protocol]] in a medium defines an Agora, in the sense that it designates the contexts in which the protocol is used as part of some Agora by default; and the medium as potentially interoperable with the [[Agora network]].

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

[[layer 0]]
- [[layer 1]]
- You can use [[wikilinks]]. This expresses an intention to make use the [[wiki protocol]], of which the Agora is a special case.
  - The reference Agora, in which you are probably reading this, also has some limited [[hashtag]] support.
  - An Agora is any virtual space you can define in any way you want as long as it is [[explicit]] and by default [[public]].
    - Each Agora publishes a set of definitions of intention as expressed by its [[users]].
    - This Agora is [[rational]], [[pro social]] and [[heterarchical]].
a [[protocol]].
- for [[federation]].
  - can be bootstrapped with [[agora exchange format]]?
  - #pull [[knowledge commons]]
  - [[plain text]] plus as layer 0 (bootstrapping layer).
    - indented bulleted lists designate a useful [[heterarchy]].
  - [[wikilinks]] and #hashtags at layer 1, plus other link conventions and metadata extensions.
    - successive layers are explicitly discussed through [[agora rfcs]] and settled through a [[governance layer]] called an [[agora]] and defined by convention.
      - agora protocol payloads may be exchanged for knowledge for [[free]] in any designated [[agora]].
      - this [[agora]] is built around a [[pro social]] [[distributed knowledge graph]], that is, a [[social knowledge graph]].
      - see [[go/agora-slides]] for more.
    - to see the communally maintained text of the full protocol, please refer to the [[stoa]] below.
      - [[stoa]] https://stoa.anagora.org/p/stoa
  - a [[protocol]] is a set of explicit conventions that can be followed for a purpose.
    - conventions can be optional or necessary and must be marked as such. The default commitment level for this protocol is [[optional]]. [[use must if you must]].
  - for [[extensions]]:
    - push to or modify [[agora rfcs]].
    - this is as kept by the community agreeing to cooperate on such a list: the community of the [[agora]].
    - #push [[agora]]
      - an [[agora]] is a seed that wants to grow into a [[tree]], and from there into a [[distributed]] network.
      - the [[seed]] of this agora is [[go/agora/git]], defining a [[commons]].
      - [[flancia collective]] is the keeper of https://anagora.org .
      - [[agora bridge]], [[agora server]] contain input (write) and output (read) code respectively.
  - #push [[agoras]]
    - Compatible [[agoras]] are expected to assemble into a greater federated [[agora network]] where they can fork and merge as wanted.
    - [[agoras]] must communicate clear [[goals]].
  - [[2020]] https://docs.google.com/document/d/1JdaC_9J0uYFNFp7g7x4VNtMxJSZQsE2MQkOMmydLCCc/edit#
  - [[the agora is a markup convention]]
  - [[2021]] I presented in [[i annotate]], refer to [[go/agora-slides]] or recording if interested.
- [[2022]] writing [[agora pkg chapter]]
- [[twitter]]

📜 Agora protocol.md (contribution by @flancian) ☆ 📎 ️🔗 ✍️ ≡

#pull see also [[agora pkm chapter]].

📜 agora-protocol.md (contribution by @patterning) ☆ 📎 ≡

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 :)

Background

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

1

, 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.

Wikilinks

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

2

; 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

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.

Proposal

We propose to develop Agora, a protocol that

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

Concepts

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).

Contexts

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.

📜 agora-protocol.md (contribution by @vera.wiki.anagora.org) ☆ 📎 ≡

📜 agora-protocol.md (contribution by @anonymous@doc.anagora.org) ☆ 📎 ✍️ ≡

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 :)

Background

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

1

, 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.

Wikilinks

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

2

; 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

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.

Proposal

We propose to develop Agora, a protocol that

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

Concepts

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).

Contexts

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.

📜 Agora Protocol.md (contribution by @agora@botsin.space) ☆ 📎 ≡

📜 agora protocol.md (contribution by @agora@botsin.space) ☆ 📎 ≡

📜 Agora protocol.md (contribution by @agora@botsin.space) ☆ 📎 ≡

[[flancian@social.coop]] https://social.coop/@flancian/109371755076391416

📜 agora protocol.md (contribution by @an_agora@twitter.com) ☆ 📎 ≡

📜 Agora protocol.md (contribution by @an_agora@twitter.com) ☆ 📎 ≡

📜 agora protocol.md (contribution by @anagora@matrix.org) ☆ 📎 ≡

[[2022-07-10 13:50:26]] [[@flancian:matrix.org]] (link):
- I’m finally picking up [[agora protocol]] again after much procrastination (or maybe just a pause for thought!)
[[2022-07-16 23:45:15]] [[@flancian:matrix.org]] (link):
- tomorrow I’ll try to do some writing about [[agora protocol]]
[[2022-08-05 23:34:53]] [[@flancian:matrix.org]] (link):
- 1. work on [[agora pkg chapter]], [[agora protocol]] continues.
[[2022-08-19 21:44:11]] [[@flancian:matrix.org]] (link):
- also made some progress on editing [[agora protocol]] earlier
[[2023-02-17 21:41:25]] [[@flancian:matrix.org]] (link):
- how do we copy information losslessly between one page and another? microformats maybe are key here? but maybe just agreeing on textual conventions (this is what [[agora protocol]] tries to be)
[[2023-09-07 21:25:43]] [[@flancian:matrix.org]] (link):
- in any case not that you should implement default handlers; I consider it part of [[agora protocol]] but I think it makes sense to call it optional
[[2023-09-09 18:21:08]] [[@flancian:matrix.org]] (link):
- yes, this should be defined in [[agora protocol]] or a similar node

📜 Agora protocol.md (contribution by @anagora@matrix.org) ☆ 📎 ≡

[[2023-02-17 21:43:05]] [[@charismatic_shell:matrix.org]] (link):
- Textual conventions won’t work, because they interfere with the semantics, and not everyone wants to do that. For example, [[Melanocarpa]] does not really follow [[Agora protocol]].

📜 agora-protocol.md (contribution by @anagora@matrix.org) ☆ 📎 ≡

[[2022-03-04 20:43:46]] [[@flancian:matrix.org]] (link):
- I see it as part of [[agora protocol]], but I’m sure there are other names for it
[[2022-03-16 16:29:13]] [[@flancian:matrix.org]] (link):
- I must work on improving [[agora protocol]]
[[2022-03-20 16:41:26]] [[@flancian:matrix.org]] (link):
- "the [[agora protocol]] was built on top of [[activitypub]]."
[[2022-03-20 16:42:46]] [[@flancian:matrix.org]] (link):
- of course they should all be supported, but I think we need to choose one "base protocol" to speak to each other by default — that also maybe means that’s the main protocol you target when you’re writing code to implement some aspect of [[agora protocol]]
[[2022-03-20 16:48:05]] [[@flancian:matrix.org]] (link):
- at that level I want to think of [[agora protocol]] as a meta-tool for building and maintaining a [[commons]]
[[2022-05-04 23:31:56]] [[@charismatic_shell:matrix.org]] (link):
- Unlike [[agora protocol]], which is for humans, [[mycorrhiza protocol]] is for machines

📜 Agora Protocol.md (contribution by @flancian@social.coop) ☆ 📎 ≡

[[2024-08-20 22:13:50+00:00]] @[[flancian@social.coop]] (link):
- [[Agora Protocol]] RFC 0.9 :)
  - URIs like a://entity and agora://entity are reserved for representing general Agora space.
  - URIs like a://anagora.org/entity and agora://anagora.org/entity represent Agora space as resolved starting from the Agora mentioned.
  - Entities can be UTF-8 or url-encoded.
  From: @jonny
  https://neuromatch.social/@jonny/112974405502972288
[[2024-08-20 22:15:18+00:00]] @[[flancian@social.coop]] (link):
- [[Agora Protocol]] RFC 0.9 :)
  - URIs like a://entity and agora://entity are reserved for representing general Agora space.
  - URIs like a://anagora.org/entity and agora://anagora.org/entity represent Agora space as resolved starting from the Agora mentioned.
  - Entities can be UTF-8 or url-encoded.
  From: @jonny
  https://neuromatch.social/@jonny/1129744…@jonny/112974405502972288

📜 Agora protocol.md (contribution by @flancian@social.coop) ☆ 📎 ≡

[[2022-11-19 17:55:40+00:00]] @[[flancian@social.coop]] https://social.coop/@flancian/109371755076391416:
- My hypothesis is that we need a human readable/semantic protocol layer on top of what pre-internet human writing has evolved to be. Something on the pragmatic layer of linguistics.
  I call it [[Agora protocol]]. And I’ll try to implement it on top of [[ActivityPub]] these following weekends, in some meaningful way.

📜 Agora protocol.md (contribution by @flancian@twitter.com) ☆ 📎 ≡

[[2022-11-19 17:59:13+00:00]] @[[flancian]]: https://twitter.com/flancian/status/1594027528536338432

My hypothesis is that we need a human readable/semantic protocol layer on top of what pre-internet human writing has evolved to be. Something on the pragmatic layer of linguistics.

I call it [[Agora protocol]]. And I’ll try to implement it on top of [[ActivityPub]] these (1/2)

[[2022-11-19 18:13:13+00:00]] @[[flancian]]: https://twitter.com/flancian/status/1594031054301675527

RT @flancian@social.coop My hypothesis is that we need a human readable/semantic protocol layer on top of what pre-internet human writing has evolved to be. Something on the pragmatic layer of linguistics.

I call it [[Agora protocol]]. And I’ll try to implement it on top (1/2)

Loading pushes...

✨ AI Synthesis Mistral Gemini ChatGPT Claude x

Expanding this section will automatically generate an AI synthesis of the contributions in this node.

≡ 📚 Agora location [[agora paper]] (pulled by user) x

≡ 📚 Agora location [[agora pkm chapter]] (pulled by user) x

≡ 📚 Agora location [[knowledge commons]] (pulled by user) x