lets-order-some-fries/loreweave

A temporal knowledge engine for markdown vaults.
It indexes, links, remembers, forgets, and dreams — locally, over files you own.
= 22">
Quickstart ·
What it does ·
CLI ·
Agent memory ·
Benchmarks ·
How it works ·
Research
Most knowledge tools are write-only. You capture diligently, the vault grows, and
six months later you can't find the thing you know you wrote — because retrieval is
keyword search over prose, nothing ever resurfaces on its own, and nothing notices when
what you wrote last year stopped being true.
Loreweave is the layer that fixes that. Point it at a folder of markdown (Obsidian or
plain) and it builds a knowledge graph, a bitemporal fact store, and a memory model over
your notes — then hands them to you through a CLI and to your AI agents through MCP.
Three guarantees, enforced by the code rather than promised:
Your files win. User markdown is never mutated; the engine only appends, and only
under lore/. The vault is the source of truth — the index is a cache you can
delete at any time and rebuild identically (there's a test for that).
No LLM anywhere in the core. Indexing and retrieval use zero tokens and make zero
network calls. Same vault, same query, same answer — forever.
Memory you can read. Every fact an agent stores is a markdown line you can open,
edit, and git diff.
## Quickstart
bash
npm i -g --allow-scripts=better-sqlite3 loreweave # the flag is for npm 12: see Requirements
cd ~/my-vault
lore init # creates .lore/
lore index # incremental sync; one changed note: 32 ms at 1k notes, 656 ms at 20k (see Scale)
lore search "why did we drop the queue design"
lore ask "what's the status of project atlas"
lore dream # what's duplicated, contradicted, stale, unlinked
Zero configuration and no network: out of the box it runs on BM25 + knowledge-graph
spreading activation. Add local embeddings when you want them:
jsonc
// .lore/config.json
{ "embedding": { "provider": "ollama", "model": "mxbai-embed-large" } }
Pick mxbai-embed-large (670 MB) for quality or nomic-embed-text (274 MB) when disk
and indexing speed matter more — required task prefixes are applied automatically for
both, and for the E5, BGE and Arctic families. The measured difference between the two
is in Benchmarks. No embedding provider means lexical + graph retrieval,
still fully functional.
Works with non-English vaults: Chinese, Japanese and Korean text is segmented per
character so it is searchable at all, and other scripts index as written.
## What it does
1. Knowledge that has a timeline. Facts are bitemporal: when they were true in the
world (validfrom/validuntil) and when the system learned them (recordedat).
Contradictions supersede rather than overwrite, so history stays queryable.
bash
$ lore assert "Ledger Format" status draft --valid-from 2026-01-01
$ lore assert "Ledger Format" status final --valid-from 2026-08-01
✓ Ledger Format :: status :: final
superseded: "draft" (now valid until 2026-08-01)
journal: lore/journal/2026-08-01.md
(lore and loreweave are the same binary — the global install gives you both;
npx --allow-scripts=better-sqlite3 loreweave runs it without installing.)
Both time axes are queryable, which is what makes it bitemporal rather than merely