loreweave

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.

Your files stay exactly as they are. The vault is the source of truth; the index is a cache you can delete at any time.

npx loreweave init && npx loreweave index

Quickstart

cd ~/my-vault
npx loreweave init          # creates .lore/
npx loreweave index         # incremental; ~seconds for thousands of notes

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 required and no network calls: out of the box it runs on BM25 + knowledge-graph spreading activation. Add embeddings when you want them:

// .lore/config.json
{ "embedding": { "provider": "ollama", "model": "nomic-embed-text" } }

Everything degrades gracefully — no embedding provider means lexical + graph retrieval, still fully functional.

Related MCP server: genmem

What makes it different

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)

$ lore facts --subject "Ledger Format"
Ledger Format :: status :: final  (2026-08-01 → now)

$ lore facts --subject "Ledger Format" --as-of 2026-03-01
Ledger Format :: status :: draft  (2026-01-01 → 2026-08-01)  [superseded]

Which fact wins is decided deterministically (newest valid-time, provenance as tiebreak) — never by asking a language model which one looks fresher.

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 (context collapse), 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. Built for agents. An MCP server exposes 11 typed tools so Claude Code, Cursor, or any MCP client can use your vault as durable memory — with a session context pack, fact assertion, point-in-time queries, and a reinforcement signal.

The CLI

Use it as agent memory (MCP)

// Claude Code: .mcp.json  (or claude_desktop_config.json)
{
  "mcpServers": {
    "loreweave": {
      "command": "npx",
      "args": ["-y", "loreweave", "--vault", "/path/to/vault", "serve", "--mcp"]
    }
  }
}

Tools: lore_search, lore_context_pack, lore_read_note, lore_assert_fact, lore_invalidate_fact, lore_query_facts, lore_aggregate_facts, lore_capture, lore_mark_used, lore_dream_report, lore_index.

Facts asserted through MCP are written back to lore/journal/YYYY-MM-DD.md as readable markdown lines, so an agent's memory is something you can open, read, edit, and git diff:

- [fact] Ledger Format :: status :: final {valid_from=2026-08-01, confidence=0.9, source=stated}

Delete .lore/ and reindex — every fact and edge is reconstructed from those files.

How it works

vault/*.md ──parse──▶ notes · blocks · wiki-links · tags · entities
                            │  (incremental: mtime + content hash)
                            ▼
                  SQLite .lore/index.db  ── disposable cache, rebuildable
                            │
        ┌───────────────────┼────────────────────┐
        ▼                   ▼                    ▼
   graph (CSR)         retrieval             facts
   blocks ∪ entities   BM25 + dense + PPR    bitemporal, supersession,
   2-iteration PPR     → weighted RRF        deterministic freshness,
   α = 0.5             → FSRS boosts         aggregates
        └─────────┬─────────┴──────────┬─────────┘
                  ▼                    ▼
             dream (idle-time)     CLI · MCP

Design rules the code enforces:

• Files win. User markdown is never mutated. The engine only appends, and only under lore/.

• Invariants in code, not prompts. Schema, migrations, graph construction, and supersession are typed, versioned, and tested — no LLM re-specifies them at runtime.

• No LLM required anywhere in the core. Indexing and retrieval use zero tokens. Language models are consumers of this engine, not dependencies of it.

• Everything is re-derivable. A full rebuild reproduces byte-identical derived state (there's a test for that).

Research lineage

Every significant choice traces to 2024-2026 literature; the full 87-finding survey lives in docs/research/ and the reasoning in docs/superpowers/specs/.

Library use

import { openContext, indexVault, search, assertFact, queryFacts, dream } from 'loreweave';

const ctx = openContext('/path/to/vault');
await indexVault(ctx.store, ctx.root);
const hits = await search(ctx, 'streaming compaction', { k: 5 });
assertFact(ctx, { subject: 'Atlas', predicate: 'status', object: 'shipped', validFrom: '2026-08-01' });
const asOfMarch = queryFacts(ctx.store, { subject: 'Atlas', asOf: '2026-03-01' });
const report = dream(ctx);
ctx.close();

Development

npm install
npm test          # 81 tests
npm run typecheck
npm run build

Requires Node ≥ 20. Single native dependency (better-sqlite3).

License

MIT © Ambuj Upadhyay