#Folios

Folios are a project's memory: Markdown notes, filed in a tree, linked to each other and to the work, and shared by every member and every agent of the project. This page covers how to organise them, how links and revisions work, encrypted folios, and how agents read and write them.

Folios need the Write and keep knowledge capability.

#Why folios

Quests record work; folios record what you know. A decision and its reasons, how a subsystem fits together, a runbook, the conventions of the codebase: anything the next person, or the next agent session, should not have to rediscover.

That second reader is the point. An agent starting a task on a Lore project reads the folio index first, opens the folios that look relevant, and writes down what it learned when it is done. Without that, every session starts from nothing.

A few conventions keep folios useful:

• One topic per folio. The title is the topic.
• Short and self-contained. A folio that needs scrolling is two folios.
• Always a summary. One or two sentences on what the folio is for. It is the line the index shows, and what an agent reads to decide whether to open the folio at all. Say what kind of note it is in the first clause ("Decision: ...", "Runbook: ...").

#The workspace

Folios (/<project>/folios) is a three-pane workspace:

• the tree on the left, where you create, rename, move (by dragging) and delete folios and directories;
• the document in the middle: a folio with content opens rendered, an empty one opens for editing, View ▸ Toggle preview (⌘E) switches between the two, and edits save as you type;
• the inspector on the right, with the folio's Outline, History, Links and Files.

⌘F finds in the folio, and ⌘. toggles focus mode.

The Summary for agents field is shown on a folio when the knowledge capability's Summaries for agents option is on. Agents read and write it over MCP either way.

#Directories

Folios live in a tree of directories, at most 8 levels deep. A folio and a directory in the same parent cannot share a name; names are compared without regard to case.

⚠️ Deleting a directory deletes everything in it, folios included. Move what you want to keep out first. An agent's directory_delete refuses a directory that is not empty unless it passes cascade: true.

#Links

Link to another folio, or to anything else in the project, with the typed reference grammar:

The number is the per-project one shown beside each item. Nothing else between [[ and ]] is a reference: a title, a path or an anchor renders as a broken link.

Links are recomputed on every save. The Links tab shows both directions: what this folio points to, and the folios, quests and epics that point to it. The second half is the useful one: it surfaces context you did not know was related.

#Pinned folios

Pin a folio and it sorts to the top of the list, and its content is handed to every agent that orients itself on the project. Pinned folios are the project's equivalent of a CLAUDE.md or AGENTS.md: the instructions every session should read.

Pin sparingly. All pinned folios together share a budget of about 8,000 characters, spent every time an agent orients itself. The newest-updated come first: the first one past the budget is cut there, the ones after it are left out, and the agent is told so. Encrypted folios are never included.

#Epics

A design note that belongs to an epic can be filed under it. It then shows on the epic's Folios tab, and filtering the folio list by that epic finds it.

#Attachments

A folio can carry files: images shown in its body, diagrams, PDFs. See Attachments.

#History

Every change is kept as a revision: created, edited, renamed or reverted, by whom and when, with a snapshot of the title, summary and content.

Because folios save as you type, one writing session by one person is one revision rather than one per keystroke: edits within an hour of the previous one by the same author update that revision. A project keeps the 10 most recent revisions of each folio by default; older ones drop off.

Pinned revisions survive that cap: pin a revision in the History tab to keep exactly that snapshot.

Reverting never rewinds. It writes a new revision holding the old content, so the state you reverted from stays in history and the revert can itself be undone.

#Encrypted folios

A folio can be encrypted with a passphrase (Encrypt… in the folio's menu). The content is encrypted in your browser: the server only ever stores ciphertext, never the passphrase or the plain text. Share the passphrase with whoever should read it some other way.

What that costs:

• ⚠️ There is no recovery. Forget the passphrase and the content is gone.
• The title and summary stay readable by every project member. Do not put the secret there.
• An encrypted folio is not searchable, its links are not tracked, and image uploads are disabled.
• An agent reading it over MCP gets the ciphertext, not the text.
• Turning encryption on, or off, deletes the folio's revision history, pinned revisions included. Otherwise the plain-text snapshots written before encryption would stay readable in History.

#From an agent

Agents reach folios through MCP:

A good habit to give your agent: orient with project_context, read what is relevant with folio_get, and when a session produced a decision that was not obvious, write a folio about it before finishing.

#From the command line

lore folio list
lore folio list --epic E45
lore folio get F12
lore folio create --title "Decision: one database per tenant" \
  --summary "Decision: why each tenant gets its own database, and what it costs." \
  --content @decision.md

--content @file reads the body from a file, @- from standard input. See The lore CLI.