ainative-zerodb-memory-mcp

ZeroDB エージェントメモリ MCP サーバー

AI エージェントのための永続メモリ

エージェントメモリ管理、コンテキスト合成、自動コンテキストミドルウェア、外部サービスへの書き戻しアクションに対応する、14 個のツールを提供する最適化された MCP サーバーです。

この MCP を選ぶ理由

導入前： 77 個のツールを備え、10,400 トークン以上を消費するモノリシックなサーバー 導入後： 14 個のツールを備え、約 1,400 トークンを消費する特化型サーバー 結果： コンテキストの使用量を 87% 削減し、エージェントの意思決定を高速化し、精度を向上

主な機能

スマートなコンテキスト管理

• トークン数の自動制限 - LLM のコンテキストウィンドウを超過しません
• インテリジェントな剪定 - 重要で新しいメモリを保持します
• メモリの減衰 - 古いメモリは時間とともに自然に薄れていきます
• 重要度のスコアリング - メモリの重要度を自動的にランク付けします

セマンティックメモリ

• ベクトル埋め込み - BAAI BGE モデル（384、768、1024 次元）
• セマンティック検索 - キーワードだけでなく、意味から検索します
• セッション間メモリ - 会話をまたいで記憶します
• 埋め込みの自動生成 - 手動で埋め込みを生成する必要はありません

あらゆる環境との互換性

• ZeroLocal - localhost:8000（高速、無料、プライベート）
• ZeroDB Cloud - api.ainative.studio（スケーラブル、マネージド）
• 自動検出 - 利用可能なエンドポイントを自動的に検出します

インストール

# Clone repository
git clone https://github.com/ainative/zerodb-memory-mcp.git
cd zerodb-memory-mcp

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your credentials

# Test locally
npm start

設定

認証情報

# Recommended: API key auth (no login needed)
ZERODB_API_KEY=sk_xxx
ZERODB_API_URL=https://api.ainative.studio
ZERODB_PROJECT_ID=your-project-id

# OR username/password auth:
[email protected]
ZERODB_PASSWORD=your-password
ZERODB_API_URL=https://api.ainative.studio
ZERODB_PROJECT_ID=your-project-id

ヒント： API キー認証（ZERODB_API_KEY）は、ユーザー名とパスワードによる認証よりも推奨されます。トークンの有効期限切れの問題を回避でき、シェルの環境変数との競合の影響も受けません。

オプション 1：環境変数

export ZERODB_API_URL="http://localhost:8000"  # or cloud URL
export ZERODB_API_KEY="sk_your-api-key"        # recommended
export ZERODB_PROJECT_ID="your-project-id"

オプション 2：Claude Desktop の設定

{
  "mcpServers": {
    "zerodb-memory": {
      "command": "node",
      "args": ["/path/to/zerodb-memory-mcp/index.js"],
      "env": {
        "ZERODB_API_URL": "http://localhost:8000",
        "ZERODB_USERNAME": "your-username",
        "ZERODB_PASSWORD": "your-password",
        "ZERODB_PROJECT_ID": "your-project-id"
      }
    }
  }
}

オプション 3：ローカルとクラウドの両方を使用

{
  "mcpServers": {
    "zerodb-local": {
      "command": "node",
      "args": ["/path/to/zerodb-memory-mcp/index.js"],
      "env": {
        "ZERODB_API_URL": "http://localhost:8000",
        "ZERODB_USERNAME": "your-local-username",
        "ZERODB_PASSWORD": "your-local-password",
        "ZERODB_PROJECT_ID": "your-local-project-id"
      }
    },
    "zerodb-cloud": {
      "command": "node",
      "args": ["/path/to/zerodb-memory-mcp/index.js"],
      "env": {
        "ZERODB_API_URL": "https://api.ainative.studio",
        "ZERODB_USERNAME": "your-cloud-username",
        "ZERODB_PASSWORD": "your-cloud-password",
        "ZERODB_PROJECT_ID": "your-cloud-project-id"
      }
    }
  }
}

ツール

1. zerodb_store_memory

重要度の自動スコアリングと埋め込み生成を行い、会話のコンテキストを保存します。

入力：

{
  "content": "User prefers technical explanations over simplified ones",
  "role": "system",
  "session_id": "chat-123",
  "tags": ["preference", "important"],
  "user_id": "user-456"
}

出力：

{
  "success": true,
  "memory_id": "mem_abc123",
  "importance": 0.85,
  "message": "Memory stored successfully"
}

機能：

• 重要度を自動計算します（0.0～1.0）
• 埋め込みを自動生成します
• 分類用のタグに対応しています
• セッション間メモリ用にユーザーと関連付けます

---

2. zerodb_search_memory

自然言語を使って、メモリを意味的に検索します。

入力：

{
  "query": "What are the user's dietary restrictions?",
  "limit": 10,
  "session_id": "chat-123",
  "scope": "agent",
  "min_importance": 0.5
}

出力：

{
  "results": [
    {
      "content": "User is allergic to peanuts",
      "role": "user",
      "importance": 0.95,
      "timestamp": "2026-02-28T10:30:00Z",
      "tags": ["health", "critical"],
      "similarity": 0.89,
      "session_id": "chat-123"
    }
  ],
  "count": 1,
  "scope": "agent"
}

機能：

• セマンティック検索（キーワードではなく意味で検索）
• scope: "agent" を指定したセッション間検索
• 重要度、タグ、ユーザーで絞り込みます
• 類似度スコアを返します

---

3. zerodb_get_context

スマートな剪定を適用して、会話のコンテキスト全体を取得します。

入力：

{
  "session_id": "chat-123",
  "max_tokens": 8192,
  "include_stats": true
}

出力：

{
  "memories": [
    {
      "content": "Hello, how can I help?",
      "role": "assistant",
      "importance": 0.6,
      "timestamp": "2026-02-28T10:00:00Z",
      "tags": []
    }
  ],
  "total_tokens": 2048,
  "stats": {
    "pruned": true,
    "original_count": 50,
    "returned_count": 25,
    "token_limit": 8192
  }
}

機能：

• トークン数の上限に収まるよう自動的に剪定します
• 重要で新しいメモリを保持します
• 有効な場合はメモリの減衰を適用します
• 剪定の統計情報を返します

---

4. zerodb_embed_text

テキストのベクトル埋め込みを生成します。

入力：

{
  "text": "The quick brown fox jumps over the lazy dog",
  "model": "BAAI/bge-small-en-v1.5",
  "normalize": true
}

出力：

{
  "embedding": [0.123, -0.456, 0.789, ...],
  "model": "BAAI/bge-small-en-v1.5",
  "dimensions": 384,
  "normalized": true
}

機能：

• 3 種類のモデルサイズ（384d、768d、1024d）
• 正規化されたベクトル
• 高速なローカル埋め込み（ZeroLocal を使用する場合）

---

5. zerodb_semantic_search

テキストクエリを使わず、意味的な類似性で検索します。

入力：

{
  "text": "food preferences",
  "limit": 10,
  "session_id": "chat-123",
  "min_similarity": 0.7
}

出力：

{
  "results": [
    {
      "content": "User prefers vegetarian meals",
      "similarity": 0.85,
      "metadata": {
        "role": "user",
        "tags": ["preference"]
      }
    }
  ],
  "count": 1,
  "search_vector_dims": 384
}

機能：

• ベクトルの類似性を直接検索します
• テキストまたは事前計算済みのベクトルを指定できます
• 類似度のしきい値で絞り込みます
• セッション単位またはグローバルに検索します

---

6. zerodb_clear_session

セッションのすべてのメモリを消去します。

入力：

{
  "session_id": "chat-123",
  "keep_important": true,
  "confirm": true
}

出力：

{
  "success": true,
  "deleted_count": 45,
  "kept_count": 5,
  "message": "Session cleared, important memories preserved"
}

機能：

• 確認が必要です
• 重要なメモリを任意で保持できます
• 削除の統計情報を返します

7. zerodb_synthesize_context

関連するメモリを取得し、LLM で合成して、一貫性のあるコンテキスト文字列にまとめます。POST /memory/v2/context をラップします。（Issue #2631）

入力：

{
  "query": "What did we decide about the pricing model?",
  "agent_id": "user-456",
  "synthesis_style": "narrative",
  "max_tokens": 1000,
  "top_k": 10
}

出力：

{
  "context": "In previous discussions, the team decided to use a usage-based pricing model...",
  "synthesis_style": "narrative",
  "sources_count": 5,
  "confidence": 0.87,
  "token_count": 312,
  "agent_id": "user-456"
}

機能：

• 3 種類の合成スタイル：narrative、bullet、structured
• Claude Haiku を活用し、高速で一貫性のある要約を生成します
• 合成に失敗した場合も適切にフォールバックします（上位スニペットを連結）
• agent_id でスコープを限定し、ユーザーごとにメモリを分離します

---

8. zerodb_configure_auto_context

エージェントごとに、関連するメモリがすべてのツール応答の先頭に自動的に追加されるよう、オートコンテキストミドルウェアを有効にします。（Issue #2678）

入力：

{
  "agent_id": "user-456",
  "enabled": true,
  "max_results": 10,
  "synthesis_style": "bullet",
  "auto_trace": false
}

出力：

{
  "success": true,
  "agent_id": "user-456",
  "config": {
    "enabled": true,
    "max_results": 10,
    "synthesis_style": "bullet",
    "auto_trace": false
  },
  "message": "Auto-context enabled for agent user-456"
}

機能：

• 有効にすると、以降のすべてのツール呼び出しで、応答に_auto_contextが自動的に追加されます（agent_idに対して適用）。
• auto_trace: trueにすると、各ツール応答が新しいエピソード記憶として保存され、後から呼び出せます。
• 設定は/remember経由で永続化され、MCP サーバーを再起動しても保持されます。
• スキップリスト：設定ツール自体はオートコンテキストの対象になりません。

---

9. zerodb_get_auto_context_config

エージェントの現在のオートコンテキスト設定を取得します。

入力：

{
  "agent_id": "user-456"
}

出力：

{
  "agent_id": "user-456",
  "config": {
    "enabled": true,
    "max_results": 10,
    "synthesis_style": "bullet",
    "auto_trace": false
  }
}

---

書き戻しアクションツール

ZeroDB の同期接続に保存された OAuth トークンを使用して外部サービスに書き戻す5つのツールです。/api/v1/public/memory/v2/connectionsでアカウントを接続します。

エージェントのワークフロー： zerodb_recall → zerodb_synthesize_context → アクションを実行（Slack の送信、メールへの返信、イベントの作成など）

10. zerodb_slack_send

ユーザーが保存した OAuth トークンを使用して Slack メッセージを送信します。（Issue #2645）

入力：

{
  "agent_id": "user-456",
  "channel": "C012AB3CD",
  "message": "Sprint planning scheduled for Monday 10am",
  "thread_ts": "1609459200.000100"
}

出力：

{
  "ts": "1609459201.000200",
  "channel": "C012AB3CD",
  "message": "Message sent successfully"
}

注： thread_tsは省略可能です。新しいメッセージを投稿する場合は省略し、スレッドに返信する場合は指定します。

---

11. zerodb_gmail_reply

ユーザーが保存した Google OAuth トークンを使用して Gmail のスレッドに返信します。（Issue #2646）

入力：

{
  "agent_id": "user-456",
  "thread_id": "17abc123def456",
  "body": "Thanks for the update. I'll review the PR by EOD.",
  "cc": ["[email protected]"]
}

出力：

{
  "id": "17abc123def999",
  "thread_id": "17abc123def456",
  "message": "Reply sent successfully"
}

---

12. zerodb_calendar_create

ユーザーが保存した Google OAuth トークンを使用して Google Calendar のイベントを作成します。（Issue #2647）

入力：

{
  "agent_id": "user-456",
  "title": "Sprint Planning",
  "start": "2026-05-10T10:00:00Z",
  "end": "2026-05-10T11:00:00Z",
  "description": "Q2 sprint kickoff",
  "attendees": ["[email protected]", "[email protected]"],
  "calendar_id": "primary"
}

出力：

{
  "id": "evt_abc123",
  "html_link": "https://calendar.google.com/event?eid=abc123",
  "title": "Sprint Planning",
  "message": "Event created successfully"
}

注： Gmail と同じ Google OAuth トークンを使用します。calendar_idのデフォルト値は"primary"です。

---

13. zerodb_github_create_issue

ユーザーが保存した GitHub OAuth トークンを使用して GitHub の Issue を作成します。（Issue #2648）

入力：

{
  "agent_id": "user-456",
  "repo": "acme/widget",
  "title": "Fix null pointer in payment flow",
  "body": "Steps to reproduce:\n1. Add item to cart\n2. Proceed to checkout\n3. Observe crash",
  "labels": ["bug", "priority:high"]
}

出力：

{
  "number": 142,
  "html_url": "https://github.com/acme/widget/issues/142",
  "title": "Fix null pointer in payment flow",
  "message": "Issue created successfully"
}

---

14. zerodb_notion_create_page

ユーザーが保存した Notion OAuth トークンを使用して Notion ページを作成します。（Issue #2649）

入力：

{
  "agent_id": "user-456",
  "parent_id": "parent-page-uuid",
  "title": "Meeting Notes — May 10",
  "content": "Attendees: Alice, Bob\n\nDecisions:\n- Ship v2 on Friday\n- Rollback plan: revert to v1.9"
}

出力：

{
  "id": "page-uuid-xyz",
  "url": "https://notion.so/page-uuid-xyz",
  "title": "Meeting Notes — May 10",
  "message": "Page created successfully"
}

注： コンテンツは Notion の段落ブロックに変換されます（空でない行ごとに1つ）。2000文字を超える行は切り捨てられます。

---

詳細設定

コンテキストウィンドウの管理

# Set maximum tokens (default: 8192)
CONTEXT_WINDOW=16384

# Choose pruning strategy (default: hybrid)
# - relevance: Keep highest-scored memories
# - recency: Keep most recent memories
# - hybrid: Combine both (70% relevance, 30% recency)
PRUNE_STRATEGY=hybrid

# Always keep N recent messages (default: 5)
KEEP_RECENT=5

# Keep memories tagged as important (default: true)
KEEP_IMPORTANT=true

メモリの減衰

時間の経過に伴う自然なメモリの減衰を有効にします。

# Enable decay (default: false)
DECAY_ENABLED=true

# Half-life in days (default: 30)
# After 30 days, importance score is halved
DECAY_HALFLIFE=30

# Protect tags from decay
PRESERVE_TAGS=important,permanent,critical

例：

• 0日目：importance = 0.8
• 30日目：importance = 0.4
• 60日目：importance = 0.2
• importantタグが付いたメモリ：減衰しません

自動要約

古い会話を自動的に圧縮します。

# Enable summarization (default: true)
SUMMARIZE_ENABLED=true

# Summarize after N messages (default: 20)
SUMMARIZE_AFTER=20

# Model for summarization
SUMMARY_MODEL=claude-3-haiku-20240307

# Keep original messages (default: false)
KEEP_ORIGINALS=false

動作：

1. 20件のメッセージの後、最も古い15件を要約します
2. 要約はsummaryタグ付きの新しいメモリとして保存されます
3. 元のメッセージは削除されます（KEEP_ORIGINALS=trueの場合を除く）
4. 直近の5件のメッセージは常に保持されます

埋め込みモデル

ニーズに応じて埋め込みモデルを選択します。

# Small (384 dimensions) - Fast, efficient
EMBEDDING_MODEL=BAAI/bge-small-en-v1.5

# Base (768 dimensions) - Balanced
EMBEDDING_MODEL=BAAI/bge-base-en-v1.5

# Large (1024 dimensions) - Most accurate
EMBEDDING_MODEL=BAAI/bge-large-en-v1.5

トレードオフ：

• Small： 3倍高速、精度70%
• Base： 2倍高速、精度85%
• Large： 基準速度、精度95%

---

ユースケース

カスタマーサポートエージェント

// Store user preferences
await zerodb_store_memory({
  content: "User prefers email support over phone",
  role: "user",
  session_id: "support-session-123",
  tags: ["preference", "communication"],
  user_id: "customer-456"
});

// Later, search across all sessions for this user
const prefs = await zerodb_search_memory({
  query: "communication preferences",
  scope: "agent",
  user_id: "customer-456"
});

パーソナルアシスタント

// Store important facts
await zerodb_store_memory({
  content: "User's birthday is March 15th",
  role: "system",
  session_id: "assistant-123",
  tags: ["important", "permanent", "personal"],
  metadata: { category: "birthday" }
});

// Retrieve context before responding
const context = await zerodb_get_context({
  session_id: "assistant-123",
  max_tokens: 4096
});

リサーチアシスタント

// Store findings
await zerodb_store_memory({
  content: "Study shows 85% efficacy in clinical trials",
  role: "assistant",
  session_id: "research-789",
  tags: ["research", "statistics"],
  metadata: { source: "Nature 2026", confidence: 0.9 }
});

// Search semantically
const related = await zerodb_semantic_search({
  text: "clinical trial results",
  limit: 5,
  min_similarity: 0.7
});

エンドツーエンドのエージェントワークフロー：呼び出し → 要約 → 実行

// 1. Recall relevant memories
const memories = await zerodb_recall({
  query: "pending items from last standup",
  agent_id: "agent-456",
  top_k: 10,
  rerank: true
});

// 2. Synthesize into a coherent summary
const context = await zerodb_synthesize_context({
  query: "pending items from last standup",
  agent_id: "agent-456",
  synthesis_style: "bullet",
  top_k: 5
});
// context.context = "- PR #42 needs review\n- Deploy blocked on staging tests\n- Alice OOO Monday"

// 3. Take action — send Slack update
await zerodb_slack_send({
  agent_id: "agent-456",
  channel: "C012AB3CD",
  message: `Standup summary:\n${context.context}`
});

// 4. Log the action as a memory for future recall
await zerodb_store_memory({
  content: `Sent standup summary to #engineering: ${context.context}`,
  role: "assistant",
  session_id: "agent-456",
  tags: ["action", "slack", "standup"]
});

オートコンテキストミドルウェア

すべてのツール呼び出しに関連するメモリが自動的に追加されるよう、オートコンテキストを有効にします。

// Enable once per agent
await zerodb_configure_auto_context({
  agent_id: "agent-456",
  enabled: true,
  max_results: 10,
  synthesis_style: "bullet",
  auto_trace: true  // also store tool responses as memories
});

// Now every subsequent tool call automatically includes _auto_context
const result = await zerodb_slack_send({
  agent_id: "agent-456",
  channel: "C123",
  message: "Update sent"
});
// result._auto_context = "• User prefers concise updates\n• Last message sent 2h ago"
// result.ts = "..."

---

パフォーマンス

コンテキストフットプリントの比較

指標	モノリシックサーバー	Agent Memory MCP	改善
ツール数	77	6	92%削減
トークンコスト	~10,400	~800	92%削減
読み込み時間	2.5s	0.3s	8倍高速
メモリ使用量	150MB	20MB	87%削減
エージェントの精度	60%	95%	58%向上

ベンチマーク

ZeroLocal（localhost:8000）：

• メモリの保存：約5ms
• メモリの検索：約15ms
• コンテキストの取得：約20ms
• テキストの埋め込み：約10ms

ZeroDB Cloud（api.ainative.studio）：

• メモリの保存：約50ms
• メモリの検索：約75ms
• コンテキストの取得：約100ms
• テキストの埋め込み：約60ms

---

開発

テストの実行

npm test

詳細ログを有効にして実行

DEBUG=* npm start

開発モード（自動リロード）

npm run dev

---

トラブルシューティング

エラー：「Authentication failed」または store_memory で 401 が発生する

よくある原因： シェルの環境変数（~/.zshrc、~/.bashrc）が、MCP の設定（例：.claude.json または Claude Desktop の設定）で指定した認証情報を上書きしています。MCP サーバーはすべてのシェル環境変数を引き継ぐため、シェルのプロファイルに古い ZERODB_USERNAME／ZERODB_PASSWORD の値があると、そちらが優先されます。

解決方法：

1. ~/.zshrc または ~/.bashrc から古い ZERODB_USERNAME／ZERODB_PASSWORD のエクスポート設定を削除するか、更新します
2. または、通常シェルのプロファイルには設定されていない ZERODB_API_KEY による API キー認証に切り替えます
3. または、MCP サーバーの設定の env ブロックで認証情報を明示的に指定し、シェル変数を上書きします

次の点も確認してください：

• ZERODB_USERNAME と ZERODB_PASSWORD が正しいこと
• ZeroDB にアカウントが存在すること
• パスワードが変更されていないこと

エラー：「Project not found」

次の点を確認してください：

• ZERODB_PROJECT_ID が正しいこと
• アカウントにプロジェクトが存在すること
• アクセス権限があること

エラー：「Connection refused」

ZeroLocal を使用している場合：

# Check if ZeroLocal is running
curl http://localhost:8000/health

# Start ZeroLocal
cd /path/to/zerodb-local
zerodb local up

Cloud を使用している場合：

# Check internet connection
ping api.ainative.studio

# Verify API is online
curl https://api.ainative.studio/health

メモリがプルーニングされない

設定を確認してください：

# Ensure context window is set
echo $CONTEXT_WINDOW

# Verify prune strategy
echo $PRUNE_STRATEGY

# Check if keep_recent is too high
echo $KEEP_RECENT

---

アーキテクチャ

┌─────────────────────────────────────────────┐
│         Agent Memory MCP Server             │
├─────────────────────────────────────────────┤
│                                             │
│  Main (index.js)                            │
│  └── MCP Server initialization              │
│                                             │
│  Client (zerodb-client.js)                  │
│  ├── Auto-detection (local vs cloud)       │
│  ├── Authentication & token refresh         │
│  └── API request handling                   │
│                                             │
│  Memory Manager (memory-manager.js)         │
│  ├── Context window management             │
│  ├── Memory pruning (relevance/recency)    │
│  ├── Importance scoring                     │
│  ├── Memory decay                           │
│  └── Automatic summarization                │
│                                             │
│  Tools (memory-tools.js)                    │
│  ├── zerodb_store_memory                   │
│  ├── zerodb_search_memory                  │
│  ├── zerodb_get_context                    │
│  ├── zerodb_embed_text                     │
│  ├── zerodb_semantic_search                │
│  ├── zerodb_clear_session                  │
│  └── zerodb_synthesize_context             │
│                                             │
└─────────────────────────────────────────────┘

---

ロードマップ

v1.1（予定）

• LLM による自動要約
• メモリのクラスタリングと整理
• メモリアーカイブのエクスポート／インポート
• メモリー分析ダッシュボード

v1.2（予定）

• 複数エージェント間でのメモリ共有
• メモリの権限とアクセス制御
• インスタンス間でのフェデレーションメモリ
• メモリのレプリケーションとバックアップ

v2.0（将来）

• グラフベースのメモリ関係
• 時間ベースのメモリクエリ
• メモリ圧縮アルゴリズム
• リアルタイムのメモリストリーミング

---

コントリビューション

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

ライセンス

MIT ライセンス — 詳細は LICENSE ファイルをご覧ください

サポート

• ドキュメント： https://www.ainative.studio/docs
• 課題： https://github.com/ainative/zerodb-memory-mcp/issues
• Discord： https://discord.gg/ainative

---

AINative Studio が開発

ひとつずつメモリを増やし、AI エージェントをよりスマートに。