Lorekeeper

Concepts

Why it works without a model

Lexical search alone is not good enough — a fact this project measured rather than assumed, and recorded in context/project-overview.md on 2026-08-21.

What makes it good enough is that the agent asks the same question several ways in a single call, and Lorekeeper fuses the ranked lists. That is not an optimization bolted on afterwards; it is the retrieval contract, and the integration artifact instructs agents to use it.

The effect is visible in the demo in agent-integration.md: a question phrased one way surfaces the wrong note, and the same question phrased three ways surfaces the note that answers it — a note that never uses the words the first phrasing was built from.

Frombrand/narrative.md · Why it works without a model

What Lorekeeper is not

Four specific things this project has decided not to become, recorded in context/project-overview.md:

Not an Obsidian template bundle. Obsidian is an optional viewer, not the architecture. The folder set carries epistemic role and nothing else — no numeric prefixes to force a sidebar’s sort order. Meaning lives in frontmatter, so you can reorganize the folders without breaking retrieval.

Not a vault-shaped dumping ground of transcripts. A capture is self-describing on arrival: it records what it is and when it came, so an item you never get around to processing is still worth finding. Retrieval ranks passages, not files, so the answer comes back rather than the container it lives in.

Not a one-time scaffold. A manifest records which files the toolkit owns and which are yours. Toolkit files can be updated; yours are never rewritten, moved, or reformatted, and a file you edited is reported as drifted rather than overwritten. Adoption of an existing vault is adoption, not migration: nothing is restructured to suit the tool.

Not a system that stops working when an AI provider changes. The CLI makes zero model calls by design. There is no API key to rotate, no embedding index to rebuild against a new model, and no vendor whose deprecation notice becomes your migration. The intelligence lives in whatever agent calls the CLI, and the CLI is testable with no agent in the loop.

And, in identity terms: not a generic productivity app, not an “AI brain” gimmick, not cyberpunk neon AI styling, not a clone of Pathfinder, and not a clone of any existing second-brain project.

Frombrand/narrative.md · What Lorekeeper is not

What it saves

Measured on 2026-09-17 over a synthetic corpus of 3,000 notes, the prescribed agent call returned a JSON payload approximately 2.0x smaller than the whole notes those passages came from. The measured ratio was 1.97x; 2.0x is it rounded up, and it is the ceiling on what we publish — not a claim about the best case.

Four caveats sit behind that number. The proxy caveat travels with every byte figure; the generous-baseline and pretty-printed caveats travel with this saving wherever it appears:

  • Bytes are a proxy for token cost, not a literal token count. No tokenizer and no provider coupling was added to produce it.
  • The baseline is deliberately generous. It charges only for the files the returned passages came from, as though the agent had already known which files to open. Without span retrieval it would not have known — which is why Feature 07 recorded 1.97x as a floor for the realistic case rather than a best case. The ceiling above is a ceiling on what is published, not on what the tool can do.
  • The payload is pretty-printed, which is 12% of its bytes. Compact JSON would read 2.2x. The output format is a retrieval contract and was not changed to improve this number.
  • The corpus was not shaped to flatter the result. Its notes average about a kilobyte, which bounds how much smaller a passage can be than the note holding it.

The saving is real and modest, and it is reported as measured rather than as improved. proof.md has the table, the machine, and the rest of the caveats.

Frombrand/narrative.md · What it saves

Where v0.1 stops

Stated plainly, because a presentation surface that omits the known limitation is not an honest one.

The CLI makes no LLM call. None. Not for query expansion, not for summarizing a result, not for ranking. If you run lore search with no agent in front of it, you get deterministic lexical retrieval and nothing more. The several-wordings behavior that makes retrieval good enough is supplied by the calling agent, which means a caller that issues one wording gets a materially worse product than one that issues three.

Retrieval cannot prove that something is absent. This is the known v0.1 limitation, recorded on 2026-08-21 rather than hidden. A score ranks passages against each other; it does not separate knowledge that is present from knowledge that is not there. During evaluation, a control question with no answer anywhere in the corpus outranked genuine questions that did have one. A top result can therefore be nothing more than the best of a bad field. That is exactly why there is no relevance threshold: a cutoff would turn an honest miss into false confidence.

So a calling agent must treat results as evidence to weigh, not as proof. When the evidence does not settle a question, it searches again in other words; when it still does not, it says the evidence is insufficient. It never reports that your brain lacks something because a score looked low.

And what v0.1 simply does not include yet: no embeddings or semantic search, no MCP server, no mobile capture, no automated ingestion of web pages or video, no server component of any kind, and no Windows support. macOS and Linux, on Node 24 or newer.

Frombrand/narrative.md · Where v0.1 stops