Total Agent Memory

AI コーディングエージェントのための永続的なローカルメモリ：Claude Code、Codex CLI、Cursor、およびあらゆる MCP クライアントに対応します。

ウェブサイトとドキュメント：totalmemory.dev · クイックスタート · Claude Code ガイド · ベンチマーク · 他のツールとの比較

total-agent-memory（TAM）は、AI コーディングエージェント向けのオープンソースメモリサーバーです。 コーディングエージェントは、毎回のセッションを以前のセッションの記憶なしに開始するため、決定事項、修正内容、プロジェクトの規約を何度も説明しなければなりません。TAM は、決定事項、解決策、事実、エラー、セッションの要約をお使いのマシンに保存し、Model Context Protocol（MCP）を通じて提供するため、あらゆる MCP クライアントがコードを変更せずに利用できます。

各ストアは、SQLite データベースを中心とした単一のディレクトリです。想起処理では、全文検索 BM25、ローカルで計算される高密度埋め込み、ファジーマッチング、ナレッジグラフを組み合わせ、逆順位融合によってランキング済みリストを統合します。オプションのクロスエンコーダーで結果を再ランキングすることもできます。デフォルトのプロファイルでは、書き込み時も検索時も LLM を呼び出さないため、検索をオフラインで評価でき、再実行しても同じ結果が得られます。事実には有効期間（kg_add_fact、kg_at）を設定でき、単一値の事実に新しい値が登録されると、古い値を無効化できます。

TAM は、コーディングエージェントを日常的に利用する開発者と、ローカルで実行し、内容を確認して変更できるメモリのベースラインを必要とする研究者を対象としています。同じパッケージをチームサーバーとして実行することもできます。個人、部門、会社の領域を、ロール、作成者情報、監査証跡を備えた単一のゲートウェイの背後にある別々のストアとして管理します（チームサーバー）。

インストール

TAM には Python 3.11 以降が必要です。CI では Ubuntu、Windows、macOS 上で Python 3.11、3.12、3.13 をテストしています。

PyPI からインストール（仮想環境、または pipx / uvx を使用してください）：

pip install total-agent-memory          # or: pipx install total-agent-memory
uvx total-agent-memory                  # run once without installing

これにより、total-agent-memory（別名 tam）MCP サーバーと、tam-team、tam-remote、lookup-memory コマンドがインストールされます。オプションのクロスエンコーダーリランカーは PyTorch を必要とするため、追加機能として提供されています。 pip install "total-agent-memory[rerank]"。チームサーバーの PostgreSQL バックエンドは [postgres] 追加機能です。

クライアントに登録します。 ターミナルで tam setup を実行します。ウィザードで「自分だけ」または「会社のサーバー」を選ぶと、Claude Code、Claude Desktop、Codex、Cursor、Windsurf、Gemini CLI、Cline、OpenCode を検出し、選択したクライアントにサーバーを登録します（セットアップウィザード）。

その他の方法：

方法	コマンド
Docker（linux/amd64、linux/arm64）	docker run -p 3737:3737 -p 37737:37737 -v ~/.tam:/data ghcr.io/vbcherepanov/total-agent-memory:14.9.0 — :3737/mcp で MCP over HTTP、:37737 でダッシュボードを提供します
npx コネクター	npx -y total-agent-memory connect claude-code（または codex、cursor、cline、continue、aider、windsurf、gemini-cli、opencode）
Claude Code プラグイン（サーバー、スキル、記録フック）	/plugin marketplace add vbcherepanov/total-agent-memory /plugin install total-agent-memory@vbcherepanov
プラグインリポジトリの Claude Code と Cowork 用プラグイン（サーバーとスキル、フックなし。uv が必要）	/plugin marketplace add vbcherepanov/total-agent-memory-plugin /plugin install total-agent-memory@vbcherepanov
Codex CLI 用の同じプラグイン	codex plugin marketplace add vbcherepanov/total-agent-memory-plugin codex plugin add total-agent-memory@vbcherepanov
IDE フックとバックグラウンドサービスを含むソースのチェックアウト	git clone https://github.com/vbcherepanov/total-agent-memory.git && cd total-agent-memory && ./install.sh --ide claude-code（Windows の場合：install.ps1 -Ide claude-code）

Claude Code プラグインは、2 つのうちどちらか一方だけを使用してください。プラットフォームごとの詳細、WSL2、IDE 対応状況、アンインストール、トラブルシューティングについては、インストールガイドをご覧ください。

クイックスタート

1. パッケージをインストールして tam setup を実行するか、サーバーをクライアントに手動で追加します。Claude Code の場合：

   claude mcp add memory -- total-agent-memory
   

   mcpServers ファイルを使うクライアントの場合：

   { "mcpServers": { "memory": { "command": "total-agent-memory" } } }
   

   仮想環境にインストールした場合は、その環境にある total-agent-memory 実行ファイルのフルパスを指定してください。

2. クライアントを再起動します。メモリは、TAM_MEMORY_DIR で別の場所を指定しない限り、~/.tam/ に保存されます。

3. エージェントに何かを記憶するよう依頼します（「行レベルセキュリティを理由に、請求処理には PostgreSQL を選んだことを覚えておいて」）。エージェントは memory_save を呼び出します。後のセッションで「請求処理にはどのデータベースを選んだ？」と尋ねると、エージェントは memory_recall を呼び出して記録を取得します。

エージェントを使わずにサーバーを試すには、このスクリプトを実行します。MCP Python SDK（依存関係としてインストール済み）でサーバーを stdio 経由で起動し、記録を 1 件保存して取得します。SDK は既定ではサーバーに少数の環境変数しか渡さないため、スクリプトは TAM_MEMORY_DIR を含む環境全体を渡します：

import asyncio
import os

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client


async def main() -> None:
    server = StdioServerParameters(command="total-agent-memory", env=dict(os.environ))
    async with stdio_client(server) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            await session.call_tool("memory_save", {
                "type": "decision",
                "content": "Chose PostgreSQL over MySQL for the billing service",
                "context": "WHY: row-level security per tenant",
                "project": "demo",
            })
            result = await session.call_tool("memory_recall", {
                "query": "which database for billing", "project": "demo", "limit": 3,
            })
            print(result.content[0].text)


asyncio.run(main())

TAM_MEMORY_DIR="$(mktemp -d)" python quickstart.py

初回の実行時に、既定の埋め込みモデルがダウンロードされます。出力は JSON で、保存された決定事項は results.decision に含まれます。その他の例については、ツールとインターフェースをご覧ください。

テストの実行

テストはソースチェックアウトから実行します。以下のコマンドは、.github/workflows の CI ワークフローと同じです。

git clone https://github.com/vbcherepanov/total-agent-memory.git
cd total-agent-memory
python3 -m venv .venv
.venv/bin/pip install -e . -r requirements-dev.txt

export FASTEMBED_CACHE_PATH="$PWD/.tam-models" TAM_MEMORY_DIR="$PWD/.tam-test-memory"
.venv/bin/python tests/smoke/prewarm_models.py   # downloads the text and code embedding models and the cross-encoder (~940 MB) once
.venv/bin/python -m pytest tests -q

テストに API キーや LLM は不要です。全テストスイートの実行には、ノート PC で 15～20 分かかります。全テストスイートを実行するときは、MEMORY_LLM_ENABLED=false を設定しないでください。設定テストでは LLM の自動検出を確認します。利用できないサービスが必要なテストはスキップされます。

• PostgreSQL（チームサーバーのバックエンド）：.venv/bin/pip install -e ".[postgres]" で追加機能をインストールしてから、.venv/bin/python -m pytest tests -m postgres --backend=postgres または --backend=both を実行します。TAM_TEST_PG_URL が設定されていない場合、フィクスチャは Docker 経由で pgvector コンテナーを起動します。CONTRIBUTING.md と .github/workflows/postgres.yml を参照してください。
• ブラウザーテスト（tests/browser、Chromium、Firefox、WebKit を使用する Playwright）は、docker/Dockerfile.browser からビルドしたイメージで実行します。.github/workflows/smoke.yml の browser ジョブを参照してください。
• インストール済みパッケージのスモークテスト：python tests/smoke/installed_runtime.py は、ローカルおよびリモートの MCP を介してインストール済みの wheel を確認します。

ベンチマークの再現

検索ベンチマーク（LoCoMo、LongMemEval、BEAM）は API キー不要で、公開データセットをダウンロードすれば、benchmarks/ のスクリプトで実行できます。デフォルトプロファイル v13.0.0 での結果：

ベンチマーク	指標	結果
LongMemEval（470 問）	R@5（recall_any）	95.1%
LoCoMo（1,536 問）	R@5	0.607
BEAM、100 万トークンスケール（625 プローブ）	R@5	0.448

データセットの場所、コマンド、エンドツーエンド（LLM による判定）精度、ネガティブコントロール、レイテンシ、14.x の調査については、docs/benchmarks.md を参照してください。

ドキュメント

• インストールガイド：すべてのチャネル、プラットフォーム別のセットアップ、WSL2、IDE の一覧、トラブルシューティング
• セットアップウィザード：tam setup とチームサーバーの Web ウィザード
• ツールとインターフェース：79 個の MCP ツール、CLI、TypeScript SDK、ダッシュボード
• 設定：環境変数、LLM プロバイダー、パフォーマンスの調整
• ローカル設定ページ と 内部 LLM 設定
• アーキテクチャ
• チームサーバーのクイックスタート、ダッシュボード、PostgreSQL、バックアップ、オンボーディング、レポート
• ベンチマーク と 他のシステムとの比較（2026 年 4 月時点）
• 更新とアップグレード
• 14.x の新機能、ロードマップと v8～v13 の履歴、CHANGELOG
• セキュリティポリシー

引用

TAM を説明する論文は Journal of Open Source Software で査読中です（paper/paper.md）。公開されるまでは、ソフトウェアとプレプリントを次のように引用してください。

Cherepanov, V. total-agent-memory (version 14.9.0) [software]. https://github.com/vbcherepanov/total-agent-memory

プレプリント：doi:10.5281/zenodo.23011523

ソフトウェアの引用メタデータは CITATION.cff にあります。

貢献

イシュー、プルリクエスト、ベンチマークの再現を歓迎します。開発環境のセットアップ、プルリクエストのルール、コミット規約については、CONTRIBUTING.md を参照してください。セキュリティ上の問題は、SECURITY.md に記載の方法で非公開に報告してください。 開発支援の寄付はこちら：PayPal。

ライセンス

MIT。LICENSE を参照してください。サードパーティのライセンスは THIRD-PARTY-LICENSES.md に記載されています。