loreweave

Loreweave

Markdown vault 向けの時間軸対応ナレッジエンジンです。
ファイルをローカルで処理し、インデックス化、リンク、記憶、忘却、夢想を行います。

クイックスタート · できること · CLI · エージェントメモリ · ベンチマーク · 仕組み · 研究

---

多くのナレッジツールは書き込み専用です。せっせと情報を記録すれば、vault は大きくなっていきます。それなのに半年後には、書いたはずのことが見つかりません。検索が文章のキーワード検索にすぎず、情報が自動的に再浮上することも、昨年書いた内容が今では真実でなくなったことに気づく仕組みもないからです。

Loreweave は、そうした問題を解決するレイヤーです。Markdown のフォルダー（Obsidian またはプレーンな Markdown）を指定すると、ノートをもとにナレッジグラフ、二時点事実ストア、メモリモデルを構築します。そして、CLI を通じてユーザーに、MCP を通じて AI エージェントに提供します。

コードによって保証される、次の 3 つの約束があります。

• ファイルが優先されます。 ユーザーの Markdown は変更されません。エンジンが追記するのは lore/ の配下だけです。真実のソースは vault です。インデックスはいつでも削除できるキャッシュで、まったく同じ状態に再構築できます（それを検証するテストもあります）。
• コアには LLM が一切ありません。 インデックス作成と検索では、トークンを一切使わず、ネットワーク呼び出しも一切行いません。同じ vault、同じクエリなら、答えはいつまでも変わりません。
• 読み取れるメモリです。 エージェントが保存するすべての事実は、開いて編集し、git diff で差分を確認できる Markdown の行です。

クイックスタート

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

設定不要でネットワークも使いません。初期状態では BM25 とナレッジグラフの拡散活性化で動作します。必要に応じて、ローカル埋め込みを追加できます。

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

品質を重視する場合は mxbai-embed-large（670 MB）を、ディスク容量やインデックス作成速度をより重視する場合は nomic-embed-text（274 MB）を選んでください。どちらも、E5、BGE、Arctic ファミリーと同様に、必要なタスクプレフィックスが自動で適用されます。両者の実測差はベンチマークをご覧ください。埋め込みプロバイダーを使わない場合は、語彙検索とグラフ検索を組み合わせて取得します。それでも完全に機能します。

英語以外の vault にも対応しています。中国語、日本語、韓国語のテキストは、検索できるよう文字単位で分割され、その他の文字体系は書かれたとおりにインデックス化されます。

主な機能

1. 時系列を持つナレッジ。 事実には二時点があります。現実世界でその事実が成立していた期間（valid_from／valid_until）と、システムがそれを知った時点（recorded_at）です。矛盾する事実は上書きされず、置き換えとして記録されるため、履歴を引き続き検索できます。

$ 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 と loreweave は同じバイナリです。グローバルインストールでは両方を利用できます。 npx --allow-scripts=better-sqlite3 loreweave を実行すれば、インストールせずに利用できます。）

どちらの時間軸もクエリできるため、単なる履歴ではなく二時点データを扱えます。--as-of はその時点で何が真実だったかを問い合わせ、--as-known-at はその時点で何が信じられていたかを問い合わせます。事後に何かを知った場合に限って両者は食い違います。過去の判断が実際に何を根拠としていたのかを再構成したいのは、まさにそういうときです。

$ 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]

どの事実を優先するかは決定論的に（有効時刻が新しいものを優先し、出典情報をタイブレーカーとして）決まり、どちらが新しそうかを言語モデルに尋ねることはありません。また、どんな項目でも、その履歴全体を1つのコマンドで確認できます。値の変更を時系列順にマージし、それに言及する日付付きの文章と一緒に表示します。

$ 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]

時間グラフシステムでは、取り込み時にあらゆるドキュメントをLLMで処理してこれを構築します。ここでは置き換えの連鎖がずっと維持されているため、読み取り時の結合だけで済みます。LLMもネットワークも不要で、毎回同じ結果が得られます。

2. 単語だけでなく、つながりをたどる検索。 クエリでは、BM25、密な類似度（設定時）、ボルト独自のグラフに対するPersonalized PageRankを組み合わせます。グラフにはwikiリンク、共有エンティティ、タグ、共起が含まれます。2ホップ先の近傍は、クエリと共通の語彙がなくても見つかり、各結果にはその理由が示されます。

• data/glacier-dataset.md#@0  (0.0327)  ⟨via amara osei⟩
  The Glacier Dataset holds meltwater sensor readings from 2019-2024.

3. 動態を持つメモリー。 各文章には、べき乗則による忘却曲線に基づくFSRS形式の安定性と想起可能性が付与されます。実際に使われた文章は、検索されただけの文章より減衰が遅くなります。重要でありながら薄れつつあるナレッジは、ひそかに劣化させるのではなく、レビュー用に提示します。削除されるものはありません。

4. 夢を見ます。 lore dream は、アイドル時間にボルトを確認して、重複する文章、矛盾する事実、古いナレッジ、明らかに関連があるのにノート間で欠けているリンク、孤立した項目を報告する統合処理です。--apply を付けると、ダイジェストとレビューキューを書き込みます。追記専用で、lore/ の下に保存されます。 文章を書き換えることはありません。LLMによるファイル全体の書き換えは、書き換えるたびに細部がひそかに失われ、ファイルの内容が崩れてしまうという既知の失敗パターンです。そのため、このアーキテクチャでは禁止しています。

5. 検索では答えられない質問。 集計、グループ化、日付範囲のクエリは、埋め込みの雰囲気読みではなく、ファクトストアに対する決定論的なSQLとして実行されます。

$ lore count --predicate trip_to --since 2025-01-01 --until 2025-12-31
    2  Japan
    1  Kenya

6. 事実はフォームではなく、ノートから取り出します。 - [fact] X :: y :: z を手作業で書く人はいないため、抽出機能は、ボルトですでに使われている規則を活用します。

status: shipped              # frontmatter
- owner:: Priya              # Dataview inline field
- [location] Hyderabad       # Basic Memory observation

曖昧さのないフィールド構文だけが自動的に受け付けられます。- **Owner:** Priya のような文章形式は、エンティティノートでは正確でも、レポートノートではノイズになりやすいため、オプトイン方式（facts.extract: "all"）です。あるいは、エージェントが lore_propose_facts で候補を確認し、正しい事実を登録できます。判断はインデックスに含めません。

7. 時間とは、ファイルを保存したときではなく、出来事が起きたときです。 --since と --until は、コンテンツの時刻で絞り込みます。対象となるのは、フロントマターの日付、日付付きファイル名（2025-03-14-standup.md）、または本文中の日付です。ノートに固有の日付がない場合に限り、ファイルの更新時刻を使用します。lore watch がインデックスを最新に保つため、再インデックスを忘れる心配はありません。

8. エージェント向けに構築。 MCP サーバーが15個の型付きツールを公開するため、Claude Code、Cursor、その他のMCPクライアントがボルトを永続的なメモリーとして利用できます。セッションの継続性は言い換えではなく、クエリで実現します。lore resume は、記録時刻から計算した、エージェントが最後に接続してからの変更点を正確に返します。

$ 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

前のセッションをLLMで要約する方法では、言い換えが混入します。こちらは決定論的な差分です。詳しい設定については、エージェントのメモリーをご覧ください。

CLI

コマンド	機能
lore init	デフォルト設定で .lore/ を作成します
lore index [--full] [--no-nlp] [--rebuild-similar]	vault からインデックスへの差分同期を行います
lore search <q> [-k] [--since] [--until] [--tag] [--folder] [--json]	出典情報付きのハイブリッド検索を行います
lore ask <q>	抽出型の回答を返します：現在の事実と上位の文章（LLM は不要です）
lore facts [--subject] [--predicate] [--as-of] [--as-known-at] [--history] [--limit]	事実ストアを検索します（--limit で別の値を指定しない限り 200 行です。上限に達したリストには、省略された件数が表示されます）
lore timeline <entity> [--since] [--until]	時系列の履歴を表示します：事実の変更と日付付きの言及を統合します
lore resume [--since]	前回の再開以降の変更を表示します：ノート、事実、置き換え
lore review [--threshold] [--limit]	重要でありながら見過ごされつつある、再確認またはアーカイブする知識を表示します
lore assert <s> <p> <o…> [--valid-from]	事実を記録します（ジャーナルに記録され、既存の事実に取って代わります）
lore invalidate <s> <p>	スロット内の現在の事実を終了します
lore count [--predicate] [--group-by] [--since]	事実の履歴を集計します
lore capture <text…>	タイムスタンプ付きの行を lore/inbox.md に追加します
lore dream [--apply]	統合処理を行い、任意でダイジェスト／レビューキューを作成します
lore watch	vault の変更に応じて自動的にインデックスを再作成します
lore mark-used <note> [anchor]	役に立った文章を強化します
lore graph export --format json|graphml|dot	グラフをエクスポートします
lore doctor	ヘルスチェックを行います：リンク切れ、整合性、カバレッジ
lore stats	vault の統計情報と上位のエンティティを表示します
lore serve --mcp	stdio で MCP サーバーを起動します

エージェントのメモリとして使う（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"]
    }
  }
}

--allow-scripts 引数は npm 12 用です。要件では、この引数について、また npx がすでにこの引数なしで行ったインストールを削除する方法について説明しています。

ツール	エージェントが得られるもの
lore_search	出典情報と時間フィルターを備えたハイブリッド検索
lore_context_pack	1 回の呼び出しで取得できるセッションコンテキスト：関連する文章＋現在の事実＋最近の変更
lore_read_note	パスで指定したノートの全文
lore_assert_fact / lore_invalidate_fact	事実の記録／終了 — ジャーナル形式で記録され、置き換え可能で、破壊的な変更は行われません
lore_query_facts	特定時点の事実クエリ（asOf、asKnownAt、履歴）
lore_timeline	エンティティの事実と文章を統合した時系列
lore_resume	エージェントが最後に接続してからの変更内容
lore_review	再提示する価値のある、重要度は高いものの薄れつつある文章
lore_aggregate_facts	事実の履歴を対象にした件数集計／グループ化
lore_capture	タイムスタンプ付きの行を受信箱に追記
lore_mark_used	強化シグナル：この文章が実際に役立ったことを示します
lore_propose_facts	エージェントが確認して記録するための抽出候補
lore_dream_report	統合レポート（重複、矛盾、古い項目、孤立した項目）
lore_index	再インデックスを実行

MCP 経由で記録された事実は、lore/journal/YYYY-MM-DD.md に読みやすい Markdown として書き戻されるため、エージェントのメモリを開いて編集し、git diff で確認できます：

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

.lore/ を削除して再インデックスすると、すべての事実とエッジがそれらのファイルから再構築されます。

- [fact] 行はどのノートからも再生されますが、source= 属性が読み戻されるのは、loreweave が書き込む唯一のパスである lore/journal/ の下だけです。通常のノートに同じ行があれば、事実は extracted として記録されます。ノートには何かを記述できますが、あなたが述べたとは記録できません。

ホスト型メモリサービス（Mem0、Zep）との比較：これらのサービスは書き込み時に LLM を実行して情報を抽出・要約し、独自のストアに保存します。一方、loreweave はコアでモデルを実行せず、メモリをバージョン管理下のファイルに保持し、すべての検索結果を再現可能にします。その代わり、これらのサービスは抽象的な要約を行いますが、このエンジンは意図的に行いません。公開されているベンチマークに対する検索品質は以下のとおりです。ただし、公開されているエージェントメモリの数値の多くは、LLM を使ったエンドツーエンドの QA を測定しており、検索とは異なる指標であるため、記載の注意点も確認してください。

ベンチマーク

ここに掲載するのは、関連性ラベルをこのプロジェクトの関係者が選んでいない、サードパーティー製のベンチマークです。loreweave の数値はすべて検索指標です。証拠を見つけるものであり、回答を書くものではありません。そのため、検索の後に言語モデルを配置したシステムが示す、エンドツーエンドの QA 精度とは比較できません。数値を再現する方法はこちらをご覧ください：docs/benchmarks.md。注意点を明記した分野別の比較はこちらです：docs/scoreboard.md。

LongMemEval_S（ICLR 2025）— 各質問に約 50 セッション分のチャット履歴がある 500 件の質問から、証拠を含むセッションを見つけます。セッション単位の再現率、全 500 件の質問：

構成	R@1	R@5	R@10
モデル不要（埋め込みなし、ネットワーク接続なし）	0.552	0.899	0.943
+ 埋め込みと 8 ターン単位のチャンク化	0.590	0.959	0.983

同じタスクに対するサードパーティーのベンチマークでは、BM25 単独で R@5 86.2%、BM25 とベクトルのハイブリッドで 95.2%、ベクトルのみのシステムで 96.6% という結果が報告されています。比較する前に注意点が 1 つあります。先方の指標では、正解セッションのいずれか 1 つが取得されれば質問を 1 と評価しますが、こちらでは、見つかった正解セッションの割合を評価します。つまり、こちらの定義のほうが厳しいため、システム間の差が 1 ポイント未満の場合は誤差として扱ってください。その点を踏まえると、loreweave は 95.9% でハイブリッドを上回り、ベクトルのみのシステムにわずかに届かない水準です。ローカルモデルを使い、ネットワーク接続なしで、必要に応じてフォールバックできる語彙インデックスも備えています。

BEIR / SciFact — 科学論文の要約 5 183 件と主張 300 件を対象に、nDCG@10 で評価します（ランキング品質を示す指標で、関連文書が上位に並ぶほど高く評価されます）。

構成	nDCG@10	Recall@10
BM25 ベースライン（BEIR 論文、Anserini）	0.665	—
loreweave、モデル不要	0.681	0.817
loreweave + nomic-embed-text	0.727	0.865
loreweave + mxbai-embed-large	0.742	0.884

LoCoMo — 長い会話 10 件と、証拠ラベル付きの質問 1 982 件を対象に、ターン単位の再現率を評価します。比較可能なサードパーティーの検索指標はありません（公開されている LoCoMo の結果は LLM による QA 精度です）。そのため、これらの数値は比較ではなく目標値として示します。

	R@1	R@5	R@10	R@20
モデル不要	0.337	0.538	0.610	0.656
+ 埋め込み	0.318	0.532	0.627	0.705

数値が示すことを率直に説明します。 再現率は高く、1 位の順位付けには課題があります。LongMemEval の R@10 は 0.983 ですが、R@1 は 0.590 です。そのため、ここでは R@5 の数値を示しており、これらの結果を利用するエージェントには、1 位だけを信頼するのではなく、上位 5 件のリストを読むようにしてください。測定された品質向上の要因として最も大きいのは、埋め込みモデルそのものです。文書（BEIR）およびセッション（LongMemEval）の検索では、mxbai は nomic を上回り、その差は後段の調整をすべて合わせたものより大きくなります。一方、LoCoMo の単一ターンの文章では両者の差はなく、これは魔法ではなく規模による効果です。クロスエンコーダーの再ランキング機能（設定の rerank）も利用できますが、役立つのは埋め込みなしで 1 位の結果を使う場合に限られます。埋め込みと組み合わせると、公開ベンチマークの両方で再現率が低下するため、そのトレードオフが必要な場合を除いて無効にしてください。失敗した実験や、ベンチマークで発見された不具合を含む詳細な分析はこちらをご覧ください：docs/evaluation.md。

Loreweave には、専用に構築した 3 つのボールトを対象とする内部回帰ベンチマーク（npm run eval）も用意されています。これには、同梱の設定が BM25 の 0% に対して**一貫性 100%**を達成する、時間的摂動テストも含まれており、プッシュのたびに CI で実行されます。内部コーパスは回帰テストには有用ですが、性能の証明にはなりません。そのため、詳細はここではなくdocs/evaluation.mdに記載しています。

規模

品質の数値と同様に計測しています。npm run scale を実行すると、手元のマシンでも再現できます（合成ボルト、ノートあたり3ブロック、高密度な相互リンク）。

ノート	ブロック	エンティティ	エッジ	全件インデックス	差分更新	検索 p50	p95	夢	ヒープ
1 000	3 000	2 766	17 k	1.2 s	32 ms	3 ms	4 ms	0.2 s	63 MB
5 000	15 000	13 766	85 k	6.1 s	165 ms	9 ms	12 ms	1.0 s	145 MB
20 000	60 000	55 016	339 k	22.5 s	656 ms	38 ms	53 ms	4.8 s	333 MB

全件インデックスは、5 k から 20 k まで、ノートあたり 0.93 倍のペースでスケールします。線形かそれ以上で、途中に超線形な段階はありません。「差分更新」は変更されたノート1件を指し、lore watch が実際に行う処理です。ここでの処理はすべて単一プロセス、単一の SQLite ファイルで実行され、デーモンは不要です。検索の p50 が 3～38 ms なので、エージェントのループ内で使うにも十分な速度です。

仕組み

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

コードで徹底されている設計ルール：

• ファイルを優先します。 ユーザーの Markdown は変更されません。エンジンは追記のみを行い、その対象も lore/ 以下に限られます。
• 不変条件はプロンプトではなくコードで定めます。 スキーマ、マイグレーション、グラフ構築、置き換え処理は、型付けされ、バージョン管理され、テストされています。LLM が実行時に再定義することはありません。
• コアのどこにも LLM は必要ありません。 インデックス作成と検索ではトークンを一切使いません。言語モデルはこのエンジンの利用者であり、依存関係ではありません。
• すべて再導出できます。 全件再構築すると、導出された状態がバイト単位で完全に一致します（これを検証するテストがあります）。

研究の系譜

重要な選択はすべて、2024～2026年の文献に基づいています。調査資料は docs/research/ にあります。

選択	出典
密・疎の融合 + 密なリセット確率による PPR	HippoRAG 2（ICML 2025）、2502.14802
浅い2回反復の PPR、異種ノード	NodeRAG（2025）、2504.11544
関係を持たないグラフ — LLM によるトリプル抽出なし	LinearRAG（ICLR 2026）、2510.10114
インデックス作成時のコミュニティ要約なし	LazyGraphRAG（Microsoft、2024）— インデックス作成コスト0.1%で同等の品質
グラフですべてを処理せず、ルーティングと融合を使用	GraphRAG-Bench（ICLR 2026）、2506.05690
二時点の事実、削除せず無効化	Zep/Graphiti（2025）、2501.13956
べき乗則による忘却、使用に応じた強化	FSRS、RMM（ACL 2025）、2503.08026
統合をアイドル時間の処理として実行	Sleep-time compute（Letta、2025）、2504.13171
LLM にメモリファイル全体を書き換えさせない	ACE（2025）、2510.04618
集約に利用できる計算可能な事実	User as Code（2026）、2606.16707
きめ細かなインデックス作成 + 事実を補強したキー	LongMemEval（ICLR 2025）、2410.10813

ライブラリの利用

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();

開発

npm install
npm run build     # the stdio-server tests run the built CLI, and skip without it
npm test          # 546 tests
npm run eval      # retrieval benchmark vs BM25 baseline
npm run typecheck

要件

Node 22 以降が必要です。CI では Linux、macOS、Windows 上で Node 22、24、26 を使ってテストしています。唯一のネイティブ依存関係である better-sqlite3 は、Node 22、24、25、26 では macOS、Linux、Windows 用のビルド済みバイナリからインストールされるため、コンパイラーは不要です。Node 23 用のバイナリはないため、npm がソースからコンパイルします。この場合、C++ ツールチェーンが必要です。

npm 12 は、指示がない限り依存関係のインストールスクリプトを実行しません。better-sqlite3 はそのスクリプト内でバイナリを取得するため、--allow-scripts=better-sqlite3 を指定しないと、インストール自体は成功しますが、インデックスを開くすべてのコマンドが「Could not locate the bindings file」というエラーで失敗します。Node 22、24、26 に同梱されている npm 10 と 11 では、特別な指定は不要で、npm i -g と npx でこのフラグを指定できます。

• npm i -g と npx ではこのフラグを指定できます。クイックスタートとMCP 設定を参照してください。
• npx は、フラグを追加した後も、フラグなしでインストールしたものを再利用し続けます。npm cache npx ls で該当するインストールを見つけ、npm cache npx rm <key> で削除してください。
• プロジェクト内（自分のプロジェクトでも、このリポジトリのクローンでも）では、npm 12 はこのフラグを受け付けません。Node 24 と 26 に同梱されている 11.16 以降の npm 11 も同様です。npm 11 はフラグがなくてもスクリプトを実行します。npm 12 では、代わりに npm approve-scripts better-sqlite3 でスクリプトを承認してください。これにより、package.json の allowScripts に記録されます。その後、npm rebuild better-sqlite3 を実行してください。

ライセンス

MIT © Ambuj Upadhyay