Toon Memory

English | Español | 中文 | 日本語 | 한국어 | Português (BR) | Deutsch | Français

toon-memory

AI エージェントのための継続性レイヤー — AI エージェントがセッションのたびにプロジェクトを学び直す必要はありません。

---

目次

• 概要
• ブログ記事
• 機能
• インストール
• 対応エージェント
• MCP ツール
• 複数セッション間の連携
• メモリーグラフ（グラフベースの想起）
• ヒントとベストプラクティス
• CLI コマンド
• 設定
• 仕組み
• TOON を選ぶ理由
• トラブルシューティング
• よくある質問
• 開発
• コントリビューション
• セキュリティとプライバシー
• ライセンス

---

概要

AI エージェントが昨日のセッションのことをすべて忘れてしまう、そんな経験はありませんか？アーキテクチャ上の決定を3回目も説明したのに、すでに却下した方法をまた提案されることはありませんか？

toon-memory がその問題を解決します。 AI エージェントのための継続性レイヤーです。プロジェクトの知識、決定事項、規約をセッションをまたいで保持する軽量なシステムで、毎回のセッションを前回の続きから始められます。完全にローカルでプライベートに、MCP 経由で動作します。クラウドもサーバーも不要です。

📖 ドキュメントを読む

実際のユースケース

シナリオ	toon-memory の動作
設計上の議論	「pub/sub をサポートしているため、Memcached ではなく Redis を選びました」
フレームワークの選定	「このプロジェクトでは Joi ではなく Zod をバリデーションに使います」
バグ修正	「Redis のプール枯渇 — 修正内容は max_connections=20 でした」
アーキテクチャのメモ	「ブローカーサービスは HTTP ではなく RESP プロトコルを使用します」
オンボーディング	「デプロイスクリプトは scripts/deploy.sh にあります」
チームのコンテキスト	「PR #142 でキャッシュの変更が取り消されました — 再度追加しないでください」

---

ブログ記事

toon-memory が AI エージェントを賢くする仕組みを読んで、永続メモリーが実際にどのように動作するかをご覧ください。

---

機能

• 完全なメモリツールキット — Model Context Protocol による包括的なメモリ管理。memory_smart_recall（セッションの重み付けを含む統合リコール）、複数セッションの連携に使う memory_sessions、1 回の呼び出しでコンテキストを生成する context_* ツール（ブリーフィング、差分、フォーカス、ヘルス監査、エクスポート）、memory_compress（LLM による圧縮）、memory_consolidate（決定論的な重複排除／マージ／クリーンアップ）、memory_primer（自動注入されるコンテキスト）、memory_merge_sessions（セッション間マージ）、重要なエントリを優先度 1～5 でピン留めする memory_pin／memory_unpin、7 日間の TTL を持つセッションスナップショットを作成する memory_checkpoint、タグフィルターとセッションの重み付けを含む統合検索を行う memory_search、タグを一括操作する memory_tag、GitHub Gist と同期する memory_export_gist／memory_import_gist、暗号化されたシークレット保管庫 memory_secret、プロジェクト間の規約を扱う memory_export_global／memory_import_global、ソフト／ハード削除、復元、置き換えを行う memory_forget、古さや品質を振り返る memory_reflect、信頼度の低い下書きを自動昇格する memory_promote を含みます
• MCP リソース — ツールを呼び出さずに、（自動生成されるナレッジマップであるシステムプライマーを含む）メモリをコンテキストとして読み取れます
• 22 のエージェントに対応 — OpenCode、VS Code、Claude Code、Cursor、Windsurf、Cline、Continue、Codex CLI、Gemini CLI、Zed、Antigravity、Aider、KiloCode、OpenClaw、Kiro、Qwen、Kimi、Goose、Junie、Amp、Grok、Trae
• 対話型インストーラー — メニューから設定するエージェントを選択できます
• SessionStart フック — Claude Code、Codex CLI、Gemini CLI、Antigravity でリマインダーを自動表示します
• TOON 形式 — JSON よりトークン数を 22％削減（実測値）し、LLM の理解度も向上します
• プロジェクトごとのメモリ — 各プロジェクトに専用のメモリファイルが作成されます
• 設定不要 — インストールするだけですぐに使えます
• gitignore への自動追加 — .toon-memory/memory/ を .gitignore に自動追加します
• 日付フィルタリング — 日付範囲でメモリを検索できます
• 自動アーカイブ — 古いエントリ（30 日超）、TTL が切れたエントリ、または 100 件以上のエントリを自動的にアーカイブへ移動します
• 暗号化 — 機密データを AES-256-GCM で暗号化します
• 監視モード — N 分ごとにバックアップを自動作成します
• メモリ TTL — エントリごとに有効期限を設定できます（7 日、30 日、または指定日）
• タグ推定 — タグが空の場合、内容からタグを自動検出します（組み込み語彙とプロジェクトの依存関係を使用）
• メモリ差分 — 前回のセッション以降に変更された内容を確認できます
• 関連エントリ — 保存時に関連メモリを自動提案します
• メモリグラフ — links／[[key]] 参照でエントリを接続できます。memory_recall は関係を考慮したサブグラフを展開し、より正確でトークン消費の少ないリコールを実現します（埋め込みも LLM も不要です）
• トークン効率の高いリコール — memory_recall({ compact: true }) は数値インデックス付きのエントリを返し、id／date／file を省略します。グラフのエッジは ->2 として表示され、グラフの近傍ノードはスニペットに短縮されます
• BM25 ＋中心性ランキング — リコールでは BM25 の関連度とグラフの中心性に基づいて再ランキングします（クエリ語がなくてもハブが上位に表示されます）。ホップごとの減衰により、離れたノードは低い順位に保たれます
• 依存関係からの自動タグ付け — toon-memory init は package.json／Cargo.toml／requirements.txt／go.mod をスキャンし、プロジェクトの語彙を書き出します。依存関係に言及するエントリには、その依存関係のタグが自動的に付与されます
• スマートリコール — memory_smart_recall は BM25、グラフ、減衰、品質を 1 回の呼び出しで組み合わせます。LLM はすべてのタスクの開始時にこれを呼び出します
• 品質スコアリング — 各エントリに、構造（タグ、リンク、内容の具体性、鮮度、アクセス数）に基づく 0～1 の品質スコアが付与されます。品質の高いエントリが先に表示されます
• マージによる重複排除 — 同じ key で保存すると上書きせず、属性をマージします（タグの和集合、信頼度の最大値、最新の日付、リンクの統合）
• 類似重複の検出 — 統合処理では、Jaccard 類似度（しきい値 0.7）によって類似重複を検出し、マージします
• 信頼度スコア — 各エントリの信頼性を記録します。ユーザーによる明示は 1.0、推定は 0.65～0.75 です
• LLM による圧縮 — memory_compress は AI を使って長いエントリを要約します。memory_consolidate(mode: "low-quality") は決定論的に一括クリーンアップします
• セッション間マージ — memory_merge_sessions は、あるファイルについて並行するセッション間の観察内容をマージします
• GitHub Gist 同期 — memory_export_gist と memory_import_gist は GitHub Gist を介してメモリエントリを同期します（依存関係ゼロ）
• 逐語モード — config.verbatim を有効にすると、保存時に上書きせず、元のエントリを保持します
• コンテキスト生成ツール — context_generate（完全なブリーフィング）、context_diff（差分）、context_focus（対象を絞った情報）、context_health（監査）、context_export（Markdown）は、それぞれ手動でのツール呼び出し 5～6 回分を置き換えます。LLM は不要で、決定論的な集約のみを行います
• システムプライマー — systemPrimer() によってセッション開始時に自動注入され、上位 5 件のメモリを表示してすぐにコンテキストを把握できます
• パススコープ — グロブパターン（path_scope）でエントリの対象ファイルパスを指定できます。リコール時にはスコープで自動的に絞り込まれます
• 予算制御 — 出力レベルは 3 種類です。budget: "tiny"（キーと 1 行、約 50 トークン）、"normal"（タグとエッジを含む簡潔な出力）、"deep"（由来／スコープ／ステータスを含む全フィールド）。compact: true との後方互換性があります
• 由来の追跡 — 各エントリの由来（human、agent、inferred）を記録します。人間による明示には品質の加点があります
• ソフト削除 — memory_forget は既定でソフト削除を行います（status=obsolete に設定）。memory_forget(key, action: "restore") で復元し、action: "soft" で非表示にし、action: "hard" で完全に削除できます
• 強化されたヘルス監査 — context_health は、証拠の欠落（ファイルがない path_scope）と古い主張（同じカテゴリ内で内容が重複）も検出するようになりました
• 型付きグラフエッジ — エッジには型（superseded_by、supersedes、relates）があり、グラフ内では type:key として記述されます。明示的な links は relates:key になるため、エントリ同士に関連があることだけでなく、どのように関連しているかも判別できます
• RRF ランキング — リコールは Reciprocal Rank Fusion と適応型 k = clamp(3..60, round(sqrt(n))) により、BM25（×3）とグラフ中心性の順位を融合します。ベンチマーク（正解クエリ 8 件）：nDCG 0.776、MRR 0.917 — 以前の線形スコアリングと完全に同等です。以前の方式に戻すには rrf: false を指定してください
• メモリの振り返り — memory_reflect は古さ、品質、過剰な接続に基づいてエントリをランク付けし、注意やクリーンアップが必要な項目を浮かび上がらせます。決定論的で、LLM は不要です
• メモリの置き換え — memory_forget(key, action: "supersede", new_key) は、エントリが新しいエントリに置き換えられたことを示します（superseded_by リンクと supersededOn 日付を設定）。memory_recall({ as_of }) は、置き換え前の時点を指定したクエリで古いエントリを再び含めます
• 自動昇格 — memory_promote は、信頼度の低い下書きを決定論的にアクティブなエントリへ昇格します（しきい値 0.65、Jaccard による重複排除）。既定では dryRun が有効です
• 取得理由の説明 — memory_recall／memory_smart_recall は explain: true を受け付け、返される各エントリに決定論的な理由の行（↳ 100% relevance · used 14× · used today · importance HIGH）を追加します。LLM を使わず、なぜ取得されたのかを示します
• トークン予算 — budget_tokens は推定トークン数でリコール出力を制限します。エントリは貪欲法で追加され、予算を超える末尾部分は除外されます（0 = 無制限）
• バージョンの置き換え — memory_consolidate(mode: "versions") は、同じ対象について異なるライブラリバージョンを説明するエントリ（例：「React 18 を使う」対「React 19 を使う」）を検出し、古いものを最新のものに置き換えて退役させます
• 否定的なメモリ — 「これは絶対にしない」という事実を記録する warning カテゴリがあります。warning エントリはリコール時に優先され、エージェントが同じ失敗を繰り返す前に危険な点を確認できます
• 言語とフォルダーに基づくランキング — リコールでは、同じ文字体系（ラテン文字／CJK／キリル文字など）で書かれたエントリと、path_scope が現在のファイルに一致するエントリを優先します
• 重要度の明示指定 — memory_remember({ importance }) で critical、high、medium、low を設定できます。重要な決定は先に表示され（+0.3）、重要度の低いメモは邪魔にならないように扱われます（−0.1）。空の場合は自動設定（鮮度＋頻度）です。再保存時には高いレベルが保持されます
• 証拠レイヤー — memory_remember による保存時、すべてのエントリに証拠レベルが付与されます。参照先のファイルがディスク上に存在する場合は verified、存在しない場合は unverified、警告または重要度が critical／high の決定と内容が重複する場合は conflict です。競合時は保存時に ⚠️ CONTRADICTION 警告が表示され、リコール時に +0.15 の加点が行われます（verified は +0.03、unverified は −0.02）。ただし、書き込みが拒否されることはありません
• シークレット保管庫 — memory_secret は認証情報を暗号化されたサイドカー（secrets.toon、AES-256-GCM）に保存します。これにより data.toon は読み取り可能なオープン形式のまま保たれ、機密値が平文になることもありません
• グローバルメモリのインポート／エクスポート — memory_export_global はプロジェクトのメモリを ~/.toon-memory/memory/global.toon に書き出します。memory_import_global は、1 回限りの決定論的なオフラインマージでプロジェクト間の規約を取り込みます（常時接続の二重ソースにはなりません）
• インストールサイズ約 1 MB — 小さなプロンプトパッケージ 3 種（@inquirer/checkbox／select／confirm）を使用します。MCP SDK、zod、TOON パーサーは配布バイナリにバンドルされています。npm i -g を 1 回実行すると約 1 MB（以前は約 14 MB）がダウンロードされ、ディスク上のサイズは約 4.4 MB（以前は約 33 MB）です

---

インストール

1. インストール

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/LuiggiVal08/toon-memory/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/LuiggiVal08/toon-memory/main/install.ps1 | iex

# Or with npm (any platform)
npm i -g toon-memory

ヒント： npm によるインストールが最も確実な方法です。curl/irm スクリプトは便利なラッパーです。

サイズ： npm i -g toon-memory のみを実行すると、約 1 MB がダウンロードされ、約 4.4 MB がインストールされます。小さなプロンプトパッケージが 3 つ含まれています。それ以外（MCP SDK、zod、TOON パーサー）はすべて同梱されています。

2. エージェントを設定する

# Interactive installer — detects agents and configures MCP
npx toon-memory

インストーラーは次の処理を行います。

1. インストール済みの AI エージェントを検出します
2. 設定するエージェントを確認します
3. MCP サーバーの設定を自動的に追加します

3. 使用する

これで完了です。次のエージェントセッションで、次を試してください。

memory_stats      # See what's in memory
memory_recall     # Search memory before reading files
memory_remember   # Save important decisions

ヒント： セッションの開始時には、必ず memory_recall を実行してください。エージェントは、以前のセッションのコンテキストをすぐに利用できます。

MCP クライアントのクイックセットアップ

Cursor

.cursor/mcp.json に追加します。

{
  "mcpServers": {
    "toon-memory": {
      "command": "npx",
      "args": ["-y", "toon-memory", "mcp"]
    }
  }
}

Claude Desktop

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "toon-memory": {
      "command": "npx",
      "args": ["-y", "toon-memory", "mcp"]
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json に追加します。

{
  "mcpServers": {
    "toon-memory": {
      "command": "npx",
      "args": ["-y", "toon-memory", "mcp"]
    }
  }
}

---

対応エージェント

エージェント	設定場所	形式	フック	自動セットアップ
OpenCode	.opencode/opencode.json + .opencode/plugins/toon-memory.ts	プラグイン	SessionStart（プラグイン、トップレベルの hooks なし）	✅
VS Code / Copilot	.vscode/mcp.json	JSON	—	✅
Claude Code	.mcp.json（MCP）+ .claude/settings.json（フック）	JSON	SessionStart + PostToolUse + Stop	✅
Cursor	.cursor/mcp.json	JSON	—	✅
Windsurf	~/.codeium/windsurf/mcp_config.json	JSON	—	✅
Cline	.cline/mcp.json	JSON	—	✅
Continue	.continue/config.json	JSON	—	✅
Codex CLI	.codex/config.toml	TOML	SessionStart + PostToolUse + Stop（[[hooks]] event=）	✅
Gemini CLI	.gemini/settings.json	JSON	SessionStart + PostToolUse + Stop（hooks.*）	✅
Zed	~/.config/zed/settings.json	JSONC	—	✅
Antigravity	.agents/mcp_config.json + .agents/hooks.json	hooks.json	PreInvocation + PostToolUse + Stop（SessionStart イベントなし）	✅
Aider	—	—	—	📝 手順
KiloCode	~/.kilocode/mcp_settings.json	JSON	—	✅
OpenClaw	.openclaw.json	JSON	—	✅
Kiro	.kiro/settings/mcp.json	JSON	—	✅

ヒント： toon-memory は複数のエージェント向けに同時に設定できます。どのエージェントも、.toon-memory/memory/ にある同じ共有メモリファイルを使用します。

---

MCP ツール

ツール	説明
memory_remember	決定事項、パターン、バグ、知識、または警告（「これは絶対にしてはいけない」という否定的なメモ。想起時に優先度が上がります）を保存します。TTL の設定、タグの自動推定、メモリグラフを構築する links、同じキーの項目の重複排除を伴う統合、品質スコアと信頼度の自動設定に対応しています。書き込み時のインテリジェンス：保存時に各項目へ証拠レベルを付与します。参照先ファイルがディスク上に存在する場合は verified、存在しない場合は unverified、警告または重要度が「重大」／「高」の決定事項と重複する場合は conflict になります。conflict の項目は優先度を上げて想起され、⚠️ CONTRADICTION の警告とともに表示されますが、書き込みがブロックされることはありません。
memory_recall	メモリを検索します（ファイルを読む前に使用してください。期限切れの TTL は除外されます）。mode: "graph" は関係性を考慮したサブグラフを展開し、精度を高めます。`budget: "tiny"
memory_smart_recall	統合検索：BM25、グラフ、減衰、品質を1回の呼び出しで組み合わせます。sessionBias は現在の git ブランチの項目を優先します。explain: true は取得理由を項目ごとに追加し、budget_tokens は推定トークン数で出力を制限します。すべてのタスクの開始時に使用してください。簡潔で、トークン効率の高い出力を返します。
memory_forget	キーまたは ID を指定したライフサイクル操作：action: "soft"（既定値）は古い項目としてマークし、"hard" は完全に削除し、"restore" は有効な状態に戻し、"supersede" は new_key への superseded_by リンクを付けて終了します。
memory_stats	メモリの状態を表示します（TTL 統計、品質の分布、由来／ステータス別の内訳、品質／アクセスのしきい値を下回る低利用メモリ、ヒット率／重複／古い項目の指標を含みます）。
memory_summary	ファイルの要約を保存／取得します。
memory_archive	古い項目（30日超）と TTL の期限切れ項目をアーカイブします。
memory_diff	指定した日付以降の変更を表示します（24時間、7日、または正確な日付）。
memory_suggest	指定したコンテキストに関連する項目を検索します。
memory_encrypt	AES-256-GCM 暗号化を有効にします。
memory_decrypt	暗号化を無効にします。
memory_backup	メモリファイルのタイムスタンプ付きバックアップを作成します（最新の10件を自動的に保持します）。
memory_captured	フックが自動取得したアクティビティを一覧表示（オプトイン）するか、ログを消去します。
memory_checkpoint	セッションチェックポイント：現在のメモリ状態のスナップショットを、TTL 7日で作成します。長時間のセッションでロールバックの参照として便利です。
memory_consolidate	クリーンアップ操作。決定論的に実行され、LLM は使用しません。mode: "identical"（既定値）は内容が同一の項目の重複を排除し、"similar" は類似した項目を統合します（Jaccard >50%）。"low-quality" は品質の低い項目を一括削除します（minQuality、dryRun）。"versions" は古いライブラリバージョンの項目を、新しいバージョンの項目に置き換えて終了します。
memory_sessions	アクティブなエージェントセッション（ブランチ、ファイル、最終確認時刻）と、並行作業におけるソフトコンフリクトを表示します。
memory_compress	LLM を利用した2段階圧縮：要約してから上書きします。anthropic／openai CLI が利用可能な場合は使用し、利用できない場合は手動圧縮用のプロンプトを返します。
memory_primer	1回の呼び出しでコンテキストの事前情報を提供します：主要なメモリ、カテゴリ、セッション中のファイル変更を返します。セッション開始時に自動挿入されます。
memory_merge_sessions	ファイルに関する観察結果を並行セッション間で統合します。重複を排除し、任意でメモリへ自動昇格できます。
memory_export_gist	メモリ項目を GitHub Gist にエクスポートします（公開または非公開）。GITHUB_TOKEN または gh CLI を使用します。
memory_import_gist	GitHub Gist から項目をインポートします。既存の項目と統合します（タグの和集合、信頼度の最大値を使用）。
memory_secret	暗号化されたシークレット保管庫（secrets.toon、AES-256-GCM）：store／get／list／forget に対応しています。data.toon は読み取り可能な状態に保ち、機密値は保存時に暗号化します。TOON_MEMORY_KEY が必要です。
memory_export_global	現在のプロジェクトのメモリをグローバルファイル（~/.toon-memory/memory/global.toon）に書き込みます。プロジェクト横断の規約を1回限りで共有できます。
memory_import_global	グローバルファイルからプロジェクト横断の規約をこのプロジェクトに統合します（1回限り、決定論的、オフライン）。merge: false を指定すると置き換えます。
memory_graph_path	ナレッジグラフ内の2つの項目間にある最短経路を BFS で検索します。概念間のつながりを表示します。
context_brief	1回の呼び出しでコンテキストを要約：メモリ、セッション、ヘルス情報を簡潔な Markdown でまとめます。memory_* を5～6回個別に呼び出す代わりに使用できます。LLM は使用せず、決定論的な集約のみを行います。
context_generate	プロジェクト全体の概要：プロジェクト構造、git の状態、メモリ項目、アクティブなセッションを1回の呼び出しでまとめます。手動でのツール呼び出し5～6回を置き換えます。
context_diff	差分コンテキスト：前回のセッション以降の git コミット、変更ファイル、新規／更新メモリ、アクティブなセッションを表示します。
context_focus	焦点を絞った概要：クエリに関連するメモリ、関連するソースファイル、呼び出し元、テストファイルのみを表示します。
context_health	メモリのヘルス監査：リンク切れ、重複、参照先ファイルの不整合、期限切れ TTL、古いセッションを確認し、0～100のスコアを表示します。
context_export	メモリを Markdown としてエクスポート：システムプロンプトに挿入できるコンテキストを出力します（完全版または簡潔版）。
memory_pin	優先度1～5で項目をピン留め：ピン留めした項目は、キーワードが一致しない場合でも、優先度順に想起結果の先頭へ常に表示されます。
memory_unpin	項目のピン留めを解除：優先度フラグを削除します。
memory_search	フィルター付きの統合検索：memory_recall と同様の機能に加え、category、tags、from_date、to_date フィルターを利用できます。タグフィルターは AND ロジックを使用するため、指定したタグすべてに一致する必要があります。budget は出力の詳細度を制御します。path_scope は glob パターンで絞り込みます。sessionBias は現在の git ブランチの項目を優先します。
memory_tag	タグの一括操作：キーまたは ID で指定した1つ以上の項目に対し、タグの add、remove、set を実行します。

MCP リソース

メモリは、コンテキストを直接読み取るための MCP リソースとしても公開されています。

リソース	URI	説明
メモリエントリー	toon://memory/entries	メモリ全体のダンプ
現在のメモリ	toon://memory/current	最近のエントリーを含む現在のメモリ状態
メモリ統計	toon://memory/stats	カテゴリ別の件数と TTL 情報
システム概要	toon://memory/summaries	自動生成されたナレッジマップ（上位エントリー、カテゴリ、パターン）

MCP プロンプト

プロンプト	説明
summarize_project_context	現在の TOON メモリを分析し、簡潔なプロジェクト概要を生成します。特定の領域に焦点を当てるための任意の intent パラメーターがあります

例

決定事項を記憶する

memory_remember({
  category: "decision",
  key: "use-zod",
  content: "Use Zod for validation — simpler than Joi, better TS support",
  file: "src/types.ts",
  tags: "validation;types"
})
// 🧠 Guardado: decision/use-zod (a1b2c3d4)
// Quality score: 0.65 (2 tags, detailed content)
// 🔗 Entradas relacionadas:
//   [pattern] zod-schemas — Shared Zod schemas for API validation

ヒント： validation のような曖昧なキーではなく、use-zod のような説明的なキーを使ってください。エージェントはキーと内容をもとに検索するため、具体性が役立ちます。同じキーで保存すると自動的にマージされます（タグの和集合、最大の信頼度）。

TTL を指定して記憶する

memory_remember({
  category: "knowledge",
  key: "sprint-deadline",
  content: "Sprint ends July 18, feature freeze is July 16",
  ttl: "7d"
})
// 🧠 Guardado: knowledge/sprint-deadline (x1y2z3w4)
// ⏰ TTL: 2026-07-19
// Quality score is calculated automatically.

ヒント： 締め切り、スプリント情報、時間に依存するメモなど、一時的なコンテキストには TTL を使ってください。TTL の期限が切れたエントリーは、検索結果から自動的に除外されます。

重要度を明示的に設定する

memory_remember({
  category: "decision",
  key: "db-choice",
  content: "We chose Postgres over MySQL — JSONB for flexible schemas, better extension ecosystem",
  importance: "critical"
})
// 🧠 Guardado: decision/db-choice (a1b2c3d4)
// 🎯 Importance: critical (+0.3 boost) — surfaces above routine entries

ヒント： 基盤となる決定には critical を指定すると、想起時に常に上位に表示されます。importance には critical、high、medium、low を指定できます。空欄にすると、システムが新しさと頻度をもとに自動的に順位付けします。

タグの自動推定

memory_remember({
  category: "bug",
  key: "redis-connection-timeout",
  content: "Redis connection timeout in production, increased pool size"
  // tags left empty — auto-inferred from content
})
// 🧠 Guardado: bug/redis-connection-timeout (a1b2c3d4)
// 🏷️ Tags inferidos: redis
// Quality score is calculated automatically based on inferred tags and content.

ヒント： tags を空欄にすると、システムは組み込みの 20 以上のカテゴリの語彙（redis、auth、api、db、security など）に加えて、init 時に依存関係から導出したプロジェクト語彙を使って、コンテンツからタグを推定します。そのため、プロジェクトが redis に依存している場合、「redis」に言及するエントリーには redis タグが自動的に付与されます。

メモリを検索する

memory_recall({ query: "redis" })
// [bug] redis-pool-fix (i9j0k1l2)
//   Added max_connections=20
//   File: redis.ts | Tags: redis;fix | Date: 2026-07-10

ヒント： ファイルを読む前に検索してください。トークンを節約でき、コードだけでは得られないコンテキストをエージェントに提供できます。品質を加味した順位付けにより、最も有用なエントリーが最初に表示されます。より包括的な結果を得るには、memory_smart_recall を使うこともできます。

日付で絞り込んで検索する

memory_recall({
  query: "redis",
  from_date: "2026-07-01",
  to_date: "2026-07-31"
})

ヒント： 何が起きたかは正確に思い出せなくても、いつ頃 起きたかを覚えている場合は、日付フィルターを使ってください。品質を加味した順位付けも引き続き適用されます。

古いエントリーをアーカイブする

memory_archive()
// 📦 Archivadas 5 entradas antiguas
// 📋 Quedan 42 entradas activas

ヒント： メモリを簡潔に保つため、定期的に実行してください。アーカイブされたエントリーも、日付フィルターを使った memory_recall で検索できます。TTL の期限が切れたエントリーも自動的にアーカイブされます。品質の低いエントリーは想起の優先度が下がります。品質の低いエントリーは想起の優先度が下がります。

前回のセッション以降の変更を表示する

memory_diff({ since: "24h" })
// 📋 Cambios desde 2026-07-11:
//
// ➕ Nuevas (2):
//   [decision] use-zod (a1b2c3d4)
//     Use Zod for validation
//   [bug] redis-timeout (e5f6g7h8)
//     Redis connection timeout fix

ヒント： セッション開始時に memory_diff を使うと、プロジェクトで前回作業してからエージェントが学習した内容を確認できます。新しいエントリーには品質スコアが含まれます。新しいエントリーには品質スコアが含まれます。

関連するエントリーを見つける

memory_suggest({ context: "redis cache configuration" })
// 🔍 Sugerencias para "redis cache configuration":
//
// [decision] redis-cache-config (a1b2c3d4)
//   Redis cache layer for session storage
//   File: src/cache.ts | Tags: redis;cache | Date: 2026-07-10
//
// [bug] redis-pool-fix (i9j0k1l2)
//   Added max_connections=20
//   File: redis.ts | Tags: redis;fix | Date: 2026-07-10

ヒント： トピックに関するコンテキストが必要でも、何を検索すればよいか分からない場合は memory_suggest を使ってください。より包括的な結果を得るには、memory_smart_recall を使うこともできます。

スマート想起（統合）

memory_smart_recall({ intent: "diseño de base de datos para backend" })
// [1] decision/use-postgres
//   Choose Postgres for ACID compliance and JSON support
//   tags: db;decision · edges: ->2
//
// [2] pattern/db-migrations
//   Use sequential migration files, never edit committed ones
//   tags: db;pattern · edges: ->1
//
// [3] bug/redis-timeout
//   Redis connection timeout — increased pool to 20
//   tags: redis;bug

ヒント： すべてのタスクの開始時に memory_smart_recall を使ってください。BM25、グラフ、減衰、品質を 1 回の呼び出しで組み合わせるため、検索語を推測する必要はありません。

結果が返された理由を説明する

memory_recall({ query: "redis", explain: true })
// [decision] redis-cache-config (a1b2c3d4)
//   Redis cache layer for session storage
//   File: src/cache.ts | Tags: redis;cache | Date: 2026-07-10
//   ↳ 92% relevance · used 14× · used today · importance HIGH

↳ の理由行は決定論的です（関連度％、アクセス回数、最終使用時期、重要度）。LLM は関与しません。エージェントにそれらのエントリーが提示された 理由 を知りたい場合は、explain: true を使ってください。

budget_tokens で出力を制限する

memory_recall({ query: "redis", budget_tokens: 300 })
// Entries accumulate greedily; the tail that would exceed the estimate is dropped.
// budget_tokens: 0 (default) = no limit.

ヒント： budget_tokens と budget: "deep" を組み合わせると、メモリのサイズにかかわらず、コンテキストウィンドウを厳格なトークン上限内に収められます。

プロジェクトの概要を一括取得する（1 回の呼び出し）

context_generate({})
// # Project Briefing (full)
//
// ## Project
// - Name: my-app
// - Root: /path/to/project
// - Package Manager: npm
// - TypeScript: ✓ (v5.3)
//
// ## Git Status
// - Branch: main
// - 3 uncommitted, 0 untracked
//
// ## Memory (42 entries, 12 patterns, 8 bugs)
// [1] decision/use-postgres
//   Choose Postgres for ACID compliance
//   tags: db;decision
//
// ## Sessions
// - egraterol (main, 2m ago): 42 files touched

ヒント： セッション開始時に context_generate を使うと、1 回の呼び出しで完全なコンテキストを取得できます。個別に行う 5～6 回のツール呼び出しを置き換えます。

メモリの健全性監査

context_health({})
// # Memory Health (score: 87/100)
//
// ## Summary
// - 42 entries (12 patterns, 8 bugs, 15 decisions, 7 knowledge)
// - 65.3% average quality
//
// ## Issues (3)
// - Orphan link: pattern/db-migrations → pattern/db-seed (key not found)
// - Duplicate: [bug] redis-pool-fix has identical content
// - Expired TTL: [knowledge] sprint-deadline (expired 2026-07-20)
//
// ## Stale Files (1)
// - src/legacy.ts (deleted, 2 refs)

ヒント： メモリが乱雑になったと感じたら、context_health を実行します。孤立したリンク、重複、TTL の期限切れエントリ、壊れたファイル参照、根拠が不足しているエントリ（ファイルのない path_scope）、古くなった主張（内容が重複しているもの）を表示します。

マージ時の重複排除（自動）

同じ key で保存すると、属性は上書きされずにマージされます。

// First save
memory_remember({
  category: "decision",
  key: "use-zod",
  content: "Use Zod for validation",
  tags: "types"
})
// 🧠 Guardado: decision/use-zod (a1b2c3d4)

// Later save with same key — merges automatically
memory_remember({
  category: "decision",
  key: "use-zod",
  content: "Use Zod for validation — also handles API response parsing",
  tags: "types;api"
})
// 🧠 Actualizado: decision/use-zod (a1b2c3d4)
// 🔗 Merge: tags combinados, fecha y links actualizados
// Tags now: "types;api" (union of both)

ヒント： わかりやすく安定したキーを使います。同じキーならマージされ、異なるキーなら新しいエントリが作成されます。

品質スコア

すべてのエントリには、構造に基づく自動品質スコア（0～1）が付与されます。

要素	重み	評価内容
タグ	最大 0.3	タグが具体的であるほど品質が高くなります
リンク	最大 0.2	関連付けられたエントリが多いほど品質が高くなります
内容の長さ	最大 0.3	詳細な内容ほど、曖昧な内容より高く評価されます
新しさ	最大 0.1	最近のエントリほど高く評価されます
具体性	最大 0.1	繰り返しの語句より、固有の語句が多いほど高く評価されます
出所	+0.1／−0.05	人間による主張は加点され、推論による内容はわずかに減点されます

品質の高いエントリは、想起時に優先して表示されます。memory_stats で品質を確認します。

memory_stats()
// ...
// Calidad promedio: 0.58 (12 con score)

信頼度スコア

各エントリでは、情報の信頼性を記録します。

出所	信頼度	意味
ユーザーによる主張	1.0	「Postgres を使用しています」— 直接的な発言
推論	0.65～0.75	エージェントがコンテキストから推論した内容
不確実	0.50	エージェントによる推測

マージ時も信頼度は維持されます（2 つのエントリのうち高い方）。

システムプライマー

システムプライマーは、自動生成されるナレッジマップで、MCP リソースとして公開されます。エージェントはセッション開始時にこれを読み込み、すぐにコンテキストを把握します。

// Exposed as toon://memory/summaries
// Auto-regenerates on every read
// Contains: top entries, categories, patterns

ヒント： セッション開始時にすぐコンテキストを把握できるよう、toon://memory/summaries をエージェントのシステムプロンプトに追加します。

暗号化を有効にする

// First, set TOON_MEMORY_KEY in your environment (or .env file):
// export TOON_MEMORY_KEY="your-secret-key-here"

memory_encrypt()
// 🔐 Encriptación habilitada

警告： 暗号化する前に、TOON_MEMORY_KEY 環境変数で暗号化キーを設定する必要があります。キーは安全な場所に保管してください。紛失すると、メモリデータは永久に失われます。品質スコアと信頼度は暗号化後も維持されます。

---

複数セッション間の連携

複数の AI エージェントセッションを並行して実行する場合（例：同じリポジトリで OpenCode セッションを 3 つ同時に実行する場合）、互いの作業を誤って上書きしてしまうことがあります。toon-memory には memory_sessions が付属しており、ファイルベースの連携ツールとして、すべてのセッションが他のセッションの状況を確認できます。サーバーもネットワークも LLM 呼び出しも不要です。

仕組み

• 起動時に SessionStart フックが、.toon-memory/memory/sessions/<id>.json にセッションの ハートビートファイルを書き込みます。各プロセスは自分自身のファイルのみを書き込むため、ロックの競合は発生しません。
• ハートビートには、エージェント名、git ブランチ、変更されたファイル、および最終確認時刻が記録されます。
• これらすべてのファイルを読み取ることで、各セッションは他のどのセッションがアクティブかを共有ビューで確認できます。これは最終的に整合します。
• プロセスの PID が存在せず、かつ TTL の期間を過ぎた古いハートビートがある停止済みセッションは、必要に応じて削除されます。

memory_sessions ツール

memory_sessions({ conflictsOnly: false })
// 🧭 Sesiones activas (2) — ventana 30 min:
//
// • opencode @ feature/auth (tú)
//   id: a1b2c3d4
//   hace 2 min
//   Archivos:
//     • src/auth.ts
//
// • claude @ feature/db
//   id: e5f6g7h8
//   hace 9 min
//     • src/db.ts
//
// 🔥 Conflictos suaves (1):
//   ⚠️ src/types.ts  ↔  opencode @ feature/auth, claude @ feature/db

• セッション一覧を省略し、ソフトコンフリクトのみを表示するには、conflictsOnly: true を渡します。

  memory_sessions({ conflictsOnly: true })
  // 🔥 Conflictos suaves (1):
  //
  // ⚠️ src/types.ts
  //    ↔ opencode @ feature/auth (a1b2c3d4), claude @ feature/db (e5f6g7h8)
  

• ソフトコンフリクトとは、2 つ以上のアクティブなセッションが変更しているファイルのことです。同じコードを編集している可能性を知らせる注意喚起です。強制的なロックではなく、連携を促す警告です。

推奨される並行セッションの習慣

1. 各セッションの開始時に、SessionStart フックが他のアクティブなセッションとソフトコンフリクトをすでに表示します。
2. memory_smart_recall({ intent: "what I'm working on" }) を実行して、完全なコンテキスト（メモリー＋グラフ＋品質）を取得します。
3. memory_sessions() を実行して全体像（ブランチ、ファイル、最終確認時刻）を確認し、競合だけを確認したい場合は memory_sessions({ conflictsOnly: true }) を実行します。
4. 別のセッションとファイルを共有している場合は、編集前に同期し、お互いの変更を上書きしないようにします。

ヒント： これは完全にローカルで、ロックフリーです。好きなだけ安全に実行できます。セッション開始時に memory_smart_recall({ intent: "project context" }) と組み合わせると、セッション間の メモリー と 存在状況 の両方を確認できます。システムプライマー（MCP リソース）も、すぐにコンテキストを提供します。

---

メモリーグラフ（グラフベースの想起）

メモリーが増えてくると、フラットなキーワード検索では、結果が多すぎたり（一致するものがすべて返されたり）、適切なコンテキストが得られなかったり（関連性が考慮されなかったり）することがあります。toon-memory はメモリーを軽量なナレッジグラフとして扱うことで、より少ないトークン数で適切なエントリを想起できます。品質スコアリングと組み合わせると、最も有用なエントリが上位に表示されます。

完全に決定論的でオフラインです。埋め込み、ベクトル DB、LLM、サーバーは不要です。エッジは次の 2 つのソースから生成されます。

• 明示的な links — エントリの保存時に宣言するキーです。
• 暗黙的な [[key]] 参照 — コンテンツ内にある [[some-key]] 形式の記述です。

仕組み

1. memory_remember はエントリに links を保存します（スペースまたは ; 区切りのキー）。品質スコアは自動的に計算されます。
2. memory_recall({ mode: "graph" }) はキーワードに一致するもの（シード）を見つけ、エッジをたどって hops（1 または 2）までエゴサブグラフを展開します。
3. 関連性はシードから隣接エントリに伝播するため、クエリの語句が含まれていなくても、関連する決定事項や仕様が表示されます。品質を加味したランキングにより、最も有用なエントリが上位に表示されます。
4. 結果セットは上限（デフォルトは 6）までに制限されるため、エージェントに渡すコンテキストをより小さく、より正確にできます。統合された呼び出しには memory_smart_recall を使うこともできます。

リンク付きで記憶する

memory_remember({
  category: "decision",
  key: "risk-engine-priority",
  content: "The engine prioritizes risk over speed (see [[risk-spec]]).",
  file: "spec.md:10",
  tags: "risk;spec",
  links: "engine-arch"          // explicit edge to another entry
})
// 🧠 Guardado: decision/risk-engine-priority (a1b2c3d4)
// Quality score is calculated automatically based on tags, links, and content detail.

グラフモードで想起する

memory_recall({ query: "riesgo", mode: "graph", hops: 2 })
// [decision] risk-engine-priority (a1b2c3d4)
//   The engine prioritizes risk over speed (see [[risk-spec]]).
//   File: spec.md:10 | Tags: risk;spec | Date: 2026-07-01
//   links: engine-arch
//
// [knowledge] risk-spec (a2b3c4d5)
//   Risk specification for the engine.
//   links: risk-engine-priority;engine-arch
//
// [pattern] engine-arch (e6f7g8h9)
//   Engine architecture.
//   links: risk-spec

ヒント： ある決定が複数のエントリ（アーキテクチャ、仕様、関連するバグ）に波及する場合は、mode: "graph" を使います。独立した事実であれば、デフォルトの flat モードで十分です。または、グラフ＋BM25＋品質を自動的に組み合わせる memory_smart_recall を使います。

トークン効率の高い想起（compact）

すべてのトークンを節約したい場合は、compact: true を渡して、より密度の高い出力を取得します。

memory_recall({ query: "riesgo", mode: "graph", hops: 2, compact: true })
// [1] decision/risk-engine-priority
//   The engine prioritizes risk over speed (see [[risk-spec]]).
//   tags: risk;spec · edges: ->2, ->3
//
// [2] knowledge/risk-spec
//   Risk specification for the engine.
//   tags: risk · edges: ->1
//
// [3] pattern/engine-arch
//   Engine architecture.
//   tags: engine · edges: ->1

compact による出力の変化：

• 各エントリには、スコア順に安定した数値インデックス（[1]、[2]、…）が付きます。
• id、date、file は省略され、tags のみが保持されます。
• graph モードでは、エッジは ->2 のように数値で表示され、キー名は使われません。
• グラフ経由で到達した隣接エントリ（シード以外）は、省略記号付きの短い抜粋に切り詰められます。一方、直接一致したシードは全文が保持されます。
• 品質を加味したランキングにより、最も有用なエントリが上位に表示されます。
• 保存された .toon ファイルは変更されません。compact はレスポンスの形式を変更するだけです。

ヒント： 大規模で相互に関連したメモリーから想起する場合は、compact: true を mode: "graph" と組み合わせると、コンテキストウィンドウを最小限にできます。先回りした想起やバックグラウンドでの想起には、キーと 1 行だけ（約 50 トークン）を返す budget: "tiny" を使います。または、これらを自動で行う memory_smart_recall を使います。

Recall が結果をランク付けする仕組み

Recall は決定論的かつオフラインで動作します（埋め込みも LLM も使用しません）。各候補エントリには、次の要素を組み合わせたスコアが付与されます。

• BM25 関連性 — クエリに対する従来の確率的な用語頻度スコアです。id + category + key + content + file + tags + quality + confidence を対象に使用します。
• グラフ中心性 — 次数で正規化されます（0..1）。多くのエントリと接続されたハブは 1 に近いスコアになり、クエリにその単語が含まれていなくても表示されます。
• 重要度 — 新しさとアクセス頻度です（ほかの箇所でも使用される同じシグナルです）。
• 品質ブースト — 品質スコアが高いエントリ（タグ、リンク、詳細情報が多いエントリ）のランキングを引き上げます。
• シードボーナス — クエリに直接一致するエントリに固定のブーストを加えます。
• ホップごとの減衰 — シードから d ホップ離れたノードには 0.5^d を乗算し、遠いコンテキストの順位が近いコンテキストより低くなります。

graph モードでは、Recall はキーワードの一致をシードとして、最大 hops までエゴサブグラフを展開し、複合スコア順に上位 limit 件（デフォルトは 6 件）を返します。memory_smart_recall は、これらすべてのシグナルを 1 回の呼び出しで組み合わせます。

プロジェクトの依存関係から自動タグ付け

toon-memory init の実行時、CLI は依存関係マニフェストをスキャンし、.toon-memory/memory/config.json に vocab テーブルを書き込みます。

{
  "vocab": {
    "react": ["react"],
    "zod": ["zod"],
    "redis": ["redis"]
  }
}

その後、memory_remember は組み込みの語彙に加えてこの語彙にも照らして新しいエントリを照合するため、コンテンツ内で依存関係に言及すると、そのタグが自動的に付与されます。タグが多いほど品質スコアが高くなります。対応するマニフェスト：package.json、Cargo.toml、requirements.txt、pyproject.toml、go.mod。

ヒント： 主要な依存関係を追加した後に toon-memory init を再実行すると、語彙が更新されます。vocab キーは config.json 内の encrypted／capture フラグと統合されます（上書きされることはありません）。タグが多いほど品質スコアが高くなります。

---

メモリーグラフビューアー

インタラクティブな力学ベースのグラフとしてメモリーを視覚化できます。エントリ、相互の接続、カテゴリ、アクセスパターンを一目で確認できます。

CLI ビューアー（単独の HTTP サーバー）

npx toon-memory viewer          # Start HTTP server + open browser
npx toon-memory viewer --port 3001  # Custom port
npx toon-memory viewer --export     # Save as static HTML

開いた後、ターミナルで r を押すとディスクから再読み込みできます。または、ブラウザーで r／↻ を押してページを更新できます。

インラインビューアー（MCP Apps）

MCP Apps 対応ホストで memory_visualize を呼び出すと、グラフがインラインで表示されます。サーバーは不要です。ビューアーはチャットインターフェース内にインタラクティブなパネルとして表示されます。

機能

操作	説明
ノードに ホバー	コンテンツのプレビュー、品質、アクセス回数をツールチップで表示します
ノードを クリック	選択して中央に配置し、近隣ノードを強調表示します
ノードを ダブルクリック	詳細パネルを開きます
ノードを ドラッグ	手動で位置を変更します（固定を解除するには右クリックします）
検索	エントリを絞り込みます。一致するノードは光って点滅します
⇿ パスファインダー	2 つのノードをクリックすると、最短経路を検索して強調表示します
ズーム／パン	マウスホイールまたは +／− ボタンを使用します
⚙ 物理演算	反発力、リンク距離、中心への引力を調整します
テーマ切り替え	ダークモード／ライトモード（設定は保持されます）
エクスポート	グラフを PNG または SVG として保存します

スクリーンショット

グラフ表示	検索結果の強調表示	パスファインダー	詳細パネル

独自のスクリーンショットを撮影する

npm run capture:viewer

Playwright（npx playwright install chromium）と ffmpeg が必要です。

---

ヒントとベストプラクティス

toon-memory で効果的に使えるパターンを紹介します。

「セッション開始時」の習慣

新しいセッションを開始するたびに、次を実行します。

memory_smart_recall({ intent: "what I was working on" })

これにより、BM25、グラフ、品質、減衰を 1 回の呼び出しで組み合わせ、以前に起きたことをエージェントがすぐに把握できます。

「セッション終了時」の習慣

セッションを終了する前に、重要な情報を保存します。

memory_remember({
  category: "decision",
  key: "auth-approach",
  content: "Chose JWT over sessions — stateless, works across microservices",
  file: "src/auth.ts",
  tags: "auth;architecture"
})

エントリには、その構造（タグ、コンテンツの詳細さ、リンク）に基づいて品質スコアが自動的に付与されます。

カテゴリの選び方

カテゴリ	使用する場面
decision	アーキテクチャの選択、トレードオフ、「YではなくXを選ぶ理由」
pattern	慣習、フレームワーク、コードスタイルのルール
bug	修正した問題とその方法
knowledge	プロジェクトの事実、ドメイン情報、チームの状況
warning	「これは絶対にしない」——アンチパターン、落とし穴、避けるべきミス（優先して呼び出されます）

ヒント： 考えすぎないでください。将来の自分（またはエージェント）が知っておきたいことなら、保存しておきましょう。詳細で具体的なタグが付いたエントリほど、品質スコアが高くなります。

効果的なタグ

絞り込みやすいよう、セミコロンで区切ったタグを使用します：

tags: "redis;performance;fix"
tags: "auth;jwt;security"
tags: "api;rest;versioning"

ヒント： タグは短く、一貫性を保ちましょう。ハッシュタグではなく、検索フィルターです。タグが具体的であるほど、品質スコアが高くなります。

保存しないもの

• コードを読めば明らかなことは保存しないでください
• 一時的なデバッグメモは保存しないでください
• シークレット、API キー、認証情報は保存しないでください（代わりに環境変数を使用してください）
• 同じ情報を異なるキーで重複して保存しないでください（merge-dedup が同じキーのエントリを自動的に処理します）
• タグのない曖昧なエントリは品質スコアが低くなります。具体的に記述してください

メモリを整理する

毎月 memory_archive() を実行して、古いエントリをアーカイブに移動します。memory_stats() を実行すると、サイズと品質の分布を確認できます。品質の低いエントリ（内容が曖昧、タグなし）は、自動的に呼び出しの優先度が下がります。memory_consolidate を使用して重複を統合し、新しいライブラリバージョンによって置き換えられたメモを終了するには mode: "versions" を使用します。

---

CLI コマンド

npx toon-memory              # Interactive installer
npx toon-memory init         # Quick setup (no prompts)
npx toon-memory mcp          # Run MCP server directly
npx toon-memory status       # Check installation status
npx toon-memory stats        # View memory statistics
npx toon-memory export       # Export memory to JSON
npx toon-memory import <file> # Import memory from JSON
npx toon-memory viewer       # Open the memory graph viewer (http server)
npx toon-memory viewer --export # Save viewer as static HTML
npx toon-memory viewer --port 3001 # Custom port
npx toon-memory watch [options] # Auto-backup with options
npx toon-memory upgrade      # Update to latest version
npx toon-memory uninstall    # Remove from all agents

例

統計情報

$ npx toon-memory stats

🧠 toon-memory stats

📊 Memory Stats
━━━━━━━━━━━━━━━━━━
Total entries: 45
├── decision: 12
├── pattern: 18
├── bug: 8
└── knowledge: 7
Last updated: 2026-07-10
File size: 12.4 KB

ヒント： メモリが大きくなりすぎた場合（エントリが100件以上）、memory_forget を使って古いエントリをアーカイブするか削除してください。

エクスポート

$ npx toon-memory export

🧠 toon-memory export

Exported 45 entries to:
  /path/to/project/toon-memory-export.json

ヒント： 大規模なリファクタリングの前にエクスポートしてください。問題が起きても、後からバックアップをインポートできます。

インポート

$ npx toon-memory import backup.json

🧠 toon-memory import

Imported 3 new entries
Skipped 2 duplicates

ヒント： 重複はキーによって検出されます。エントリを再インポートする場合は、まず memory_forget で古いエントリを削除してください。

監視

$ npx toon-memory watch 15 -c -m 20

🧠 toon-memory watch

Watching memory file every 15 minutes...
Max backups: 20
Compression: enabled
Logging: disabled
Press Ctrl+C to stop

📦 Backup #1 created: 2026-07-11T16-00-00-000Z
📦 Backup #2 created: 2026-07-11T16-15-00-000Z
^C
✅ Watch stopped. 2 backups created.

ヒント： 監視モードは長時間実行するセッションに最適です。-c で圧縮し、-m 5 でバックアップを5件だけ保持します。

監視オプション：

オプション	説明	デフォルト
[interval]	バックアップの間隔（分）	5
-c, --compress	gzip 圧縮を有効にする	オフ
-l, --log [path]	ファイルへのログ記録を有効にする	オフ
-m, --max-backups <n>	保持するバックアップの最大数（0=無制限）	10

---

設定

対話型インストーラー（推奨）

npx toon-memory

インストーラー（ターミナルが必要）では、次の操作を行います：

1. 対応している22個のエージェントすべてを、検出状況（✓ 設定が見つかりました）と対応範囲（local/global または solo local）とともに表示します
2. 設定するエージェントを、番号（1,3,5）、名前（claude,codex）、all で選択できます。Enter キーを押すとすべてを選択し、q を押すと終了します
3. インストール範囲を尋ねます：(1) Local（プロジェクト：.toon-memory とリポジトリ内のエージェント設定）または (2) Global（~home の設定）
4. 確認内容（agent → scope → path (MCP/plugin/hooks/instrucciones)）を表示し、¿Proceder? [Y/n] と尋ねます
5. MCP サーバー、指示ファイル、フックを自動的に設定します

ターミナルがない場合（CI／パイプ）に npx toon-memory を実行すると、非対話型インストールのヘルプが表示されます。質問に答えずにインストールするには、npx toon-memory init [local|global] を使用してください。不明なコマンドを実行すると、使用方法が表示され、エラーで終了します。

OpenCode

.opencode/opencode.json または ~/.config/opencode/opencode.json に追加します：

{
  "mcp": {
    "toon-memory": {
      "type": "local",
      "command": ["npx", "-y", "toon-memory", "mcp"],
      "enabled": true
    }
  }
}

フックはトップレベルの hooks キーではなく、プラグイン経由で提供されます。 OpenCode 1.17+ は、設定内の "Unrecognized key: hooks" を拒否します。toon-memory init は代わりに .opencode/plugins/toon-memory.ts を作成します。opencode.json に hooks を追加しないでください。

Claude Code

.mcp.json（プロジェクトのルート）に追加します：

{
  "mcpServers": {
    "toon-memory": {
      "command": "npx",
      "args": ["-y", "toon-memory", "mcp"]
    }
  }
}

VS Code / Copilot

.vscode/mcp.json に追加します：

{
  "servers": {
    "toon-memory": {
      "command": "npx",
      "args": ["-y", "toon-memory", "mcp"]
    }
  }
}

Codex CLI

.codex/config.toml に追加します：

[mcpServers.toon-memory]
command = "npx"
args = ["-y", "toon-memory", "mcp"]

Gemini CLI

.gemini/settings.json に追加します：

{
  "mcpServers": {
    "toon-memory": {
      "command": "npx",
      "args": ["-y", "toon-memory", "mcp"]
    }
  }
}

Zed

~/.config/zed/settings.json に追加します。

{
  "mcp_servers": {
    "toon-memory": {
      "command": "npx",
      "args": ["-y", "toon-memory", "mcp"]
    }
  }
}

ヒント： すべてのプロジェクトでメモリを使用する場合はグローバル設定を使用します。特定のプロジェクトでのみ使用する場合は、プロジェクトレベルの設定を使用します。

---

仕組み

1. MCP サーバー — ローカルで実行され、stdio 経由でエージェントと通信します
2. TOON 形式 — Token-Oriented Object Notation でデータを保存します（gpt-tokenizer で 16 件のエントリを測定した場合、JSON よりトークン数が約 22.5％少なくなります）。各エントリの品質（0～1）と信頼度（0～1）は自動的に追跡されます。
3. プロジェクトごとのメモリ — 各プロジェクトに .toon-memory/memory/data.toon が作成されます
4. 設定不要 — インストールして使用するだけです

メモリファイルの形式

version: 1
entries[3|]{id|category|key|content|file|tags|date|ttl|accessed|links|quality|confidence|lastAccessed|priority|path_scope|origin|status|supersededOn|importance|evidence}:
  a1b2c3d4|decision|use-zod|Use Zod for validation|src/types.ts|validation;types|2026-07-10||0||0.65|1.0||0||agent|active|||verified
  e5f6g7h8|pattern|pydantic-configs|Project uses Pydantic v2|config.py|python;patterns|2026-07-10||0||0.55|1.0||0||agent|active|||
  i9j0k1l2|bug|redis-pool-fix|Added max_connections=20 (see [[use-zod]])|redis.ts|redis;fix|2026-07-10|7d|0|use-zod|0.70|0.9||0||agent|active|||conflict
summaries:
  src/services/redis.ts: Redis connection pool with retry logic

ファイル構造

.toon-memory/
├── memory/
│   ├── data.toon        # Main memory file
│   ├── archive.toon     # Archived entries (>30 days)
│   ├── config.json      # Encryption settings
│   └── backups/         # Watch mode backups
│       ├── backup-2026-07-11T16-00-00-000Z.toon
│       └── backup-2026-07-11T16-10-00-000Z.toon
└── hooks/
    ├── session-start-claude.sh
    ├── session-start-codex.sh
    ├── session-start-gemini.sh
    └── session-start-antigravity.sh

---

TOON を選ぶ理由

TOON（Token-Oriented Object Notation）は LLM 向けに設計されています。

形式	トークン数（16 件）
JSON	1097
TOON	850

gpt-tokenizer（cl100k_base）を使って、代表的なメモリエントリ 16 件を測定しました。詳細は scripts/benchmark-toon.mjs（npm run bench）を参照してください。

トークンの削減効果はセッション中にも積み重なります。npm run bench:impact は、メモリのあり／なしでコンテキストを取得するシミュレーションを行い、同じコンテキストを得るためのトークン数が約 68％少なくなることを測定します（ソースファイルを読み直す代わりに compact をリコールします）。セッション全体のベンチマーク（npm run bench:full）では、context_* ツールを使うとツール呼び出しが 80％減少し、トークン数が 47％減少することが示されています。

• ファイルレベルで JSON よりトークン数が 22.5％少なくなります（単一のエントリでは最大 30.5％）。
• 可逆ラウンドトリップ — データの損失はありません
• LLM の理解が向上 — AI が利用しやすい構造です
• 品質と信頼度 — 各エントリの構造品質（0～1）と信頼性（0～1）が自動的に追跡されます

ヒント： トークン数が少ないほど、応答が速くなり、API コストも低くなります。エージェントはセッション開始時に毎回メモリファイルを読み込むため、効率が重要です。

---

ベンチマーク：toon-memory と代替製品の比較

機能	toon-memory	@modelcontextprotocol/server-memory	mem0	shodh-memory
ストレージ	ローカルファイル（TOON）	ローカルファイル（JSON）	クラウド	RocksDB
依存関係	なし	なし	クラウド API	sentence-transformers、RocksDB
検索	BM25 + グラフ + 品質	基本的なキーワード検索	ベクトルのみ	ハイブリッド（ベクトル + グラフ）
トークン効率	JSON より 22.5％少ない	ベースライン（JSON）	該当なし（クラウド）	同程度
品質スコアリング	自動（0～1、ヒューリスティック）	なし	なし	BND アルゴリズム
マージ時の重複排除	タグの和集合 + 信頼度の最大値	なし	なし	内容の重複排除
信頼度の追跡	エントリごと（0～1）	なし	なし	エントリごと
システムプライマー	自動生成	なし	なし	なし
マルチセッション	ファイルベースの連携	なし	該当なし	なし
フック	15 種のエージェント	なし	なし	Claude のみ
暗号化	AES-256-GCM	なし	クラウド管理	なし
セットアップ時間	npx toon-memory	JSON を手動で設定	クラウドへの登録	Docker + 設定

トークン効率（実測）

Format          Tokens (16 entries)    vs JSON
──────────────  ───────────────────    ───────
JSON            1097                   baseline
TOON            850                    -22.5%

リコール効率（実測）

Method                          Tokens to get context    vs re-reading files
──────────────────────────────  ─────────────────────    ───────────────────
Re-read source files            ~3000                    baseline
memory_recall (flat)            ~1200                    -60%
memory_recall (graph, compact)  ~900                     -70%
memory_smart_recall             ~850                     -72%

コンテキストツールのベンチマーク（実測）

context_* ツールは、3〜6 回の個別のツール呼び出しを 1 回にまとめ、トークンとツール呼び出しのオーバーヘッドを削減します。

Scenario                          Without   With    Saved    Tools
────────────────────────────────  ────────  ──────  ───────  ──────
context_generate (full briefing)    5,556     378    93.2%   6 → 1
context_diff (incremental)            533     152    71.5%   4 → 1
context_focus (targeted)              413     225    45.5%   4 → 1
context_health (audit)                322     246    23.6%   5 → 1
context_export (injectable md)      1,178     218    81.5%   3 → 1
────────────────────────────────  ────────  ──────  ───────  ──────
TOTAL                              8,002   1,219    84.8%  22 → 5

各シナリオで測定する内容：

ツール	使用しない場合（手動の手順）	使用する場合（1 回の呼び出し）	削減できる理由
context_generate	package.json ＋ README ＋ tsconfig.json ＋メモリの完全なダンプ＋メモリ統計＋セッションを読み込む＝6 回の呼び出し	すべてを含む簡潔なブリーフィングを 1 回	重複する 5 回の読み込みを省略し、出力を重複排除して簡潔にまとめます
context_diff	git log ＋ git diff --name-only ＋ memory_diff ＋セッション＝4 回の呼び出し	増分差分を 1 回	git の状態とメモリの変更を 1 つの出力にまとめ、重複をなくします
context_focus	memory_recall ＋ findCallers ＋ findRelatedFiles ＋ findTestFiles＝4 回の呼び出し	対象を絞ったブリーフィングを 1 回	関連する内容のみを返すため、メモリ全体をスキャンする必要がありません
context_health	memory_stats ＋孤立項目のスキャン＋重複項目のスキャン＋ファイル参照の検証＋古いセッションの確認＝5 回の呼び出し	ヘルスレポートを 1 回	各チェックを 1 回だけ行って重複排除するため、冗長なクエリがありません
context_export	memory_stats ＋ memory_recall({ compact: true, mode: "graph" }) ＋手動での整形＝3 回の呼び出し	Markdown エクスポートを 1 回	出力を直接整形するため、エージェントが「Markdown として整形する」手順を省略できます

ヒント： セッション開始時には context_generate を使用してください（トークンを 93% 削減）。「前回から何が変わったか？」を確認するには context_diff を使用してください（72% 削減）。特定のトピックを詳しく調べるには context_focus を使用してください（45% 削減）。

現実的なプロジェクトシナリオを対象に gpt-tokenizer（cl100k_base）で測定しています。詳細は scripts/bench-context-tools.mjs（npm run bench:context）をご覧ください。

セッション全体への影響（実測）

メモリなし、memory_recall 使用、context_* ツール使用の 3 つのアプローチで、5 フェーズのエージェントセッション全体（セッション開始 → デバッグ → 実装 → レビュー → まとめ）をシミュレーションします。

Phase                                   Without memory     memory_recall      context_* tools
──────────────────────────────────────  ─────────────────  ─────────────────  ─────────────────
Phase 1: Session Start                  516 t /  6 c       409 t /  3 c       373 t /  1 c
Phase 2: Debug Issue                    176 t /  4 c       182 t /  2 c       252 t /  1 c
Phase 3: Implement Feature              189 t /  6 c       183 t /  3 c       305 t /  1 c
Phase 4: Code Review                    316 t /  4 c       130 t /  2 c       243 t /  1 c
Phase 5: Wrap-up                      1,214 t /  5 c        68 t /  2 c       117 t /  1 c
──────────────────────────────────────  ─────────────────  ─────────────────  ─────────────────
TOTAL                                 2,411 t / 25 c       972 t / 12 c     1,290 t /  5 c

主な結果：

指標	メモリなし	memory_recall 使用	context_* ツール使用
セッションあたりのトークン数	2,411	972（-60%）	1,290（-47%）
セッションあたりのツール呼び出し回数	25	12（-52%）	5（-80%）
セッションあたりのコスト（GPT-4）	$0.072	$0.029	$0.039

トレードオフ： memory_recall は一致するエントリのみを返すため、使用トークン数が少なくなります（972 対 1,290）。一方、context_* ツールは、呼び出し元、関連ファイル、テストファイル、ヘルス監査など、より豊富なコンテキストを返します。呼び出しあたりのトークン数は増えますが、ツール呼び出し回数を 80% 削減できます。実際には、context_focus に含まれる「関連項目を検索する」追加呼び出しを、エージェントが 3〜4 回省略できます。

context_ が特に効果を発揮する場面：*

• セッション開始（フェーズ 1）：トークンを 28% 削減し、呼び出し回数を 6→1 に削減。6 ファイルの読み込みを 1 回のブリーフィングで置き換えます
• まとめ（フェーズ 5）：トークンを 90% 削減。context_health が 5 回の手動スキャンを置き換えます
• ツール呼び出し：25→5 回の呼び出しとなり、セッションあたりの レイテンシーオーバーヘッドを 80% 削減します

ヒント： 特定のエントリが必要な場合は memory_recall（トークン数を削減）を使用してください。ラウンドトリップを減らしながら包括的なコンテキストが必要な場合は context_*（呼び出し回数を削減）を使用してください。

gpt-tokenizer（cl100k_base）で測定しています。詳細は scripts/bench-full-impact.mjs（npm run bench:full）をご覧ください。

ヒント： memory_smart_recall は BM25、グラフ、品質を 1 回の呼び出しにまとめ、トークンとツール呼び出しのオーバーヘッドを削減します。各タスクの開始時に使用してください。

RRF ランキングのベンチマーク（実測）

v3.7.0 以降、recall は BM25（×3）とグラフ中心性のランキングに対して Reciprocal Rank Fusion を適用し、適応型の k = clamp(3..60, round(sqrt(n))) で結果をランク付けします。関連性を手作業でラベル付けした 8 件のゴールドスタンダードクエリで測定しています（scripts/bench-rrf.mjs、npm run bench:rrf を参照）。

Metric        linear (v3.6.x)     RRF (v3.7.0)
────────────  ─────────────────   ────────────────
nDCG@10       0.776               0.776   (parity)
MRR           0.917               0.917   (parity)

RRF はランキングのコストを ゼロに抑えながら、以前の線形加重スコアと同等の結果を実現し、スコアリングパイプラインを簡素化します（BM25×3 ＋中心性。重要度や新しさによるノイズはありません）。グラフモードでは上書きが考慮されます。as_of による時点指定クエリを除き、古くなったエントリは除外されたままです。

検索ベンチマーク（LongMemEval 形式、実測）

v4.1.0 以降、検索は実際のプロジェクトメモリの凍結スナップショットを使用してベンチマークされています。これは、手作業で作成した正解クエリを含む LongMemEval 形式のテストセットです。コーパスは、実際の data.toon エントリ 187 件（スナップショット 2026-08-01）と、6 カテゴリ（core-fact、temporal、knowledge-updating、multi-hop、meta/session、distractor）にわたる正解クエリ 42 件で構成されています。測定対象のコードは本番パイプライン（src/lib）であり、esbuild を使ってメモリ内にバンドルされています。忠実に再現したコピーは使用していません。決定論的な today パラメーターで最近性／減衰を固定するため、結果が実時間によって変動することはありません。実行は読み取り専用です（アクセス追跡は行いません）。データファイル自体を説明する優先度の高いメタエントリ 2 件は除外されています。benchmarks/retrieval-corpus.toon、benchmarks/gold-queries.json を参照してください（npm run bench:retrieval）。

Mode            R@5     nDCG@5  MRR@5   answerable
─────────────   ─────   ─────   ─────   ──────────
linear         0.643   0.654   0.776   81.0%
rrf            0.861   0.764   0.788   97.6%
smart (unified) 0.829  0.739   0.760   92.5%

RRF が最も高い順位のモードです（R@5 は 0.861、クエリの 97.6% が上位 5 件から回答可能）。memory_smart_recall も 1 回の呼び出しで高い競争力を保っています。

---

トラブルシューティング

インストール後にメモリが見つからない

症状： エージェントがメモリツールを持っていないと言います。

対処方法：

1. npx toon-memory status を実行して、インストールを確認します
2. エージェントを完全に再起動します（終了してから再度開きます）
3. MCP 設定ファイルが存在し、有効な JSON であることを確認します

メモリファイルが空

症状： memory_stats にエントリが 0 件と表示されます。

対処方法： 初回インストール時は正常です。memory_remember を使ってエントリを保存してください。

エントリの重複

症状： 同じキーが複数回表示されます。

対処方法： 同じキーを指定した memory_remember は、自動的にマージされるようになりました（タグの和集合、最大の信頼度、最新の日付が適用されます）。memory_consolidate を使うと、同じキーを持つすべてのエントリをマージし、内容が完全に重複するエントリを削除できます。手動で整理する場合は、memory_forget を使用してください。

暗号化キーを紛失した

症状： メモリを復号できません。

対処方法： 残念ながら、復元する方法はありません。暗号化キーは生成後、どこにも保存されません。これはセキュリティ上の設計です。新しく始めるか、暗号化されていないバックアップから復元する必要があります。

メモリが大きすぎる

症状： エージェントの応答が遅くなります。

対処方法：

1. memory_archive() を実行して、古いエントリをアーカイブに移動します
2. memory_forget を使って、関連性のないエントリを削除します
3. エントリは簡潔に保ち、会話全体ではなく決定事項を保存します
4. 品質の低いエントリ（曖昧でタグがないもの）は、自動的に想起の優先度が下がります

---

よくある質問

どの AI エージェントでも使えますか？

はい。MCP（Model Context Protocol）に対応していれば使用できます。22 種類のエージェント向けに自動セットアップを用意しており、その他のエージェントでは手動で設定できます。

データはどこかに送信されますか？

いいえ。すべてお使いのマシン内にとどまります。MCP サーバーは stdio 経由でローカルに実行されます。ネットワーク通信、テレメトリー、クラウドのいずれも使用しません。

複数のマシンで使用できますか？

はい。.toon-memory/memory/ ディレクトリを同期すれば使用できます（Git や共有フォルダーなど）。各マシンに toon-memory をインストールする必要がありますが、メモリファイルはポータブルです。

複数のプロジェクトがある場合はどうなりますか？

プロジェクトごとに専用のメモリファイルが作成されます。プロジェクト間でメモリが漏れることはありません。

特定のエントリだけを暗号化できますか？

いいえ。暗号化はメモリファイル全体に適用されます。選択的に暗号化する必要がある場合は、機密データを別のツールに保存してください。

Markdown ファイルを使う場合と何が違いますか？

Markdown ファイルは構造化されておらず、同じ方法でエージェントから検索できません。また、MCP 経由で統合されず、アーカイブ、日付フィルタリング、品質スコアリング、マージと重複排除、信頼度の追跡、暗号化などの機能もありません。toon-memory は AI エージェント専用に開発されています。

---

開発

git clone https://github.com/LuiggiVal08/toon-memory.git
cd toon-memory
npm install
npm run build
npm test

プロジェクト構成

toon-memory/
├── src/
│   ├── bin/
│   │   └── toon-memory.ts      # Entry point
│   ├── cli/
│   │   ├── setup.ts             # CLI commands
│   │   └── toon-memory.ts       # CLI runner
│   ├── mcp/
│   │   ├── server.ts            # MCP server (38 tools + 4 resources + 1 prompt)
│   │   ├── tools.ts             # Tool registration (38 tools)
│   │   ├── resources.ts         # Resource registration (4 resources)
│   │   ├── prompts.ts           # Prompt registration (1 prompt)
│   │   ├── session-store.ts     # Session layer (auto-promote, cleanup)
│   │   ├── memory-io.ts         # Memory file read/write
│   │   ├── entries.ts           # Entry parsing & utilities
│   │   ├── scoring.ts           # Entry scoring & access tracking
│   │   ├── archive.ts           # Archive management
│   │   ├── consolidation.ts     # Duplicate consolidation
│   │   ├── config.ts            # Config loading & saving
│   │   └── crypto.ts            # AES-256-GCM encryption
│   ├── lib/
│   │   ├── lock.ts              # Advisory file lock + atomic write
│   │   ├── sessions.ts          # Multi-session coordination
│   │   ├── graph.ts             # Memory graph (parse, build, BM25, centrality, compact render)
│   │   ├── quality.ts           # Quality scoring, merge-dedup, smart recall, system primer
│   │   ├── context.ts           # Context briefing generator (one-call context)
│   │   └── vocab.ts             # Project-vocabulary discovery from dependencies
├── tests/
│   ├── cli.test.ts              # CLI tests
│   ├── memory.test.ts           # Memory tests
│   ├── sessions.test.ts         # Multi-session tests
│   ├── graph.test.ts            # Memory graph tests
│   └── quality.test.ts          # Quality scoring, merge-dedup, smart recall, system primer tests
├── .github/workflows/
│   ├── ci.yml                   # CI (Node.js 20/22)
│   └── publish.yml              # Auto-publish on release
├── package.json
├── tsconfig.json
└── vitest.config.ts

---

コントリビューション

コントリビューションを歓迎します！まず、行動規範とコントリビューションガイドをお読みください。

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'feat: add amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. プルリクエストを作成します

---

セキュリティとプライバシー

toon-memory は、セキュリティとプライバシーを基本原則として設計されています。

• 100% ローカルストレージ — すべてのメモリは、マシン上の .toon-memory/memory/ にローカル保存されます。外部サーバー、クラウドサービス、第三者にデータが送信されることはありません。
• テレメトリーなし — このプロジェクトには、いかなる種類のテレメトリー、分析、トラッキングもありません。利用データは収集されません。
• リモートコード実行なし — toon-memory は、標準的な MCP サーバーとして stdio 経由で動作します。リモートコードのダウンロード、実行、評価は行いません。
• 保存データの暗号化 — メモリファイル全体を対象とした AES-256-GCM による暗号化を任意で利用できます。memory_encrypt で有効にしてください（TOON_MEMORY_KEY 環境変数が必要です）。
• 暗号化キーは保存されません — 暗号化キーは環境変数で指定する必要があり、toon-memory によって永続化されることはありません。キーを紛失した場合、データを復元できません。
• プロジェクトごとの分離 — 各プロジェクトには、独立したメモリファイルがあります。メモリがプロジェクト間で漏えいすることはありません。
• .gitignore の自動設定 — インストーラーは、メモリデータを誤ってコミットしないよう、.toon-memory/memory/ を .gitignore に追加します。

---

ライセンス

MIT

---

クレジット

@toon-format/toon および @modelcontextprotocol/server を使用して構築されています。