opencode-mem: AI 코딩 에이전트를 위한 영구 메모리 시스템

지원 언어: 🇬🇧 | 🇩🇪 | 🇨🇳 | 🇸🇦 | 🇹🇷 | 🇳🇱

로컬 벡터 데이터베이스 기술을 사용하여 세션 간 장기적인 컨텍스트 유지(long-term context retention)를 가능하게 하는 AI 코딩 에이전트를 위한 영구 메모리 시스템입니다.

네이티브 벡터 검색 기능을 갖춘 로컬 Turso/libSQL 데이터베이스, 지속적인 프로젝트 메모리, 자동 사용자 프로필 학습, 통합 메모리-프롬프트 타임라인, 기능이 풍부한 웹 UI, 지능형 프롬프트 기반 메모리 추출, 다중 공급자 AI 지원(OpenAI, Anthropic), 12개 이상의 로컬 임베딩 모델, 스마트 중복 제거(deduplication), 그리고 내장 개인 정보 보호 기능이 제공됩니다.

이 플러그인은 F32_BLOB 벡터와 vector_distance_cos를 통한 정확한 코사인 검색을 위해 임베디드 Turso(@tursodatabase/database)를 사용합니다. 별도의 벡터 데이터베이스나 커스텀 SQLite 빌드가 필요하지 않습니다.

권장 런타임:

• Bun
• 표준 OpenCode 플러그인 환경
• 기본 로컬 임베딩 모델을 사용하는 경우 첫 사용 시 인터넷 접속이 필요합니다. 이는 모델이 @huggingface/transformers에 의해 다운로드되기 때문입니다.
• 소스/개발 설치의 경우, 빌드하거나 테스트하기 전에 bun install을 실행하십시오. 게시된 플러그인 패키지는 OpenCode를 통해 런타임 종속성을 자동으로 설치합니다.

CI 테스트 플랫폼: Linux, Windows, 그리고 Apple Silicon용 macOS 15 / macOS 26 (darwin/arm64)입니다. Intel Mac (darwin/x64)는 지원되지 않습니다. —

@tursodatabase/database와 수정된 onnxruntime-node 릴리스는 x64 네이티브 바인딩을 포함하지 않습니다. 이전 macOS 릴리스가 이 매트릭스에 의해 제외되는 것은 아니며, 단순히 현재 GitHub 호스팅 러너 세트에 속하지 않을 뿐입니다.참고:

• 벡터 임베딩은 Turso에 직접 저장 및 검색되며, 삽입 시 정확한 코사인 순위를 위해 F32_BLOB 벡터를 저장합니다. - 벡터 검색은 vector_distance_cos를 통한 정확한 코사인 거리를 사용하며 (DiskANN/근사 인덱스 없음), 쿼리 문자열이 제공될 경우 선택적 키워드 하이브리드 순위 지정 기능을 제공합니다 (@tursodatabase/database는 FTS5를 포함하지 않습니다). - 세션 조회에는 색인된 session_id 컬럼을 사용하며 (metadata.sessionID에서 백필됨)

on schema v2)로 변경하려면 AI 제공업체가 구조화된/도구 호출(tool-call) 출력을 반환할 수 있어야 합니다. 메모리 검색/추가/목록 보기 기능은 자동 캡처 제공업체 구성 없이도 여전히 작동합니다.

opencode-mem은 GPU를 요구하지 않습니다. 로컬 임베딩은 @huggingface/transformers를 통해 CPU에서 실행됩니다.

그리고 ONNX(MLX 백엔드는 없음)가 필요합니다. 추가 VRAM이 필요하지 않습니다.

위의 플랫폼 제한 사항은 여전히 적용됩니다 (Intel Mac darwin/x64는 사용 불가; Apple Silicon, Linux, Windows 또는 원격 임베딩 엔드포인트를 사용해야 합니다). 임베딩 선택 및 구성(Choosing / configuring embeddings)을 참조하세요.

시작 시 중단된 재임베드 스왑(re-embed swaps)을 복구하고, libSQL DiskANN 인덱스를 현재 Turso 엔진으로 변환하며, 그런 다음 레거시 샤드 스키마를 확인하거나 업그레이드합니다. 엔진 변환은 저장소가 이미 완료된 레거시 마이그레이션 마커를 가지고 있더라도 실행되며, 재임베딩 없이 저장된 벡터를 보존합니다. 변환된 각 데이터베이스는 <database>.pre-tursodb-<timestamp>.bak로 백업됩니다.

macOS와 Linux에서는 Turso의 실험적인 multiprocess_wal을 통해 여러 OpenCode 세션이 동일한 storagePath를 공유할 수 있습니다 (모든 프로세스는 동일한 모드를 사용해야 함 — 업그레이드 후 모든 세션을 재시작해야 합니다). Windows에서는 엔진이 해당 플래그를 거부하므로, 한 번에 하나의 OpenCode 세션만이 메모리 데이터베이스를 소유할 수 있습니다.

업그레이드 후 처음 시작할 때, opencode-mem은 기존 메모리 샤드 데이터베이스를 네이티브 Turso/libSQL 벡터 형식으로 자동 마이그레이션합니다:

• 각 샤드는 재작성 전에 <shard>.db.legacy.bak로 백업됩니다.
• 진행 상황은 <shard>.db.turso-migrate.json에서 샤드별로 추적됩니다.
• 전역 마커 .turso-migrated는 모든 샤드가 성공적으로 검증된 후에만 작성됩니다 - 마이그레이션 중에는 여러 OpenCode 인스턴스가 동일한 storagePath를 대상으로 실행되지 않도록 하십시오. 잠금 파일 (.turso-migrate.lock)이 동시 마이그레이션을 방지합니다 - 수동 차원 마이그레이션은 .turso-operation.lock을 사용합니다; 다른 플러그인 프로세스는 마이그레이션이 완료될 때까지 새로운 메모리 쓰기를 거부합니다.

마이그레이션이 중단되면, 다음 시작 시 백업에서 자동으로 재개됩니다.

만약 샤드가 호환되지 않게 되면 (예를 들어 embeddingDimensions 변경 후), 쓰기는 차단되고 원래 데이터베이스는 손대지 않은 상태로 유지됩니다. Web UI의 re-embed 마이그레이션을 사용하여 교체할 것을 빌드하고 검증한 후에 배치해야 합니다. 이전 샤드는 <shard>.db.pre-reembed-<pid>-<timestamp>.bak로 계속 사용할 수 있습니다.

로컬 Turso 샤드 및 보조 데이터베이스 (metadata.db, user-prompts.db, user-profiles.db, ai-sessions.db)는 src/services/turso/schema-migrations.ts에서 순서가 지정된 PRAGMA user_version 마이그레이션으로 업그레이드됩니다. 마이그레이션은 반복 가능(idempotent)합니다: 플러그인을 시작하면 보류 중인 버전만 적용됩니다.

OpenCode v2의 경우, 패키지를 네이티브 plugins 목록에 추가하십시오:

{
"plugins": ["opencode-mem@latest"],
}

OpenCode는 또한 패키지의 ./tui 컴패니언을 자동으로 로드하므로 TUI에서 자동 캡처/프로필/오류 토스트가 렌더링됩니다 (서버 플러그인은 ui.toast를 직접 호출할 수 없습니다). plugins에 두 번째 항목이 필요하지 않습니다. CLI 전용 TUI를 원격 OpenCode 서버와 함께 실행하는 경우, 해당 CLI의 플러그인 목록(예: cli.json)에 opencode-mem/tui를 등록하십시오.

OpenCode v1의 경우, 기본 진입점을 ~/.config/opencode/opencode.json에서 구성에 추가하십시오:

opencode-mem.jsonc에 @latest(또는 semver 범위)와 autoUpdate: true를 설정하면, 플러그인은 더 새로운 npm 릴리스가 사용 가능할 때 OpenCode의 캐시된 설치본을 지우고 재시작을 요청합니다. [email protected]과 같은 고정 버전(Pinned versions)은 절대 자동으로 업데이트되지 않습니다.

v2 플러그인은 모델의 시스템 컨텍스트(system context)를 통해 자동 메모리 컨텍스트를 제공합니다. 이 블록들은 작성된 사용자 프롬프트에 추가되거나 채팅 기록에 저장되지 않습니다. chatMessage.injectOn: "first" (기본값)을 사용하면, 세션의 초기 컨텍스트가 사용자 턴(user turns)과 모델 단계 전반에 걸쳐 유지됩니다. "always"를 사용하면, 작성된 사용자 턴마다 새로 고침됩니다.

호스트 또는 플러그인 재시작 후, 재개된 세션은 새로운 사용자 프롬프트가 도착하지 않더라도 다음 모델 요청 시 현재 메모리 저장소(memory store)로부터 컨텍스트를 재구축합니다. 기억과 프로필이 진화함에 따라 재구축된 컨텍스트는 원래의 컨텍스트와 다를 수 있습니다. 복원 과정은 합성 사용자 프롬프트(synthetic user prompt)를 캡처하거나 OpenCode 플러그인 저장소에 메모리 텍스트의 두 번째 사본을 저장하지 않습니다. 압축(Compaction)은 캐시된 자동 컨텍스트를 무효화하며, 기존의 압축-메모리 복원 기능도 계속 실행됩니다.

npm 릴리스 대신 로컬 소스 체크아웃(local source checkout)에서 플러그인을 실행하려면, 체크아웃 디렉토리에서 bun install && bun run build를 실행한 다음, plugins 목록을 해당 체크아웃 디렉토리에 지정합니다:

{
"plugins": ["/absolute/path/to/opencode-mem"],
}

dist/나 단일 파일이 아닌 패키지 루트(package root)를 가리켜야 합니다. OpenCode는 디렉토리 플러그인을 <directory>/index로 폴백(fallback)하여 해석합니다 (현재 릴리스에서 경로 지정 시 OpenCode는 package.json exports / main을 읽지 않음). 따라서 이 저장소는 dist/plugin.js에서 빌드된 v2 진입점(entrypoint)을 다시 내보내는 얇은 루트 index.js와, TUI 컴패니언용으로 dist/tui.js를 다시 내보내는 루트 tui.js를 배포합니다. 파일 경로로 지정하는 것은 거부됩니다 (configured plugin path must be a directory), 그리고 루트 index.js가 없는 디렉토리는 조용히 건너뜁니다.

로컬 Turso 샤드에 대한 AES-256-GCM 암호화 활성화 (~/.config/opencode/opencode-mem.jsonc에서)

{
"databaseEncryptionEnabled": true,
}

플러그인은 첫 시작 시 ~/.config/opencode/opencode-mem-db.key (32바이트 헥스 키, chmod 600)를 생성하고 기존의 평문 샤드들을 마이그레이션합니다. 만약 사용자가 직접 키를 관리하는 경우, "databaseEncryptionKey": "env://OPENCODE_MEM_DB_KEY" 또는 "file://~/path/to.key"로 재정의할 수 있습니다. 이 키를 분실하면 암호화된 데이터베이스를 열 수 없습니다.

Windows: %USERPROFILE%\.config\opencode\opencode.json을 사용하십시오 (예: C:\Users\<you>\.config\opencode\opencode.json). 이 플러그인은 OpenCode 플러그인 항목에 대해 %APPDATA%나 %LOCALAPPDATA%를 읽지 않습니다. 파일을 사용자 프로필의 .config\opencode 아래에 두고, 그 후 OpenCode를 다시 시작하십시오. 플러그인이 나타나지 않으면 해당 경로를 확인하고 다시 시작하십시오.

이 플러그인은 다음 시작 시 자동으로 다운로드됩니다.

플러그인이 작동하기 위해 OpenCode에게 무언가를 "기억"하라고 요청할 필요는 없습니다. 기본 설정으로도 작업하는 동안 메모리가 축적됩니다.

• 플러그인을 활성화하고 (Getting Started 참조) OpenCode를 다시 시작합니다.
• 자동 캡처를 위해 AI 제공업체를 구성합니다 — 권장: opencodeProvider +opencodeModel (또는 "opencodeModel": "inherit"). 자세한 내용은 Auto-Capture AI Provider에서 확인하십시오. - OpenCode에서 정상적으로 작동합니다. 세션이 유휴 상태가 되면, 자동 캡처 기능이 기억할 만한 기술적 컨텍스트를 추출하여 저장합니다.
• 이후 세션에서는 관련 메모리가 컨텍스트에 주입됩니다 (chatMessage 또는 압축(compaction) 설정 참조). 웹 UI(http://127.0.0.1:4747)에서 이를 탐색하거나 편집할 수 있습니다.
• 무언가를 즉시 저장하거나 검색하고 싶을 때 memory 도구를 사용하십시오 (Usage Examples 참조).

자동 캡처에 제공업체(provider)가 구성되어 있지 않아도 수동 검색/추가/목록 확인은 작동합니다. 자동 캡처와 사용자 프로필 학습에는 구조화된/도구 호출 출력을 반환할 수 있는 제공업체가 필요합니다.

일반적인 규칙: 영속적이고 항상 활성화된 프로젝트 지침 $
ightarrow$ AGENTS.md

; 증가하는 작업 컨텍스트 $
ightarrow$ 메모리(memory); 필요할 때 재사용 가능한 절차 $
ightarrow$ 스킬 (Skills).

• 웹 탐색기에서 스킬 생성/편집 (Skills 탭: /skill-library). - 플러그인 저장 경로의 skills.db에 영속적으로 저장됩니다 (메모리 벡터로 저장되는 것이 아님). - OpenCode V2에서는 플러그인이 ctx.skill.transform을 통해 활성화된 스킬을 등록하여 에이전트가 네이티브 skill 도구로 로드할 수 있게 합니다. - 다른 OpenCode 인스턴스를 위한 선택적 HTTP 카탈로그: `

기능 목록에 있는 해당 문구는 **자동 캡처(auto-capture)**입니다. 대화가 끝난 후, 백그라운드 AI 요청이 기술적인 작업을 요약하여 메모리로 저장합니다. 사용자의 특별한 프롬프트가 필요하지 않습니다. 이는 opencodeProvider와 opencodeModel을 사용할 때 작동하며, 그렇지 않으면 수동의 memoryProvider 폴백(fallback) 기능을 사용합니다.

**사용자 프로필(User Profile)**은 사용자가 어떻게 작업하는지(선호도, 습관 등)에 대한 별도의 프로젝트 간 요약 정보입니다. 이는 주기적으로(userProfileAnalysisInterval, 기본값 10개 분석 프롬프트마다) 업데이트되며, 웹 UI의 프로필 보기에서 확인하고 memory({ mode: "profile" })를 통해 읽을 수 있습니다. 일반적인 사용 시에는 직접 채울 필요가 없으며, 프로필 학습 기능이 제공업체가 준비되면 자동으로 내용을 채웁니다. 출력 언어는 autoCaptureLanguage (기본값 `