[--since] [--until]` | chronological history: fact changes merged with dated mentions |\n| `lore resume [--since]` | what changed since the last resume: notes, facts, supersessions |\n| `lore review [--threshold] [--limit]` | important-but-fading knowledge to revisit or archive |\n| `lore assert [--valid-from]` | record a fact (journalled, supersedes) |\n| `lore invalidate ` | close the current fact in a slot |\n| `lore count [--predicate] [--group-by] [--since]` | aggregate over fact history |\n| `lore capture ` | append a timestamped line to `lore/inbox.md` |\n| `lore dream [--apply]` | consolidation pass + optional digest/review queue |\n| `lore watch` | reindex automatically as the vault changes |\n| `lore mark-used [anchor]` | reinforce a passage that proved useful |\n| `lore graph export --format json\\|graphml\\|dot` | export the graph |\n| `lore doctor` | health check: broken links, integrity, coverage |\n| `lore stats` | vault statistics and top entities |\n| `lore serve --mcp` | start the MCP server on stdio |\n\n## Use it as agent memory (MCP)\n\n```jsonc\n// Claude Code: .mcp.json (or claude_desktop_config.json)\n{\n \"mcpServers\": {\n \"loreweave\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"loreweave\", \"--vault\", \"/path/to/vault\", \"serve\", \"--mcp\"]\n }\n }\n}\n```\n\n| Tool | What the agent gets |\n|---|---|\n| `lore_search` | hybrid retrieval with provenance and temporal filters |\n| `lore_context_pack` | one-call session context: relevant passages + current facts + recent changes |\n| `lore_read_note` | full text of a note by path |\n| `lore_assert_fact` / `lore_invalidate_fact` | write/close facts — journalled, superseding, never destructive |\n| `lore_query_facts` | point-in-time fact queries (`asOf`, `asKnownAt`, history) |\n| `lore_timeline` | an entity's merged fact + prose chronology |\n| `lore_resume` | exactly what changed since the agent last connected |\n| `lore_review` | important-but-fading passages worth resurfacing |\n| `lore_aggregate_facts` | count/group-by over fact history |\n| `lore_capture` | append a timestamped line to the inbox |\n| `lore_mark_used` | reinforcement signal: this passage actually helped |\n| `lore_propose_facts` | extraction candidates for the agent to review and assert |\n| `lore_dream_report` | the consolidation report (duplicates, contradictions, stale, orphans) |\n| `lore_index` | trigger a reindex |\n\nFacts asserted through MCP are written back to `lore/journal/YYYY-MM-DD.md` as readable\nmarkdown, so an agent's memory is something you can open, edit, and `git diff`:\n\n```markdown\n- [fact] Ledger Format :: status :: final {valid_from=2026-08-01, confidence=0.9, source=stated}\n```\n\nDelete `.lore/` and reindex — every fact and edge is reconstructed from those files.\n\n`- [fact]` lines are replayed out of any note, but the `source=` attribute is read back\nonly under `lore/journal/`, which is the only path loreweave writes. The same line in an\nordinary note still records the fact, as `extracted` — a note can state something; it\ncannot say that *you* stated it.\n\n**Compared to hosted memory services** (Mem0, Zep): those run LLMs at write time to\nextract and summarize into their own store; loreweave runs no model in the core, keeps\nmemory in your files under your version control, and makes every retrieval\nreproducible. The trade: they do abstractive summarization, this engine deliberately\ndoes not. Retrieval quality against their published benchmarks is below — with the\ncaveats stated, because most published agent-memory numbers measure end-to-end QA with\nan LLM, which is a different quantity than retrieval.\n\n## Benchmarks\n\nThese are third-party benchmarks with relevance labels nobody here chose. All loreweave\nnumbers are **retrieval** metrics — it finds the evidence, it does not write the\nanswer — so they are not comparable to the end-to-end QA accuracy quoted by systems\nthat put a language model after retrieval. Reproduce any number:\n[`docs/benchmarks.md`](docs/benchmarks.md). Field comparison with the traps called out:\n[`docs/scoreboard.md`](docs/scoreboard.md).\n\n**LongMemEval_S** (ICLR 2025) — 500 questions, each with ~50 sessions of chat history;\nfind the sessions holding the evidence. Session-level recall, all 500 questions:\n\n| configuration | R@1 | R@5 | R@10 |\n|---|---|---|---|\n| model-free (no embeddings, no network) | 0.552 | 0.899 | 0.943 |\n| + embeddings & 8-turn chunking | **0.590** | **0.959** | **0.983** |\n\n[A third-party benchmark][lme] of the same task reports BM25 alone at **86.2%** R@5,\nBM25+vector hybrid at **95.2%**, and a vector-only system at **96.6%**. One caveat\nbefore the comparison: their metric scores a question 1 if *any* gold session is\nretrieved, ours scores the *fraction* of gold sessions found — ours is the stricter\ndefinition, so treat cross-system gaps of under a point as noise. With that stated:\n**at 95.9% loreweave is past the hybrid and just short of the vector-only system**,\nwith a local model, no network, and a lexical index it can fall back to.\n\n[lme]: https://github.com/rohitg00/agentmemory/blob/main/benchmark/LONGMEMEVAL.md\n\n**BEIR / SciFact** — 5 183 scientific abstracts, 300 claims, scored by nDCG@10\n(ranking quality: rewards putting relevant documents nearer the top):\n\n| configuration | nDCG@10 | Recall@10 |\n|---|---|---|\n| BM25 baseline (BEIR paper, Anserini) | 0.665 | — |\n| loreweave, model-free | 0.681 | 0.817 |\n| loreweave + nomic-embed-text | 0.727 | 0.865 |\n| loreweave + mxbai-embed-large | **0.742** | **0.884** |\n\n**LoCoMo** — 10 long conversations, 1 982 evidence-labelled questions, turn-level\nrecall. No comparable third-party *retrieval* number exists (published LoCoMo results\nare LLM QA accuracy), so these are offered as a target rather than a comparison:\n\n| | R@1 | R@5 | R@10 | R@20 |\n|---|---|---|---|---|\n| model-free | 0.337 | 0.538 | 0.610 | 0.656 |\n| + embeddings | 0.318 | 0.532 | **0.627** | **0.705** |\n\n**What the numbers say, plainly.** Recall is strong and rank-1 is the weakness —\nLongMemEval R@10 0.983 vs R@1 0.590 — which is why figures here are quoted at R@5 and\nwhy an agent consuming these results should read a top-5 list, not trust rank 1. The\nsingle biggest quality lever measured is the embedding model itself: mxbai over nomic\nis worth more than every downstream tuning combined on document (BEIR) and session\n(LongMemEval) retrieval — and measures flat on LoCoMo's single-turn passages, so it\nis a scale effect, not magic. A cross-encoder reranker is available (`rerank` in config) but earns its keep only\nfor rank-1 consumers without embeddings — stacked on embeddings it *loses* recall on\nboth public benchmarks, so leave it off unless that trade is yours. Full analysis,\nincluding the failed experiments and the defect that benchmarking caught:\n[`docs/evaluation.md`](docs/evaluation.md).\n\nLoreweave also ships an internal regression benchmark (`npm run eval`) over three\npurpose-built vaults — including a temporal-perturbation test where the shipped config\nscores **100% consistency vs BM25's 0%**, gated in CI on every push. Internal corpora\nare good for regression and worthless as proof, so the details live in\n[`docs/evaluation.md`](docs/evaluation.md) rather than here.\n\n## Scale\n\nMeasured, like the quality numbers — `npm run scale` reproduces this on your own\nmachine (synthetic vaults, 3 blocks per note, dense interlinking):\n\n| notes | blocks | entities | edges | full index | incremental | search p50 | p95 | dream | heap |\n|---|---|---|---|---|---|---|---|---|---|\n| 1 000 | 3 000 | 2 766 | 17 k | 1.2 s | 32 ms | 3 ms | 4 ms | 0.2 s | 63 MB |\n| 5 000 | 15 000 | 13 766 | 85 k | 6.1 s | 165 ms | 9 ms | 12 ms | 1.0 s | 145 MB |\n| 20 000 | 60 000 | 55 016 | 339 k | 22.5 s | 656 ms | 38 ms | 53 ms | 4.8 s | 333 MB |\n\nFull index scales at **0.93× per note** from 5 k to 20 k — linear or better, no\nsuperlinear step hiding in the middle. \"Incremental\" is one changed note, which is what\n`lore watch` actually does all day. Everything here is one process, one SQLite file, no\ndaemon — and search at 3-38 ms p50 is fast enough to sit inside an agent loop.\n\n## How it works\n\n```\nvault/*.md ──parse──▶ notes · blocks · wiki-links · tags · entities\n │ (incremental: mtime + content hash)\n ▼\n SQLite .lore/index.db ── disposable cache, rebuildable\n │\n ┌───────────────────┼────────────────────┐\n ▼ ▼ ▼\n graph (CSR) retrieval facts\n blocks ∪ entities BM25 + dense + PPR bitemporal, supersession,\n 2-iteration PPR → weighted RRF deterministic freshness,\n α = 0.5 → FSRS boosts aggregates\n └─────────┬─────────┴──────────┬─────────┘\n ▼ ▼\n dream (idle-time) CLI · MCP\n```\n\nDesign rules the code enforces:\n\n- **Files win.** User markdown is never mutated. The engine only appends, and only under\n `lore/`.\n- **Invariants in code, not prompts.** Schema, migrations, graph construction, and\n supersession are typed, versioned, and tested — no LLM re-specifies them at runtime.\n- **No LLM required anywhere in the core.** Indexing and retrieval use zero tokens.\n Language models are consumers of this engine, not dependencies of it.\n- **Everything is re-derivable.** A full rebuild reproduces byte-identical derived state\n (there's a test for that).\n\n## Research lineage\n\nEvery significant choice traces to 2024-2026 literature; the survey lives in\n[`docs/research/`](docs/research/).\n\n| Choice | Source |\n|---|---|\n| Dense-sparse fusion + PPR with dense reset probabilities | HippoRAG 2 (ICML 2025), [2502.14802](https://arxiv.org/abs/2502.14802) |\n| Shallow 2-iteration PPR, heterogeneous nodes | NodeRAG (2025), [2504.11544](https://arxiv.org/abs/2504.11544) |\n| Relation-free graph — no LLM triple extraction | LinearRAG (ICLR 2026), [2510.10114](https://arxiv.org/abs/2510.10114) |\n| No index-time community summarization | LazyGraphRAG (Microsoft, 2024) — same quality at 0.1% index cost |\n| Route/fuse instead of graph-everything | GraphRAG-Bench (ICLR 2026), [2506.05690](https://arxiv.org/abs/2506.05690) |\n| Bitemporal facts, invalidate-never-delete | Zep/Graphiti (2025), [2501.13956](https://arxiv.org/abs/2501.13956) |\n| Power-law forgetting, use-gated reinforcement | FSRS; RMM (ACL 2025), [2503.08026](https://arxiv.org/abs/2503.08026) |\n| Consolidation as idle-time work | Sleep-time compute (Letta, 2025), [2504.13171](https://arxiv.org/abs/2504.13171) |\n| Never let an LLM rewrite whole memory files | ACE (2025), [2510.04618](https://arxiv.org/abs/2510.04618) |\n| Computable facts for aggregation | User as Code (2026), [2606.16707](https://arxiv.org/abs/2606.16707) |\n| Fine-grained indexing + fact-augmented keys | LongMemEval (ICLR 2025), [2410.10813](https://arxiv.org/abs/2410.10813) |\n\n## Library use\n\n```ts\nimport { openContext, indexVault, search, assertFact, queryFacts, dream } from 'loreweave';\n\nconst ctx = openContext('/path/to/vault');\nawait indexVault(ctx.store, ctx.root);\nconst hits = await search(ctx, 'streaming compaction', { k: 5 });\nassertFact(ctx, { subject: 'Atlas', predicate: 'status', object: 'shipped', validFrom: '2026-08-01' });\nconst asOfMarch = queryFacts(ctx.store, { subject: 'Atlas', asOf: '2026-03-01' });\nconst report = dream(ctx);\nctx.close();\n```\n\n## Development\n\n```bash\nnpm install\nnpm test # 440 tests\nnpm run eval # retrieval benchmark vs BM25 baseline\nnpm run typecheck\nnpm run build\n```\n\nRequires Node ≥ 20. Single native dependency (`better-sqlite3`). Tested in CI on\nLinux, macOS and Windows across Node 20 and 22.\n\n## License\n\nMIT © Ambuj Upadhyay\n","readmeFilename":"README.md"}
![\"npm\"](\"https://img.shields.io/npm/v/loreweave\")
\n ![\"CI\"](\"https://github.com/lets-order-some-fries/loreweave/actions/workflows/ci.yml/badge.svg\"){kind=icon}
\n ![\"node](\"https://img.shields.io/badge/node-%E2%89%A520-brightgreen\"){kind=icon}
= 20\">\n ![\"MIT\"](\"https://img.shields.io/npm/l/loreweave\")
\n![\"loreweave](\"docs/demo.gif\")
\n