Thoth-Mem

AIコーディングエージェント向けの永続メモリ

セッション、コンパクション、コンテキストリセットをまたいで、コーディングエージェントに永続的なプロジェクトメモリを提供します。

Thoth-Mem は、SQLite と FTS5 をバックエンドとするローカルファーストのMCPサーバーです。有用な決定、バグ修正、規約、セッションの継続性を保持し、エージェントが必要とするエビデンスだけを取得します。同じインストールには、CLI、オプションのHTTP API、対応コーディングハーネスのネイティブライフサイクル統合も含まれます。

グローバルスコープは現在のユーザーのハーネス設定を管理します。プロジェクトスコープは明示的であり、選択したプロジェクトとそのレシートツリーに限定されます。Engram、thoth-agents、または別のメモリ統合と重複する可能性があります。これは警告としてのみ扱ってください: thoth-mem は外部リポジトリを編集、無効化、削除、または書き込みすることはありません。

クイックスタート

Node.js 18以降が必要です。ネイティブセットアップは任意です: 手動のMCP接続には mcp コマンドだけが必要です。

公開済みパッケージを実行する

グローバルコマンドをインストールせずに、最新の公開済みMCPサーバーを起動します:

npx -y thoth-mem@latest mcp

これによりMCPサーバーとそのローカルHTTPブリッジが起動します。MCPトランスポートのみが必要な場合は --no-http を追加してください。新しいクライアント設定では明示的な mcp サブコマンドを使用してください。

ネイティブ統合はセットアップ後に永続的な thoth-mem コマンドを呼び出すため、ハーネスを設定する前にそのコマンドをグローバルにインストールまたは更新してください。最新の公開済みパッケージからセットアップ実装を npx で実行し、そのゼロ書き込みプランを確認してから適用します:

npx -y thoth-mem@latest setup codex --scope global --plan --json
npx -y thoth-mem@latest setup codex --scope global --json

別のサポート対象ハーネスでは、codex を opencode または claude に置き換えてから、そのハーネスを再起動します。setup を実行するだけでは npm パッケージはインストールまたは更新されません。

このリポジトリをインストールする

まだ公開されていないコミットをテストするには、リポジトリのフローを使用します:

pnpm install
pnpm run build
pnpm add -g .
thoth-mem version
thoth-mem setup codex --scope global --plan --json
thoth-mem setup codex --scope global --json

thoth-mem@latest には最新の公開リリースのみが含まれます。新しい未公開コミットを取得したら、再ビルドして pnpm add -g . を再実行してください。

既存のインストールを更新する

まずパッケージを更新します。ネイティブ統合がインストールされている場合は、そのセットアップを再実行して、コピーされたアセット、スキル、フック、管理対象の宣言が新しいパッケージバージョンに収束するようにします:

pnpm add -g thoth-mem@latest
npx -y thoth-mem@latest setup codex --scope global --plan --json
npx -y thoth-mem@latest setup codex --scope global --json

次に、ハーネスまたはMCPプロセスを再起動します。手動MCPユーザーは setup を必要としません。npx -y thoth-mem@latest mcp を再起動するだけで十分です。

セットアップはメモリデータベースとユーザー所有の設定を保持します。起動時に、欠落している設定フィールドがバックフィルされる場合がありますが、LM Studio モデルなどの明示的な値は選択されたままです。設定形式は "version": 1 のままです。公開インストールの場合は、現在のエディタでの検証とオートコンプリートのために、古い $schema URL をそのリリースバージョンに手動で更新してください。未公開のチェックアウトでは、リリース前に unpkg が変更を公開できないため、一致する検証にはこのリポジトリの config.schema.json を使用する必要があります。スキーマURLはランタイムの移行を制御しません。

埋め込みモデルの変更は、セットアップ操作ではなく設定操作です。必要に応じて embedding.provider、model、baseUrl、ネイティブの dimensions を編集してください。profile: "auto" はサポートされているモデルファミリーを解決します。thoth-mem を再起動し、変更された埋め込み系統にべき等なセマンティックインデックスの再構築をエンキューさせます。

Related MCP server: LumenCore

メモリループ

有用なエージェントワークフローは小さくて繰り返し可能です:

1. 永続すべき教訓を保存する。 現在のコンテキストを超えて残すべき決定、根本原因、規約、その他の明白でない事実には mem_save を使用します。

2. 狭く想起する。 mem_recall(mode="compact") から始め、有力な候補を mode="context" で展開し、完全な選択レコードを mem_get で取得します。

3. IDをもって再開する。 同じ安定した session_id と project を維持します。最近の継続性には mem_context、ルート所有のライフサイクルイベントには mem_session を使用します。

観察の例:

{
  "kind": "observation",
  "title": "Retry SQLite writes in a new transaction",
  "type": "bugfix",
  "project": "my-project",
  "topic_key": "sqlite/busy-retry",
  "content": "**What**: Roll back after SQLITE_BUSY and retry in a new transaction.\n**Why**: Retrying inside the failed transaction repeats the failure.\n**Where**: write transaction helper.\n**Learned**: Use bounded backoff before opening the new transaction."
}

永続化の前に <private>...</private> 内のコンテンツを削除します。再利用可能な教訓なしに、資格情報、完全なトランスクリプト、ユーザーの意図としての生成エージェントプロンプト、または生のログを保存しないでください。

6つのMCPツール

セットアップ、同期、移行、再構築、およびメンテナンスコマンドはCLI/HTTP管理であり、追加のMCPツールではありません。

グラフコミュニティを検査する

コミュニティは、プロジェクトの知識グラフから導出された境界付きサマリーです。オペレーターはCLIを通じてコミットされたサマリーを作成または更新します:

thoth-mem rebuild-communities --project my-project

エージェントはその後、mem_project を通じてそれらを取得します:

{
  "action": "graph",
  "project": "my-project",
  "navigation": "community",
  "limit": 5,
  "max_chars": 2000
}

レスポンスはコミュニティの状態と鮮度を報告し、その後 community=<id>、グラフカバレッジ、信頼度、劣化状態、境界付きサマリー、sources=obs:<id> などのエントリを報告します。コミュニティ検査にはプロジェクトが必要ですが、フォーカスノードや観察IDは不要です。コミットされたサマリーが存在しない場合は、グローバルな回答を合成する代わりに、その旨が示されます。

コミュニティの背後にある証拠を調べるには、その sources フィールドから obs:<id> を取得し、mem_get(kind="observation", id=<id>) を呼び出します。観察IDはリコール結果にも表示されます。境界付きのグラフ近傍については、いずれかを focus_node_id="obs:<id>" として navigation="neighborhood" とともに再利用します。

ネイティブハーネス統合

ネイティブセットアップは、ハーネスがサポートする場所に、パッケージ化されたMCP宣言、メモリスキル、ライフサイクルフックをインストールします。まずゼロ書き込みプランを確認してから、--plan なしで再実行して適用します:

デフォルトのOpenCodeセットアップコマンドは thoth-mem setup opencode です。プロジェクトを明示的にターゲットにする場合は thoth-mem setup opencode --scope project --project /path/to/project --force を追加し、レシートスコープのロールバックには thoth-mem setup codex --rollback /path/to/receipt.json を使用します。

セットアップのステータスとプロセス終了コードは安定しています:

プロジェクトローカルのセットアップは明示的です:

thoth-mem setup opencode --scope project --project /path/to/project --plan --json

適用する前に、検出された競合を確認してください。--force は、thoth-memの所有権がすでに証明されている競合する場所にのみ使用します。Codex 0.144.x、0.146.x、0.147.x はテスト済み互換性セットに含まれており、--force は必要ありません。他のCodexバージョンの場合、選択したスコープが完全で独立に検証可能なプラグインマネージャー機能をまだ公開している場合に限り、--force はテスト済みバージョンゲートのみをオーバーライドできます。セットアップはそのオーバーライドを使用するときに警告を発します。状態検証、所有権、封じ込め、調整、クリーンアップの保護をバイパスせず、無関係な設定に対する権限も付与しません。

Claude Code はネイティブマーケットプレイスのフローもサポートしています:

claude plugin marketplace add EremesNG/thoth-mem
claude plugin install thoth-mem

ネイティブ統合は任意です。既存のメモリと6つのツールからなるMCPサーバーは、手動接続でも引き続き動作します。

手動MCPフォールバック

ネイティブフックは任意です。管理されたセットアップやネイティブプラグインを必要としない場合は、プレーンな6ツールMCP接続を維持してください。既存のメモリは引き続き利用可能です。

ネイティブハーネス統合への移行

ネイティブセットアップはオプトインです。ゼロ書き込みプランを確認し、競合を確認してから、一致するハーネスコマンドを適用します。Codexの場合は、/plugins を開き、EremesNG/thoth-mem から thoth-mem をインストールし、マーケットプレイスとプラグインの状態を確認します。外部のCodex登録はアトミックに元に戻せないため、ローカルセットアップを再試行またはロールバックする前に外部状態を確認してください。

管理セットアップの契約: プランモードはゼロ書き込みを実行し、thoth-mem管理の場所でのみ変更を行います。最初の変更の前にバックアップが作成されます。OpenCode は opencode.json または opencode.jsonc を受け入れます。各変更試行は、変更の前にステータス in_progress のHMACで保護されたレシートを書き込みます:

• グローバルレシート: <thoth-data-dir>/setup/receipts/<receipt-id>/receipt.json

• プロジェクトレシート: <project>/.thoth/setup/receipts/<receipt-id>/receipt.json

欠落している、または改ざんされたレシートはフェイルクローズします。検証済みのロールバックは無関係な設定を保持しますが、ドリフトまたは利用できない機能がある場合は requires_user_action を返します。検証済みの状態がすでに一致している場合、セットアップの繰り返しと完了済みロールバックの繰り返しはノーオペレーションです。

Gemini CLI: 手動MCP

Gemini CLI は手動のMCPクライアントパスであり、管理されたネイティブ thoth-mem 統合ではありません。このエントリを ~/.gemini/settings.json に追加してください:

{
  "mcpServers": {
    "thoth": {
      "command": "npx",
      "args": ["-y", "thoth-mem@latest", "mcp"]
    }
  }
}

検索とグラフ品質の評価

リポジトリには決定的な評価コマンドが含まれています:

pnpm run eval:retrieval
pnpm run eval:kg
pnpm run eval:embedding-models -- --help

eval:retrieval はシグナル観察とディストラクタをシードし、期待されるメモリが上位にランクインするかどうかを測定します。そのレポートをシグナルの集合として読んでください:

• 再現率と順位 は、正しいエビデンスが見つかったかどうか、およびどの程度早く見つかったかを示します。

• ノイズとケースミックス は、直接、言い換え、リポジトリ由来の例にわたる堅牢性を示します。

• 圧縮 は、コンテキスト配信前にどれだけのエビデンスが削除されたかを示します。これは効率性のシグナルであり、残りのテキストが正しいという証明ではありません。

• レーンとフォールバックエビデンス は、語彙的、セマンティック raw/HyDE、およびKGの参加を示し、保留中または劣化したセマンティック動作を含みます。

• 系統と出所 は、返されたエビデンスがそのソースに帰属可能なままであるかどうかを示します。

eval:kg は、期待される主語-関係-目的語の再現率、禁止トリプルの漏えい、決定的な抽出動作、検証済みのオプションLLMエンリッチメントを測定します。期待される事実が欠落している場合はカバレッジのギャップを示し、禁止されたヒットは安全でないグラフの創作を示します。

これらの評価は、キュレーションおよび合成フィクスチャに対する決定的な開発ゲートです。すべての本番コーパスを予測したり、人間のレビューを置き換えたり、ネイティブハーネス統合を証明したり、それだけでオプションのコミュニティ読み取りパスを有効にすることを正当化したりするものではありません。単一の集計数値を普遍的な品質として扱うのではなく、個々のケースと失敗メッセージを比較してください。

埋め込みプロファイルとモデル比較

セマンティック埋め込み入力は、バージョン管理されたモデルプロファイルによってフォーマットされます。auto は Nomic、EmbeddingGemma、Qwen3-Embedding のモデルファミリーエイリアスを認識します。不明なモデルは raw を使用し、推論された非対称フォーマットは適用されません。公開設定には意図的にグローバルな task フィールドがありません。検索意図とクエリ/ドキュメントの役割は、ドキュメント役割のHyDE回答を含む各入力に対して内部的に割り当てられます。

{
  "embedding": {
    "provider": "lmstudio",
    "model": "text-embedding-embeddinggemma-300m",
    "baseUrl": "http://127.0.0.1:1234",
    "dimensions": 768,
    "profile": "auto",
    "normalize": true
  }
}

サポートされているプロファイル値は、auto、nomic、embeddinggemma、qwen3、raw です。THOTH_EMBEDDING_PROFILE と THOTH_EMBEDDING_NORMALIZE は、永続化された値を上書きします。解決されたプロファイルのバージョンと正規化フラグは、セマンティックインデックスのリネージの一部です。そのため、これらを変更すると、以前のベクトルが古いものとしてマークされ、既存の冪等な再構築キューが使用されます。

ローカルの Transformers.js 推論では、特定の ONNX 実行デバイスを選択できます：

{
  "embedding": {
    "provider": "transformers_local",
    "model": "onnx-community/embeddinggemma-300m-ONNX",
    "device": "dml",
    "dimensions": 768,
    "profile": "auto",
    "normalize": true
  }
}

サポートされているデバイス値は、auto、cpu、dml、cuda、coreml です。デフォルトは cpu です。THOTH_EMBEDDING_DEVICE は、永続化された embedding.device 値を上書きします。Transformers.js が使用するプリビルドの Node ONNX Runtime では、dml は Windows 上の DirectML をターゲットにし、cuda はサポートされている Linux x64 CUDA インストールをターゲットにし、coreml は macOS をターゲットにします。明示的に利用できないデバイスを指定すると、黙って CPU に切り替わる代わりに、モデルの初期化が失敗します。auto は、プラットフォーム固有のプロバイダーの順序付けとフォールバックを Transformers.js に委任するため、実効バックエンドはホストや依存関係のバージョンによって変わる可能性があります。

デバイス選択は transformers_local にのみ影響します。リモートの Ollama および LM Studio リクエストでは無視されます。GPU バックエンドはコールドスタートが大幅に遅くなる可能性があるため、永続的な MCP プロセスやより大きな埋め込みバッチに最も役立ちます。デバイスは意図的にセマンティックインデックスのリネージから除外されています。embedding.device のみを変更しても、既存のベクトルが古いものとしてマークされたり、再構築がキューに入ったりすることはありません。

プロバイダーモデルの例：

EmbeddingGemma のローカル実行は sentence_embedding を消費します。Qwen のローカル実行は、検索命令をクエリにのみ適用し、プーリングには最後にアテンションされた隠れ状態トークンを使用します。すべてのプロバイダーは、不完全、非有限、ゼロ、または次元が一貫しないバッチを拒否します。LM Studio のレスポンスインデックスは検証され、有効な順序不同の行は入力順に復元されます。欠落、重複、または無効なインデックスは拒否されます。リコール中、これらのエラーはセマンティック検索を明示的に劣化させますが、語彙検索と KG 検索は継続されます。

3つのモデルの品質ゲートを、明示的なモデル ID と永続的な出力パスで実行します：

pnpm run eval:embedding-models -- --provider lmstudio --base-url http://127.0.0.1:1234 --nomic-model <nomic-id> --embeddinggemma-model <gemma-id> --qwen3-model <qwen-id> --output <result.json>

このゲートでは、3つの実行すべてが完了し、少なくとも1つの候補が、Nomic のどのメトリクスも後退させることなく、Recall@1/Recall@5/MRR のしきい値を満たすことが必要です。Nomic は相対比較の基準であり、絶対しきい値の対象となる候補ではありません。両方の候補が資格を満たした場合、明示的な品質スコアと安定したタイブレーク順序によって勝者が選択されます。モデルが見つからない場合、ベクトルが無効な場合、資格のある候補がいない場合、またはレポートの書き込みに失敗した場合は、非ゼロで終了し、現在のデフォルトが維持されます。

記録された 2026-08-08 の LM Studio 実行では、出荷時のローカルデフォルトとして EmbeddingGemma が選択されました。EmbeddingGemma と Qwen3 はどちらも Recall@1 1.00、Recall@5 1.00、MRR 1.00 で完了しました。一方、Nomic は 0.50、1.00、0.7167 でした。両方の候補が資格を満たし、EmbeddingGemma は、両者が完全に同点だった品質スコアにおいて、安定した語彙プロファイル ID ルールによって勝利しました。永続化された決定実行における中央値レイテンシは、Nomic が 190.5 ms、EmbeddingGemma が 195 ms、Qwen3 が 320.5 ms でした。

Qwen3 のファイルサイズは、ランタイムアーティファクトによって異なります：

Qwen3 Q8 モデルは、Transformers.js では EmbeddingGemma Q8 より 304,069,133 バイト大きく、LM Studio では 305,559,648 バイト大きくなります。また、EmbeddingGemma の 768 次元ではなく、ネイティブの 1024 次元ベクトルを使用します。ランナーは、オペレーターに代わってプロバイダーモデルをインストールしたり検出したりしません。

より厳しいローカル実行を行いたい場合は、検索ノイズをスケーリングします：

$env:THOTH_RETRIEVAL_EVAL_NOISE='250'
pnpm run eval:retrieval

高度な操作

• 完全な CLI コマンドとオプションの一覧については、thoth-mem help を実行してください。

• http://localhost:7438/ でローカルダッシュボードを開き、http://localhost:7438/docs で OpenAPI ドキュメントを開いてください。

• Git に適した移植性のために、thoth-mem sync --dir=.thoth-sync と thoth-mem sync-import --dir=.thoth-sync を使用してください。

• repair-sync-journal (--project <name> | --all) --apply は、修復バッチを内部的にプレビューしてバインドします。外部ワークフローがすでにプレビューバインディングを持っている場合、オプションの --expected-fingerprint は引き続き利用可能です。

• prune-operation-traces (--project <name> | --all) --apply も同様に、1つの保持バッチを内部的にバインドします。--until-complete を追加すると、最初に制限されたバックログを、1つの固定された有効時点とその後の新しいフィンガープリントで処理します。外部から提供されるバインディングには、--expected-fingerprint と --effective-now の両方を含める必要があります。

• compact-database [--data-dir <path>] は、読み取り専用のプレビューを実行します。回収可能なスペースと容量の見積もりを確認した後にのみ、--apply を追加してください。適用には、物理データベースサイズと論理データベースサイズの大きい方の2倍が必要になる場合があり、他の SQLite クライアントによってブロックされる可能性があり、整合性、外部キー、スキーマ、永続カウント、WAL チェックの後にのみ成功を報告します。SQLite 管理のチェックポイントと VACUUM を使用します。コミットされた圧縮後のロールバックは保証しません。

• 圧縮が自動で行われることはありません。ライブデータに対して実行するには、別途オペレーターの承認が必要です。リポジトリのテストでは、使い捨てデータベースのみを使用します。

• 永続化された構成と環境変数による設定については、config.schema.json を確認してください。

• データはデフォルトで ~/.thoth/thoth.db に保存されます。データディレクトリは THOTH_DATA_DIR または --data-dir で上書きできます。

セマンティックインデックス作成は非ブロッキングです。埋め込みまたは sqlite-vec が利用できない場合でも、リコールはサポートされている語彙およびグラフのエビデンスを通じて引き続き利用可能であり、黙ってセマンティックの成功を主張するのではなく、劣化したレーンを報告します。

開発

pnpm install
pnpm run integration:verify
pnpm run build
pnpm test

ライセンス

MIT