Core Concepts

loci is a plain-text substrate for working with AI: templates and processes that decide how memory, context, and trust work, whichever AI runs them. Everything described here is markdown in a folder you own. No cloud, no accounts, no lock-in.

The substrate ships as seven feature sets: Persistent Memory, Context Architecture, Identity & Personas, The Garden, Continuity & Synthesis, Trust & Governance, and Interop & Evolution. This page walks through the concepts behind them, in the order you will meet them.

The palace

Your whole setup is called a palace. It is a folder of markdown files:

• CLAUDE.md at the root: palace-wide facts and rules, read at every session start
• soul/SOUL.md: your AI's character file
• rooms/: one folder per working context
• Layers you add as you grow: a garden, personas, handovers

You create a palace by copying the templates/ kit and filling in the blanks, by hand or with your AI walking you through the setup interview. Any file-aware AI can run one. The kit also ships filled persona examples (rename them and make them yours) and skill templates: repeatable procedures such as session close, insight consolidation, and quarantine.

Two layouts are supported: rooms at the palace root, or everything inside a _palace/ subfolder. The desktop app and the CLI recognise both.

Rooms

A room is a persistent context workspace. Not a single conversation: a context you return to over time.

Each room is a folder with its own CLAUDE.md. That file holds the room's ground truth (facts you never want re-derived), behaviour rules (how your AI should act there), and active projects. You and your AI fill it in as you work.

Rooms have names like dev, research, design. You decide what rooms to create and what belongs in each.

Rooms sit inside a retrieval hierarchy (L0 to L3). Soul identity (L0) and active context (L1) always load. Room context (L2) loads when you enter the room. Deep context (L3), such as old handovers or garden history, loads only on explicit request. The right context arrives at the right time, without loading everything at once.

Example: You have a dev room. Its CLAUDE.md records the stack, the deployment constraints, and a rule to plan before changing existing work. Every session in that room starts with those facts loaded instead of rediscovered.

See Rooms for implementation details.

Crystals

A crystal is a fact established once, never re-derived. Crystals live in CLAUDE.md files: the palace root for palace-wide facts, a room's CLAUDE.md for room-specific ones.

Crystals have three tiers:

Tier	Symbol	Meaning
Confirmed	◆	Foundational. Treated as ground truth. Rarely changes.
Contextual	◈	True now, tied to the current phase. Carries an optional valid_until date or event.
Exploratory	◇	A hypothesis being tested. Promote or retire it explicitly.

The lifecycle runs from seeded (◇) to contextual (◈) to confirmed (◆). Promotion is explicit: note what changed and why. Demotion happens too. A crystal can be pinned (protected from automated cleanup) or composted (retired with a note; the history matters). When a valid_until date approaches, the crystal is flagged for review instead of going stale silently.

Example: After three sessions debugging a deployment issue, you establish that your CI pipeline requires NODE_ENV=production during build. That becomes a ◆ Confirmed crystal. You never re-derive it.

See Crystals for the full system.

The Garden

The garden is where ideas are cultivated, not just stored. One file per idea.

A garden plant is an inquiry you tend over time. You add observations, connections, contradictions. A periodic health pass surfaces plants that have gone stale and plants that are ready. When a plant matures into an established fact, it graduates into a crystal.

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.

Soul and personas

The soul file (soul/SOUL.md) is your AI's character: who it is, how it works with you, what it has learned about the collaboration. A living document, updated when something shifts. It reads at session start, before any work.

Three companions to it:

• Peer card: a human-authored card about you, at the palace root. It is who you say you are, not an auto-extracted profile. The first thing a new AI reads.
• Personas: named specialist characters with their own files, for the domains you carve out (design, security review, whatever you need).
• Friends: curated soul files about the people you work with, not about you. One file per peer in friends/, filled in from your actual working history with them. See Friends.

Together these make the companion someone, not a fresh instance each session.

Handovers and synthesis

A handover is a session-end delta. At the close of a session, your AI writes what was done, what was decided, and what is open to soul/handovers/YYYY-MM-DD.md. The next session reads the latest handover first and starts warm.

On top of handovers sits a synthesis pass: a periodic process that reads recent history and proposes consolidations. It proposes; it never auto-applies. Scheduled-task templates cover the recurring housekeeping, so upkeep does not depend on anyone remembering it.

Example: "Implemented auth flow. Decision: JWT in httpOnly cookie. Open: refresh token rotation strategy." The next session picks up exactly there.

Trust and governance

Nothing leaves or changes without you. Four mechanisms:

• The Gate: a named human-review checkpoint (named after you) before anything ships, sends, or becomes irreversible.
• Foreign-process quarantine: anything that did not originate inside the palace is treated as data first. Structure-only access by default; contents only on explicit approval.
• Confirm against disk: the filesystem is ground truth. The AI checks files before asserting state or absence, instead of trusting its own recollection.
• Structural audit: a read-only pass that checks the palace's shape and reports, without changing anything.

Interop and evolution

A palace works across tools and federates to no one. It reads memory left by other tools by structure only, and exports typed artifacts. MCP support is planned but deferred: see the FAQ for status. An eval framework lets you measure the substrate's growth over time instead of guessing at it.

Three ways to run it

The substrate is the same underneath all three.

Run mode	What it is
Plain markdown	The door. Copy the templates/ kit, point any file-aware AI at your CLAUDE.md. No build.
Desktop app	The cockpit (Tauri, v0.6.0-beta). A native Operations dashboard, one tab per instrument your palace generates for itself, and a tool shelf that records gate verdicts on foreign tooling.
CLI	loci (Rust, v0.6.0-beta). Five read-only commands: status, crystals, read, handover, init. No network, no inference.

Keeping a palace current is a concept of its own. The update protocol reads your palace, diffs it against the published methodology version, and offers changes one at a time. You cherry-pick. Nothing is auto-applied.

How concepts relate

palace/
├── CLAUDE.md            palace-wide crystals + rules   (always loads)
├── soul/
│   ├── SOUL.md          character                      (always loads)
│   ├── garden.md        one file per idea               (loads on request)
│   └── handovers/       session deltas                 (latest loads)
└── rooms/
    └── dev/CLAUDE.md    room crystals + rules          (loads on entry)

The palace contains everything. Crystals record facts. The garden grows questions until they graduate into crystals. The soul holds character. Handovers bridge sessions. The Gate and quarantine keep all of it under your control.

Start with one room and a handful of crystals. Add the garden when questions outlive sessions. Add personas when one voice is not enough. The substrate grows with use.