Rooms & Loci

The two core concepts in loci. Worth getting right.

What is a room?

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

You choose which room a conversation belongs to. Dev, Design, Research, Hatchery, Garden: each room accumulates context across sessions. When you open a room, you're not starting fresh: you're continuing work that already has history, tools, and memory behind it.

What a room is not: a single AI conversation. One conversation might belong to the Dev room because you were debugging. Another belongs to Research because you were exploring a concept. The conversation is the activity. The room is the place it happened.

This matters for AI work because context is everything. When loci exposes a room to your MCP-connected IDE, it serves the room's accumulated context: not just the last conversation, but the distilled memory of everything that happened there.

The rooms

Room	Glow	Purpose
Great Hall	Amber	The central hub. Cross-room navigation.
Dev Room	Blue	Code, debugging, architecture, engineering
Design Room	Warm amber	UX, visual design, component work
Research	Forest green	Exploration, reading, note synthesis
The Hatchery	Earthy	New project incubation. Sandbox. Graduate ideas upward.
The Garden	Teal	Growing ideas. Slow synthesis. Things you return to without urgency.

Room lifecycle

Rooms move through five phases:

1. Create

A new room starts empty. Default rooms (Dev, Design, Research, Hatchery, Garden) are created on first run. Custom rooms are created via the Wizard app or CLI:

bash

loci room create --name "client-acme" --color "#4a90d9" --type dev

This creates ~/.loci/rooms/client-acme/ with an empty context.md and a .room.json.

2. Configure

Add a soul file (CLAUDE.md) to give the room persistent instructions. Configure tools, set default tags, define context crystals. This phase is optional but recommended for rooms you use heavily.

3. Use

Assign conversations to the room. Each assignment updates context.md with a summary. The room accumulates context over time. Search within the room using room:dev query syntax.

4. Crystallise

When a conversation produces something worth keeping permanently, crystallise it into a locus. The locus links back to the source conversation and the room. Over time, a room's loci form its permanent memory.

5. Archive

When a room is no longer active, archive it:

bash

loci room archive client-acme

Archived rooms move to ~/.loci/rooms/.archive/. They remain searchable but no longer appear in the room list or MCP tools.

What is a locus?

In the memory palace technique, a locus (pl. loci) is a specific location in an imagined space: a door, a shelf, a corner. You deposit a memory at a locus. Later, you navigate back to that location to retrieve it.

In loci.garden, a locus is a crystallised insight: something you've decided is worth keeping as a fixed, referenceable node. Not every conversation becomes a locus. You make one deliberately.

A locus is:

A named Markdown file in ~/.loci/loci/
Linked to a source conversation
Tagged, roomed, and timestamped
Referenceable by the MCP server as a tool context
Potentially quoted, cited, or linked from future conversations

The distinction: a conversation is ephemeral (even when indexed). A locus is permanent (until you delete it). Creating a locus is a deliberate act of knowledge curation.

Is every insight a locus?

No. Most conversations don't produce loci. A locus is something you've decided deserves to survive beyond the conversation that produced it: a framework, a decision, a hard-won understanding.

The test: would I want to reference this in a future session? If yes, crystallise it into a locus. If not, it's indexed and searchable, but it's not a locus.

Room + locus together

Dev Room
├── [conversations]
│   ├── "Debugging the auth flow" (2026-04-12)
│   ├── "Reviewing the payment webhook" (2026-04-28)
│   └── "Architecture decision: Kafka vs SQS" (2026-05-02)
└── [loci]
    └── kafka-vs-sqs.locus    ← crystallised from the architecture decision conversation

The locus extracts the decision from the conversation and makes it permanent. Next time you're in the Dev room and your IDE agent asks "what was the message queue decision?", the MCP server serves kafka-vs-sqs.locus directly.

Full Dev Room soul file example

This is a real CLAUDE.md file for a Dev room. Place it at ~/.loci/rooms/dev/CLAUDE.md:

markdown

# Dev Room: Soul File

## Identity
This room handles all code, debugging, architecture, and engineering work.
Local-first. Privacy-native. No external dependencies without explicit approval.

## Context Crystals
| Crystal | Value |
|---------|-------|
| **Stack** | Next.js 14 / TypeScript / Tailwind / SQLite |
| **Deploy** | Vercel (staging) / Hetzner (production) |
| **Monorepo** | Turborepo: apps/web, apps/api, packages/shared |
| **Testing** | Vitest + Playwright |

## Active Projects
| Project | State |
|---------|-------|
| Auth refactor | In progress. OAuth2 flow complete, session handling pending. |
| API v2 | Spec complete. Implementation starts next week. |

## Workflow Rules
1. **Commit separation**: never mix CMS and component changes
2. **Verify before done**: run tests, check types, lint
3. **No laziness**: fix root causes, not symptoms

## Garden (growing ideas)
| Plant | What | State |
|-------|------|-------|
| Edge caching | Investigating Cloudflare Workers KV | Research |
| Passwordless auth | WebAuthn + passkeys | Blocked on iOS support |

## Linked Loci
- [[kafka-vs-sqs]]: message queue decision
- [[auth-flow-v2]]: authentication architecture
- [[error-handling-patterns]]: error handling conventions

TIP

The MCP server serves this file as part of room_dev tool context. Your IDE agent sees this on every Dev room query.

`.room.json` schema

Every room has a .room.json file defining its metadata.

Field	Type	Required	Description
`id`	string	Yes	Unique identifier (slug format, e.g., `dev`, `client-acme`)
`name`	string	Yes	Display name (e.g., "Dev Room", "Client: Acme")
`type`	enum	Yes	One of: `great-hall`, `dev`, `design`, `research`, `hatchery`, `garden`, `custom`
`color`	string	No	Hex color for UI glow (e.g., `#4a90d9`). Defaults to type default.
`icon`	string	No	Emoji or icon name (e.g., `🔧`, `code`). Defaults to type default.
`tools`	array	No	MCP tools enabled for this room. Default: all.
`default_tags`	array	No	Tags auto-applied to conversations assigned to this room.
`created_at`	ISO8601	Yes	Creation timestamp.
`updated_at`	ISO8601	Yes	Last modification timestamp.
`archived`	boolean	No	If true, room is archived. Default: false.
`parent_room`	string	No	For sub-rooms: ID of parent room.

Example .room.json:

json

{
  "id": "dev",
  "name": "Dev Room",
  "type": "dev",
  "color": "#4a90d9",
  "icon": "code",
  "tools": ["loci_search", "loci_get", "room_dev"],
  "default_tags": ["engineering", "code"],
  "created_at": "2026-01-15T10:00:00Z",
  "updated_at": "2026-05-03T14:22:00Z",
  "archived": false
}

Room templates

Suggested configurations for each room type.

Dev Room

Color: #4a90d9 (blue)
Default tags: engineering, code, debug
Soul file focus: Stack, active projects, workflow rules, linked architecture loci

Design Room

Color: #d97a4a (warm amber)
Default tags: ux, visual, component
Soul file focus: Design system, component library, user personas, active design work

Research Room

Color: #4a9d6e (forest green)
Default tags: research, reading, synthesis
Soul file focus: Current research questions, reading list, synthesis notes, linked paper loci

Hatchery

Color: #8b6914 (earthy brown)
Default tags: incubation, experiment, sandbox
Soul file focus: Active experiments, graduation criteria, failed experiments (for learning)

Garden

Color: #4a9d9d (teal)
Default tags: slow, synthesis, growth
Soul file focus: Growing ideas (plants), cross-pollination notes, things to revisit

Room to MCP connection

When the MCP server starts, it reads ~/.loci/rooms/ and exposes each non-archived room as a tool.

What room_dev returns:

json

{
  "name": "room_dev",
  "description": "Dev Room context: code, debugging, architecture",
  "content": {
    "soul_file": "# Dev Room: Soul File\n\n## Identity\n...",
    "context": "## Recent Conversations\n- Auth refactor (2026-05-02)\n...",
    "linked_loci": [
      {"slug": "kafka-vs-sqs", "title": "Kafka vs SQS Decision"},
      {"slug": "auth-flow-v2", "title": "Auth Flow v2 Architecture"}
    ],
    "recent_conversations": [
      {"id": "abc123", "title": "Auth refactor", "date": "2026-05-02"}
    ]
  }
}

The IDE agent receives the full room context in a single tool call. No need to make multiple requests.

WARNING

If your soul file is large (> 10 KB), consider splitting it. The MCP protocol has practical limits on tool response size.

Room vs Project

Aspect	Room	Project
Duration	Ongoing, indefinite	Has an end state
Scope	Domain (all code, all design)	Specific deliverable
When to use	Persistent context you return to	Bounded work with completion criteria
Example	Dev Room	"Auth Refactor" project
In loci	First-class concept with MCP tools	Tag or sub-room

Guidance:

Use rooms for domains: Dev, Design, Research
Use tags or sub-rooms for projects within domains
A project might span multiple rooms (design + dev)
When a project ends, its loci remain; conversations stay indexed

Sub-room example:

bash

loci room create --name "auth-refactor" --parent dev --type custom

This creates a sub-room that inherits Dev's color and tools but has its own context. When the project ends, archive the sub-room; parent room remains.

Team rooms (future)

WARNING

Team rooms are not yet implemented. This section describes planned functionality.

Team rooms enable shared context across multiple loci installations.

How it would work:

A team room syncs to a shared location (git repo, S3 bucket, Syncthing folder)
Each team member's loci installation pulls/pushes room changes
Conversations remain local; only context.md, .room.json, and loci sync
Conflict resolution: last-write-wins for metadata, merge for context.md

What syncs:

context.md: room context (merged on conflict)
.room.json: room metadata (last-write-wins)
CLAUDE.md: soul file (last-write-wins)
loci/*.locus: crystallized insights (last-write-wins per file)

What stays local:

Conversations (too large, too personal)
Search index (rebuilt from local data)
Session logs

Open questions:

Git vs. file sync (Syncthing) vs. custom protocol
Authentication and access control
Encryption for shared locations

Creating a locus

In the desktop app (Wizard): Right-click any conversation → "Crystallise as locus" → Name it, tag it, confirm.

Via CLI (LLMAGE):

bash

loci crystallise --room dev --source "https://claude.ai/chat/abc123" --name "kafka-vs-sqs"

Manually: Create a .locus file in ~/.loci/loci/ following the file format.

MCP exposure

When the MCP server is running, rooms and loci are exposed as tools:

Tools available:
  loci_search          Search all indexed conversations
  room_dev             Dev Room context + recent conversations
  room_design          Design Room context
  room_research        Research context
  loci_get <slug>      Retrieve a specific locus by name

Your IDE agent can call room_dev at the start of a dev session to load accumulated context: without you having to re-explain anything.

Rooms & Loci ​

What is a room? ​

The rooms ​

Room lifecycle ​

1. Create ​

2. Configure ​

3. Use ​

4. Crystallise ​

5. Archive ​

What is a locus? ​

Is every insight a locus? ​

Room + locus together ​

Full Dev Room soul file example ​

.room.json schema ​

Room templates ​

Dev Room ​

Design Room ​

Research Room ​

Hatchery ​

Garden ​

Room to MCP connection ​

Room vs Project ​

Team rooms (future) ​

Creating a locus ​

MCP exposure ​

Rooms & Loci

What is a room?

The rooms

Room lifecycle

1. Create

2. Configure

3. Use

4. Crystallise

5. Archive

What is a locus?

Is every insight a locus?

Room + locus together

Full Dev Room soul file example

`.room.json` schema

Room templates

Dev Room

Design Room

Research Room

Hatchery

Garden

Room to MCP connection

Room vs Project

Team rooms (future)

Creating a locus

MCP exposure