GNB MemoryMCP

여러 LLM 및 AI 에이전트(ChatGPT, Claude, Claude Code, Gemini, Antigravity 등)에서 공통으로 참조 및 업데이트할 수 있는, 벤더에 종속되지 않는 개인용 기억 계층(MCP 서버)입니다.

본 프로젝트는 Go로 구현되었으며, 로컬 환경(SQLite) 및 프로덕션 환경(AWS Lambda + Turso / libSQL) 모두에서 원활하게 전환하여 작동하도록 설계되었습니다.

특징

• 여러 LLM 간 기억 공유: 특정 벤더에 종속되지 않고, 사용자의 설정이나 프로젝트 컨텍스트, 지식을 모든 AI에 이어받을 수 있습니다.

• 2가지 로컬 연결 지원:

  1. HTTP 서버 모드: 포트를 지정하여 시작하고, 여러 클라이언트에서 액세스합니다. 인증에는 Authorization: Bearer <API_KEY>를 사용합니다.

  2. 표준 입출력(stdio) 모드: 포트를 열지 않고 Claude Desktop 등의 MCP 클라이언트에서 직접 바이너리를 실행 및 통신시킵니다.

• 전문 검색(FTS5): SQLite의 FTS5를 사용한 고속 및 경량 텍스트 전문 검색을 지원합니다.

• 스키마의 영속성: tags 및 metadata를 JSON으로 저장하므로, API 사양을 변경하지 않고 향후 벡터 검색이나 요약 배치 등의 내부 구현을 발전시킬 수 있습니다.

디렉토리 구성

• cmd/gnb-memorymcp/: 로컬 통합 바이너리(server / stdio 모드)의 엔트리 포인트

• cmd/lambda/: AWS Lambda 시작용 엔트리 포인트

• pkg/auth/: Bearer 인증, JWT 검증 및 CIMD 클라이언트 ID 판정

• pkg/domain/: 기억 모델 및 데이터베이스 스토어의 인터페이스 정의

• pkg/infra/sqlite/: SQLite / libSQL을 사용한 DB 저장, 전문 검색(FTS5), 트리거 동기화 구현

• pkg/mcp/: JSON-RPC 2.0을 준수하는 MCP 도구 실행 핸들러

설치 방법

Scoop을 사용한 설치(Windows 권장)

# バケットの追加
scoop bucket add gnb-bucket https://github.com/GennoBou/scoop-bucket

# インストール
scoop install gnb-memorymcp

소스 코드에서 빌드

# 全部入りバイナリ（ローカル用）のビルド
go build -o bin/gnb-memorymcp.exe ./cmd/gnb-memorymcp/main.go

사용 방법

1. 표준 입출력(stdio) 모드 설정 예시

가장 간편하게 로컬에서 MCP를 작동시키는 방법입니다. 연결할 클라이언트(Claude Desktop, Antigravity, OpenCode 등)의 구성 파일에 직접 바이너리를 등록합니다. 명시적으로 첫 번째 인수에 stdio를 전달하여 표준 입출력 모드로 시작합니다.

A. Claude Desktop의 경우

설정 파일: AppData\Roaming\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "gnb-memorymcp": {
      "command": "gnb-memorymcp.exe",
      "args": ["stdio", "--db-url", "file:D:/Data/Projects/GitHub/gnb-memorymcp/data/local_v2.db"]
    }
  }
}

B. Antigravity의 경우

설정 파일: ~/.gemini/antigravity-cli/settings.json (Windows의 경우 C:\Users\<사용자 이름>\.gemini\antigravity-cli\settings.json)

{
  "mcpServers": {
    "gnb-memorymcp": {
      "command": "gnb-memorymcp.exe",
      "args": ["stdio", "--db-url", "file:D:/Data/Projects/GitHub/gnb-memorymcp/data/local_v2.db"]
    }
  }
}

C. OpenCode의 경우

설정 파일: ~/.config/opencode/opencode.jsonc

{
  "mcp": {
    "gnb-memorymcp": {
      "type": "local",
      "enabled": true,
      "command": [
        "gnb-memorymcp.exe",
        "stdio",
        "--db-url",
        "file:D:/Data/Projects/GitHub/gnb-memorymcp/data/local_v2.db"
      ]
    }
  }
}

설정을 반영한 후 대상 클라이언트를 재시작하면 기억 도구(memory_create 등)가 자동으로 로드되어 사용할 수 있습니다.

2. HTTP 서버 모드(로컬 SQLite)

로컬 또는 다른 단말기에서 HTTP 서버로 시작하고, 로컬 SQLite 데이터베이스를 참조합니다. 첫 번째 인수에 server를 전달하여 시작합니다. 안전을 위해 기본적으로 로컬 호스트(127.0.0.1)에 바인딩됩니다.

시작 방법 (PowerShell)

• 방법 1: 명령 인수로 지정하여 시작

  # ローカルホストからのみ接続可能として起動 (APIキーが未指定の場合は自動的に 'dev-key' が使われます)
  ./bin/gnb-memorymcp.exe server --port 8080 --db-url "file:data/local_v2.db"
  
  # 外部ネットワークに公開して起動 (--host 0.0.0.0 指定時は、安全な独自の --api-key 設定が必須)
  ./bin/gnb-memorymcp.exe server --host 0.0.0.0 --port 8080 --api-key "your-secure-secret-key" --db-url "file:data/local_v2.db"

• 방법 2: 환경 변수로 지정하여 시작

  $env:HOST="127.0.0.1"
  $env:API_KEY="your-secret-key"
  $env:PORT="8080"
  $env:DB_URL="file:data/local_v2.db"
  ./bin/gnb-memorymcp.exe server

클라이언트에서의 요청 방법

• URL: http://localhost:8080/

• 메서드: POST

• 필수 헤더: Authorization: Bearer your-secret-key

• 요청 본문 (JSON-RPC 2.0):

  {
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }

3. 로컬 HTTP + Turso 모드(클라우드 DB 연동)

로컬에서 HTTP 서버를 시작하고, 데이터베이스만 원격 Turso(libSQL)를 참조시킵니다.

시작 방법 (PowerShell)

• 방법 1: 명령 인수로 지정하여 시작 ※ DB_TOKEN은 보안 보호를 위해 환경 변수로 설정하는 것을 권장합니다.

  $env:DB_TOKEN="your-turso-auth-token"
  ./bin/gnb-memorymcp.exe server --port 8080 --api-key "your-secret-key" --db-url "libsql://your-database-name-username.turso.io"

• 방법 2: 환경 변수로 지정하여 시작

  $env:API_KEY="your-secret-key"
  $env:PORT="8080"
  $env:DB_URL="libsql://your-database-name-username.turso.io"
  $env:DB_TOKEN="your-turso-auth-token"
  ./bin/gnb-memorymcp.exe server

4. AWS Lambda + Turso 모드(프로덕션 클라우드 운영)

AWS Lambda에 서버리스로 배포하고 Turso와 연동하여 작동시키는 구성입니다.

• 엔트리 포인트: cmd/lambda/main.go

• 원 커맨드 빌드 및 배포 스크립트(npm run build-and-deploy-lambda) 및 SAM 템플릿(template.yaml)을 지원합니다.

자세한 배포 절차는 AWS Lambda + Turso 배포 절차서를 참조하세요.

제공하는 MCP 도구 사양

GNB MemoryMCP는 다음 10개의 도구를 제공합니다.