Getting Started: Plain Markdown
For: anyone starting from zero who wants a persistent, private memory system for their AI work. What you need: an AI tool that can read files on your machine (Claude Code, Cowork, or similar). A text editor helps. What you install: nothing.
This is the beginner 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 you get
loci is plain-text templates and processes that decide how memory, context, and trust work, whichever AI runs them. The current release is v0.6.0-beta. The same palace also runs from an optional CLI; you do not need it to start.
The kit holds seven feature sets:
- 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 as data behind a gate, exports typed artifacts
The full map is features/features.yaml. 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 sets each one uses. Unsure where to begin? Run templates/feature-helper.md.
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
Agent-run (recommended): point your AI at AGENT-SETUP.md. It interviews you about your work, your tools, your rooms, and how your companion should behave, then writes the files.
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
Full walkthrough: SETUP-GUIDE.md. Quickstart card for your first session: 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.
On session one there is no history yet, so say "First session, no prior state." and tell it what you want to work on.
Ending a session
Say "Write the session delta." Your AI writes a 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 to feel like a collaborator instead of a fresh tool.
The CLI (optional)
loci-cli reads the same palace from the terminal. It never writes to your palace, makes no network calls, and runs no inference. Install it from the repo with cargo install --path loci-cli; commands and flags are in the CLI guide.
Keeping your palace current
Updates are pull-based. When a new methodology version ships, tell your AI "Update my palace" (or "What's new in loci"). It compares your palace against the published PALACE-METHODOLOGY.md and offers the new pieces one at a time. You decide what enters; nothing is auto-applied. Full protocol: 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 cloud storage, and the CLI makes no network calls. To delete 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/: guided walkthroughs, starting with your first crystal - Read the crystals and garden concept pages
- Share what your palace became in
discoveries/, the community folder for palace portraits - To contribute to the substrate itself, see
CONTRIBUTING.md