th-memory-mcp

th-memory-mcp

要件

• Node.js 22.23.4+、24.22.1+、または 26.12.1+ — パッチ適用済みリリースのみ対応しています。このサーバーは Node.js 専用 API（better-sqlite3 のネイティブビルド、import.meta.url）を使用します。Node.js 20 は EOL のため、サポート対象外です。CI では、サポート対象の各系列（22/24/26）の最小パッチ適用バージョンをテストします。
• npm — npm install、npm run build、npm test に使用します。外部サービス、アカウント、API キーは不要です。すべて単一のローカル SQLite ファイルに保存されます。
• OpenCode — MCP サーバーと自動キャプチャプラグインを読み込むホストです（stdio 経由の MCP とプラグインに対応する任意のビルド）。プラグインは OpenCode Desktop／Node 22.5+ では node:sqlite を使用し、Bun ベースの CLI では bun:sqlite にフォールバックします。
• OS：Windows／macOS／Linux — クロスプラットフォーム対応（Node）。Windows では setx で MEMORY_DB_PATH を設定し、macOS／Linux ではシェルプロファイルで export を設定します。

セキュリティ： パッチ適用済みの Node.js リリースを使用してください。npx is-my-node-vulnerable でランタイムを確認できます。npm audit が対象とするのは npm の依存関係のみで、Node.js コアの CVE は対象外です。

クイックスタート

最速の方法： クローン後に npm run quickstart を実行すると、ビルド、opencode.json の設定、プラグインの配置、MEMORY_DB_PATH の設定が行われます。以下の手順はその手動での実行方法です。npm を使う方法： npm install -g th-memory-mcp（または npx th-memory-mcp）を実行し、dist/index.js の代わりに th-memory-mcp を mcp.command に指定します（プラグインは引き続きこのリポジトリから取得します。GitHub Packages では提供されなくなりました）。

# 1. Clone and build
git clone https://github.com/worakorn-prince/th-memory-mcp.git
cd th-memory-mcp && npm install && npm run build
# 2. Share one DB between the server and the plugin
setx MEMORY_DB_PATH "$PWD/data/memory.db"      # Windows (PowerShell)
# export MEMORY_DB_PATH="$PWD/data/memory.db"  # macOS/Linux — add to your shell profile (~/.zshrc)

3. これを ~/.config/opencode/opencode.json に統合します（<REPO> をクローン先の絶対パスに置き換えてください。すぐに使える設定ブロックは opencode.example.json にあります）。MEMORY_DB_PATH はサーバーとプラグインで同じファイルを指定する必要があります。システムまたはユーザーレベルの環境変数を設定すれば両方に適用されます。以下の environment はサーバーのみに適用されます。ルールの例は AGENTS.memory.example.md を参照してください（プロジェクトレベルで追加できます）。

{ "instructions": ["<REPO>/AGENTS.memory.example.md"],
  "mcp": { "memory": { "type": "local", "command": ["node", "<REPO>/dist/index.js"], "enabled": true, "environment": { "MEMORY_DB_PATH": "<REPO>/data/memory.db" } } } }

4. （任意）自動キャプチャ：src/plugin/learning-capture.ts を ~/.config/opencode/plugins/ にコピーします
5. OpenCode を再起動します（設定は起動時にのみ読み込まれます）。次に、「pnpm を使うのが好みだと覚えておいて」 → 新しいセッション → 「どのパッケージマネージャーを使うのが好みですか？」 と試してみてください。

起動時に Failed to load plugin ... Received protocol 'bun:' と表示される場合は、古いプラグインをコピーしています。最新の src/plugin/learning-capture.ts を再度コピーしてください。このファイルはまず node:sqlite を読み込み、Bun 環境でのみ bun:sqlite にフォールバックします。

アーキテクチャ

OpenCode はプラグイン learning-capture（Node/Bun）を読み込み、プロンプト／ツール／エラーを自動的に DB に記録し、コンパクション時にプロファイルを注入します。また、MCP サーバー th-memory-mcp（Node stdio）は、同じ SQLite DB 上で 16 個のツールを公開します。グローバルルール（memory-protocol.md）は、それらの使い方を AI に教えます。

th-memory-mcp を選ぶ理由

• ファインチューニングではなく、コンテキストベースの学習 — ユーザーの好み、修正、習慣を記録し、次のセッションで呼び出します。データがマシンの外に出ることはありません。
• 100％ローカルでプライベート — SQLite ファイル 1 つだけを使用し、クラウドや外部 API は不要です。シークレット（api_key=、password:、token）は保存前にフィルタリングされます。
• 低オーバーヘッドで高い耐障害性 — ツール呼び出しには上限が設けられており（レイテンシー < 10 ms、出力サイズに上限あり）、DB を利用できない場合も適切に機能を縮退します。
• オープンで拡張可能 — MIT ライセンスです。ドキュメント化された 16 個のツール、ルールベースの蒸留、自動記録プラグインを備えています。Node と better-sqlite3 のみを使用し、追加のネイティブ拡張は不要です。

主な特長

• 構造化されたメモリー — 確信度スコア付きの好みに加え、単なるフラットな事実ではなく、lesson レコード（状況 → 間違い → 修正）を保存します。
• ライフサイクル、時間的変化、競合への対応 — 状態（active/stale/superseded/archived）、確信度／重要度／顕著性のスコアリング、タイプ別の減衰、ある時点での真実を示す有効期間と継承チェーンに対応します。重複や矛盾の解決では、曖昧な証拠の両方を保持します。
• ハイブリッド検索 — get_context は、FTS5 キーワード検索と、依存関係のない語彙的ファジーマッチング（ハッシュ化した n-gram 類似度、512 次元の FNV-1a）を RRF 融合で組み合わせ、オプションのメモリーグラフ展開を含め、トークン予算に合わせたコンテキストを組み立てます。
• 統合 — 類似したメモリーをクラスタリングし、完全な来歴（derived_from リンク）を持つ派生メモリーを作成します。
• タイ語と i18n を標準サポート — 蒸留時にタイ語対応のトークン化を行います。タイ語と英語は相互に置き換えて使用できます。

他のハーネスとの連携

標準的な MCP サーバーです。MCP-over-stdio が動作する環境ならどこでも 16 個のツールを使用でき、すべてのハーネスが MEMORY_DB_PATH を介して 1 つの SQLite ファイルを共有します。自動記録にはフックのランタイムが必要です（OpenCode には組み込み済み、Claude Code ではブリッジ経由で利用できます）。

機能	OpenCode	Claude Code	Qwen Code	Codex	Cursor
16 個の MCP ツール	✅	✅	✅	✅	✅
自動記録（バックグラウンド）	✅ プラグイン	✅ フック	⚠️ アダプター	❌ 手動	❌ ルール
プロファイルの注入	✅ コンパクション	✅ UserPromptSubmit	❌ get_profile	❌ get_profile	❌ get_profile
語彙的ファジーマッチング	✅（v2.0）	✅（v2.0）	✅（v2.0）	✅（v2.0）	✅（v2.0）

• Claude Code（CLAUDE_CODE_HOOKS.md） — プラグインの代わりに、すぐに使えるフックを導入します。UserPromptSubmit／PreCompact で記録とプロファイル注入を行い、SessionEnd で蒸留します。Qwen Code（QWEN_SETUP.md） — MCP は完全対応です。フックには小規模な Gemini-CLI アダプターが必要です。Codex（CODEX_SETUP.md） · Cursor（CURSOR_SETUP.md） — ツールを手動で使用します。

スクリプト

コマンド	説明
npm run build	TypeScript を dist/ にコンパイルします
npm start	dist/index.js から MCP サーバー（stdio）を実行します
npm run distill	やり取りからプロファイルのセクションを作成し、古いデータを削除します（RETENTION_DAYS、デフォルトは 30）
npm test	ビルドと全テストスイートを実行します（32 ファイル、75 テスト）
node test/<name>.test.mjs	テストスイートを 1 つ実行します：capture、distill、lifecycle、temporal、conflict、retrieval、graph、context、consolidation、benchmark、security
node test/smoke.mjs	JSON-RPC を使用したエンドツーエンドのスモークテストを実行します（16 個のツール）

ツール（16）

ツール	説明
remember	設定を追加または更新します（category+key）。再保存するたびに信頼度が+0.1されます（上限1.0）。
recall	設定と教訓（FTS5）、最近の一致するインタラクションを検索します。新しいタスクの前に実行してください。
get_profile	プロフィールの各セクション、主な設定、直近5件の教訓を取得します。
save_lesson	修正内容から教訓を記録します（状況／誤り／修正）。
search_history	キーワードで過去のプロンプトを検索します（200文字の抜粋）。
forget	IDで1行（設定／教訓／インタラクション）を削除します（テーブル間のID重複を避けるには+typeを指定します）。
memory_stats	種類ごとの件数、DBサイズ、最も古い／新しいインタラクション、プロフィールの各セクションを表示します。
get_recent_interactions	最近の生のインタラクションを取得します（種類で絞り込み可能）。Smart Distillのフィードストックです。
export_memory	data/exports/内のみにJSONをエクスポートします（ファイル名は自動的にサニタイズされます）。
get_context	ハイブリッド検索（グラフ展開を含む）でタスクに関連するメモリを取得します。トークン予算に対応しています。
consolidate	埋め込み類似度で類似するメモリをクラスタリングします。必要に応じて、derived_fromでリンクした派生メモリを作成できます。
link_memory	2つのメモリ間に型付きリンクを作成します。対応する型：supports／contradicts／supersedes／derived_from／related_to／caused_by／depends_on
merge_memory	重複するメモリを正規メモリに統合します（元のメモリは置き換え済みとして扱われ、由来情報はmetadata.merged_fromに記録されます）。
update_memory	フィールドをその場で更新します。contentが変更された場合は、置き換えメモリを作成します（supersede=falseの場合はその場で編集します）。
import_memory	JSONからインポートします（型を検証し、重複を除去し、無条件で上書きすることはありません）。デフォルトはドライランで、挿入するにはapply=trueを指定します。
extract_memories	最近のインタラクションからメモリに関する意図を示す表現をスキャンし、候補を提案します（決定的で、LLMは使用しません）。デフォルトはドライランで、作成するにはapply=trueを指定します（source=captured）。

CLI（th-memory）

バイナリ	エントリ	用途
th-memory-mcp	dist/index.js	MCP サーバー（stdio）— 上記の16個のツール
th-memory	dist/cli.js	依存関係なしのローカルCLI（MEMORY_DB_PATHを介して同じDBを使用）

使い方：th-memory [--db <path>] [--json] [--plain] <command> [options] — コマンドごとのヘルプはth-memory <command> --helpで表示します。highlight／recall --highlightでは、カラー対応のTTY上では一致箇所に下線（ESC[4m）を付け、それ以外では[mem]…[/mem]マーカーを使用します（パイプ出力時、--plain、--json）。

フラグ	動作
--db <path>	このSQLiteファイルを使用します（MEMORY_DB_PATHを設定します）。
--json	プレーンテキストの代わりにJSON {ok,data}を出力します。
--plain / --no-color	色を無効にします。
-h, --help / -V, --version	ヘルプを表示／バージョンを出力します。

コマンド	使い方
remember	remember --category <c> --key <k> --value <v|-> — 設定を保存します（--value -は標準入力から読み込みます）。
recall	recall <topic> [--limit <n>] [--highlight] — メモリを検索します。
forget	forget <id> [--type <t>] — IDで削除します（t：memory|preference|lesson|interaction）。
export	export [--include-interactions] [--filename <n>] — data/exports/*.jsonにエクスポートします。
import	import (--file <p>|--json <s>) [--apply] [--user-id <id>] — バックアップをインポートします（デフォルトはドライラン）。
stats	stats — メモリの統計情報を表示します。
profile	profile — 要約されたユーザープロフィールを表示します。
history	history [--query <q>] [--limit <n>] — 過去のプロンプトを検索します（クエリなしの場合は最近のプロンプトを表示します）。
recent	recent [--limit <n>] [--kind <k>] — 最近のインタラクションを表示します（k：prompt|tool_call|error）。
highlight	highlight [text...] -q <topic> [--limit <n>] — トピックに一致する箇所を強調表示します（テキストが空の場合は標準入力をパイプします）。

th-memory remember --category coding_pref --key package_manager --value pnpm
th-memory recall pnpm --limit 5
echo "I prefer pnpm for installs" | th-memory highlight -q pnpm

日常的な使い方

AI はタイ語と英語のどちらでも同じように対応します。長期的なメンテナンスでは、npm run distill が統計を要約し、30 日より古いインタラクションを削除します。

• 「覚えておいて…」→ remember — 好みを保存します
• 「メモリを要約して」／「メモリを蒸留して」→ Smart Distill — AI が get_recent_interactions を読み取り、パターンを見つけて、自らインサイトを保存します
• 「メモリの状態は？」／「メモリのステータス」→ memory_stats
• 「メモリをエクスポートして」／「メモリをバックアップして」→ export_memory
• 「履歴を検索して…」→ search_history · 「忘れて…」→ forget

data/ の構造

data/
├── memory.db          # SQLite (WAL mode) — main DB (+ .db-wal, .db-shm); path overridable via MEMORY_DB_PATH
└── exports/           # JSON files from export_memory (writeable only in this dir)
# everything in data/ is git-ignored

既知の制限事項

• 保存データは暗号化されません — data/memory.db は暗号化されていないプレーンな SQLite（WAL モード、better-sqlite3）です。「100% local & private」とは、クラウド／ネットワークへのデータ流出がないことを意味し、保存データが暗号化されているという意味ではありません。ファイルシステムにアクセスできる人なら誰でも読み取れます。機密データには、OS のフルディスク暗号化（BitLocker／FileVault／LUKS）またはオプトインの SQLCipher ビルド（ネイティブの再ビルドとキー管理）を使用してください。デフォルトではコード内の暗号化は行われません（src/db/index.ts に記載されています）。
• 単一ユーザー向けで、認証レイヤーはありません（Batch B-3） — userId／sessionId／projectId は呼び出し元から提供され、サーバー内部で認証や認可のチェックは行われません。スコープの分離（取得、get_context、グラフ、consolidate、link_memory、merge_memory）は呼び出し元から送られた値にのみ紐づくため、別の ID を渡せば、どのスコープも読み取り・書き込みできます。単一ユーザーのローカルプロセスには適していますが、正しい userId（projectId／sessionId）を強制する認証レイヤーを前段に設けずに、信頼できないユーザー間で 1 つのサーバー／DB を共有しないでください。設計上、認証機能は組み込まれていません。

ライセンス

MIT © 2026 worakorn-prince — 全文については LICENSE を参照してください。