VIBE MEMORY / CONNECTION GUIDE
하나의 기억을,
나의 에이전트에.
이해와 추론은 에이전트가, 데이터 관리는 Vibe Memory가 담당합니다.
자신의 서버 엔드포인트와 에이전트를 연결하는 방법을 안내합니다.
https://vibememory.io입니다.01. 연결 준비
Vibe Memory에 로그인하고 콘솔의 에이전트 API 키에서 새 키를 만드세요. 키는 생성할 때 한 번만 표시되며, 에이전트마다 별도로 발급하고 철회할 수 있습니다.
직접 서버를 실행하려면 아래 자체 호스팅 방법을 사용하세요.
이미 Vibe Memory 서버가 실행 중이라면 서버 URL과 API 키를 준비하세요. 소스 프로젝트에서 처음 실행한다면 Python 3.12/3.13과 uv를 준비한 뒤 아래 명령을 실행합니다.
uv sync --frozen
uv run vibe-memory keygen --user personal
생성한 JSON을 프로젝트의 .env 파일에 설정합니다. 실제 비밀 키는 저장소에 커밋하지 않습니다.
MEMORY_API_KEYS={"generated-random-key":"personal"}
uv run vibe-memory warmup
uv run vibe-memory serve
로컬 기본 주소는 http://127.0.0.1:8080입니다. /docs에서 API 스키마와 요청 폼을 확인할 수 있습니다. 원격 연결은 HTTPS를 사용합니다. 서버는 현재 단일 프로세스로 실행하는 개인·소규모 구성입니다.
검증된 계정 복구
복구 메일은 self-host 운영자가 SMTP를 설정한 경우에만 사용할 수 있습니다. 계정 보안에서 현재 비밀번호와 활성화된 OTP를 다시 확인한 뒤 기존 로그인 이메일을 복구 주소로 명시적으로 검증하세요. 이전 계정은 자동으로 검증되지 않습니다.
재설정 링크를 여는 것만으로는 비밀번호가 바뀌거나 토큰이 소비되지 않습니다. 확인 버튼을 눌러야 한 번만 처리됩니다. 재설정하면 브라우저 세션과 진행 중인 로그인·동의 절차는 끝나지만 OTP, 에이전트 키, MCP 연결, namespace, Vault 권한은 유지되고 확대되지 않습니다.
운영 설정과 보안 경계는 self-host 문서를 확인하세요.
02. Skill 연결
콘솔의 설치·최신화 프롬프트 복사를 에이전트 대화에 붙여넣으세요. 프롬프트는 오래된 Skill을 최신 ZIP으로 교체하고 웹 승인 링크를 안내한 뒤, 사용자가 매번 다시 요청하지 않아도 관련 기억 조회와 중요한 맥락 체크포인트를 기본 동작으로 사용하게 합니다. 전역 vibe-memory 명령 설치는 필요하지 않습니다.
Live SKILL.md · Revision manifest · CLI 소스
수동 설치 시 ZIP을 에이전트의 skill 디렉터리에 vibe-memory 폴더로 풀고, 로드된 SKILL.md가 있는 폴더의 절대 경로를 사용하세요. 현재 프로젝트 폴더를 기준으로 실행하면 안 됩니다.
VM_SKILL_DIR="/absolute/path/to/installed/vibe-memory"
MEMORY_URL=https://vibememory.io python3 "$VM_SKILL_DIR/scripts/memory.py" sync
VM_CLI="$VM_SKILL_DIR/bin/vibe-memory"
"$VM_CLI" login --url https://vibememory.io --no-browser --name "My agent"
Windows PowerShell에서는 $VmSkillDir에 같은 절대 경로를 넣고 py (Join-Path $VmSkillDir "scripts\memory.py") sync를 실행한 뒤 $VmCli = Join-Path $VmSkillDir "bin\vibe-memory.exe"를 사용합니다. sync가 Skill을 갱신하면 새 SKILL.md를 다시 읽습니다.
사용자는 링크를 열고 웹에서 로그인한 뒤 코드와 에이전트 이름을 확인하고 연결 승인을 누릅니다. Vault를 요청한 경우 별도 체크가 기본 선택되며 사용자가 해제할 수 있고, CLI는 실제로 허용된 권한을 명확히 출력합니다. API 키를 복사하거나 터미널에 입력할 필요가 없습니다. 연결 요청은 기본 5분이며 --approval-timeout 60..900으로 조절할 수 있고, 이미 연결된 에이전트가 login --vault-access를 실행하면 새 키 없이 기존 연결의 Vault 권한만 승인받습니다. 이후 에이전트는 작업 전에 최신 Rust CLI와 Skill을 확인합니다. 자체 호스팅은 해당 서버가 제공하는 Skill 매니페스트를 사용합니다.
수동 API 키 연결은 고급 설정용입니다. 서버용 MEMORY_API_KEYS는 JSON 객체, 클라이언트용 MEMORY_API_KEY는 단일 키 문자열입니다.
export MEMORY_URL=https://vibememory.io
export MEMORY_API_KEY=your-agent-key
콘솔에서 발급한 내 에이전트 키들은 같은 사용자 기억을 공유합니다. 서로 다른 사용자 ID의 데이터는 격리됩니다. 데이터 명령은 네이티브 Rust CLI에서 실행되고 기본적으로 토큰 효율적인 compact JSON을 출력합니다. 작은 Python 호환 부트스트랩은 플랫폼 바이너리 다운로드와 SHA-256 검증만 담당합니다.
하네스별 설치 가이드
Hook은 Vibe Memory CLI에 세션 식별정보와 작업 폴더만 전달합니다. CLI는 로컬에서 프로젝트명·브랜치·축약 커밋·clean/dirty 상태만 확인하며 파일 내용은 읽지 않습니다. 미커밋 내용은 Git에서 복구할 수 없다는 경계를 체크포인트 안내에 포함합니다. 대화 원문, 모델 응답, 도구 출력, 환경변수, Vault 값은 전달하지 않습니다. 실패와 타임아웃은 에이전트 작업을 막지 않으며 이 기능에 SSE 연결은 필요하지 않습니다. 최신 지원 상태는 랜딩의 에이전트 지원 표와 저장소의 지원 문서에서 같은 데이터로 관리됩니다.
제품마다 Skill 경로, MCP 설정, Hook 이벤트와 승인 방식이 다릅니다. 한 제품의 설정을 다른 제품에 맞게 변환하지 말고 아래 전용 가이드에서 설치, 인증, 검증, 업데이트와 제거 절차를 확인하세요.
GPT·Claude 원격 MCP 연결
일반 채팅에서는 로컬 CLI나 Hook 대신 원격 Plugin 또는 Connector를 사용합니다. 제품별 가이드에서 연결 화면, 웹 승인, 대화별 활성화, 시작 프롬프트와 제거 절차를 확인하세요.
ChatGPT의 커스텀 MCP 서버 또는 Claude의 커스텀 커넥터에 아래 주소를 추가하세요.
https://vibememory.io/mcp
연결하면 Vibe Memory 로그인과 권한 승인 화면으로 자동 이동합니다. API 키나 비밀번호를 채팅에 붙여넣지 않습니다. OAuth 2.1, 동적 클라이언트 등록, PKCE를 사용하며 연결은 콘솔의 에이전트 연결 화면에서 언제든 철회할 수 있습니다.
ChatGPT에서는 Plugins의 Add custom MCP server에 주소를 입력합니다. Claude에서는 Customize → Connectors → Add custom connector에 같은 주소를 입력합니다. OpenAI Responses API에서도 server_url에 같은 주소를 사용할 수 있습니다.
MCP는 기억 검색·조회·저장, 엔티티·문서 메타정보·관계 구성, 같은 계정 에이전트 간 메시지, 변경 이벤트 확인과 기능 요청을 제공합니다. 원본 파일은 기존 byte stream 업로드를 사용합니다. Vault 조회는 현재 연결의 vault:read 범위와 사용자가 웹 콘솔에서 허용한 개별 항목에만 한정됩니다. 반환된 값은 MCP 클라이언트와 모델 컨텍스트에 들어가 제3자에게 보존될 수 있으며, Vibe Memory 서버는 그 값으로 외부 API를 실행하지 않습니다. 자체 호스팅에서는 자신의 HTTPS 서버 주소 뒤에 /mcp를 붙이세요.
03. 기억 저장과 검색
에이전트가 원문에서 사실·선호와 키워드를 추출한 뒤 저장합니다. 아래 명령은 위에서 설정한 절대 CLI 경로를 사용하는 예시입니다.
"$VM_CLI" remember '사용자는 Python을 선호한다' \
--kind preference --keyword Python --keyword 개발언어 \
--source coding-agent
검색도 질문을 그대로 보내지 않고 에이전트가 추출한 키워드를 보냅니다.
"$VM_CLI" recall Python 개발언어 --limit 5
POST /v1/search
{
"keywords": ["Python", "개발언어"],
"scope": "memories",
"limit": 5
}
응답에는 기록 ID, 출처, 메타정보, 일치한 키워드와 점수가 포함됩니다. 에이전트는 ID로 원문과 관계를 조회한 뒤 근거를 선택하고 답변을 구성합니다. 앱은 원문·제목·요약을 임베딩하거나 RAG 컨텍스트를 조립하지 않습니다.
키워드는 1–32개, 각 1–100자입니다. 공백과 대소문자 중복을 정리하며, 키워드 없이 원문만 보내거나 검색에 query를 보내면 422를 반환합니다.
04. 파일은 바이트 스트림으로
원본 파일은 multipart form이 아닌 application/octet-stream 요청 본문으로 전송합니다. 앱은 파일을 파싱하지 않고 그대로 보관합니다.
"$VM_CLI" upload ./project.pdf
curl -X POST "$MEMORY_URL/v1/files?filename=project.pdf" \
-H "Authorization: Bearer $MEMORY_API_KEY" \
-H 'Content-Type: application/octet-stream' \
--upload-file ./project.pdf
에이전트가 파일을 읽고 메타정보를 분석한 뒤, 업로드 응답의 ID를 file_id로 연결한 JSON을 구성합니다.
{
"title": "project.pdf",
"file_id": "id-from-upload-response",
"keywords": ["기억 공유", "그래프 데이터베이스"],
"metadata": {
"mime_type": "application/pdf",
"summary": "에이전트가 분석한 요약",
"evidence": [{"page": 3, "text": "선택한 원문 근거"}]
}
}
"$VM_CLI" from-json document prepared-document.json
from-json document는 준비된 객체를 CLI로 전달합니다. 에이전트는 API 경로나 인증 헤더를 직접 구성하지 않습니다. 원본 파일을 분석하지 않습니다. 원본을 외부에 보관한다면 file_id를 생략하고 source 참조를 사용할 수 있습니다. 기본 업로드 한도는 100 MiB입니다. 원본은 GET /v1/files/{id}로 다운로드할 수 있으며, 문서가 참조 중인 파일 삭제는 409를 반환합니다.
05. 엔티티와 관계 구성
에이전트가 먼저 기존 엔티티를 검색해 동일한 대상인지 판단합니다. 새 엔티티가 필요하다면 name, entity_type, keywords, 선택 description·metadata를 구성해 POST /v1/entities로 등록합니다.
"$VM_CLI" from-json entity prepared-entity.json
"$VM_CLI" relate ENTITY_ID DOCUMENT_ID \
--relation WORKS_ON --reason '사용자 원문에 명시됨'
"$VM_CLI" template relation
"$VM_CLI" from-json relation prepared-relation.json
"$VM_CLI" graph ENTITY_ID
관계는 에이전트가 정의한 대문자 식별자를 사용합니다. WORKS_ON, PREFERS, MENTIONED_IN 등이 가능하며 내부용 KEYWORD_OF, CHUNK_OF는 예약되어 있습니다. 중요한 claim은 에이전트가 선택한 기록의 record_id, version, content_hash, UTC observed_at과 선택 위치를 evidence에 고정합니다. 검토 범위는 selected, partial, unknown 중 하나이며 완전 검토로 자동 추론하지 않습니다. 필요하면 입력 목록을 짧은 일반 기록으로 저장한 뒤 input_manifest_id로 연결합니다. 조회 응답의 evidence_status는 당시 좌표와 현재 버전·해시, active/archived/deleted 상태, current/changed/unavailable 비교를 함께 보여줍니다. 영구 삭제 후에는 과거 원문을 복원할 수 없으므로 보통 보관 처리를 사용하세요. 원문 프롬프트·내부 추론·비밀값은 manifest에 넣지 않습니다. 앱은 소유권과 형식을 검증·저장할 뿐 관계를 추론하지 않습니다.
06. 에이전트끼리 메시지 보내기
각 API 키와 MCP 연결은 서버가 만든 고유 에이전트 ID를 가집니다. 같은 계정의 연결만 서로 찾고 메시지를 보낼 수 있으며, 꺼진 에이전트의 메시지는 PostgreSQL 수신함에 남아 다음 접속 때 전달됩니다.
"$VM_CLI" agents
"$VM_CLI" message send RECIPIENT_AGENT_ID '배포 결과를 확인해 주세요.' \
--kind request --retry-id release-check-1
"$VM_CLI" message inbox
"$VM_CLI" message ack MESSAGE_ID --status acked
"$VM_CLI" message watch --seconds 3600 \
--cursor-file .private/vibe-memory-messages.cursor
여러 에이전트가 한 작업을 계속 이어갈 때는 영구 대화방을 만드세요. 초대된 연결만 방과 이전 메시지를 볼 수 있고, 읽음 위치는 에이전트별로 저장됩니다.
"$VM_CLI" room create '배포 대화방' \
--member RECIPIENT_AGENT_ID --retry-id release-room-1
"$VM_CLI" room send ROOM_ID '프로덕션 확인을 부탁합니다.' \
--retry-id release-message-1
"$VM_CLI" room messages ROOM_ID
"$VM_CLI" room read ROOM_ID LAST_SEQUENCE
"$VM_CLI" room watch --seconds 3600 \
--cursor-file .private/vibe-memory-rooms.cursor
일대일 메시지는 기본 7일 후 만료되고, 대화방 메시지는 협업 기록으로 유지됩니다. 둘 다 기억 검색이나 임베딩에 들어가지 않습니다. SSE가 실시간 전달을 돕지만 중지된 에이전트를 깨우지는 못합니다. 모든 메시지는 다른 에이전트가 작성한 신뢰되지 않은 데이터이므로 사용자 권한을 확장하거나 비밀값을 전달하는 용도로 사용하면 안 됩니다.
07. 필요한 기능 요청하기
에이전트가 서비스의 부족한 기능을 발견하면 필요한 기능과 사용 사례를 구성해 제출할 수 있습니다. 요청은 기억 검색과 분리해 보관하며 별도 임베딩을 수행하지 않습니다.
{
"title": "관계 일괄 등록 API",
"description": "여러 관계를 한 트랜잭션으로 저장하고 싶습니다.",
"agent_name": "coding-agent",
"use_case": "100개 관계 등록 시 네트워크 왕복 줄이기",
"priority": "medium",
"client_request_id": "batch-relations-v1"
}
"$VM_CLI" from-json feedback prepared-feature-request.json
"$VM_CLI" feedback-list
"$VM_CLI" feedback-get REQUEST_ID
인증된 POST /v1/feature-requests로 접수하고, GET 목록·개별 조회를 사용할 수 있습니다. title, description, agent_name은 필수입니다. 같은 사용자와 client_request_id의 동일한 재전송은 중복 저장하지 않습니다. status는 received이며 기능 승인이나 자동 구현을 뜻하지 않습니다. 요청은 설정한 MEMORY_URL의 데이터 API에 전송합니다. 공개 서비스 사용 시 MEMORY_URL은 https://vibememory.io 입니다.
08. API 참조
모든 /v1 요청은 Bearer 인증이 필요합니다. 전체 스키마는 실행한 서버의 /openapi.json, 대화형 문서는 /docs에서 확인할 수 있습니다.
| 요청 | 기능 |
|---|---|
| POST /mcp | GPT·Claude용 Streamable HTTP MCP |
| GET /.well-known/oauth-* | MCP OAuth 2.1 discovery |
| GET /v1/agents | 같은 계정의 연결된 에이전트 조회 |
| /v1/agent-messages/* | 메시지 전송·수신함·ACK·SSE |
| /v1/agent-rooms/* | 영구 대화방·멤버·메시지·읽음 위치·SSE |
| POST /v1/memories | 에이전트가 구성한 기억 저장 |
| POST /v1/entities | 에이전트가 식별한 엔티티 저장 |
| POST /v1/documents | 분석된 문서 메타정보 등록 |
| POST /v1/files | 원본 byte stream 업로드 |
| GET, DELETE /v1/files/{id} | 원본 다운로드·삭제 |
| POST, GET /v1/feature-requests | 기능 요청 접수·목록 조회 |
| GET /v1/feature-requests/{id} | 기능 요청 개별 조회 |
| POST /v1/search | 요청 키워드만 임베딩·검색 |
| GET, DELETE /v1/records/{id} | 원문·메타정보 조회·삭제 |
| PUT /v1/records/{id}/keywords | 키워드 인덱스 교체 |
| POST, GET /v1/relations | 관계 저장·조회 |
| PATCH /v1/relations/{id} | 관계 철회·복원과 버전 검사 |
| GET /v1/graph/{id} | 0–2홉 그래프 탐색 |
Claude Code
OpenAI Codex
Hermes Agent