Getting Started: Wizard

For: People working with AI agents, local LLMs, and MCP tools who want structured, persistent memory. Setup time: 20 minutes for full palace configuration. What you need: An LLM endpoint (local Ollama or API key), Chrome, the loci desktop app.

What you get

The Wizard tier extends Scholar with:

Rooms: persistent workspaces that maintain context across sessions
Crystals: pinned facts and decisions your AI can retrieve instantly
The garden: living documents that evolve through collaboration
MCP integration: expose your palace to Claude Code, Cursor, or any MCP client
Session handovers: structured deltas that let new sessions resume where old ones ended
The chronicle: automatic logging of session activity

Requirements

Requirement	Details
LLM endpoint	Ollama (local) or API key (Claude, OpenAI)
Node.js	v18+ for building from source
Chrome	120+ for the extension
Desktop app	Required for palace management

Installation

From source

bash

git clone https://github.com/huximaxi/Loci.git
cd Loci
npm install
npm run build
npm run start

The desktop app launches automatically after build completes.

From Homebrew (macOS)

bash

brew install loci-garden

From installer script

bash

curl -sSL https://loci.garden/install.sh | bash

First run: palace setup

The onboarding wizard walks you through five screens.

Screen 1: Choose your tier

Select Wizard. This unlocks rooms, crystals, garden, and MCP features.

Screen 2: Select your rooms

loci offers five default rooms. Enable the ones relevant to your work:

Room	Purpose
Dev	Code, architecture, debugging sessions
Design	UI/UX discussions, design systems, visual iteration
Research	Literature review, exploration, open questions
Hatchery	Pre-made orchestration and processes
Garden	Living documents, evolving knowledge, long-term threads

You can create custom rooms later.

Screen 3: Configure your LLM

Choose your provider and configure the connection.

For local Ollama:

Provider: local
Endpoint: http://localhost:11434
Model: llama3

For Claude API:

Provider: anthropic
Model: claude-sonnet-4-20250514

API keys are stored in your OS keychain: never in config files.

Screen 4: MCP setup

Toggle which rooms to expose as MCP tools. Copy the generated config snippet for your IDE.

Screen 5: Enter the palace

Setup complete. loci bootstraps ~/.loci/ with your room structure and config.json.

Creating your first room

Open the palace view in the desktop app. Click + New Room in the sidebar.

Enter:

Name: The room identifier (lowercase, no spaces): e.g., dev
Display name: Human-readable label: e.g., "Dev Room"
Description: One-line purpose statement

Click Create. The room appears in your palace floor plan and creates:

~/.loci/rooms/dev/: the room folder
~/.loci/rooms/dev/context.md: the room's living context
~/.loci/rooms/dev/CLAUDE.md: the soul file

Writing your first CLAUDE.md soul file

The soul file tells your AI who it is when operating in this room. It lives at ~/.loci/rooms/{name}/CLAUDE.md.

Here is a real 10-line example for a Dev Room:

markdown

# Dev Room: Soul

You are operating inside the Dev Room of my loci palace.

## Context
- Primary language: TypeScript
- Framework: Next.js 14 with App Router
- Style: Functional, explicit, minimal dependencies
- Tests: Vitest, prefer integration over unit

## Behaviour
- Propose the simplest solution first
- Ask before adding new dependencies
- Reference existing patterns in the codebase

The soul file is loaded automatically when you invoke room context via MCP.

TIP

Keep soul files short. 10-30 lines is ideal. The AI reads this on every context load: verbosity costs tokens.

Planting your first crystal

A crystal is a pinned fact, decision, or reference. Crystals are immutable once created: they represent settled knowledge.

In the desktop app:

Open any room
Click + Crystal in the room toolbar
Enter the crystal content

Example crystal:

markdown

---
id: "crystal-auth-decision"
created: "2026-05-04T10:30:00Z"
room: "dev"
type: "decision"
---

# Auth provider decision

We use Clerk for authentication. Not Firebase Auth, not Auth0, not custom JWT.

Rationale: hosted UI, good DX, reasonable pricing, integrates with Next.js middleware.

Revisit: never (unless Clerk changes pricing dramatically).

Crystals are saved to ~/.loci/rooms/{room}/crystals/{id}.crystal and are queryable via loci_get.

Starting your first session

A session begins when you tell your AI to load palace context.

In your IDE (Claude Code, Cursor, or any MCP client):

@loci room_dev

This loads:

The Dev Room soul file (CLAUDE.md)
The room's living context (context.md)
Recent session handovers
Pinned crystals

Your AI now has the full context of your Dev Room without you re-explaining anything.

The garden

The garden is where living documents grow. Unlike crystals (immutable) or session logs (append-only), garden plants are collaborative, evolving artifacts.

Creating your first plant

Open the Garden room (or any room with garden enabled)
Click + Plant
Enter:
- Name: Identifier slug: e.g., api-design-principles
- Title: Human-readable: e.g., "API Design Principles"
- Initial content: Starting text

Plants are saved to ~/.loci/garden/{slug}.plant as Markdown with YAML frontmatter.

How plants differ from crystals

Aspect	Crystal	Plant
Mutability	Immutable once created	Evolves over time
Purpose	Settled decisions, fixed facts	Living documents, open questions
Versioning	Single version	Full edit history
Retrieval	`loci_get {id}`	`loci_garden {slug}`

MCP setup

loci exposes rooms and tools via the Model Context Protocol. Configure your IDE to connect.

Claude Code

Add to ~/.claude/settings.json:

json

{
  "mcpServers": {
    "loci": {
      "command": "loci",
      "args": ["mcp", "--port", "3721"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

json

{
  "mcpServers": {
    "loci": {
      "url": "http://localhost:3721/mcp"
    }
  }
}

Zed

Add to your Zed settings:

json

{
  "language_models": {
    "mcp_servers": {
      "loci": {
        "url": "http://localhost:3721/mcp"
      }
    }
  }
}

Restart your IDE after configuration. Verify tools appear in the MCP tool list.

Using loci tools from your IDE

Once connected, these tools are available to your AI:

Tool	What it does
`room_dev`	Load Dev Room context (soul + context.md + crystals)
`room_design`	Load Design Room context
`room_research`	Load Research Room context
`room_hatchery`	Load Hatchery context
`room_garden`	Load Garden context
`loci_search`	Full-text search across all indexed content
`loci_get <id>`	Retrieve a specific crystal or locus by ID
`loci_garden <slug>`	Retrieve a garden plant

Example invocations

# Load room context at session start
@loci room_dev

# Search for past discussions
@loci loci_search "authentication flow"

# Retrieve a specific decision
@loci loci_get auth-decision

Session handover

When a productive session ends, write a handover. This is a structured delta that tells the next session what happened.

Writing a handover

In the desktop app: Room → Session → Write Handover.

Or create manually at ~/.loci/rooms/{room}/handovers/{date}.md:

markdown

# Session handover: 2026-05-04

## State
- Implemented auth middleware
- Tests passing
- Ready for PR review

## Decisions made
- Using Clerk (see crystal: auth-decision)
- Middleware pattern from Next.js docs

## Open threads
- Need to add rate limiting
- Session expiry policy undefined

## Next session should
- Start with rate limiting implementation
- Review session expiry options

Using a handover

At the start of your next session:

@loci room_dev

The most recent handover is loaded automatically as part of room context.

The chronicle

loci maintains an automatic log of session activity in ~/.loci/chronicle/.

Each entry records:

Session start/end timestamps
Room context loaded
Tools invoked
Crystals created or referenced
Handover written (if any)

The chronicle is append-only and not editable through the UI. It serves as an audit trail and memory backup.

WARNING

The chronicle can grow large over time. Run loci chronicle prune --older-than 90d periodically to archive old entries.

config.json reference

Full configuration lives at ~/.loci/config.json:

json

{
  "version": "0.1.0",
  "tier": "wizard",
  "index": {
    "auto_sync": true,
    "sync_interval": "5m",
    "full_text": true,
    "semantic": false
  },
  "llm": {
    "provider": "local",
    "endpoint": "http://localhost:11434",
    "model": "llama3"
  },
  "mcp": {
    "expose_rooms": ["dev", "research", "design"],
    "port": 3721
  },
  "garden": {
    "enabled": true,
    "auto_version": true
  },
  "chronicle": {
    "enabled": true,
    "retention_days": 90
  }
}

TIP

API keys are stored in your OS keychain, not in config.json. The desktop app manages keychain access.

Next steps

Read the rooms reference for detailed room configuration
Explore crystal documentation for effective knowledge capture
See the MCP API reference for full tool documentation
For CLI-native workflows, consider LLMAGE tier

Getting Started: Wizard ​

What you get ​

Requirements ​

Installation ​

From source ​

From Homebrew (macOS) ​

From installer script ​

First run: palace setup ​

Screen 1: Choose your tier ​

Screen 2: Select your rooms ​

Screen 3: Configure your LLM ​

Screen 4: MCP setup ​

Screen 5: Enter the palace ​

Creating your first room ​

Writing your first CLAUDE.md soul file ​

Planting your first crystal ​

Starting your first session ​

The garden ​

Creating your first plant ​

How plants differ from crystals ​

MCP setup ​

Claude Code ​

Cursor ​

Zed ​

Using loci tools from your IDE ​

Example invocations ​

Session handover ​

Writing a handover ​

Using a handover ​

The chronicle ​

config.json reference ​

Next steps ​

Getting Started: Wizard

What you get

Requirements

Installation

From source

From Homebrew (macOS)

From installer script

First run: palace setup

Screen 1: Choose your tier

Screen 2: Select your rooms

Screen 3: Configure your LLM

Screen 4: MCP setup

Screen 5: Enter the palace

Creating your first room

Writing your first CLAUDE.md soul file

Planting your first crystal

Starting your first session

The garden

Creating your first plant

How plants differ from crystals

MCP setup

Claude Code

Cursor

Zed

Using loci tools from your IDE

Example invocations

Session handover

Writing a handover

Using a handover

The chronicle

config.json reference

Next steps