Knowledge structure
A brain is a directory of Markdown. The folders help you browse it, the frontmatter says what each file is, and one manifest says which files belong to the toolkit.
What lore init writes
lore init brain
Initialized a brain at ~/brain
inbox/
daily/
notes/
sources/
entities/
7 starter files, recorded in .lorekeeper/manifest.json.
Everything else in that directory is yours.
Start by reading ~/brain/README.md
Five folders, a README in each, a README and an AGENTS.md at the root, and the manifest. That is all.
The folders
The folders give each file an epistemic role, and nothing more. There are no numeric prefixes and no sort order to preserve. Meaning lives in frontmatter, so moving a file between folders changes nothing about how it is found.
| Folder | What it is for, from its own README |
|---|---|
daily/ | Dated entries, one file per day. |
entities/ | The projects, areas, and people your notes keep referring to. |
inbox/ | Things you captured and have not processed yet. |
notes/ | What you have worked out, written in your own words. |
sources/ | External things you took in: an article, a video, a talk, a conversation. |
Frompackages/cli/src/starter.ts · read back from a real lore init
Frontmatter
Frontmatter is optional. A Markdown file with none is still valid knowledge, and lore search indexes it. These are the fields this version of the contract recognizes:
| Field | Meaning |
|---|---|
id | A stable identifier. Sources carry one; ordinary notes do not need one, and a note without one is not a defect. |
type | Browsing ergonomics only. Retrieval never depends on it. Provisional in v0.1: its values are not fixed. |
kind | A free string, not validated in v0.1. |
url | Where a source came from, exactly as it was written. |
created | When the file was made, kept exactly as written — never reparsed into another timezone. |
updated | When the file last changed, kept exactly as written. |
tags | A list of tags. |
aliases | Other names for this file. The last thing a link is resolved against. |
derived_from | The stable ids of the sources this was derived from. Absent means unknown or unrecorded, never original. |
about | Provisional in v0.1. What the file is structurally about, added alongside its links rather than copied from them. |
Frompackages/core/src/fields.ts · RECOGNIZED_FIELDS
A field the contract does not recognize is kept, never dropped. The schema only ever grows, so a file written for a later version still reads here, and a write never loses what it did not understand.
The manifest
.lorekeeper/manifest.json records every file the toolkit wrote, with a SHA-256 of what it wrote. It is the only way lore tells its files from yours, and it checks the manifest before it writes anything.
- A file in the manifest is the toolkit's. If you edit it,
lorereports it as modified and leaves your version in place. - A file not in the manifest is yours.
lorenever rewrites, moves or reformats it.
These are the files a fresh lore init claims:
AGENTS.mdREADME.mddaily/README.mdentities/README.mdinbox/README.mdnotes/README.mdsources/README.md
The manifest also records each thought and URL you capture, because lore wrote those files too. Anything you write yourself is never listed. Provenance covers ownership in more detail.