remote-memory-mcp-server
Remote Memory MCP Server
A GitHub-integrated remote memory management MCP server that syncs knowledge graph data with GitHub repositories for remote storage and collaboration.
Features
- CRUD operations for entities, relations, and observations
- Real-time synchronization with GitHub repositories
- Conflict detection and resolution
- Automatic/manual synchronization options
- Search and filtering capabilities
- Enhanced entity query features (v1.3.0)
- Entity list retrieval (with filtering, sorting, pagination)
- Quick entity name lookup
- Entity type statistics
- Date range filtering
- Enhanced commit messages (customizable)
- Backup functionality
- Commit history tracking
- Optional auto-push (AUTO_PUSH environment variable)
Installation
cd C:\YOUR_PATH\remote-memory-mcp
npm install
npm run build
Configuration
Required Parameters
GITHUB_TOKEN: GitHub Personal Access Token (requires repo permissions)GITHUB_OWNER: GitHub repository ownerGITHUB_REPO: GitHub repository name
Optional Parameters
GITHUB_BRANCH: Branch name to use (default: main)SYNC_INTERVAL: Auto-sync interval in seconds (0 for manual)AUTO_PUSH: Auto-push after CRUD operations (true/false, default: false)
Claude Desktop Setup
Add to your claude_desktop_config.json file:
{
"mcpServers": {
"remote-memory": {
"command": "node",
"args": ["C://YOUR_PATH//remote-memory-mcp//dist//index.js"],
"env": {
"GITHUB_TOKEN": "YOUR_GITHUB_TOKEN_HERE",
"GITHUB_OWNER": "YOUR_GITHUB_USERNAME",
"GITHUB_REPO": "YOUR_GITHUB_REPO",
"GITHUB_BRANCH": "main",
"SYNC_INTERVAL": "0",
"AUTO_PUSH": "false"
}
}
}
}
Usage
For detailed API usage and examples, see SPEC.md.
Data Structure
Memory data is stored in the memory/graph.json file in your GitHub repository:
{
"entities": {
"Kim Kim": {
"name": "Kim Kim",
"entityType": "Person",
"observations": ["Software developer", "Lives in Seoul"],
"createdAt": "2025-01-01T00:00:00.000Z",
"updatedAt": "2025-01-01T00:00:00.000Z"
}
},
"relations": [
{
"from": "Kim Kim",
"to": "Company ABC",
"relationType": "works_at",
"createdAt": "2025-01-01T00:00:00.000Z"
}
],
"metadata": {
"version": "1.0.0",
"lastModified": "2025-01-01T00:00:00.000Z",
"lastSync": "2025-01-01T00:00:00.000Z"
}
}
Architecture
Core Components
- GitHubClient: Handles GitHub API interactions
- MemoryGraphManager: Manages the memory graph
- SyncManager: Handles synchronization
- RemoteMemoryMCPServer: Main MCP server class
Synchronization Strategy
- Conflict Resolution: Prioritizes based on latest modification timestamp
- Auto-push: Immediately pushes local changes to remote
- Auto-pull: Checks for remote changes at configured intervals
- Force Sync: Performs bidirectional sync ignoring conflicts
Important Notes
- Requires GitHub Personal Access Token (with repo permissions)
- GitHub API limits: 5,000 requests per hour for authenticated users
- Network connection required
- Rate limit of 5,000 requests/hour; 403 error when exceeded
License
MIT License - Free to use, modify, and distribute
Changelog
v1.3.0
- New query tools
list_entities: Retrieve entity list (with filtering, sorting, pagination)get_entity_names: Quick entity name lookupget_entity_types: Entity type statistics
- Enhanced query capabilities
- EntityType filtering
- Date range filtering (based on createdAt)
- Sort options (createdAt, updatedAt, name)
- Pagination (limit, offset)
- Improved handling of large datasets
v1.2.0
- Prevented unnecessary auto-commits on initialization
- Added AUTO_PUSH environment variable for optional auto-push
- Added logic to prevent pushing empty graphs
- Improved initial load state tracking
v1.1.0
- Custom commit message support
- Added backup system (
create_backup) - Commit history tracking (
get_commit_history) - Automatic commit message generation
v1.0.0
- Initial release
remote-memory-mcp-server
Remote Memory MCP Server
GitHub 연동 원격 메모리 관리 MCP 서버입니다. 지식 그래프 데이터를 GitHub 저장소와 동기화하여 Memory의 원격 저장 및 협업을 지원합니다.
기능
- 엔티티, 관계, 관찰 데이터의 CRUD 연산
- GitHub 저장소와의 실시간 동기화
- 충돌 감지 및 해결
- 자동/수동 동기화 옵션
- 검색 및 필터링 기능
- 향상된 엔티티 조회 기능 (v1.3.0)
- 엔티티 목록 조회 (필터링, 정렬, 페이지네이션)
- 엔티티 이름만 조회 (빠른 검색)
- 엔티티 타입별 통계
- 날짜 범위 필터링
- 향상된 커밋 메시지(커스텀 명령 가능)
- 백업 기능 추가
- 커밋 히스토리 조회 기능
- 선택적 자동 푸시 기능 (AUTO_PUSH 환경변수)
설치
cd C:\YOUR_PATH\remote-memory-mcp
npm install
npm run build
설정
필수 파라미터
GITHUB_TOKEN: GitHub Personal Access Token (repo 권한 필요)GITHUB_OWNER: GitHub 저장소 소유자GITHUB_REPO: GitHub 저장소 이름
선택 파라미터
GITHUB_BRANCH: 사용할 브랜치명 (기본값: main)SYNC_INTERVAL: 자동 동기화 간격 초단위 (0이면 수동)AUTO_PUSH: CRUD 작업 후 자동 푸시 여부 (true/false, 기본값: false)
Claude Desktop 설정
claude_desktop_config.json 파일에 추가:
{
"mcpServers": {
"remote-memory": {
"command": "node",
"args": ["C://YOUR_PATH//remote-memory-mcp//dist//index.js"],
"env": {
"GITHUB_TOKEN": "YOUR_GITHUB_TOKEN_HERE",
"GITHUB_OWNER": "YOUR_GITHUB_USERNAME",
"GITHUB_REPO": "YOUR_GITHUB_REPO",
"GITHUB_BRANCH": "main",
"SYNC_INTERVAL": "0",
"AUTO_PUSH": "false"
}
}
}
}
사용법
자세한 API 사용법과 예제는 SPEC.md를 참조하세요.
데이터 구조
메모리 데이터는 GitHub 저장소의 memory/graph.json 파일에 저장됩니다:
{
"entities": {
"Kim Kim": {
"name": "Kim Kim",
"entityType": "Person",
"observations": ["Software developer", "Lives in Seoul"],
"createdAt": "2025-01-01T00:00:00.000Z",
"updatedAt": "2025-01-01T00:00:00.000Z"
}
},
"relations": [
{
"from": "Kim Kim",
"to": "Company ABC",
"relationType": "works_at",
"createdAt": "2025-01-01T00:00:00.000Z"
}
],
"metadata": {
"version": "1.0.0",
"lastModified": "2025-01-01T00:00:00.000Z",
"lastSync": "2025-01-01T00:00:00.000Z"
}
}
아키텍처
주요 컴포넌트
- GitHubClient: GitHub API 상호작용 담당
- MemoryGraphManager: 메모리 그래프 관리
- SyncManager: 동기화 관리
- RemoteMemoryMCPServer: MCP 서버 메인 클래스
동기화 전략
- 충돌 해결: 최신 수정 시간 기준으로 우선순위 결정
- 자동 푸시: 로컬 변경 시 즉시 원격으로 푸시
- 자동 풀: 설정된 간격으로 원격 변경사항 확인
- 강제 동기화: 충돌 무시하고 양방향 동기화
주의사항
- GitHub Personal Access Token 필요 (repo 권한)
- GitHub API 제한: 인증된 사용자 시간당 5,000 요청
- 네트워크 연결 필수
- 시간당 5,000 요청 제한, 제한 초과 시 403 오류 발생
라이선스
MIT License - 자유롭게 사용, 수정, 배포 가능
변경 로그
v1.3.0
- 새로운 조회 도구 추가
list_entities: 엔티티 목록 조회 (필터링, 정렬, 페이지네이션 지원)get_entity_names: 엔티티 이름만 빠르게 조회get_entity_types: 엔티티 타입별 통계 조회
- 향상된 쿼리 기능
- EntityType별 필터링
- 날짜 범위 필터링 (createdAt 기준)
- 정렬 옵션 (createdAt, updatedAt, name)
- 페이지네이션 (limit, offset)
- 대량 데이터 처리 개선
v1.2.0
- 초기화 시 불필요한 자동 커밋 방지
- AUTO_PUSH 환경변수 추가로 선택적 자동 푸시 지원
- 빈 그래프 푸시 방지 로직 추가
- 초기 로드 상태 추적 개선
v1.1.0
- 커스텀 커밋 메시지 지원
- 백업 시스템 추가 (
create_backup) - 커밋 히스토리 조회 (
get_commit_history) - 자동 커밋 메시지 생성
v1.0.0
- 초기 릴리스