longterm-memory

LongtermMemory-MCP

AI エージェントに永続的でセマンティックな長期記憶を提供する、完全ローカルで動作する MCP サーバーです。クラウドへの依存は一切ありません。

mcp-mem0 に着想を得ていますが、100% お使いのマシン上で動作します。

機能	mcp-mem0	このプロジェクト
ストレージ	PostgreSQL / Supabase	SQLite（Node 組み込みの node:sqlite）
埋め込み	OpenAI API	ローカルトランスフォーマー（all-MiniLM-L6-v2）
ベクトル検索	クラウドベクトル DB	プロセス内のコサイン類似度
LLM 依存関係	OpenAI / OpenRouter / Ollama	なし
セットアップ	データベース + API キー	npx longterm-memory-mcp

ツール

コア

ツール	説明
save_memory	自動生成されるセマンティック埋め込み、タグ、重要度、種類とともにテキストを保存します
search_memory	自然言語クエリを使って関連する記憶を検索します（コサイン類似度）
update_memory	既存の記憶の内容、メタデータ、タグ、重要度、種類を変更します
delete_memory	ID を指定して特定の記憶を削除します
delete_all_memories	すべての記憶を消去します（取り消し不可）
get_all_memories	保存されているすべての記憶を一覧表示します（ページネーション対応）
memory_stats	件数とデータベースの場所を取得します

検索

ツール	説明
search_by_type	カテゴリー（general、fact、preference、conversation、task、ephemeral）で記憶を絞り込みます
search_by_tags	指定したタグのいずれかに一致する記憶を検索します
search_by_date_range	指定した日付範囲内に作成された記憶を検索します（ISO 形式）

メンテナンス

ツール	説明
create_backup	JSON エクスポートを伴うデータベースのバックアップを手動で実行します

クイックスタート

Claude Code プラグイン（推奨）

Claude Code マーケットプレイスからインストールします。MCP サーバーと、記憶を効果的に使う方法を Claude に教える補助スキルの両方がセットアップされます。

/plugin marketplace add MarcelRoozekrans/LongtermMemory-MCP
/plugin install longterm-memory@longterm-memory-marketplace

これにより、次の設定が自動的に行われます。

• MCP サーバーを設定します（手動で JSON を編集する必要はありません）
• long-term-memory スキルをインストールします（Claude はセッション開始時にコンテキストを想起し、タスク後に知見を保存し、記憶の重複を排除する方法を学習します）

npx で使用（インストール不要）

npx longterm-memory-mcp

またはグローバルにインストール

npm install -g longterm-memory-mcp
longterm-memory-mcp

またはソースからインストール

git clone https://github.com/MarcelRoozekrans/LongtermMemory-MCP.git
cd LongtermMemory-MCP
npm install && npm run build
npm start

設定

Claude Code

プラグインマーケットプレイスからインストールした場合、MCP サーバーはすでに設定されています。手動で設定する場合は、MCP 設定（~/.claude/settings.json またはプロジェクトの .claude/settings.json）に追加します。

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

Claude Desktop

claude_desktop_config.json に追加します。

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

エージェントへの指示

このリポジトリには、AI エージェントが記憶を効果的に使う方法（自動想起、保存パターン、重複排除）を教えるエージェント向けの指示が含まれています。

ファイル	目的
skills/long-term-memory/SKILL.md	単独で利用できるスキルです。Claude Code プラグインによって自動読み込みされ、あらゆる MCP クライアントから参照できます

データベースの場所

デフォルトでは、メモリはユーザー単位で共有される場所に保存されます。

~/.longterm-memory-mcp/memories.db

つまり、すべてのプロジェクトとすべての MCP クライアントが同じメモリプールを共有します。あるプロジェクトで保存したメモリは、どこでも利用できます。

複数のセッションで同じデータベースを同時に使用できます。各サーバープロセスが共有ファイルを直接読み書きするため（WAL モードの SQLite）、あるセッションで保存したメモリはすぐに他のすべてのセッションから見えるようになり、別のセッションが保存した内容を上書きすることもありません。Node.js 22.13 以降が必要です。

以前のリリースのデータベースは、そのまま開けます。schema_meta テーブルのない v1.0～1.3 のデータベースは、すべてのメモリを保持したままその場で移行されます。移行前に、memories.db.pre-migration-<timestamp>.bak という名前のコピーが同じ場所に作成されます。

1.4 以前からのアップグレード： 新しいバージョンを起動する前に、古いバージョンを使用している実行中のセッションをすべて停止してください。以前のリリースはデータベース全体をメモリに保持し、保存のたびにファイルを書き換えるため、古いプロセスを実行したままにすると、新しいセッションが保存した内容を上書きしてしまいます。

プロジェクトごとのデータベース

特定のプロジェクトのメモリを分離するには、MEMORY_DB_PATH 環境変数を設定します。

{
  "mcpServers": {
    "longterm-memory": {
      "command": "npx",
      "args": ["-y", "longterm-memory-mcp"],
      "env": {
        "MEMORY_DB_PATH": "/path/to/project/memories.db"
      }
    }
  }
}

メモリの種類

各メモリには、分類方法と減衰速度を決定する memory_type があります。

種類	説明	減衰の半減期
general	デフォルトの汎用タイプ	60 日
fact	検証済みの情報	120 日
preference	ユーザー／プロジェクトの設定	90 日
conversation	会話のコンテキスト	45 日
task	タスク関連のメモ	30 日
ephemeral	短期間のみ有効なコンテキスト	10 日

タグと重要度

• タグ：文字列タグ（例：["auth", "backend"]）を使ってメモリを分類します。search_by_tags で検索できます。
• 重要度（1～10）：メモリの減衰しにくさを制御します。デフォルトは 5 です。重要度が高いほど、減衰が遅くなります。
• 保護タグ：core、identity、pinned のいずれかが付いたメモリは、減衰しません。

減衰と強化

ストアの関連性を保つため、メモリは時間の経過とともに減衰します。

• 減衰：各メモリの種類には半減期があります（上の表を参照）。最後にアクセスしてからの経過時間に応じて重要度が指数関数的に低下しますが、完全に削除されないよう下限が設けられています。
• 強化：検索を通じてメモリにアクセスするたびに、重要度が +0.1 上がります（最大 10）。頻繁にアクセスされるメモリは重要度を保ちます。
• 遅延評価：減衰はタイマーではなくアクセス時に計算されるため、バックグラウンドプロセスは不要です。

コンテンツの重複排除

保存時にメモリのコンテンツがハッシュ化されます（SHA-256）。同一のコンテンツがすでに存在する場合、既存のメモリ ID を示して保存を拒否します。これにより、重複したエントリーが自動的に防止されます。

バックアップ

バックアップは自動的に管理され、create_backup ツールから手動で作成することもできます。

• 自動バックアップ：24 時間ごと、またはメモリ数が 100 の倍数に達したときに実行されます。
• 保持期間：最新の 10 件のバックアップが保持され、それより古いものは自動的に削除されます。
• 形式：各バックアップはタイムスタンプ付きのディレクトリで、SQLite データベースの一貫性のあるスナップショットと、すべてのメモリの JSON エクスポートが含まれます。
• 場所：デフォルトでは ~/.longterm-memory-mcp/backups/ です。変更するには MEMORY_BACKUP_PATH を設定します。

{
  "mcpServers": {
    "longterm-memory": {
      "command": "npx",
      "args": ["-y", "longterm-memory-mcp"],
      "env": {
        "MEMORY_BACKUP_PATH": "/path/to/backups"
      }
    }
  }
}

仕組み

1. 保存：テキストは all-MiniLM-L6-v2（384 次元ベクトル）を使ってローカルで埋め込み処理され、生のコンテンツ、メタデータ、タグ、重要度、種類とともに SQLite に保存されます。コンテンツは SHA-256 ハッシュによって重複排除されます。
2. 検索：クエリも同じモデルで埋め込み処理され、保存されているすべてのメモリーとコサイン類似度で比較されます。しきい値を超える結果が、関連度順に返されます。アクセスされたメモリーは自動的に強化されます。
3. 減衰：時間が経つにつれて、使われていないメモリーは種類ごとの半減期に基づいて重要度が低下します。保護されたメモリーや頻繁にアクセスされるメモリーは、減衰しにくくなります。
4. 永続化：変更はすべてディスク上の SQLite データベースに直接書き込まれるため、同時に実行されるセッション間で一貫したストアが共有されます。バックグラウンドプロセスも、管理が必要なサーバーもありません。

埋め込みモデル（量子化済みで約 30 MB）は、初回使用時に一度だけダウンロードされ、ローカルにキャッシュされます。

アーキテクチャ

src/                           — MCP server source
  index.ts                     — Entry point (stdio transport, DB/backup path resolution)
  server.ts                    — MCP server factory + 11 tool definitions
  memory-store.ts              — SQLite storage + vector search + decay integration
  embeddings.ts                — Local embedding engine (Xenova/transformers)
  decay.ts                     — DecayEngine (lazy decay, reinforcement, protected tags)
  backup.ts                    — BackupManager (auto-backup, JSON export, pruning)
  types.ts                     — TypeScript interfaces (Memory, Embedder, config types)

skills/                        — Claude Code plugin skill
  long-term-memory/SKILL.md    — Self-contained agent instructions + skill

.claude-plugin/                — Plugin & marketplace metadata
  plugin.json                  — Plugin manifest
  marketplace.json             — Marketplace manifest
.mcp.json                      — Auto-configures MCP server on plugin install
.vscode/mcp.json               — VS Code MCP server config

ベンチマーク

npm run bench で実行します。結果は、モック埋め込みを使ったインメモリストアでのものです（モデルのレイテンシーとストア／SQLite のパフォーマンスを分離します）。

コサイン類似度

操作	スループット	備考
単一計算（384 次元）	約 420 万 ops/s	実際の埋め込み次元数と同じ
128 次元	約 860 万 ops/s
768 次元	約 240 万 ops/s
1536 次元	約 130 万 ops/s	次元数に比例してスケール

メモリーストアの操作

操作	スループット	備考
保存（単一）	約 1,120 ops/s	埋め込み処理、SQLite への挿入、重複チェックを含む
100 件の一括保存	約 18 ops/s	100 件の一括処理あたり約 55 ms
1000 件の一括保存	約 0.3 ops/s	1000 件の一括処理あたり約 3.1 秒
更新（コンテンツ、再埋め込み）	約 155 ops/s
更新（メタデータのみ）	約 344 ops/s	コンテンツ更新より 2.2 倍高速
削除	約 469 ops/s

検索（セマンティック、規模別）

ストアサイズ	操作	備考
10 件のメモリー	search (limit=5)	全件走査＋各メモリーのコサイン類似度計算
100 件のメモリー	search (limit=5)
500 件のメモリー	search (limit=5)
1000 件のメモリー	search (limit=5)	線形走査 — ストアサイズに比例してスケール

減衰エンジン

操作	スループット
単一の減衰計算	約 2,100 万 ops/s
単一の強化処理	約 2,570 万 ops/s
shouldProtect（タグチェック）	約 2,200 万 ops/s

開発

npm install          # Install dependencies
npm run build        # Compile TypeScript
npm test             # Run all tests
npm run bench        # Run benchmarks
npm run test:watch   # Watch mode
npm run test:coverage # Coverage report

コントリビューション

このプロジェクトでは、自動バージョン管理に Conventional Commits と semantic-release を使用しています。

コミットメッセージの形式

<type>(<optional scope>): <description>

[optional body]

[optional footer(s)]

種類	目的	バージョンの更新
feat	新機能	マイナー（0.x.0）
fix	バグ修正	パッチ（0.0.x）
docs	ドキュメントのみ	リリースなし
style	フォーマット、空白	リリースなし
refactor	コードの再構成	リリースなし
test	テストの追加／更新	リリースなし
chore	メンテナンス、依存関係	リリースなし
ci	CI/CD の変更	リリースなし

破壊的変更：種類の後に ! を付ける（例：feat!: remove deprecated API）か、BREAKING CHANGE: フッターを含めます。これによりメジャーバージョンが更新されます。

例

git commit -m "feat: add memory tagging support"
git commit -m "fix: handle empty search query gracefully"
git commit -m "feat!: change default database location"
git commit -m "docs: update configuration examples"

コミットメッセージは、commitlint と husky の Git フックによってローカルで検証されます。形式に準拠していないメッセージは拒否されます。

リリース

リリースはすべて自動化されています。コミットが main にプッシュされると、次の処理が実行されます。

1. semantic-release がコミットメッセージを解析します
2. 次のバージョン（メジャー／マイナー／パッチ）を決定します
3. コミットからリリースノートを生成します
4. CHANGELOG.md を更新します
5. npm に公開します
6. GitHub Release を作成します

手動でのバージョン更新やタグ付けは不要です。

依存関係の更新

依存関係は Renovate によって自動管理されます。開発用依存関係のパッチおよびマイナー更新は、CI 通過後に自動マージされます。メジャー更新では、手動レビュー用の PR が作成されます。

ライセンス

MIT