RAWThink

RAWThink

AI との思考パートナーシップのための永続メモリです。意見をぶつけ合えるナレッジグラフ、これまでのすべてのセッションを横断する検索、そして決めたことだけでなく、却下したことも記録します。

Claude Code 向けの MCP サーバーです。Python 製でローカルに動作し、クラウドは使いません。

---

課題

AI との会話は、毎回何もないところから始まります。同じ背景情報を説明し、同じ結論を導き直し、すでに下した決断を再発見します。そして、その結論に至った思考は、ウィンドウをスクロールした瞬間に失われます。

チャット履歴では解決しません。履歴は会話の記録にすぎません。必要なのは構造です。どのアイデアが結びついているのか、どの信念をその後捨てたのか、どの代替案を検討して却下したのか、そしてその理由です。

RAWThink は、その構造を 3 つの層で保持します。ファイルはすべて自分で所有できます。

機能

すべてのセッションとメモを横断するハイブリッドセマンティック検索 — BGE-M3 の密ベクトルと BM25 の疎ベクトルを RRF で統合します。「自由意志についてどう考えていた？」と尋ねれば、キーワードの一致ではなく、該当する文章が得られます。

時間情報を持つナレッジグラフ — 観察事項には日付とステータスが記録されます。信念には無効化のマークを付け、後継となる信念にリンクできます。そのため、アーカイブには現在の考えだけでなく、以前の考えも残ります。

セッションのライフサイクル — 会話を書き出し、グラフにエンティティを抽出し、次のセッションが自動で読み込む引き継ぎメモを作成する終了コマンドを備えています。

アクティベーション減衰 — 使われない知識は約 23 日の半減期で薄れ、アクセスされた知識は活性を保ちます。古い情報もそのまま残りますが、今取り組んでいる内容を押しのけることはなくなります。

---

クイックスタート

前提条件

• Python 3.10+
• Qdrant 用の Docker — または、組み込みモードを使う場合は QDRANT_PATH を設定
• bge-m3 を導入した Ollama：ollama pull bge-m3

インストール

pip install rawthink-mcp
rawthink-install                 # creates ~/rawthink-vault with everything inside
cd ~/rawthink-vault
docker compose up -d             # starts Qdrant

rawthink-install は、ボールトの構成、CLAUDE.md、THINKING_DIRECTIVES.md、SETUP.md、docker-compose.yml、および /rtclose コマンドを書き込みます。場所を変更する場合は rawthink-install --vault ~/my-vault を使用してください。

Claude Code に登録する

claude mcp add --scope user rawthink -- rawthink-mcp

インストールを確認する

rawthink-doctor

9 項目をチェックし、各失敗項目に修正方法を表示します。対象は、ボールト、グラフスキーマ、BM25 の状態形式、Qdrant、インデックスのカバレッジ、ベクトルの次元数、Ollama、MCP の登録です。

特に知っておきたいのは、インデックスのカバレッジチェックです。インデックス作成が途中で止まっても、コレクションは正常に見えることがあります。コレクションは存在し、ポイントもあり、クエリを実行すれば結果が返ります。しかし、その結果はボールトの一部から得られたものであり、それを知らせてくれるものはほかにありません。

0.x からアップグレードする場合

1.5.0 ではグラフスキーマが変更され、2.0.0 では疎インデックスが変更されています。 何かを書き込む前に、グラフを移行してください。

python -m rawthink_mcp.migrate --path vault/memory.jsonl --guess-domains --heal-dangling

これはドライランです。変更内容を表示するだけで、何も書き込みません。レポートを確認してから、--apply を付けて再実行してください。最初にタイムスタンプ付きのバックアップが作成されます。

次に、BM25 の用語 ID が変更されているため、検索インデックスを再エンコードします。

reindex(full=True)

通常の再インデックスでは、変更のないチャンクはスキップされ、古いエンコードが残ります。まだ対応が必要な場合は rawthink-doctor が知らせてくれます。

変更内容とその理由については、CHANGELOG.md を参照してください。

---

最初のセッション

> search_thoughts("what have I decided about caching?")

> record_decision(
    name="api/cache: read-through",
    domain="software",
    decided="read-through cache in front of the read model",
    because="the write path is already the bottleneck; adding invalidation there costs more",
    rejected=["write-through — couples the write path to cache health",
              "no cache — p99 was 400ms against a 200ms SLO"]
  )

/rtclose で終了します。会話を書き出し、残す価値のある情報をグラフに抽出し、次回のための引き継ぎメモを残します。引き継ぎメモは、次のセッションで自動的に読み込まれます。

---

スキーマと、その設計理由

この部分を理解しておく価値があります。数か月ではなく何年にもわたって、グラフをクエリ可能に保つ仕組みだからです。

ロールと対象は別のフィールドです

entityType は、このノードがどのようなロールを担うかを示します。次の10種類から選びます。

type	用途
decision	選択肢を退けたうえで行った選択
concept	アイデア、理論、モデル、類推
finding	発見または測定されたもの — バグ、結果、監査
rule	従うべき、長期的に有効な制約またはパターン
open-question	未解決で、証拠を待っているもの
artifact	プロジェクト、ツール、ドキュメント、機能、ソース
insight	物事の見方を変えた気づき
task	実施予定の作業単位
event	ある時点で起きたこと
thing	直接名前が挙げられた人、物体、物質

domain は、何を対象としているかを示します。software、music、 history、philosophy、health、writing、neuro、finance、 personal、galaxy です。

これらを分けるのは、単なる整理整頓ではありません。1つのフィールドに両方を持たせると、対象ごとにタイプが1つずつ増えていきます。実際に、あるボルトではこの方法でタイプが46種類に達し、saglik-bulgusu、teknik-karar、bug-pattern が karar と並ぶようになりました。その時点で何もフィルタリングできません。どの2つのエントリも、タイプの意味が一致しないからです。

未知の関係タイプは警告ではなく拒否します

正規の語彙は、supports、contradicts、evolved_into、depends_on、 exemplifies、part_of、caused_by、enables、supersedes、related_to、 investigates、informs、uses です。

近い同義語は自動的に統一されます — connected_to → related_to、aspect_of → part_of。それ以外はすべてエラーになります。

以前のバージョンでは、未知のタイプを警告付きで受け入れていました。しかし、警告に対処するものはなく、固有のタイプが56種類も蓄積しました。書き込みを通してしまう警告は、反対の口調で書かれた許可の判断です。

認識論的ステータスの既定値は unknown です

assertion、hypothesis、speculation — 明記されていない場合は unknown です。

unknown とするのは意図的です。セッションで何かが確立されていないのに、それを assertion として記録すると、誰も述べていない主張を事実として格上げしてしまいます。移行でも同じルールに従い、認識論的フィールドのない144個のエンティティは assertion ではなく unknown になりました。

削除せず、修正します

> revise(entity_name="api/cache: read-through",
         observations=["read-through cache in front of the read model"],
         superseded_by="moved to write-through after the read model split",
         superseding_entity="api/cache: write-through")

古い観察内容には無効化の印を付け、日付を記録し、置き換えた内容にリンクします。削除ツールもありますが、既定のエージェント向けプロファイルには含まれません。過去の判断を自ら忘れるアーカイブでは、保存された目的の問いに答えられないからです。

決定では却下した内容を記録します

record_decision は、decided、because、rejected をそれぞれ個別にクエリできる観察内容として保存します。却下した選択肢こそ、残しておく価値がある部分です — 選ばれた内容はコードに永遠に残りますが、検討して却下した内容はほかのどこにもありません。6か月後に尋ねられるのは、まさにその問いです。

---

MCP ツール

ツール定義はセッションの最初のトークンからコンテキストウィンドウに入るため、ツールの一覧は呼び出しごとではなく、常時発生するコストになります。プロファイルでは、そのステップに必要なものだけを読み込みます。

RAWTHINK_TOOL_PROFILE=recall   #  4 tools,  ~900 tokens — read-only
RAWTHINK_TOOL_PROFILE=record   #  5 tools, ~1750 tokens — the write path
RAWTHINK_TOOL_PROFILE=full     # 17 tools, ~4200 tokens — everything (default)

アクティブなプロファイルにないツールも、通常の関数として利用できます — CLI やテストから呼び出せます。単に、そのツールを呼び出さないエージェントの目の前には表示されないだけです。

検索

ツール	機能
search_thoughts	ハイブリッド検索です。mode="overview" では、セッションごとに1行表示します
get_session	IDを指定してセッションの全内容を取得します
store_thought	簡単なメモをqnoteとして保存します
reindex	Qdrantにボルトを再インデックスします

グラフ — 読み取り

ツール	機能
search_nodes	範囲を限定した検索です。domain と entity_type で絞り込み、total_matched と truncated を報告します
open_nodes	特定のエンティティとその関係を取得します
read_graph	要約モードを備えた、ページネーション対応のグラフ全体の読み取りです

グラフ — 書き込み

ツール	機能
record	検証済みのアトミックな呼び出しで、エンティティ、関係、観察事項を記録します
record_decision	却下した代替案とともに決定を記録します
revise	観察事項を置き換え済みとしてマークし、置き換えた内容へのリンクを設定します
create_entities · create_relations · add_observations	より低レベルの同等機能
invalidate_observations	関係のリンクを付けずに信念を修正します
delete_entities · delete_observations · delete_relations	full プロファイルでのみ使用できます

record() は、書き込みを行う前にバッチ全体を検証します。一部だけ有効な バッチは何も書き込みません。誰も望んでいない状態のグラフを残すよりも、 書き込みを拒否するほうがよいためです。関係が指せるのは、すでに存在する エンティティ、または同じ呼び出しで作成されるエンティティのみです。

各ツールにはMCPアノテーション（readOnlyHint、destructiveHint、 idempotentHint）が付いているため、ホストは削除と検索を区別できます。

---

アーキテクチャ

Claude Code
    │  MCP (stdio)
    ▼
rawthink-mcp
    ├── search  ──►  Qdrant        dense (BGE-M3) + sparse (BM25), RRF fusion
    ├── graph   ──►  memory.jsonl  entities, relations, temporal observations
    └── export  ──►  vault/        sessions, qnotes, handoffs as markdown
                         │
                    Ollama (bge-m3)

すべてローカルで動作します。ボルトはYAMLフロントマター付きのプレーンなMarkdownです。 Obsidianで開けば視覚的に閲覧でき、プラグインは必要ありません。

グラフにJSONLを使う理由

人が読みやすく、Gitで差分を確認でき、依存関係もありません。ファイルを開いて 内容を読めます。また、変更時には意味のある差分を確認できます。推論を記録するための ものなので、これは重要です。

その代わり、読み込みには時間がかかります。読み取りのたびにファイル全体を解析します。 数百個程度のエンティティなら問題ありませんが、増えるにつれて遅くなります。 数万個を超えたら、次の選択肢は明らかにSQLiteです。

---

セッションのライフサイクル

session start          handoff loads automatically (SessionStart hook)
      ↓
  think together
      ↓
   /rtclose            export → extract entities → write handoff → update MEMORY.md

/rtclose は会話をクリーンなMarkdownにエクスポートし、record() を通じて エンティティと関係を抽出し、プロジェクト単位の引き継ぎ情報を書き込み、 MEMORY.md を更新します。

ライフサイクルコマンドを現在利用するにはClaude Codeが必要です。検索およびグラフの ツールは、どのMCPクライアントでも動作します。

---

設定

設定	環境変数	デフォルト
Vault のパス	RAWTHINK_VAULT	../vault
ナレッジグラフファイル	MEMORY_FILE_PATH	<vault>/memory.jsonl
Qdrant の URL	QDRANT_URL	http://localhost:6333
Qdrant の埋め込みパス	QDRANT_PATH	—（Docker をスキップするには設定してください）
Ollama の URL	OLLAMA_URL	http://localhost:11434
埋め込みモデル	OLLAMA_MODEL	bge-m3
ツールプロファイル	RAWTHINK_TOOL_PROFILE	full
トルコ語の正規化	RAWTHINK_TURKISH_NORMALIZATION	false
評価セット	RAWTHINK_EVAL_GT	tests/ground_truth.example.json

語彙 — ENTITY_TYPES、DOMAINS、RELATION_TYPES、RELATION_ALIASES — は rawthink_mcp/config.py にあります。ドメインの追加は1行の変更でできます。

---

カスタマイズ

CLAUDE.md — 思考を支援するパートナーの役割、口調、モードを定義します。

THINKING_DIRECTIVES.md — パートナーシップにおける規律を定めます。各ルールは、それを守れなかった経験を経て書かれています。独自のルールを追加してください。このファイルにとって唯一悪い状態とは、各ルールの存在理由を理解せずに従うことです。

どちらも rawthink-install によって Vault にコピーされます。リポジトリ内のコピーを編集した場合は、python scripts/check_templates.py を実行してください。インストーラーにはそれらが埋め込まれているため、同じ文書の2つのコピーは、気づかないうちに食い違ってしまいます。

---

既知の制限

率直に記載しています。長所だけを並べた README は、あまり役に立たないためです。

Ollama が利用できない場合、スパース検索のみになります。 埋め込みキャッシュは繰り返しのクエリには役立ちますが、フォールバックではありません。検索品質は目に見えて低下します。

正常なシャットダウンに対応しているのは POSIX のみです。 シグナルハンドラーは SIGINT／SIGTERM で Qdrant ディレクトリのロックとグラフファイルのロックを解放します。Windows には実質的な SIGTERM がありません。終了するクライアントは TerminateProcess を呼び出し、ハンドラーは実行されないため、強制停止するとロックが残ることがあります。Ctrl-C では引き続き正常に終了でき、rawthink-doctor が古いロックを報告します。

グラフのサイズに応じて読み込み時間が長くなります。 変更後の最初の読み込みでは、JSONL 全体を解析します。以降の読み込みでは、（mtime、size）をキーとするキャッシュを再利用します。

大規模なデータでの検索品質はベンチマークされていません。 以前ここに記載されていた検索指標は再測定されていなかったため、引き継いで掲載するのではなく削除しました。tests/search_quality.py は合成 Vault に対して実行され、MRR／nDCG を報告します。実際のデータにとって意味のある数値を得るには、RAWTHINK_EVAL_GT を独自の評価セットに指定してください。

---

ロードマップ

次の予定 — グラフの可視化、終了コマンドが Claude Code 固有にならないようにする MCP ネイティブなセッションライフサイクル、より多くの MCP クライアントへの対応、誰でも再生成できるデータで実行可能な検索ベンチマーク。

---

貢献

Issue やプルリクエストを歓迎します。

スキーマを変更する場合は、config.py、migrate.py のマイグレーション、セッション終了の手順もあわせて変更してください。これらは1つの契約を異なる角度から表したもので、まとめて編集しないと、気づかないうちに食い違ってしまいます。

docs/postmortem-bm25-term-drift.md は、その最もわかりやすい例です。2つの検索器を個別に評価するまで、あらゆる角度から問題がないように見えていた不具合です。

ライセンス

MIT