Getting Started: Plain Markdown
For: People who want a persistent, private memory system for their AI work, starting from zero. What you need: Any AI tool that can read files on your machine (Claude Code, Cowork, or similar). A text editor helps. What you install: Nothing. The entry path is plain markdown.
Naming update
Earlier versions of these docs described three product tiers (Scholar, Wizard, LLMAGE). That naming is retired. loci is one plain-text substrate with three run modes: plain markdown, a desktop app, and a CLI. All three shipped together as the 0.6 open beta (v0.6.0-beta). This page covers the plain-markdown path.
This is the entry path into loci: the plain-markdown run mode the repo calls "the door". No build, no extension, no account. You copy a folder of templates, fill in three files, and point your AI at them.
What loci is
loci is an intelligence substrate for working with AI: plain-text templates and processes that decide how memory, context, and trust work, no matter which AI runs them. Local-first. No cloud, no accounts, no lock-in.
The current release is v0.6.0-beta (the 0.6 open beta). It ships three ways to run the same substrate:
| Run mode | What it is |
|---|---|
| Plain markdown | The door. Copy the templates/ kit, point any file-aware AI at your CLAUDE.md. No build. This page. |
| Desktop app | A Tauri cockpit (desktop/): a native Operations dashboard plus a tab for each instrument your palace generates for itself. |
| CLI | loci-cli/: a small Rust binary that reads your palace from the terminal. Read-only. No network, no inference. |
You do not need the app or the CLI to start. They are expressions built on top of the substrate, not the substrate.
What you get
Seven feature sets, all shipped as plain-text templates:
- Persistent Memory: tiered crystals (◇ exploratory, ◈ contextual, ◆ confirmed) you can promote, expire, pin, and compost
- Context Architecture: rooms, a retrieval hierarchy, a local map, so the right context loads at the right time
- Identity & Personas: a soul file, a peer card, named personas
- The Garden: one file per idea, a health pass, seed-to-crystal graduation
- Continuity & Synthesis: session handovers, a synthesis pass that proposes (never auto-applies), scheduled housekeeping
- Trust & Governance: a named human-review gate, foreign-process quarantine, confirm-against-disk, a read-only structural audit
- Interop & Evolution: reads memory left by other tools by structure, exports typed artifacts (MCP support is planned, not yet shipped)
The full map, with the template behind each set, lives in features/features.yaml in the repo.
You do not need all seven. The repo's README maps six usage shapes (the Researcher, the Builder, the Companion-keeper, the Vault-keeper, the Team, the Nomad) to the feature sets each one actually uses. If you are unsure where to begin, run templates/feature-helper.md and it points you.
Setup
Step 1: Get the templates
git clone https://github.com/huximaxi/lociOr download the ZIP from GitHub and extract it.
Step 2: Copy the kit into your own folder
Copy templates/ into a folder of your own. That folder becomes your palace.
Step 3: Fill in the three core files
Two ways to do this.
Agent-run (recommended): point your AI at AGENT-SETUP.md and let it interview you. It asks about your work, your tools, your rooms, and how you want your companion to behave, then writes the files for you.
Manual: three files minimum.
- Fill in
templates/CLAUDE-master.md, save it asCLAUDE.mdin your palace folder - Fill in
templates/SOUL.md, save it assoul/SOUL.md - Add at least one room from
templates/room-template.md, saved asrooms/[room-name]/CLAUDE.md
TIP
The full walkthrough is SETUP-GUIDE.md in the repo. The quickstart card for your first working session is FIRST-SESSION.md.
Your first session
Open a new conversation with your AI and paste this, replacing the bracketed parts:
Read
CLAUDE.mdto understand who you are and how we work. Then readsoul/SOUL.mdfor your character and any prior history. Then readrooms/[ROOM NAME]/CLAUDE.mdfor this session's context.When you're ready: wake up as [YOUR_AI_NAME], state the room we're in, and ask me for the 2-line state summary.
If it is session one and there is no history yet, just say: "First session, no prior state." Then tell it what you want to work on.
Ending a session
When you are done, say: "Write the session delta." Your AI writes a structured handover to soul/handovers/YYYY-MM-DD.md: what was done, decisions made, what is next. The next session starts from that file instead of from zero.
Useful things to say
| Say this | What happens |
|---|---|
| "Write the delta" | Writes the session handover |
| "Add this as a crystal" | Adds a confirmed fact to your context |
| "We're switching rooms" | Loads the new room context |
| "Plan mode" | Stops and writes a plan before acting |
| "KISS it" | Backs up and finds a simpler solution |
| "Update the tracker" | Updates tracker.json with current status |
| "What's open?" | Surfaces open blockers and next actions |
Give it three to five sessions. The handovers accumulate, the crystals get richer, and the AI starts feeling like a collaborator instead of a fresh tool.
The CLI (optional)
loci-cli is a terminal-native door into the same palace. It reads; it never writes to your palace, makes no network calls, and runs no inference.
cargo install --path loci-cli| Command | What it does |
|---|---|
loci status | Palace path, layout, room and crystal counts |
loci crystals | List every crystal slug across all rooms |
loci crystals --room <name> | Restrict to one room |
loci read <slug> | Print a crystal's contents |
loci handover | Print the most recent handover |
loci init | Interactive wizard; writes ~/.config/loci/config.toml |
Add --json to any read command for machine-readable output. The palace is resolved from --palace <path>, then $LOCI_PALACE, then by walking up from the current directory.
Both palace layouts work: rooms inside a _palace/ subfolder (the original shape) or rooms at the folder root (palaces ported from older structures). The desktop app accepts both as well.
Keeping your palace current
loci's update story is pull-based and explicit. When a new methodology version ships, say to your AI:
"Update my palace" (or "What's new in loci")
Your AI reads the published PALACE-METHODOLOGY.md, compares it against what your palace already has, and offers the new pieces one at a time. You decide what enters. Nothing is auto-applied. The full protocol is PALACE-UPDATE.md.
Privacy
The substrate is plain text on your disk. That is the whole storage model.
| Data | Location |
|---|---|
| Memory, crystals, handovers, garden | Markdown files in your palace folder |
| Tracker state | tracker.json in your palace folder |
| CLI config | ~/.config/loci/config.toml (only if you run loci init) |
- No accounts: no sign-in, no user profile, no registration
- No cloud storage: your palace exists only on your machine
- CLI makes no network calls: read-only, no inference, no daemons
- Deleting your data: delete the folder. There is nothing else to clean up.
Your AI tool's own data handling is separate from loci and governed by that tool's policies.
Next steps
- Walk a flow in
tutorials/: seven guided tutorials, one per feature set, starting with your first crystal - Read the crystals concept page and the garden concept page
- Share what your palace became in
discoveries/, the community folder for palace portraits - To contribute to the substrate itself, see
CONTRIBUTING.md