Core Concepts
loci organises AI memory around six core concepts. Each builds on the others. Learn them in order.
Rooms
A room is a persistent context workspace. Not a single conversation: a context you return to over time.
When you work on a project, you accumulate understanding: decisions made, approaches tried, terminology established. A room holds this accumulated context. Every conversation you tag to a room becomes part of its memory. When you return to the room, that context is available again.
Rooms have names like dev, research, design, hatchery. You decide what rooms to create and which conversations belong where.
Example: You have a dev room for coding work. Over three months, you have 47 conversations tagged to it. When you open a new session in the dev room, your AI can access the patterns, decisions, and context from all 47 conversations.
See Rooms for implementation details.
Crystals
A crystal is a fact established once, never re-derived. It lives in a CLAUDE.md file at the root of a room.
Every time you restart a session, your AI starts fresh. Crystals prevent this. A crystal captures a hard-won piece of context: a decision, a constraint, a piece of knowledge: so your AI reads it immediately instead of rediscovering it through conversation.
Crystals have three tiers: ◆ confirmed (stable), ◈ working (useful but may evolve), ◇ provisional (hypothesis being tested).
Example: After three sessions debugging a deployment issue, you establish that your CI pipeline requires NODE_ENV=production during build. This becomes a ◆ confirmed crystal. You never re-derive it.
See Crystals for the full system.
Garden
The garden is where open questions grow. Not tasks: genuine inquiries that develop across sessions.
Memory is retrieval. The garden is generative. Memory asks "what did I say about X?" The garden asks "what is X, and what might it become?"
A garden plant is an inquiry you tend over time. You add observations, connections, contradictions. Plants grow into insights, papers, products: or they wither and compost into other plants.
Example: You plant "what makes privacy infrastructure different from privacy tools?" Over six sessions, you add observations from user research, technical constraints, market analysis. The plant grows into a thesis that shapes your product strategy.
See The Garden for cultivation practices.
Loci
A locus (plural: loci) is a crystallised insight. A named .locus file. Permanent, referenceable.
Crystals are facts for your AI to read. Loci are insights for you and your AI to navigate by. A locus marks a significant point in your thinking: a decision, a breakthrough, a commitment.
Loci are addressable. You can link to them from other documents. They form a navigable map of your intellectual territory.
Example: After a breakthrough session, you create privacy-paradox.locus. It captures the insight that privacy tools that advertise themselves as privacy tools undermine their own purpose. This locus becomes a reference point across multiple rooms.
Soul Layer
The soul layer is the CLAUDE.md briefing file that your AI reads before speaking.
Every room has a CLAUDE.md at its root. This file contains crystals, context, and instructions. When you start a session in a room, your AI loads this file first. The soul layer shapes how your AI thinks and responds.
The soul layer is not a prompt template. It is accumulated context, compressed and structured for rapid loading.
Example: Your research room's CLAUDE.md contains 15 crystals about your research methodology, 3 active garden plants, and instructions about citation format. Every session in this room starts with this context loaded.
Handovers
A handover is a session-end document. It bridges context across sessions.
At the end of a session, you (or your AI) write a handover that captures: what was accomplished, what decisions were made, what questions remain. The next session reads the handover first.
Handovers prevent context loss at session boundaries. They are the connective tissue between sessions.
Example: At the end of a coding session, you write a handover: "Implemented auth flow. Decision: JWT in httpOnly cookie. Open question: refresh token rotation strategy." The next session picks up exactly where you left off.
How concepts relate
┌─────────────────────────────────────────┐
│ Room │
│ ┌─────────────┐ ┌─────────────────┐ │
│ │ Soul Layer │ │ Garden │ │
│ │ (CLAUDE.md) │ │ (open plants) │ │
│ │ ◆ ◈ ◇ │ │ │ │
│ │ crystals │ │ │ │
│ └─────────────┘ └─────────────────┘ │
│ │
│ ┌─────────────────────────────────┐ │
│ │ Loci │ │
│ │ (crystallised insights) │ │
│ └─────────────────────────────────┘ │
│ │
│ Handovers ←→ Session ←→ Handovers │
└─────────────────────────────────────────┘Rooms contain everything. Crystals live in the soul layer. Plants grow in the garden. Loci mark significant points. Handovers bridge sessions.
Start with rooms. Add crystals as you establish facts. Plant questions in the garden. Create loci when insights crystallise. Write handovers at session end.