wikimoth

WikiMoth

点と点をつなぎます。いつでも同じ方法で。

wikimoth.com · pip install wikimoth

Claude とエージェントのための、決定論的でトークン消費が少なく、監査可能なメモリです。 WikiMoth に [[wikilink]] ノートのフォルダー（Obsidian の保管庫や、Claude 自身のメモリフォルダーなど）を指定すると、作成者が設定したリンクをたどり、フラット検索では見つけられない答えにたどり着き、その根拠となる正確なノートのつながりを示します。また、保管庫全体を貼り付ける場合と比べ、読み手に渡すトークンを約99％削減します。純粋な Markdown で動作し、GPU もベクトル DB も、検索処理中の LLM も必要ありません。

pip install wikimoth
wikimoth demo         # instant multi-hop recall over a bundled demo vault (no setup)

すでに [[wikilink]] の保管庫（Obsidian の保管庫やノートフォルダーなど）をお持ちですか？ WikiMoth に指定するだけで、キャプチャも待ち時間もなく、1つのコマンドで点と点をつなぐ全体像を表示できます。

wikimoth serve --vault /path/to/your/vault      # browse + "what memory fed this answer"
wikimoth recall --vault /path/to/your/vault "a connect-the-dots question"

Claude Code のセッションからメモリを作成したいですか？ キャプチャフックをインストールすると、実行して終了した各セッションが [[wikilink]] の保管庫に書き込まれます。

wikimoth install      # capture: turn your Claude Code sessions into a [[wikilink]] vault
wikimoth serve        # once you have captured sessions, browse them

---

Claude にコンテキストを自分で管理させるだけではだめですか？

その方法を正確にベンチマークしました。ノートフォルダーを参照し、自分のコンテキストを整理するエージェントは、マルチホップを含めて同じ答えに到達します（今回の実行では12問中12問）。ただし、そのためのコストがかかります。質問ごとにモデルとの往復が4〜6回、課金対象のトークン数がおよそ10倍になります。各ステップで、増え続ける会話記録を再送信するためです。WikiMoth はモデルを処理に介在させず、決定論的な1回の処理で同じノートのつながりを取得し、答えの根拠となる正確なノートを表示します。

_{再現可能な保管庫を使い、Claude Sonnet 4.6 で実施した、マルチホップ質問12問の実行結果です。約10倍という値は両方の方式で読み手を数えたものです。コーパス固有の結果であり、普遍的な法則ではありません。python scripts/run_agentic_benchmark.py を実行すると再現できます。詳しい内訳は正直な制約をご覧ください。}

---

WikiMoth を選ぶ理由

エージェントのメモリは、たいてい「メモフォルダー全体をコンテキストに貼り付ける」（コストがかかり、モデルは途中で混乱します）か、「LLM による要約付き類似検索」（情報が失われ、非決定的です。同じ質問でも、翌週には異なるメモが返されることがあります）のどちらかです。WikiMoth は別の方法を採用しています。メモ自体がストア（プレーンな Markdown）であり、グラフは人が作成します（自分の [[wikilinks]] を使うため、学習や変化に左右される埋め込みはありません）。そして、検索はモデルではなくコードで行うため、再現可能で、各メモが選ばれた理由を正確に確認できます。

	WikiMoth	BM25	Vector RAG	claude-mem	LLM Wiki (Karpathy)
関連情報をつなぐ（人が作成した [[links]] をたどるマルチホップ検索）	✅	❌	❌	❌	✅ (エージェント型)
決定的な検索（同じクエリ → 同じ結果）	✅	✅	✅	❌	❌
検索時に LLM を呼び出さない	✅	✅	✅	~	❌
監査可能なメモチェーン（回答を生成したメモを確認可能）	✅	~	❌	❌	~
直接検索の再現率@8（実際の Vault）	1.00	1.00	1.00	~	~
GPU 不要／ベクトル DB 不要／インデックスの構築不要	✅	✅	❌	~	✅
プレーンな Markdown のストア（任意のエディターで開ける）	✅	~	❌	❌	✅
Vault 全体のダンプと比較したトークン削減	✅ −99%	✅ −99%	✅ −99%	✅	~
決定的で API 不要の自動取り込み	✅	❌	❌	❌	❌
LLM なしでの整理（矛盾・重複・古い情報・置き換え）	✅	❌	❌	~	❌

_{LLM Wiki は WikiMoth と同様にリンクをたどり、ベクトル DB を使いませんが、LLM が Wiki を書き、読み取るため、検索はエージェント型です（再現可能ではなく、検索のたびに LLM を呼び出します）。一方、厳選されたページはより充実しています。~ = 一部対応／独立したベンチマーク未実施。}

優位性は再現率の高さではなく、組み合わせにあります。WikiMoth は基本的な機能ではフラット検索に匹敵しつつ、関連情報をつなぐ機能、決定性、監査証跡、プレーンな Markdown のストアを追加します。互角となる点と優位となる点の詳細は、正直な制限事項をご覧ください。

Karpathy の LLM Wiki との比較

WikiMoth は、Andrej Karpathy の LLM Wiki が広めた基盤、つまりベクトル DB を使わないプレーンな Markdown の [[wikilink]] メモを共有しつつ、エンジンを変えています。LLM Wiki のパターンでは、LLM が Wiki を書き、読み取ります。情報が豊富で出典が示されたページを作れますが、検索はエージェント型です（LLM の呼び出しが必要で、検索経路は再現できません）。WikiMoth はコードでエッジを計算し、LLM を介さない固定アルゴリズムで検索します → 毎回同じメモチェーンが返され、再現可能で監査できます。両者は競合するものではなく、互いを補完します。WikiMoth に Karpathy 方式の Wiki を指定すれば、その上で決定的なマルチホップ検索を行えます。（LLM Wiki より「優れている」と主張しているわけではありません。LLM Wiki はより充実したページを厳選し、WikiMoth は決定的に検索します。）

クイックスタート（読み取り）

from wikimoth import MemoryRAG, EchoReader

rag = MemoryRAG(reader=EchoReader())          # API-free default reader
rag.index("/path/to/your/wikilink/vault")     # notes → ~400-token chunks, graph built

chunks, tokens = rag.retrieve("a connect-the-dots question?", top_k=8)
print(f"{len(chunks)} chunks, {tokens} tokens to feed the reader")   # the headline win

# EchoReader is a deterministic stub for wiring/tests: it prints a diagnostic
# `[echo] ...` line, NOT a natural-language answer. Swap in ClaudeReader (below)
# for real prose. The retrieval + token numbers above are the same either way.
print(rag.answer("a connect-the-dots question?"))

実際の Claude の回答に置き換えます（構築時にのみ API にアクセスします）。

from wikimoth import MemoryRAG, ClaudeReader
rag = MemoryRAG(reader=ClaudeReader(model="claude-sonnet-4-6"))   # needs ANTHROPIC_API_KEY

回答の生成に使われたメモを確認：wikimoth serve

wikimoth serve                 # serves http://127.0.0.1:8765 (local-only)
wikimoth serve --vault PATH --port 8080

依存関係ゼロのローカル Web ビューアーです（標準ライブラリのみで動作し、Flask、JS フレームワーク、ネットワークは不要です）。

• メモの閲覧と検索、
• 人が作成した [[wikilink]] グラフ（リトリーバーがたどるものと同じエッジ）、
• そして最も重要な、「この回答の生成に使われたメモ」：質問を入力すると、WikiMoth が回答者に渡すメモチェーンを、チャンクごとのホップ距離、トークン数、Vault 全体のダンプと比較した −N% とともに正確に確認できます。検索のみで、LLM の呼び出しも API キーも不要です。決定的に動作します。

ストアはプレーンな Markdown なので、同じ Vault を Obsidian や VS Code で開くこともできます。このビューアーは便利な機能であり、利用を縛るものではありません。

エージェントのループ内：wikimoth mcp

wikimoth serveはあなた向けです。MCP サーバーはモデル向けです。Model Context Protocolを通じて同じ決定論的な検索を公開するため、あなたが手動でコンテキストを取得する代わりに、Claude自身が呼び出します。

# 1. install into the Python that runs your Claude Code
python -m pip install wikimoth

# 2. verify the command resolves (prints status, then exits)
python -m wikimoth status

# 3. register the MCP server with Claude Code
claude mcp add wikimoth -- python -m wikimoth mcp

重要なのはステップ2の確認です。python -m wikimoth statusがステータス行を出力すれば、python -m wikimoth mcpもClaudeで実行できます。3つのステップすべてで**同じpython**を使ってください（システムによってはpython3です）。一致させる必要があるのはこれだけです。

Node環境を使いたい場合や、Pythonをセットアップしていない場合は、ツールチェーンを合わせずに1行で実行できます。

claude mcp add wikimoth -- npx -y wikimoth-mcp

wikimoth-mcpランチャーは、WikiMothがインストールされたPythonを見つけます（またはその場でuvxを使ってインストールします）。さらに、クライアントの作業ディレクトリにある空のフォルダーをサーバーが読み込まないよう、Vaultのパスを渡し、MCPチャネルをそのまま引き継ぎます。同じnpx -y wikimoth-mcpを、どのmcpServers設定でもサーバーコマンドとして使えます（Claude Desktop、Cursor、Windsurf）。WIKIMOTH_VAULTにVaultを設定してください。

これでClaudeはrecall(query)ツールを使えるようになります。ノートにある内容を質問すると、Claudeはrecallを呼び出します。WikiMothは[[links]]をたどって、正確なノートの連鎖を返します（検索にLLMを呼び出さず、トークンを最小限に抑え、毎回同じ結果を返します）。Claudeはそれをもとに回答します。接続されたVaultを報告するstatusツールもあります。その他のMCPクライアントでは、サーバーコマンドにpython -m wikimoth mcpを使ってください（stdioトランスポート）。特定のVaultを指定するには--vault PATHを使います。

python -m wikimoth mcpは、パッケージがインストールされていればどこでも実行できる、移植性の高い形式です。コンソールスクリプトがPATHにあれば、wikimoth mcpだけでも動作します。標準ライブラリのみを使用しており、手書きのJSON-RPC 2.0 stdioサーバーで、MCP SDKへの依存はありません。

mcp-name: io.github.juliangeymonat-jpg/wikimoth

キャプチャ：セッション → ノート（書き込み側）

検索には[[wikilink]]を含むVaultが必要ですが、手作業で作るのは手間がかかります。wikimoth.captureはClaude Codeのライフサイクルフックをインストールし、各セッションを1つの決定論的なMarkdownノートに変換して、自動的にVaultを構築します。

重要な不変条件：ノートの[[wikilinks]]（グラフのエッジ）はコードによる照合（文字列／パスのマッチング）で計算され、モデルによって計算されることはありません。LLMは任意で要約文の下書きを作成できます（WIKIMOTH_LLM_PROSE=1）。ただし、出力された[[...]]はすべて取り除かれ、エッジとして解析されることはありません。そのため、グラフは再現可能で（同じセッション＋Vaultなら同じエッジ）、監査も可能です。デフォルトのキャプチャは完全に決定論的で、API呼び出しは一切行いません。

wikimoth install                 # writes 5 hooks into ./.claude/settings.json (absolute interpreter path)
wikimoth install --user          # ~/.claude/settings.json instead
wikimoth install --vault PATH    # choose where notes go (sets WIKIMOTH_VAULT)
wikimoth status                  # vault, note/session/buffer counts, hook state
wikimoth uninstall               # remove the hooks again

ライフサイクル：SessionStartでは最近のセッションをコンテキストに読み込み、UserPromptSubmit / PostToolUseではセッションをバッファリングし、Stop / SessionEndではノートを1つ書き込みます。キャプチャされたノートは、読み取りパイプラインがインデックス化するものと同一です。キャプチャと検索が一連の流れを完成させます。

メモリの健全性を保つ：衛生管理スイート

増えるだけのメモリは劣化します。メモは古くなり、2つのメモの内容が食い違い、同じ事実が重複して保存され、古い事実が置き換えられても整理されないことがあります。他のエージェントメモリツールは、LLM を使って古い状態を気付かれないうちに上書きすることで、こうした問題を解決します。WikiMoth には、問題を決定論的に明らかにし、決して何も削除しない6つのコマンドが用意されています。git が監査証跡になります。

コマンド	検出するもの	書き込み？
wikimoth conflicts	同じ事実について異なる値を主張する2つのメモ（型を考慮し、有効時間の精度を維持）	いいえ
wikimoth lint	リンク切れ、孤立したメモ、内容がほとんどないメモ、古いメモ、置換の循環	いいえ
wikimoth dedup	完全一致および類似した重複メモ（MinHash + LSH で検出し、完全な Jaccard 係数で確認）	いいえ
wikimoth decay	古く、リンクされることも思い出されることも少ない、使われなくなりつつあるメモ（確認待ちリスト。自動削除はしません）	いいえ
wikimoth recall --as-of <date>	過去の日付にメモリが主張していた内容（双時制のタイムトラベル。DB 不要）	いいえ
wikimoth supersede OLD NEW	事実を無効化して整理する。削除はしません	はい

いずれのコマンドにも、次の3つの原則が適用されます。

• 削除せず、無効化します。 supersede はメモに置換済みの印を付け、frontmatter で置換先にリンクします。古い本文は検索対象から外れますが、現在のメモへの [[link]] は有効なままです。そのため、古いメモに行き着いたクエリはそのまま新しいメモへ移動できます。rm されるものはなく、履歴は git に残ります。
• ツールが推測することはありません。 各コマンドはすべて候補を出力します。機械的に判断できない唯一の点、つまり2つのメモが本当に矛盾しているかどうかの判断は、ツールに組み込まず、呼び出し元のモデルに委ねます。そのため、出力は再現可能で、各候補が検出された理由を正確に確認できます。
• 双時制で、データベースは不要です。 recall --as-of 2026-01-01 は、frontmatter の有効期間だけを使って、その日に保管庫が主張していた内容を再現します。イベントログも、ベクトルストアも、移行も不要です。

これらは WikiMoth の他の機能と同じ不変条件を満たします。純粋な標準ライブラリのみを使用し、決定論的（出力がバイト単位で一致）で、単一の書き込みコマンド supersede を除いて読み取り専用、そして差分を確認できるプレーンな Markdown です。7つのコマンドは MCP 経由でも利用でき（list_conflicts、list_lint、list_duplicates、list_fading、supersede に加え、as_of／show_superseded が追加された recall）、エージェントは自分のメモリを整理された状態に保てます。

インストール

WikiMoth のコアは純粋な標準ライブラリのみ（dependencies = []）で構成されています。検索エンジン、チャンク分割、wikilink グラフ、パイプライン、キャプチャはすべて wikimoth/ に同梱されているため、追加のインストールも、GPU も、ベクトル DB も不要です。

pip install wikimoth
# optional extras:
pip install "wikimoth[hybrid]"          # optional BM25-seeded retriever variant
pip install "wikimoth[claude,tokens]"   # real Claude reader + exact tiktoken counts

追加機能：hybrid = BM25 を使った検索（rank_bm25） · claude = anthropic リーダー · tokens = 正確なトークン数（tiktoken） · dense = 密検索のベンチマーク用ベースライン · headroom = 可逆的な CCR 圧縮。

仕組み

検索 → 圧縮 → 読み込み。 index() は各ノートを約400トークンのチャンク（約50トークンの重複あり）に分割し、チャンクごとのノート識別情報を保持するため、[[wikilink]] グラフはチャンクをまたいでつながったままです（チャンク単位の複数ホップ検索）。GraphRetriever(source="wikilinks") は語彙的に一致する箇所を起点としてから、記述されたリンクをたどるため、質問と語彙的には類似していなくても、リンクでたどれる文章は検索されます。任意の圧縮ステージ（chopratejas/headroom を使った可逆的な CCR）によって、有料のリーダーに渡す前に文章をさらに短縮できます。headroom がインストールされていない場合、このステージは何も行わずに処理を続けます。

MEMORY.md のような純粋なナビゲーション用ハブ（目次に相当）は、グラフエッジのみとしてインデックス化できます（exclude_content のデフォルトは ("MEMORY.md",)）。その [[links]] はエッジを構築し、BFS の中継地点として機能しますが、ハブ自体のチャンクがリーダーに渡されることはありません。

各ステージは MemoryRAG(retriever=…, compactor=…, reader=…) でコンストラクターにより差し替えられるため、リトリーバー（例：BM25 を起点とする HybridRetriever）、コンパクター、リーダーを交換できます。

ベンチマーク：リーダーに渡すトークン数

wikimoth.benchmark.harness は、同じ保管庫と質問を使って、各方式でリーダーに渡すトークン数（実際に料金が発生するもの）を測定します。

方式	リーダーに渡す内容	状態
dump	保管庫全体	ベースライン
deterministic	wikilink グラフ検索	実装済み
deterministic_compacted	検索＋Headroom	実装済み
agentic	LLM が閲覧し、自身のコンテキストを整理	実装済み（Claude のツール使用）

デフォルトでは有料 API 呼び出しは実行されません。各方式のリーダーはすべて、API 不要の EchoReader をデフォルトで使用します。

正直な限界

WikiMothの価値は、実際のマルチホップ機能を備えた、決定論的で監査可能、トークン消費が最小限のプレーンなMarkdown形式のメモリであり、「BM25より優れた検索」ではありません。具体的には次のとおりです。

• −99％は、BM25との比較ではなく、保管庫全体をそのまま投入する場合との比較です（実際の356ノートの保管庫では約5k対約482kトークン）。調整済みのBM25-RAGでも約5kトークンを投入します。優位性があるのは、現実によくある方法（すべて貼り付ける／素朴なノート全体のRAG）に対してであり、しかも決定論的です。
• 一般的な実際の保管庫では、検索性能はBM25とほぼ同等です。 直接検索のrecall@8は1.00で同率です。マルチホップ／点と点をつなぐ優位性（フラット検索のスコアがゼロのとき、0％から最大100％へ）は、厳選されたリンクの多いコーパスで現れます。平均的な保管庫では、ハイブリッド方式がBM25より悪くなることはありませんが、再現率が必ず上回るわけではありません。
• 決定性は、静的な検索方式（BM25／密ベクトル方式も含む）に共通する性質です。WikiMothの決定性における優位性は、特にLLMが要約したメモリとの比較です（こちらは実行のたびに変わります）。
• モデルにコンテキストを自分で削らせる場合（agentic方式、Claude Sonnet 4.6を使った実際の実行、マルチホップの質問12件）と比べると、エージェントはマルチホップを含め、同じ回答に到達します（12/12）。違いはコストです。各ステップで増えていくトランスクリプトを再送するため、1つの質問あたり有料の往復が4〜6回発生し、課金対象のトークン数は約10倍になります。一方、WikiMothは検索ループ内でモデルを呼び出さず、決定論的な1回の処理と監査可能なノートチェーンで回答します。この倍率はコーパス固有のものであり、一般則ではありません。再現するには、python scripts/run_agentic_benchmark.pyを実行してください。

プラグイン対応とライセンス

MemoryRAG(retriever=…, compactor=…, reader=…)を使用します。デフォルトはGraphRetriever(source="wikilinks")／NoOpCompactor／EchoReaderです。小規模なProtocolを満たすものであれば、どれでも組み込めます。

Apache-2.0です。LICENSEをご覧ください。© 2026 Julian Geymonat.