codemem
Coordinator operators가 선택적 계정 연결을 업그레이드하는 경우 auth writers를 일시 중지하고 명시적 인증 스키마 전환 (explicit auth-schema cutover)을 따라야 합니다.
codemem coordinator upgrade-auth-schema --db-path coordinator.sqlite는 기존 로컬 coordinator 파일을 업그레이드하며, --export-sql은 D1 SQL을 적용하지 않고 내보냅니다.
CI
npm version npm downloads per month License: MIT
코드는 여전히 거기에 있습니다. 추론(reasoning)은 보통 그렇지 않습니다.
codemem은 OpenCode, Claude Code, Codex, 그리고 Pi coding agent에 걸쳐 세션, 머신, 팀원을 아우르는 영구적인 코딩 메모리입니다. 이는 결정 사항, 막다른 길, 리포지토리별 함정 등을 포착하여 나중에 프롬프트로 관련 컨텍스트를 자동으로 가져옵니다.
-
자동 컨텍스트 주입 (Automatic context injection) — 관련 메모리가 에이전트에게 검색을 요청하지 않고 전달됩니다. OpenCode 컨텍스트에 이미 있는 변경되지 않은 메모리는 반복되지 않습니다.
-
선택적 동기화 및 공유 (Optional sync and sharing) — 피어 투 피어(peer-to-peer) 동기화는 선택된 프로젝트 메모리를 머신 간에 전송하며, 팀원이나 팀과 프로젝트 지식을 공유하는 데 도움이 됩니다.
-
로컬 우선 저장소 (Local-first storage) — 메모리는 사용자의 장치 SQLite에 존재합니다. 관찰자 처리(observer processing)는 구성된 모델 제공업체를 사용하며 비용이 발생하거나 플랜 사용량을 소모할 수 있습니다.
-
하이브리드 검색 (Hybrid retrieval) — FTS5 BM25 어휘 검색 + sqlite-vec 의미론적 검색을 병합하고 재순위화(re-ranked)합니다.
-
OpenCode 1 및 2를 위한 자동 주입 — 플러그인이 모든 프롬프트에 컨텍스트를 주입하며, 수동 단계가 필요 없습니다. OpenCode 2 통합은 베타 버전입니다.
-
Claude Code 플러그인 지원 — codemem 마켓플레이스 소스에서 설치할 수 있습니다.
-
다중 에이전트 (Multi-agent) — OpenCode, Claude Code, Codex, pi가 하나의 프로젝트 범위 스토어를 공유합니다.
-
Pi coding agent — 세션 캡처, 자동 회상(automatic recall), 그리고 14가지 네이티브 메모리 도구를 제공하며 MCP가 필요 없습니다.
-
내장 뷰어 (Built-in viewer) — 로컬 웹 UI에서 메모리, 세션 및 옵저버 출력을 탐색할 수 있습니다.
-
원격 MCP 접근 (Remote MCP access) — 고급 단일 사용자 셀프 호스팅을 통해 OAuth로 보호되는 Streamable HTTP MCP 엔드포인트를 구성된 원격 클라이언트가 노출할 수 있습니다. 로컬호스트 뷰어는 비공개로 유지하십시오 (guide)
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/images/docs-feed-dark.png">
<img alt="발명된 코딩 결정, 발견 및 수정 사항을 보여주는 codemem 피드" src="https://raw.githubusercontent.com/kunickiaj/codemem/HEAD/docs/images/docs-feed-light.png">
</picture>
실제 세션 데이터가 아닌 합성 프로젝트 메모리입니다. Feed, Facts, and Projects walkthrough를 탐색하여 무엇이 캡처되었는지 검사하는 방법을 확인하세요.
빠른 시작 (Quick start)
전제 조건 (Prerequisites): Node.js 24.15 이상 및 npm (또는 pnpm). 네이티브 데이터베이스 지원은 macOS x64/arm64, Linux x64/arm64 (glibc 2.34+ 또는 musl), 그리고 Windows x64를 지원합니다. 32비트 대상(Linux armv7 포함)은 지원하지 않습니다.
Linux: 패키지 설치가 시작되기 전에 셸과 OpenCode, Claude Code, Codex 또는 Pi를 실행하는 환경에 ONNXRUNTIME_NODE_INSTALL=skip을 설정하십시오. 이렇게 하면 CPU 추론을 유지하면서 사용되지 않는 ONNX Runtime GPU 제공자 다운로드를 방지할 수 있습니다. 설정 관리형 npx 런처는 스스로 이를 설정할 수 없습니다.
OpenCode
Codemem은 OpenCode 1.18.29 이상을 요구합니다. 설치된 @codemem/opencode-plugin 패키지는 두 호스트 세대 모두에 서비스를 제공합니다: OpenCode 1은 server() 진입점을 호출하고 OpenCode 2는 setup() 진입점을 호출합니다. OpenCode 2 지원은 정확한 안정 버전인 @opencode/[email protected] 및 @opencode/[email protected] 릴리스를 기준으로 검증됩니다. Codemem은 완전한 릴리스 주기를 거치기 전까지는 OpenCode 2 통합을 베타로 표시합니다.
OpenCode 2에서는 플러그인이 사용자 및 어시스턴트 메시지, 터미널 사용 기록, 도구 결과, 세션 생명주기 이벤트를 모두 캡처하며 동일한 mem-status, mem-recent, 그리고 mem-stats 도구를 노출합니다. 자동 리콜은 session.context를 통해 실행됩니다: 최신 사용자 메시지 ID가 필요하며, 누락되거나 빈 ID는 안전하게 리콜을 건너뜁니다. 식별된 각 턴(turn)은 새로운 검색(retrieval)을 수행합니다. 재시도 및 도구 연속 작업은 보존된 컨텍스트를 바이트 단위로 그대로 재생합니다. 압축(Compaction), 제목(title), 그리고 생성(generate) 후크는 격리되어 유지됩니다. 기본 메시지 표면(message surface)과 레거시 CODEMEM_INJECT_SURFACE=system 표면 모두 작동합니다. OpenCode 호스트 지원, 문제 해결 및 롤백를 참조하세요.
- OpenCode 플러그인 및 MCP 설정을 설치합니다:
npx -y codemem setup --opencode-only
- OpenCode를 재시작합니다.
npx는 다운로드되거나 캐시된 패키지를 사용하여 OpenCode 호스트를 구성하며, 영구적인 codemem CLI 설치를 생성하지 않습니다. 구성된 플러그인은 두 호스트 모두에서 백엔드 실행을 독립적으로 관리하므로, 자동 캡처 및 컨텍스트 주입을 위해 전역 설치가 필요하지 않습니다.
설정은 의도적으로 단일 plugin 키를 작성합니다. OpenCode 1은 이 키를 요구하며, OpenCode 2는 이를 네이티브 plugins 구성으로 변환하므로 하나의 설정 항목이 두 호스트 모두에서 작동합니다. Codemem 항목을 하나만 유지하세요. 만약 OpenCode가 하나의 프로젝트에 대해 Codemem을 두 번 로드한다면, 첫 번째 등록이 승리하고 이후의 복사본들은 경고와 함께 해당 후크를 건너뜁니다.
- 확인합니다:
# 전역 codemem 설치가 필요 없는 새 설치에서 작동함
npx -y codemem stats
npx -y codemem db raw-events-status
이것으로 끝입니다. 어느 호스트에서든, 플러그인이 활동을 캡처하고, 메모리를 구축하며, 지금부터 관련 컨텍스트를 주입합니다.
새 세션 리콜 시도
작업을 완료한 후, 해당 결정이 http://localhost:38888의 로컬 뷰어에 나타나는지 확인하세요. 동일 프로젝트에서 새로운 OpenCode 세션을 시작하고 답변을 제공하지 않은 채 그 결정에 대해 질문해 보세요. 예를 들어, 작업 내용이 데이터베이스 마이그레이션과 관련되었다면 다음과 같이 질문할 수 있습니다:
What decision did we make about the database migration, and why?
답변을 저장된 결정 및 원래 작업 증거와 비교하여 검증하세요. 캡처가 아직 보류 중이거나 리콜(recall)이 비어 있다면, 로컬 상태를 확인해 보세요:
npx -y codemem status
npx -y codemem db raw-events-status
Observer 접근 및 외부 모델 비용
Observer는 캡처된 활동을 기억(memory)으로 변환하는 모델입니다. 설정에서 OpenCode 계정, API 키 또는 로컬 Claude/Codex 세션을 선택하세요. 명시적인 연결은 다른 계정으로 되돌아가지 않으며, 기존 자동 설정은 변경할 때까지 현재 규칙을 유지합니다. 로컬 저장소라고 해서 처리 과정이 반드시 로컬에만 이루어지는 것은 아닙니다. 캡처된 컨텍스트는 구성된 모델로 전송되며, 호출 시 비용이 발생하거나 플랜 사용량을 소모할 수 있습니다. 옵션은 구성을 참조하세요.
<details>
<summary>설치, 업그레이드 및 런타임 세부 정보</summary>
codemem은 게시된 패키지 및 워크스페이스 도구 전반에 걸쳐 최소한의 Node.js 버전을 유지합니다.
수동 명령과 의미론적 검색(semantic retrieval)을 위해 codemem을 PATH에 두고 싶다면, CLI를 전역으로 설치하세요. CLI는 기본적으로 일치하는 임베딩 런타임도 함께 설치합니다:
# Linux: 사용하지 않는 ONNX Runtime GPU 프로바이더 다운로드 건너뛰기
env ONNXRUNTIME_NODE_INSTALL=skip npm install -g codemem
...
키워드 전용으로 더 작은 설치를 원한다면, npm install -g codemem --omit=optional을 사용하고 모든 Codemem 프로세스에서 CODEMEM_EMBEDDING_DISABLED=1로 설정하세요. 이 플래그는 npm이 sqlite-vec의 선택적 플랫폼 패키지를 생략하기 때문에 필요하며, CLI는 FTS5를 사용하여 여전히 작동합니다.
npm을 지원하는 관리자(manager), 예를 들어 pnpm이나 mise의 npm:codemem 백엔드는 영구적인 CLI를 제공할 수도 있습니다. codemem이 PATH에 있는지 확인한 후, codemem setup --opencode-only를 실행하세요. pnpm 전역 CLI의 경우, codemem update check는 정확한 페어링 명령인 pnpm add -g codemem@<version> @codemem/embeddings@<version>을 보고합니다. 표준적인 pnpm 가상 스토어 감지(detection)는 지침을 제공하지만 소유권을 증명하지는 않습니다. 명시적인 codemem update install은 어떤 것도 변경하기 전에, 제한적이고 중립적인 디렉터리인 pnpm root -g, pnpm bin -g, 그리고 pnpm list -g --depth 0 --json 호출을 사용하여 활성 패키지와 전역 루트의 소유권을 재확인합니다. 이 명령어는 pnpm 9–11의 <list-root>/node_modules 루트와 pnpm 12의 <list-root> 루트만 허용합니다. 그런 다음, 기본 레지스트리와 @codemem 레지스트리 고정(pin)을 사용하여 정확히 일치하는 패키지를 설치하고, 등록된 패키지 상태와 특정 pnpm-bin 런처를 검증합니다. 업데이트기는 절대 빌드 승인 명령(build-approval command)을 실행하지 않습니다: pnpm 9는 여전히 기본적으로 install 스크립트를 실행하지만, 더 최신 pnpm 릴리스들은 구성된 build-script 정책을 적용합니다. mise으로 관리되는 CLI의 경우, codemem update check는 정확한 전역 업데이트 명령을 보고합니다. 명시적인 codemem update install은 제한적인 mise ls --json 출력으로부터 활성 도구 소스가 사용자의 홈 디렉터리 내에 있는 전역 소스와 일치하며, 그 설치 경로가 실행 중인 엔트리를 소유하고 있음을 확인합니다. 이는 정확한 릴리스를 mise의 기본 전역 설정(config)에 기록하고, 전역으로 구성된 버전을 확인하며, 호출하는 프로젝트를 통하지 않고 mise exec을 통해 구성된 도구를 실행하여, 잠재적으로 오래되었거나 로컬에서 재정의된 PATH 엔트리를 우회합니다.
내구성이 뛰어난 CLI를 설치한 패키지 관리자를 통해 업그레이드하고, 기존에 설정된 통합을 위해 해당 설정 명령어를 다시 실행하세요. Setup은 이전의 관리형 npx -y codemem mcp 런처와 UV/UVX 기반으로 감지된 codemem MCP 항목을 대체하여 두 패키지가 하나의 런타임(runtime)을 공유하게 됩니다. 다른 사용자 지정 MCP 명령어는 변경되지 않습니다. 호스트 플러그인은 독립적으로 관리됩니다. Claude 마켓플레이스 설치는 플러그인에 번들된 MCP 구성을 사용하므로 별도의 setup --claude-only 단계가 필요하지 않습니다.
생성된 MCP 구성은 전역 codemem 바이너리가 사용 가능할 때 이를 사용합니다. 그렇지 않은 경우, setup 관리형 npx 런처는 두 패키지를 하나의 임시 환경에서 요청합니다. 설치 변경 후에는 업데이트된 호스트와 모든 codemem serve 프로세스를 재시작해야 합니다. 이미 실행 중인 Claude 또는 Codex MCP 호스트는 재시작할 때까지 어휘(lexical) 기반의 검색만 유지하며, codemem serve를 재시작한다고 해서 해당 자식 프로세스가 재시작되는 것은 아닙니다.
의미론적 런타임(semantic runtime)은 모든 플랫폼에서 CPU 추론에 고정됩니다. ONNX Runtime 1.24.3은 macOS x64 바이너리를 제공하지 않기 때문에, 인텔 Mac은 의미론적 런타임 초기화 실패 시 FTS5 키워드 검색을 계속 사용합니다.
</details>
<details>
<summary>OpenCode 검색 및 소스 체크아웃 세부 정보</summary>
OpenCode 플러그인과 CLI가 의도적으로 분리되었습니다:
@codemem/opencode-plugin — OpenCode 플러그인 패키지codemem — CLI 및 MCP 명령어@codemem/embeddings — CLI에 의해 설치되는 선택적 의미론적 임베딩 런타임
OpenCode는 구성된 npm 플러그인과 checkout-local .opencode/plugins/ 파일을 별도의 소스로 취급합니다. 리포지토리 래퍼는 OpenCode 1에서는 checkout 소스를 로드하고, OpenCode 2에서는 아무 작업도 하지 않습니다(no-op). OpenCode 1 소스 변경 사항을 dogfooding하기 전에, 임시로 구성된 npm 플러그인을 제거하여 checkout 래퍼 이전에 초기화되지 못하게 한 다음; 테스트 후에는 npm 항목을 복원하십시오. OpenCode 2에서는 구성된 npm 플러그인이 유일한 활성 Codemem 인스턴스로 남아 패키지의 ./tui 컴패니언을 로드하며, 이는 서버 플러그인에서 방출되는 주입(injection), 호환성(compatibility), 지속성(persistence), 업데이트 알림을 표시합니다. 이러한 알림은 최선의 노력(best-effort)이며 캡처나 리콜에 영향을 미치지 않습니다.
소스 checkout에서 게시되지 않은 TUI 변경 사항을 dogfooding할 때는, 해당 checkout의 packages/opencode-plugin 디렉터리를 OpenCode 2의 cli.json plugins 목록에 추가하고, 구성된 npm 플러그인을 임시로 제거한 다음, TUI를 재시작하고 테스트 후 npm 항목을 복원하십시오.
OpenCode 2 지원에는 스토리지 변경이 필요하지 않습니다. 두 호스트 모두 동일한 raw-event 스트림과 SQLite 데이터베이스를 작성하므로, OpenCode 1과 OpenCode 2 간 전환이나 OpenCode 2 환경에서 CODEMEM_PLUGIN_IGNORE=1을 설정하여 V2 경로를 중지하는 것은 데이터베이스 마이그레이션이 필요하지 않습니다.
캡처는 OpenCode 1.18.29 런타임 계약을 따릅니다: 완료된 어시스턴트 메시지는 info.time.completed를 사용하고, 토큰 사용량은 info.tokens에서 가져오며, 성공 및 실패한 도구 실행 모두 기록됩니다. OpenCode는 tool.execute.after를 통해 성공적인 도구를, 오류가 발생한(errored) tool 파트를 통해 실패한 도구를 보고하며; Codemem은 반복되는 실패 업데이트 없이 둘 다 공유 raw-event 스트림으로 정규화합니다.
