Memory MCP Server

メモリ MCP サーバー

メモリ内のエンティティ、関係、観察事項を管理するためのナレッジグラフ機能を提供する Model Context Protocol（MCP）サーバーです。データの一貫性を維持するため、厳格な検証ルールを適用します。

インストール

Claude Desktop にサーバーをインストールします。

mcp install main.py -v MEMORY_FILE_PATH=/path/to/memory.jsonl

データ検証ルール

エンティティ名

• 小文字で始める必要があります
• 小文字、数字、ハイフンを使用できます
• 最大長は100文字です
• グラフ内で一意である必要があります
• 有効な名前の例：python-project、meeting-notes-2024、user-john

エンティティタイプ

次のエンティティタイプがサポートされています。

• person：人
• concept：抽象的なアイデアや原則
• project：業務上の取り組みやタスク
• document：あらゆる形式のドキュメント
• tool：ソフトウェアツールやユーティリティ
• organization：企業やグループ
• location：物理的または仮想的な場所
• event：期間が限定された出来事

観察事項

• 空でない文字列である必要があります
• 最大長は500文字です
• エンティティごとに一意である必要があります
• 事実に基づく客観的な記述にしてください
• 該当する場合はタイムスタンプを含めてください

関係

次の関係タイプがサポートされています。

• knows：人と人のつながり
• contains：親子関係
• uses：あるエンティティが別のエンティティを利用する関係
• created：著作者／作成者の関係
• belongs-to：所属／所有関係
• depends-on：依存関係
• related-to：一般的な関係

追加の関係ルール：

• 始点と終点の両方のエンティティが存在する必要があります
• 自己参照関係は許可されません
• 循環依存は許可されません
• 定義済みの関係タイプを使用する必要があります

使用方法

サーバーは、ナレッジグラフを管理するためのツールを提供します。

エンティティの取得

result = await session.call_tool("get_entity", {
    "entity_name": "example"
})
if not result.success:
    if result.error_type == "NOT_FOUND":
        print(f"Entity not found: {result.error}")
    elif result.error_type == "VALIDATION_ERROR":
        print(f"Invalid input: {result.error}")
    else:
        print(f"Error: {result.error}")
else:
    entity = result.data
    print(f"Found entity: {entity}")

グラフの取得

result = await session.call_tool("get_graph", {})
if result.success:
    graph = result.data
    print(f"Graph data: {graph}")
else:
    print(f"Error retrieving graph: {result.error}")

エンティティの作成

# Valid entity creation
entities = [
    Entity(
        name="python-project",  # Lowercase with hyphens
        entityType="project",   # Must be a valid type
        observations=["Started development on 2024-01-29"]
    ),
    Entity(
        name="john-doe",
        entityType="person",
        observations=["Software engineer", "Joined team in 2024"]
    )
]
result = await session.call_tool("create_entities", {
    "entities": entities
})
if not result.success:
    if result.error_type == "VALIDATION_ERROR":
        print(f"Invalid entity data: {result.error}")
    else:
        print(f"Error creating entities: {result.error}")

観察事項の追加

# Valid observation
result = await session.call_tool("add_observation", {
    "entity": "python-project",
    "observation": "Completed initial prototype"  # Must be unique for entity
})
if not result.success:
    if result.error_type == "NOT_FOUND":
        print(f"Entity not found: {result.error}")
    elif result.error_type == "VALIDATION_ERROR":
        print(f"Invalid observation: {result.error}")
    else:
        print(f"Error adding observation: {result.error}")

関係の作成

# Valid relation
result = await session.call_tool("create_relation", {
    "from_entity": "john-doe",
    "to_entity": "python-project",
    "relation_type": "created"  # Must be a valid type
})
if not result.success:
    if result.error_type == "NOT_FOUND":
        print(f"Entity not found: {result.error}")
    elif result.error_type == "VALIDATION_ERROR":
        print(f"Invalid relation data: {result.error}")
    else:
        print(f"Error creating relation: {result.error}")

メモリの検索

result = await session.call_tool("search_memory", {
    "query": "most recent workout"  # Supports natural language queries
})
if result.success:
    if result.error_type == "NO_RESULTS":
        print(f"No results found: {result.error}")
    else:
        results = result.data
        print(f"Search results: {results}")
else:
    print(f"Error searching memory: {result.error}")

検索機能では、次のクエリがサポートされています。

• 時間に関するクエリ（例：「最も最近の」「最後の」「最新の」）
• アクティビティに関するクエリ（例：「ワークアウト」「エクササイズ」）
• 一般的なエンティティ検索
• 類似度しきい値80％のあいまい検索
• 次の項目を対象とした重み付き検索：
  • エンティティ名（重み：1.0）
  • エンティティタイプ（重み：0.8）
  • 観察事項（重み：0.6）

エンティティの削除

result = await session.call_tool("delete_entities", {
    "names": ["python-project", "john-doe"]
})
if not result.success:
    if result.error_type == "NOT_FOUND":
        print(f"Entity not found: {result.error}")
    else:
        print(f"Error deleting entities: {result.error}")

関係の削除

result = await session.call_tool("delete_relation", {
    "from_entity": "john-doe",
    "to_entity": "python-project"
})
if not result.success:
    if result.error_type == "NOT_FOUND":
        print(f"Entity not found: {result.error}")
    else:
        print(f"Error deleting relation: {result.error}")

メモリの消去

result = await session.call_tool("flush_memory", {})
if not result.success:
    print(f"Error flushing memory: {result.error}")

エラータイプ

サーバーは次のエラータイプを使用します。

• NOT_FOUND：エンティティまたはリソースが見つかりません
• VALIDATION_ERROR：入力データが無効です
• INTERNAL_ERROR：サーバー側のエラーです
• ALREADY_EXISTS：リソースはすでに存在します
• INVALID_RELATION：エンティティ間の関係が無効です

レスポンスモデル

すべてのツールは、次のモデルを使用して型付きレスポンスを返します。

EntityResponse

class EntityResponse(BaseModel):
    success: bool
    data: Optional[Dict[str, Any]] = None
    error: Optional[str] = None
    error_type: Optional[str] = None

GraphResponse

class GraphResponse(BaseModel):
    success: bool
    data: Optional[Dict[str, Any]] = None
    error: Optional[str] = None
    error_type: Optional[str] = None

OperationResponse

class OperationResponse(BaseModel):
    success: bool
    error: Optional[str] = None
    error_type: Optional[str] = None

開発

テストの実行

pytest tests/

新機能の追加

1. validation.py の検証ルールを更新します
2. tests/test_validation.py にテストを追加します
3. knowledge_graph_manager.py に変更を実装します