MSC4438: Message bookmarks via account data by smokku · Pull Request #4438 · matrix-org/matrix-spec-proposals

smokku · 2026-03-24T10:04:42Z

Implementations:

Client: https://github.com/smokku/cinny (deployed at https://matrix.chrome.pl/ )

Signed-off-by: Tomasz Sterna tomasz@sterna.link

Copilot

Pull request overview

Adds a new MSC proposal describing an interoperable client-side convention for bookmarking Matrix room events using global account data, with a per-user index event for ordering and one account-data event per bookmark for metadata.

Changes:

Defines account data event types and schemas for a bookmark index and per-bookmark items.
Specifies client workflows for adding, removing (tombstoning), listing, and syncing bookmarks across devices.
Documents privacy/security considerations and an example bookmark ID generation approach.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

turt2live · 2026-03-24T14:36:13Z

Implementation requirements:

Client (sending)

Client (receiving/rendering)

Added to PR description.

turt2live

Early MSC checklist requirements review - I haven't meaningfully looked at the MSC content.

tulir · 2026-03-24T14:42:12Z

+### Bookmark index event
+
+The bookmark index event maintains the bookmark ID sequence for all active bookmarks along with
+versioning metadata.


What's the benefit of this? Account data is generally synced in its entirety

It lists which bookmarks are active (not deleted) and hints the ordering.

tulir · 2026-03-24T14:45:37Z

+```
+
+Clients must ignore malformed bookmark item events. Clients must also ignore bookmark item events
+where `deleted` is `true`.


What's the benefit of a separate deleted field over simply clearing the content?

Allows undeletion.

Finding all trashed bookmarks will require a linear scan of the entire bookmark set this way. If you really need a wastebin, maybe it would be better to just collect the deleted bookmarks in a separate m.bookmarks.wastebin.index?

True. Undeletion will require some one-time effort.
This is required when someone actually decides to implement undeletion feature. On the contrary, maintaining the wastebin will require effort on every client, whether it implements undeletion or not.

Conversely:

What is the benefit of simply clearing the content?

tulir · 2026-03-24T14:45:56Z

+
+The presence of `room_id`, `event_id`, and `uri` duplicates some information by design. This lets
+clients use the explicit room and event identifiers directly for display, grouping, partitioning,
+or lookup purposes without having to parse URI components out of `uri`.


Why is uri there at all? It doesn't seem like there's any benefit to that over room/event ID. If routing information is expected to be needed, it'd be better to just add a via field and remove uri

The idea is to bookmark the uri.
The room_id, event_id are additional data, for ease of client implementation - like grouping by room.

Could the URI not be built on demand and locally from the other properties in the bookmark structure?

I suppose it could. But using the uri as the main concern will allow natural updates in the future, when the uri schema gets expanded.

I do not feel strongly about keeping room_id and event_id fields though.

I could as well generate it by parsing uri when inserting the bookmark into my client bookmark storage.

Johennes · 2026-03-25T09:22:57Z

+
+The `revision` field allows clients to detect concurrent modifications from other devices. When a
+client receives an updated index via `/sync` with a `revision` higher than the locally known
+value, it should refresh its bookmark list from the server.


Would this not be a relatively rare situation given that the index should only be changed based on user interaction and people tend to not use two devices in parallel?

I am a counter-example. I usually run two devices: mobile phone and desktop client.
I sometimes run a third client in a browser tab.

Right but you probably don't bookmark events in two or more clients at the same time?

I can't promise I won't do it. 😅

Johennes · 2026-03-25T09:33:31Z

+* When creating a bookmark, if a client already knows an existing bookmark item for the same
+  `(room_id, event_id)`, it should reuse that item's `bookmark_id` instead of generating a new
+  one.
+* Clients should make reasonable effort to deduplicate bookmarks for the same `(room_id, event_id)`.


What is the use case for bookmarking the same event twice? The only thing that will differ are bookmark_id, bookmarked_ts and the cached content data.

There is no proper use case. It is a bug, which should be prevented with reasonable effort.

In that case it sounds like we should just prescribe a scheme for generating bookmark IDs that prevents that?

Even if we do, the client will need to do the effort to check for duplicates, in order to prevent clashing with identifiers generated with buggy other clients, buggy older version of the same client, older version of the MSC.
If so, we might as well leave it free to the client implementation discrepancy.

Johennes · 2026-03-25T09:47:44Z

+The ordering of `bookmark_ids` should be treated as the default display ordering hint. Clients may
+sort, group, or partition bookmarks differently when presenting bookmarks to the user.


Given that bookmarks in browsers use a file / folder schema, I wonder if we should add support for this from the start?

If someone is willing to build more features based on this MSC, I see no blockers in the current implementation. Implementations of this MSC should just ignore unknown fields, that might be added by later protocols.

hazre · 2026-03-27T13:50:17Z

+### Bookmark ID
+
+The `bookmark_id` identifies a bookmark item and forms the suffix of the corresponding account
+data event type. This MSC does not require any particular bookmark ID generation method.


I like this proposal as it can be used as message level read indicators (not to be confused with read receipts) and expanded more.

I'm not super versed on the matrix spec stuff but not having a standardized bookmark ID generation method seems counterintuitive to being a spec to me. If it's not the same across all clients, then you can't really use between different clients unless they share the same bookmark ID generation.

The bookmark_id is just an opaque string to be used as an item in the index.
Standardizing on the id generation algorithm could result in an expectation, that there is some semantic encoded in the identifier, while it should not be.
Clients would need to be resilient to out-of-spec identifiers anyway, due to bugs in implementation in the wild. We can standardize on such behavior then.

Following list is perfectly fine, and should be handled by any client without additional effort:

"bookmark_ids": [ "bmk_1a2b3c4d", "bmk_5e6f7788", "chr_shahphie3K", "9836b821-da3a-4599-be1f-76e390ae3f31", "54c30437-8775-4f44-bc60-8865702594ea", "chr_Hiemu5ahKo", "69JH5EWWFKTDQCT5N5D9LAPEMQNV7HMNUA7RSFJX2VHEelmt" ]

thetayloredman · 2026-04-01T04:34:09Z

This may also benefit from the work towards encrypting account data introduced in #4441. The primitives for encrypting account data could potentially be factored out into a separate proposal?

smokku · 2026-04-01T08:48:47Z

I've removed the details of reference implementation bookmark_id generation algorithm, as it is not required and might create confusion.

turt2live changed the title ~~MSCXXXX: Message bookmarks via account data~~ MSC4438: Message bookmarks via account data Mar 24, 2026

turt2live reviewed Mar 24, 2026

View reviewed changes

Comment thread proposals/4438-message-bookmarks.md

smokku force-pushed the message-bookmarks branch from 30a3a09 to 037fa44 Compare March 24, 2026 14:19

smokku marked this pull request as ready for review March 24, 2026 14:20

Copilot AI review requested due to automatic review settings March 24, 2026 14:20

Copilot started reviewing on behalf of smokku March 24, 2026 14:20 View session

Copilot AI reviewed Mar 24, 2026

View reviewed changes

Comment thread proposals/4438-message-bookmarks.md Outdated

Comment thread proposals/4438-message-bookmarks.md Outdated

Comment thread proposals/4438-message-bookmarks.md Outdated

Comment thread proposals/4438-message-bookmarks.md

Comment thread proposals/4438-message-bookmarks.md Outdated

turt2live reviewed Mar 24, 2026

View reviewed changes

turt2live requested changes Mar 24, 2026

View reviewed changes

Comment thread proposals/4438-message-bookmarks.md

turt2live added proposal A matrix spec change proposal client-server Client-Server API kind:feature MSC for not-core and not-maintenance stuff needs-implementation This MSC does not have a qualifying implementation for the SCT to review. The MSC cannot enter FCP. labels Mar 24, 2026

tulir reviewed Mar 24, 2026

View reviewed changes

smokku force-pushed the message-bookmarks branch 2 times, most recently from 2138484 to b518b9a Compare March 24, 2026 14:57

smokku requested a review from turt2live March 24, 2026 14:57

Johennes reviewed Mar 25, 2026

View reviewed changes

Comment thread proposals/4438-message-bookmarks.md Outdated

Johennes reviewed Mar 25, 2026

View reviewed changes

Comment thread proposals/4438-message-bookmarks.md

Johennes reviewed Mar 25, 2026

View reviewed changes

Comment thread proposals/4438-message-bookmarks.md Outdated

Johennes reviewed Mar 25, 2026

View reviewed changes

hazre reviewed Mar 27, 2026

View reviewed changes

This was referenced Mar 30, 2026

feat: Message Bookmarks (MSC4438) SableClient/Sable#600

Open

feat(bookmarks): add message bookmarks (MSC4438) SableClient/Sable#601

Draft

thetayloredman mentioned this pull request Apr 1, 2026

MSC4441: Encrypted User Profile Annotations via Account Data #4441

Open

smokku force-pushed the message-bookmarks branch from b518b9a to 98ee0d8 Compare April 1, 2026 08:35

MSC4438: Message bookmarks via account data

8f1810b

smokku force-pushed the message-bookmarks branch from 98ee0d8 to 8f1810b Compare April 1, 2026 08:47

Just-Insane mentioned this pull request Apr 15, 2026

feat(bookmarks): add message bookmarks (MSC4438) Just-Insane/Sable#18

Closed

11 tasks

		The ordering of `bookmark_ids` should be treated as the default display ordering hint. Clients may
		sort, group, or partition bookmarks differently when presenting bookmarks to the user.

Conversation

smokku commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

turt2live left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

smokku Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Johennes Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thetayloredman commented Apr 1, 2026

Uh oh!

smokku commented Apr 1, 2026

Uh oh!

smokku commented Mar 24, 2026 •

edited

Loading

smokku Mar 24, 2026 •

edited

Loading

Johennes Mar 25, 2026 •

edited

Loading