NIP-08: Handling Mentions
Before rich references, mentions needed a shared trick
NIP-08 belongs to an earlier Nostr moment. Clients needed a way to put profile and event mentions inside a short text note without inventing a different markup language in every app. The chosen trick was simple: replace the visible mention in content with #[index], then store the actual referenced public key or event ID in the matching tag.
That gave clients a portable way to render mentions. A note could say hello to a person or point to another event, while the stable identifier lived in a p or e tag. A receiving client could display a profile name, link to an event or leave the raw text alone if the index was invalid.
The problem is that the trick was narrow and awkward. It belonged mostly to kind 1 text notes, it made raw content hard to read, and it introduced escaping questions when someone wanted to write about the literal #[0] pattern. NIP-27 later replaced the approach with inline NIP-21 references that can work across readable event types.
Indexed placeholders tied to tags
The standard defines how a client treats inline mentions inside text_note content. When the composer mentions a profile or event, the client puts a tag in the event's tags array. The body text then includes #[0], #[1] and so on, where the number points at the matching tag index.
For a profile mention, that tag is a p tag. For an event mention, it is an e tag. On display, a client can replace the placeholder with a richer human-readable label. If the placeholder index does not match a p or e tag, the text remains normal text instead of turning into a broken link.
That invalid-index behavior matters more than it sounds. It protects raw notes and discussions about the syntax itself. GitHub issue #319 shows the edge clearly: if someone writes a note explaining #[0], the client needs a way not to treat every occurrence as a live mention.
A standard preserved because old notes still exist
The visible file was migrated in May 2022, finalized in November 2022 and then refined through early 2023. Shafemtol clarified how non-matching indexes behave. Arthur Franca added alternative mention-handling work in March 2023. A few days later, fiatjaf's NIP-27 refactor moved the ecosystem away from NIP-08 as the recommended path.
That is why the current README strikes through NIP-08 and marks it unrecommended: deprecated in favor of NIP-27. The final status is still useful. It means older content and older clients can be understood. It does not mean new products need to keep writing fresh notes in the old format.
This distinction is the whole story of NIP-08. It is not a failed idea so much as an early compatibility bridge that was outgrown once Nostr needed references across long-form articles, text notes and other readable events.
Read it, render it, avoid building new UX around it
Client authors still need to understand NIP-08 because old notes can contain #[index] placeholders. A user-facing client that ignores the standard may display confusing raw fragments instead of names and linked events. A migration-aware client can render legacy mentions while producing newer references through NIP-27.
NIP-27 changes the mental model. Instead of replacing content with tag indexes, it asks clients to place NIP-21 codes such as nostr:nprofile... or nostr:nevent... inside readable content. That is easier for humans to inspect, easier to copy between contexts and less tied to one event kind.
For Crays, NIP-08 belongs in the archive as a compatibility chapter. It explains why older notes look strange, why some clients still carry parsing code and why the modern reference story points people to NIP-21 and NIP-27.
The raw note can stop meaning what it says
The main weakness is that the content text and tag list have to be interpreted together. Raw content alone is not the full sentence. That makes debugging, quoting, archiving and cross-client rendering harder than it needs to be.
The second weakness is scope. Nostr quickly became more than short notes. Articles, comments, highlights and other text-bearing events need references too. NIP-08's narrow kind 1 mention approach could not carry that wider job cleanly.
Read NIP-08 in the wild
NIP-08 belongs to the early moment when Nostr clients needed a readable way to mention people and events inside text. The important part is not a prettier link. It is preserving the connection between visible words and the key or event they reference.
Mention handling breaks trust quietly. If a client displays one name while the tag points somewhere else, or if a quoted event cannot be resolved, the social surface starts lying. Use this NIP to understand old mention behavior, then compare it with newer reference patterns.
What changes when you actually use it
For you, NIP-08: Handling Mentions is felt when an app either behaves predictably or suddenly loses context. The visible symptom may be a missing reply, a broken link, a strange reaction count, an empty result or a relay error that looks like the whole network failed. The official terms unrecommended, text_note, .tags, p, .content, e are where that visible behavior begins, so the source is not background material; it is the place where the product promise gets its limits.
What changes for builders and operators
For builders, NIP-08: Handling Mentions is compatibility discipline. Implement unrecommended, text_note, .tags, p, .content, e against more than one relay and more than one library, then test malformed, missing and duplicated data. Core standards fail most painfully when the happy path looks fine and the second client exposes the shortcut.
What the official file makes concrete
Inspect unrecommended, text_note, .tags, p, .content, e because these are the pieces most likely to surface as product behavior. Read it beside NIP-27 before treating it as isolated.
NIP-08: Handling Mentions is a shared contract between independent software. The smallest field can become user-visible when two clients disagree about it.
Where it breaks
The failure mode in NIP-08: Handling Mentions is often indirect. Nobody complains about unrecommended, text_note, .tags, p, .content, e; they complain that the feed is wrong, the reply vanished or the relay behaved strangely. Use the official file to diagnose the hidden cause instead of patching only the visual symptom.
Where this appears outside the markdown
In the ecosystem, NIP-08: Handling Mentions is not something most people choose directly. It is the invisible grammar behind clients, relays, crawlers, search tools and archives. When a product team treats unrecommended, text_note, .tags, p, .content, e as implementation detail only, the mistake eventually reaches the surface as missing history, bad threading or state that cannot be reconstructed after a client switch.
The nearby-standard trap
The nearby-standard trap in NIP-08: Handling Mentions is assuming the base layer solves the higher-level feature. This NIP may define the common grammar, but publishing, wallets, moderation, media or groups still need their own constraints. Read NIP-27 to see where the base contract ends and the product-specific promise begins.
Language that keeps the feature honest
Good product copy for NIP-08: Handling Mentions does not say "the protocol handles it" and move on. It explains the visible consequence: what was sent, what was accepted, what was rejected, what is still loading and what another relay or client may show differently.
What this page does not promise
NIP-08: Handling Mentions does not promise a finished social product. It gives software a shared grammar. Feed design, moderation, ranking, notifications, storage duration and recovery remain separate product decisions. That distinction matters because a client can be technically compatible and still give you a weak experience if it hides relay errors, drops context or treats optional fields as if every app understood them.
Read it as a field test
Start NIP-08: Handling Mentions with the visible product symptom, then trace it back to unrecommended, text_note, .tags, p, .content, e. That order keeps the article grounded: you see why the field exists, which relay or client behavior depends on it, and where adjacent standards change the story. A core NIP is strong only when it explains both the normal path and the awkward edge case.
Where the standard earns trust
The source links give you places to test the interpretation in public: NIP-27 Text Note References, NIP-27 mirror, Issue #319: literal #[0] problem, NIP-21 nostr: URI scheme. Use those links to move from the spec to live libraries, mirrors, pull requests, guides or products.
Official NIP-08 source is the anchor for exact wording, and NIP-08 commit history shows how that wording moved over time. The strongest secondary clues here are NIP-27 Text Note References, NIP-27 mirror, Issue #319: literal #[0] problem. Treat this evidence chain as part of the article, not as footnotes. A NIP page becomes useful when you can move from claim to source to working behavior without guessing.
Keep the chain visible for NIP-08: Handling Mentions: first the human promise, then unrecommended, text_note, .tags, p, .content, e, then the implementation record, then the real-world failure case. That order keeps NIP-08 useful without turning it into marketing copy or protocol trivia.
Three questions to carry forward
- Can two independent clients read the same
unrecommended,text_note,.tags,pwithout a hidden compatibility rule? - Does the UI explain relay rejection, missing context or state replacement without blaming the whole network?
- Which adjacent standard, especially NIP-27, changes the behavior once the base event leaves the happy path?
What to verify before you rely on it
- Find
unrecommended,text_note,.tags,p,.contentin the official file and check where the UI exposes the same concept. - Read NIP-27 as context before treating NIP-08 as a complete product story.
- Open at least one implementation, mirror, pull request or library source from the source links before trusting that the idea is mature.
- Test the unhappy path: missing relays, stale metadata, invalid signatures, blocked events, expired state, revoked permissions or unavailable media.
- Write the user-facing copy in plain language. If a standard changes authority, privacy, money, moderation or recovery, say that before the click.
Direct sources
Use these sources for NIP-08: Handling Mentions in that order: Official NIP-08 source for the current wording; NIP-08 commit history for the change record; NIP-27 Text Note References, NIP-27 mirror, Issue #319: literal #[0] problem for public context. The article gives you the consequence in plain language, but the source trail is where exact fields, status notes, unresolved debates and implementation proof stay checkable.
