Loreweave

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

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:

// .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 (valid_from/valid_until) and when the system learned them (recorded_at). Contradictions supersede rather than overwrite, so history stays queryable.

$ 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 historical. --as-of asks what was *true* then; --as-known-at asks what was *believed* then. They disagree exactly when you learn something after the fact — which is when you most need to reconstruct what a past decision was actually based on:

$ lore facts --subject Vendor --as-of 2024-06-01

Vendor :: reliability :: poor — outage postmortem (2024-01-01 → now)

$ lore facts --subject Vendor --as-known-at 2024-06-01 Vendor :: reliability :: good (2024-01-01 → 2024-01-01) [superseded]

Which fact wins is decided deterministically (newest valid-time, provenance as tiebreak) — never by asking a language model which one looks fresher. And the whole history of anything is one command — every value change merged chronologically with the dated prose that mentions it:

$ lore timeline Project Atlas

2024-01-15 status: planning (until 2024-09-01) 2024-02-10 • [[Project Atlas]] kicked off with a three-person crew. [kickoff.md] 2024-09-01 status: planning → active 2025-06-20 • The [[Project Atlas]] midpoint review went long but well. [review.md]

Temporal-graph systems build this by running an LLM over every document at ingestion. Here the supersede chain has been maintained all along, so it is a read-side join: no LLM, no network, same answer every time.

2. Retrieval that follows connections, not just words. Queries fuse BM25, dense similarity (when configured), and Personalized PageRank over the vault's own graph — wiki-links, shared entities, tags, co-occurrence. Two-hop neighbors surface even when they share no vocabulary with your query, and every result tells you *why*:

• data/glacier-dataset.md#@0  (0.0327)  ⟨via amara osei⟩

The Glacier Dataset holds meltwater sensor readings from 2019-2024.

3. Memory with dynamics. Every passage carries FSRS-style stability and retrievability — a power-law forgetting curve. Passages that actually get *used* (not merely retrieved) decay slower; important-but-fading knowledge gets surfaced for review instead of silently rotting. Nothing is ever deleted.

4. It dreams. lore dream is an idle-time consolidation pass that reviews the vault and reports duplicate passages, contradicted facts, stale knowledge, missing links between notes that clearly belong together, and orphans. With --apply it writes a digest and a review queue — append-only, under `lore/`. It never rewrites your prose: LLM-driven whole-file rewriting is a documented failure mode — each rewrite quietly drops details until the file collapses to mush — so the architecture forbids it.

5. Questions retrieval can't answer. Counting, grouping, and date-range queries run as deterministic SQL over the fact store, not as vibes over embeddings:

$ lore count --predicate trip_to --since 2025-01-01 --until 2025-12-31

2 Japan 1 Kenya

6. Facts come from your notes, not from a form. Nobody hand-writes - [fact] X :: y :: z, so the extractor mines the conventions vaults already use:

status: shipped              # frontmatter

• owner:: Priya # Dataview inline field
• [location] Hyderabad # Basic Memory observation

Only unambiguous field syntax is accepted automatically. Prose formatting like - **Owner:** Priya is precise on entity notes and noisy on report notes, so it is opt-in (facts.extract: "all") — or an agent can review candidates via lore_propose_facts and assert the real ones. Judgement stays out of the index.

7. Time means when it happened, not when you saved the file. --since and --until filter on *content* time — frontmatter dates, dated filenames (2025-03-14-standup.md), or dates in the text — falling back to file mtime only when a note carries no date of its own. lore watch keeps the index current so you never have to remember to reindex.

8. Built for agents. An MCP server exposes 15 typed tools so Claude Code, Cursor, or any MCP client can use your vault as durable memory. Session continuity is a query, not a paraphrase — lore resume returns exactly what changed since the agent last connected, computed from record time:

$ lore resume

since 2026-08-11 15:55 ~ lore/journal/2026-08-11.md

• Project Atlas :: status :: shipped (since 2026-08-11)

± Project Atlas :: status: active → shipped

$ lore resume since 2026-08-11 15:56 nothing changed

Alternatives that summarize the previous session with an LLM inject a paraphrase; this is a deterministic diff. Full setup in Agent memory.

The CLI

Use it as agent memory (MCP)

// Claude Code: .mcp.json  (or claude_desktop_config.json)

{ "mcpServers": { "loreweave": { "command": "npx", "args": ["--allow-scripts=better-sqlite3", "-y", "loreweave", "--vault", "/path/to/vault", "serve", "--mcp"] } } }

The --allow-scripts argument is for npm 12; Requirements explains it, and how to clear an install npx already made without it.

| lore_dream_report | the consolidation