메모리 MCP 서버

데이터 일관성을 유지하기 위한 엄격한 검증 규칙을 적용하여 메모리에서 엔터티, 관계 및 관찰을 관리하기 위한 지식 그래프 기능을 제공하는 MCP(모델 컨텍스트 프로토콜) 서버입니다.

설치

Claude Desktop에 서버를 설치하세요:

지엑스피1

데이터 검증 규칙

엔터티 이름

소문자로 시작해야 합니다
소문자, 숫자, 하이픈을 포함할 수 있습니다.
최대 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 : 엔터티 간의 관계가 잘못되었습니다.

응답 모델

모든 도구는 다음 모델을 사용하여 입력된 응답을 반환합니다.

엔티티 응답

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

그래프 응답

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/

새로운 기능 추가

validation.py 에서 검증 규칙 업데이트
tests/test_validation.py 에 테스트를 추가합니다.
knowledge_graph_manager.py 에서 변경 사항을 구현합니다.

Memory MCP Server

Integrations