빠른 시작: 설치 및 설정
학습 완료 후 할 수 있는 것
이 수업을 통해 다음을 배울 수 있습니다:
- opencode-supermemory 플러그인을 OpenCode 환경에 설치합니다.
- Supermemory API Key를 설정하여 클라우드 메모리 저장소에 연결합니다.
- 플러그인이 성공적으로 로드되었는지 확인합니다.
- 다른 플러그인(예: Oh My OpenCode)과의 잠재적 충돌을 해결합니다.
완료 후, Agent는 클라우드 메모리 저장소에 연결하는 기본 능력을 갖추게 됩니다.
현재 상황
아마도 이미 OpenCode의 Agent는 똑똑하지만, 매우 잊어버리기 쉽다는 것을 알고 계실 겁니다:
- 새로운 세션을 시작할 때마다, 이전의 기본 설정을 기억하지 못하는 것처럼 행동합니다.
- 프로젝트 A에서 가르쳐 준 아키텍처 규칙을 프로젝트 B로 가면 잊어버립니다.
- 긴 세션에서 대화를 나누다 보면, 앞서의 중요한 정보가 컨텍스트에서 "밀려나게" 됩니다.
Agent가 이런 것들을 기억할 수 있도록 외장 뇌가 필요합니다.
언제 이 방법을 사용할까요
- 처음 사용할 때: opencode-supermemory를 처음 접할 때.
- 재설치할 때: 새로운 컴퓨터로 이동하거나 OpenCode 설정을 초기화했을 때.
- 문제 해결: 플러그인이 제대로 설치되지 않았거나 API 연결에 문제가 있다고 의심될 때.
🎒 시작 전 준비
시작하기 전에 다음을 확인하세요:
- OpenCode 설치: 터미널에서
opencode명령어를 사용할 수 있는지 확인. - API Key 확보:
- Supermemory Console 방문
- 계정 등록/로그인
- 새로운 API Key 생성(
sm_으로 시작)
Supermemory란?
Supermemory는 AI Agent를 위해 특별히 설계된 클라우드 메모리 계층입니다. 단순히 데이터를 저장하는 것뿐만 아니라, 시맨틱 검색을 통해 Agent가 적절한 때에 올바른 것을 떠올리도록 도와줍니다.
핵심 아이디어
설치 과정은 매우 간단하며 본질적으로 3단계입니다:
- 플러그인 설치: 설치 스크립트를 실행하여 플러그인을 OpenCode에 등록.
- 키 설정: 플러그인에게 API Key가 무엇인지 알려줌.
- 연결 확인: OpenCode를 재시작하여 Agent가 새로운 도구를 볼 수 있는지 확인.
함께 따라하세요
1단계: 플러그인 설치
두 가지 설치 방법을 제공합니다. 적합한 방법을 선택하세요.
# 권장: 대화형 안내가 제공되어 자동으로 설정 처리
bunx opencode-supermemory@latest install# Agent가 설치를 도와줄 때 사용 (확인 메시지 건너뛰고 자동 충돌 해결)
bunx opencode-supermemory@latest install --no-tui --disable-context-recovery다음을 보아야 합니다: 터미널에 ✓ Setup complete!가 출력되며, 플러그인이 ~/.config/opencode/opencode.jsonc에 성공적으로 등록되었음을 나타냄.
2단계: API Key 설정
플러그인이 클라우드 메모리를 읽고 쓰려면 API Key가 필요합니다. 두 가지 설정 방법이 있습니다:
방법 A: 환경 변수(권장)
Shell 설정 파일(예: .zshrc 또는 .bashrc)에 직접 추가:
export SUPERMEMORY_API_KEY="sm_당신의_키..."방법 B: 설정 파일
또는, 전용 설정 파일 ~/.config/opencode/supermemory.jsonc 생성:
{
"apiKey": "sm_당신의_키..."
}이유: 환경 변수가 더 안전하며 실수로 코드 저장소에 커밋되지 않음. 설정 파일은 여러 설정을 관리하기에 더 편리.
3단계: 충돌 해결(Oh My OpenCode를 사용하는 경우)
Oh My OpenCode를 설치했다면, 내장된 컨텍스트 관리 기능이 Supermemory와 충돌할 수 있습니다.
확인 방법: 설치 스크립트는 일반적으로 충돌하는 훅을 자동으로 감지하여 비활성화하도록 알려줍니다. 그렇지 않다면 ~/.config/opencode/oh-my-opencode.json을 수동으로 확인하세요:
{
"disabled_hooks": [
"anthropic-context-window-limit-recovery" // ✅ 이 줄이 있는지 확인
]
}이유: Supermemory는 더 지능적인 "선점형 압축(Preemptive Compaction)"을 제공합니다. 두 플러그인이 동시에 컨텍스트를 관리하려고 하면 혼란이 발생할 수 있습니다.
4단계: 설치 확인
OpenCode를 재시작한 다음, 확인 명령어를 실행하세요:
opencode -c또는 OpenCode 대화형 모드로 진입하여 도구 목록을 확인.
다음을 보아야 합니다: 도구 목록(Tools)에 supermemory 도구가 나타남.
Available Tools:
- supermemory (add, search, profile, list, forget)
...체크포인트 ✅
모든 준비가 되었는지 자체 점검:
- [ ]
cat ~/.config/opencode/opencode.jsonc를 실행하여"opencode-supermemory"가plugin목록에 있는지 확인. - [ ] 환경 변수
SUPERMEMORY_API_KEY가 적용되었는지 확인(echo $SUPERMEMORY_API_KEY로 확인 가능). - [ ]
opencode를 실행 후, Agent가 오류 메시지를 표시하지 않는지 확인.
일반적인 실수 주의
일반적인 오류: API Key가 적용되지 않음
환경 변수를 설정했지만 플러그인에서 인증되지 않았다고 나오는 경우 확인:
- 터미널을 재시작했나요? (
.zshrc를 수정한 후source ~/.zshrc또는 재시작 필요) - OpenCode를 재시작했나요? (OpenCode 프로세스를 재시작해야 새 변수를 읽음)
일반적인 오류: JSON 형식 오류
opencode.jsonc를 수동으로 수정하는 경우, JSON 형식이 올바른지 확인(특히 쉼표). 설치 스크립트는 이를 자동으로 처리하지만, 수동 수정 시 오류 발생하기 쉬움.
이 수업 요약
축하합니다! OpenCode에 "해마체"를 장착했습니다. 이제 Agent는 메모리를 시작할 준비가 되었습니다.
opencode-supermemory플러그인을 설치했습니다.- 클라우드 연결 자격 증명을 설정했습니다.
- 잠재적 플러그인 충돌을 해결했습니다.
다음 수업 예고
다음 수업에서 **프로젝트 초기화: 첫인상 형성**을 학습합니다.
배우게 될 내용:
- 한 명령어로 Agent가 전체 프로젝트를 심층 스캔하는 방법.
- Agent가 프로젝트의 아키텍처, 기술 스택, 암시적 규칙을 기억하게 하는 방법.
- Agent가 무엇을 기억했는지 확인하는 방법.
부록: 소스 코드 참조
소스 코드 위치 보려면 클릭
업데이트: 2026-01-23
| 기능 | 파일 경로 | 행 번호 |
|---|---|---|
| 설치 스크립트 로직 | src/cli.ts | 327-410 |
| 플러그인 등록 로직 | src/cli.ts | 195-248 |
| 충돌 감지 로직 | src/cli.ts | 273-320 |
| 설정 파일 로드 | src/config.ts | - |