Lorekeeper

You already wrote it down. Find the passage that answers.

Knowledge accumulates across notes, articles, videos, and long conversations with AI agents, and almost none of it comes back when it is needed. So you re-explain your own project to an agent for the fourth time this week, and it answers from what you just pasted rather than from what you have known for a year.

The usual fixes ask you to become an expert in an application first, and then they hold your knowledge inside it.

Lorekeeper takes the other side of that trade. Your knowledge stays as plain Markdown files you own, readable with no tool installed, including this one. On top of those files sits a deterministic retrieval layer that returns the individual passages that answer a question — and an agent calls it instead of asking you to supply context again.

The knowledge is yours. The retrieval is deterministic. The intelligence is whatever agent you were already using.

Frombrand/narrative.md · The thesis

Lorekeeper in thirty seconds

Lorekeeper is a command-line toolkit for a second brain made of plain Markdown.

lore init creates a brain, or adopts a Markdown vault you already have without rewriting a single file of it. lore capture files a thought or a URL with enough context that it is still useful months later, unprocessed. lore search ranks the passages of that brain against a question and returns each one with its file, its heading, its line range, its score, and its text.

lore init also writes an AGENTS.md into the brain, which is what makes any of it fire: a coding agent reads it, learns the directory is searchable, and searches it before answering questions about your work.

It runs offline. It takes no credentials, makes no network call, and calls no language model. Nothing about it breaks when an AI provider changes its API, its pricing, or its mind.

Frombrand/narrative.md · Lorekeeper in thirty seconds

The whole command surface, printed by the built binary when this site was built.
lore --help
Lorekeeper 0.1.0
Pathfinder finds the way; Lorekeeper remembers the journey.

Usage:
  lore init <dir>              Create a brain, or adopt an existing vault
  lore capture <brain> <item>  Write a thought or a URL into that brain
  lore search <brain> <query>  Rank the spans of that brain against a query
  lore --help                  Show this message
  lore --version               Print the version

A captured thought lands in inbox/ as YYYYMMDD-HHMMSS-subject.md, with the
same name as its id. Two captures in one second never collide: the second
one takes the next free -2, -3 suffix.

A captured URL lands in sources/ instead, named for the stable source id it
carries. URLs that name the same thing are one source, so capturing one you
already have reports the file that holds it and writes nothing. The URL is
identified, never visited.

Search ranks spans, not files: each result names a path, the heading it sits
under, its line range, and its score, and prints the lines themselves. Add
--json for that same result shape as JSON, or --limit to change how many
come back. A score ranks; it never proves an answer is absent.

Give several wordings of one question, each in its own quotes, and search
fuses their rankings into one list. Three wordings find what one misses,
so ask in other words rather than trusting a single phrasing. Spans that
repeat the same text in several files are reported once.

Search reads. It writes nothing, builds no index file, and works on any
directory of Markdown, whether or not lore init has run there.
Lorekeeper runs offline and takes no credentials.
The three surfaces Lorekeeper keeps separate Two public surfaces sit above a dashed boundary line, and one private surface sits below it. Above: this repository, `lorekeeper/`, holding the CLI, its contracts and its tests, the identity, the narrative and this diagram, and no brain data ever; and the documentation site, which renders what this repository authors, is static and installable, and holds no brain data. An arrow runs from the repository to the documentation site, labelled builds. The dashed boundary reads: no brain data crosses this line, nothing private is committed here. Below it: your brain, at a path such as ~/brain, holding your Markdown files and the manifest that says which of them the toolkit owns — private, on your machine, generated by `lore init`, and never committed to this repository. One arrow crosses the boundary downwards, through a gap in the line, from the repository into your brain: it carries `lore init`, `lore capture` and `lore search`, which run on your machine. A second arrow, from your brain back up to the documentation site, is struck through with a cross on the boundary and labelled: your notes never cross; the CLI makes no network call. So code crosses the boundary in one direction, and brain data crosses it in neither. Three surfaces, cleanly separated Two are public and one is yours. What crosses between them is code, in one direction only. PUBLIC This repository lorekeeper/ the CLI, its contracts, and its tests the identity, the narrative, and this diagram MIT licensed, and holding no brain data builds The documentation site static, installable renders what this repository authors no server, no accounts, no credentials holds no brain data No brain data crosses this line. Nothing private is committed here. PRIVATE Your brain ~/brain your Markdown files, and the manifest that says which of them the toolkit owns private, on your machine, generated by lore init never committed to this repository lore init lore capture lore search run on your machine Your notes never cross. The CLI makes no network call. No private or personal content enters this repository — fixtures, demos, and screenshots included.

Lorekeeper and Pathfinder

Pathfinder finds the way. Lorekeeper remembers the journey.

They come from the same maker and are built to read as siblings, not as one product split in two. Pathfinder is movement, direction, and execution: it takes a project from intent to delivered work. Lorekeeper is memory, provenance, and connection: it keeps what was learned along the way and hands it back when it is next needed.

You can use either without the other. Neither imports the other. Lorekeeper is not a Pathfinder plugin and does not require a Pathfinder project to be useful.

Frombrand/narrative.md · Lorekeeper and Pathfinder