loreweave

<h1 align="center">Loreweave</h1>

<p align="center">
  <strong>A temporal knowledge engine for markdown vaults.</strong><br>
  It indexes, links, remembers, forgets, and dreams — locally, over files you own.
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/loreweave"><img src="https://img.shields.io/npm/v/loreweave" alt="npm"></a>
  <a href="https://github.com/lets-order-some-fries/loreweave/actions/workflows/ci.yml"><img src="https://github.com/lets-order-some-fries/loreweave/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <img src="https://img.shields.io/badge/node-%E2%89%A520-brightgreen" alt="node >= 20">
  <img src="https://img.shields.io/npm/l/loreweave" alt="MIT">
</p>

<p align="center">
  <a href="#quickstart">Quickstart</a> ·
  <a href="#what-it-does">What it does</a> ·
  <a href="#the-cli">CLI</a> ·
  <a href="#use-it-as-agent-memory-mcp">Agent memory</a> ·
  <a href="#benchmarks">Benchmarks</a> ·
  <a href="#how-it-works">How it works</a> ·
  <a href="#research-lineage">Research</a>
</p>

---

<p align="center">
  <img src="docs/demo.gif" alt="loreweave demo: temporal search, timeline, as-of facts, session resume" width="720">
</p>

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
cd ~/my-vault
npx loreweave init          # creates .lore/
npx loreweave index         # incremental sync; one changed note: 32 ms at 1k notes, 656 ms at 20k (see Scale)

npx loreweave search "why did we drop the queue design"
npx loreweave ask "what's the status of project atlas"
npx loreweave 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](#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.

```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 — `npm i -g loreweave` gives you both;
`npx loreweave` works 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:

```bash
$ 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:

```bash
$ 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:

```bash
$ 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:

```yaml
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:

```bash
$ 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](#use-it-as-agent-memory-mcp).

## The CLI

| Command | What it does |
|---|---|
| `lore init` | create `.lore/` with a default config |
| `lore index [--full] [--no-nlp] [--rebuild-similar]` | incremental sync of vault → index |
| `lore search <q> [-k] [--since] [--until] [--tag] [--folder] [--json]` | hybrid retrieval with provenance |
| `lore ask <q>` | extractive answer: current facts + top passages (no LLM needed) |
| `lore facts [--subject] [--predicate] [--as-of] [--as-known-at] [--history]` | query the fact store |
| `lore timeline <entity> [--since] [--until]` | chronological history: fact changes merged with dated mentions |
| `lore resume [--since]` | what changed since the last resume: notes, facts, supersessions |
| `lore review [--threshold] [--limit]` | important-but-fading knowledge to revisit or archive |
| `lore assert <s> <p> <o…> [--valid-from]` | record a fact (journalled, supersedes) |
| `lore invalidate <s> <p>` | close the current fact in a slot |
| `lore count [--predicate] [--group-by] [--since]` | aggregate over fact history |
| `lore capture <text…>` | append a timestamped line to `lore/inbox.md` |
| `lore dream [--apply]` | consolidation pass + optional digest/review queue |
| `lore watc