authoring-service/docs/hidden-memory-architecture.md

Hidden Memory Architecture

The hidden ecosystem has one friendly source of truth:

• assets/content/hidden-details.json in org_web

The live site still consumes generated constants in:

• assets/scripts/hidden-details.js in org_web

Canonical Content

The old type field is now treated as the runtime delivery kind. It answers: where does this need to go in the existing JavaScript arrays?

The newer contentClass field answers: what is this thing conceptually?

Use these classes:

• fragment: tiny reusable language, such as tooltips, quotes, whispers, loading lines, and small dialogue.
• memory: a richer emotional moment or observation that can stand as an observatory node.
• story material: dialogue or sequence material that is primarily useful inside a story route.
• interaction: a trigger, route, keyboard secret, search response, seasonal event, or play-system behavior.
• lore: world material such as dreams, terminal logs, guestbook entries, or hidden archive objects.
• system layer: structural observatory material, such as the layer guide.

Stories

Stories are curated routes. They should reference entries by id through nodes.

Do not duplicate paragraphs inside a story when an existing fragment or memory can be referenced. A story gives order, title, tone, unlock conditions, and emotional shape.

Surfaces

The surfaces field says where an entry is reusable: tooltip, quote, story, observatory, search, keyboard, play, dream, temporal, and similar surfaces.

A tooltip fragment can appear in the footer without becoming a full story node. A memory can appear in the observatory and in a story without being forced into a rotating quote. An interaction can trigger a hidden route without pretending to be a narrative scene.

Observatory Roles

Use observatoryRole to keep rendering calm:

• ambient: small lights and flavor, usually fragments.
• node: substantial emotional points, usually memories or story material.
• event: triggered behavior, routes, search, keyboard, seasonal, and play content.
• guide: layer/system material.

The observatory should render stories as the main territories, then reveal entries inside them. Zoomed-out views should favor routes and clusters; detailed views can show individual nodes, ambient fragments, and triggered events.

Examples

lima left this page a little steadier than she found it.

• Class: fragment
• Runtime kind: hidden tooltip
• Surfaces: tooltip
• Observatory role: ambient

July 2022, on the way to uni induction, lima pops into my life

• Class: memory
• Runtime kind: journal entry
• Surfaces: story, observatory
• Observatory role: node

search query "lima" opens a hidden route

• Class: interaction
• Runtime kind: search route
• Surfaces: search, hidden route
• Observatory role: event

The story of love between two souls

• Class: story record, not an entry class
• References: ordered entry ids in nodes
• Purpose: emotional route, not duplicated content

Authoring Rule

Write the smallest canonical thing that is emotionally honest.

If it is one line, make it a fragment. If it is a moment with weight, make it a memory. If it happens because of a trigger, make it an interaction. If it is a route through existing things, make it a story.