Crystals

A crystal is a fact established once, never re-derived. It lives in a CLAUDE.md file and loads at session start. Crystals prevent your AI from rediscovering what you already know.

When to create a crystal

Create a crystal when you have established a fact through hard work and do not want to re-establish it.

Signs that something should become a crystal:

• You have explained it to your AI more than twice
• It took significant effort to figure out
• It constrains decisions in multiple sessions
• Getting it wrong wastes substantial time

Do not crystallise everything. Crystals add cognitive load to your AI's context window. Only crystallise facts that genuinely need to persist. A good filter: keep what surprised you. If the palace as it stands would already have predicted the fact, fold it into the crystal that covers it instead of adding a new one.

The three tiers

Crystals have confidence levels. Use the tier markers to signal stability.

Tier	Symbol	Meaning
Confirmed	◆	Foundational fact. Treated as ground truth. Rarely changes, and when it does, the change is worth noting explicitly.
Contextual	◈	True now, but tied to the current phase, sprint, or situation. Reviewed periodically. Often carries a valid_until.
Exploratory	◇	Hypothesis or early finding. Not yet confirmed. Promoted once validated, or retired with a note.

Promotion and demotion

Movement between tiers is explicit, in both directions. Never silently upgrade a crystal: note what changed.

• ◇ → ◈ when the hypothesis is confirmed once, or corroborated by evidence
• ◈ → ◆ when the fact holds across multiple sessions and contexts and is no longer phase-bound

◇ Framing: plain-language labels beat technical ones
→ Promoted to ◈ 2026-04-15: confirmed by 3 user interviews

Demotion also happens, and it is a healthy part of the lifecycle, not a failure mode. If a ◆ crystal turns out to be false or phase-dependent, move it down a tier and add a note on why. Do not delete it silently: strike it through and record the reason, the same way you would compost it. The history matters. It records how your understanding evolved.

Expiry with valid_until

◈ and ◇ crystals can carry an optional valid_until field: a specific date, a quarter, or an event.

◈ Current sprint: onboarding redesign
valid_until: 2026-05-30

◇ Edge functions may be faster than serverless for auth
valid_until: after-spike

When the date passes, the crystal is flagged for review, never silently dropped. Palaces that run a morning check-in surface crystals whose valid_until falls within the next 7 days. This is the built-in decay mechanism: facts do not go stale silently.

Pinning

A pinned crystal is protected from agent-driven review and cleanup. It will never be flagged as stale or proposed for retirement, no matter how long since it was last referenced.

◆ Privacy stance: local-first, no cloud
pinned: true

Or inline: ◆ [name]: [value] · pinned

Any tier can be pinned. Use it for foundational truths, slow-moving commitments where recency is not the signal, and anything you would be annoyed to find flagged in a routine health check. Pinning only guards against agent-initiated cleanup; you can still update or retire a pinned crystal by hand. For a time-boxed pin, add pinned_until: [date]; normal review resumes after that date.

The full lifecycle

Seeded (◇) → Contextual (◈) → Confirmed (◆) → Pinned → Composted

Composting is retirement, and it can happen at any tier. Strike the crystal through and add the reason and the date:

~~◈ Working approach: daily 9am check-in~~
retired: 2026-06-01, sprint ended, back to async

Retired crystals tell the story of how you learned. Compost, do not erase.

Writing good crystals

Good crystals are:

• Specific: Not "use good naming conventions" but "function names are verbNoun, e.g. getUserProfile"
• Actionable: Your AI can apply the crystal immediately
• Bounded: One fact per crystal, not a paragraph of context
• Dated: Note when a crystal is promoted, demoted, or retired

Bad crystals are vague, compound, or redundant with information your AI already has.

Examples

Good crystals:

◆ Repo uses pnpm, not npm
◆ All API routes return { data, error } shape
◈ User auth state lives in Zustand, not context
valid_until: after-state-refactor
◇ Edge functions may be faster than serverless for auth
valid_until: after-spike

Bad crystals:

◆ Write clean code                              ← too vague
◆ Use TypeScript and make sure types are good   ← compound, vague
◆ Don't use var                                 ← redundant (AI knows this)

Crystal placement in CLAUDE.md

Crystals live in a block near the top of a CLAUDE.md file, after identity context but before detailed instructions. Palace-wide facts (identity, stack, values) go in the root CLAUDE.md; room-specific facts go in that room's CLAUDE.md. A crystal relevant in more than one context can live in both places.

# Dev Room

## Identity
This is the development workspace for project-x.

## Crystals
◆ Monorepo: apps/web, apps/api, packages/shared
◆ Deploy target: Vercel (web), Railway (api)
◆ Auth: Clerk, not custom
◈ State: Zustand for client, tRPC for server
valid_until: after-state-refactor
◇ Consider Drizzle over Prisma for edge compat
valid_until: after-spike

## Workflow
...

When a crystal is established in conversation, write it to the file immediately. Do not leave it in chat.

Crystal hygiene

The three tiers do not age at the same rate, so do not review them on one clock.

• ◇ Exploratory turns over fast. Hypotheses are meant to resolve quickly, promoted or retired. A ◇ that has sat untouched for a long time is the normal case to revisit.
• ◈ Contextual turns over on the rhythm of the sprint, contract, or phase it is bound to.
• ◆ Confirmed almost never moves. A ◆ going stale is rare enough that when it happens, it is a real signal, not routine churn.

Pick your own intervals; the principle is only that they differ. At each review, ask:

• Is this still true?
• Did this ever get used?
• Should this be promoted, demoted, or composted?

Compost crystals that are no longer relevant rather than hard-deleting them: strike through, note the reason and the date. A cluttered crystal block slows your AI's comprehension. Ten sharp crystals beat fifty vague ones.

TIP

When a crystal becomes part of your muscle memory and you no longer need your AI to know it, compost it. Crystals are for bridging the gap between your knowledge and your AI's starting state.

Crystals vs the garden

Crystals are memory. The garden is inquiry.

A crystal answers "what did I establish about X?": a settled fact your AI acts on immediately. A garden plant asks "what is X, and what might it become?": an open question you tend across sessions.

Crystals go in CLAUDE.md and load at session start. Plants live in the garden and grow over time. The two connect: a plant that matures can graduate into a crystal. That seed-to-crystal path is how open questions become settled facts.

See The Garden for how plants grow.