flowchart TD
    A[

- `identity.md` — 에이전트의 정체성(who the agent is)
- `remember.md` — 이전 세션에서 전달된 인계 메모(handoff note from the last session)
- `now.md` — 현재 세션 버퍼(current session buffer)
- `today-*.md` — 오늘 날짜의 압축 기록(today's compressed history)
- `recent.md` — 지난 7일간의 기록(last 7 days)
- `archive.md` — 더 오래된 기록(older history)
- `archive-YYYY-MM-DD.md` / `recent-YYYY-MM-DD.md` — 이전에 너무 커졌거나 최근 기간에 걸쳐 회전된 슬라이스입니다. 세션 시작 시 이름이 지정되고 검색할 수 있지만, 컨텍스트로 주입되지는 않습니다.

수동 프롬프팅이나 "이 파일을 읽어라"와 같은 지침은 없습니다. 에이전트는 매 세션을 시작할 때 메모리가 이미 로드된 상태로 시작합니다. 그저 기억할 뿐입니다.

압축(compaction)을 거친 후에는 `identity.md`만 재주입되며, 나머지는 이미 전달되었습니다. 스토어에 대한 작성 규칙은 [docs/how-memory-files-are-written.md](docs/how-memory-files-are-written.md)를 참조하십시오.

## 같은 작업실에서 나온 것들

네 개의 플러그인, 하나의 팀이 각기 다른 역할을 수행합니다. 이 플러그인과 세 명의 형제들이 있습니다:

- [claude-jit-context](https://github.com/Digital-Process-Tools/claude-jit-context): 프롬프트, 파일 또는 도구가 일치할 때만 로드되는 프로젝트 지식입니다.
- [claude-supertool](https://github.com/Digital-Process-Tools/claude-supertool): 배치(batched) 파일 및 추적기 작업을 수행합니다. 7번의 호출 대신 한 번의 호출로, 잘못된 답변 대신 거절을 유도합니다.
- [claude-oss](https://github.com/Digital-Process-Tools/claude-oss): 이 네 개의 리포지토리를 관리하는 루프입니다. 트리아지(Triage), 빌드, 검토, 병합, 릴리스를 담당합니다.

네 가지 플러그인 모두 하나의 마켓플레이스에서 설치할 수 있습니다: `/plugin marketplace add Digital-Process-Tools/claude-marketplace`.

가끔 `SessionStart`는 사용자가 아직 설치하지 않은 `claude-supertool` 또는 `claude-jit-context` 중 하나를 단일 `systemMessage` 라인에 기록합니다. 이 메시지는 모델이 직접 볼 수 있는 것이 아닙니다. 이미 `~/.claude/plugins/installed_plugins.json`에 있는 플러그인에 대해서는 언급하지 않으며, `config.json`에서 `"features": {"plugin_promos": false}`로 설정하면 완전히 중단됩니다: [설정 방법](#configuring-it) 참조. 이 라인은 `claude-remember:`로 시작하고 해당 키로 끝나기 때문에, 누가 말했는지와 이를 멈추는 방법을 모두 메시지를 통해 알 수 있으며, 단순히 여기에서만 알 수 있는 것은 아닙니다 ([#631](https://github.com/Digital-Process-Tools/claude-remember/issues/631)).

## 설치 (Install)

**Claude Code**

이후 Claude Code를 재시작해야 합니다. 훅(hooks)은 세션 시작 시 읽어지기 때문입니다 ([#200](https://github.com/Digital-Process-Tools/claude-remember/issues/200)). 업데이트하려면 공식 Anthropic 마켓플레이스와 그 지연 시간, 수동 설치 및 버전을 확인하는 방법이 있습니다: [docs/install-claude-code.md](docs/install-claude-code.md).

**Codex**

`codex-cli 0.150.1`에서 작동하는 것을 확인했습니다. 과정에서 발견된 내용은 다음과 같습니다: [docs/install-codex.md](docs/install-codex.md).

**Antigravity CLI (`agy`)**

`agy` 1.1.27에서 작동하는 것을 확인했습니다: 이 경우, 캡처는 문서에 근거한 것이 아니라 실제 `agy` 프로세스를 대상으로 종단 간(end to end)으로 구동되었습니다. Antigravity는 플러그인별 매니페스트가 없습니다 -- `agy plugin install`은 플러그인 자체의 `hooks.json`을 복사하고, 이를 계산하며, 플러그인을 활성화된 것으로 표시하지만 실제로 로드하지 않습니다 ([#553](https://github.com/Digital-Process-Tools/claude-remember/issues/553)) -- 따라서 설치 프로그램은 공유되는 `~/.gemini/config/hooks.json`에 `remember` 항목을 병합하며, 이미 존재하는 다른 모든 플러그인의 항목들은 그대로 유지됩니다.

**호스트를 선택하기 전에 알아야 할 점:** 확인된 네 가지 Antigravity 이벤트 중 어느 것도 프로세스 종료 신호가 아니기 때문에, `SessionEnd`와 같은 개념이나 대화 끝에 마지막으로 데이터를 비우는(flush) 과정이 없습니다. `Stop`은 매 턴마다 발생하며 의도적으로 `session-end-hook.sh`에 연결되지 않습니다. 이로 인해 발생하는 비용, 파싱 실패 시 조용히 처리되는 이름 기반 스키마, 그리고 포팅 과정에서 발견된 세 가지 실제 결함(live defects)을 참고하세요: [docs/install-antigravity.md](docs/install-antigravity.md).

## 요구 사항 (Requirements)

- Python 3.9 이상
- Haiku 접근 권한이 있는 Claude CLI (`claude`)
- Bash 3.2 이상 (기본 macOS bash 사용 가능)
- `jq` 및 표준 coreutils, macOS와 Linux에 사전 설치됨

### Windows

`PATH`에 POSIX 셸이 필요합니다: Git Bash / MSYS2에 `jq` 및 `python3`가 설치되었거나 WSL을 사용해야 합니다. OS 배지는 플랫폼의 커버리지를 나타내는 것이 아니라 그저 플랫폼 자체를 나타냅니다; 대부분의 기능은 여전히 `win32`에서 건너뜁니다 ([#497](https://github.com/Digital-Process-Tools/claude-remember/issues/497)). 지금까지 발견된 모든 실제 Windows 결함은 실제 기기의 사용자에 의해 보고되었으며, 이러한 보고서가 우선순위를 가집니다. 알려진 함정(Known traps): [docs/windows.md](docs/windows.md).

## 비용 (Cost)

이 파이프라인은 요약 및 압축을 위해 Claude Haiku를 사용합니다. Haiku는 가장 작고 저렴한 Claude 모델입니다. 일반적인 세션 저장에는 **$0.01 미만**의 비용이 발생합니다 — 몇 천 개의 입력 토큰(세션 교환)과 몇 백 개의 출력 토큰(요약). 일일 압축 및 통합 작업은 추가적인 Haiku 호출을 발생시킵니다.

실제로는 하루 종일 실행해도 **하루에 몇 센트**의 비용이 듭니다. Claude CLI가 사용하는 Anthropic API 키는 호출에 사용되는 키와 동일하므로 별도의 청구(billing)가 없습니다.

## 사용 방법 (Using it)

설치 후에는 실행할 것이 없습니다. 알아두면 좋은 두 가지 명령어가 있습니다.

### 세션 간 인계 (`/remember`)

컨텍스트를 지우거나 세션을 종료하기 전에 `/remember`를 입력합니다. 에이전트가 짧은 인계 메모(handoff note)를 작성하고, 다음 세션에서 이 메모를 로드하여 시작합니다. 전달 횟수 계산 및 하나의 스토어에 두 개의 세션을 저장하는 방법에 대해서는 [docs/handoff.md](docs/handoff.md)를 참조하세요.

### 진단 (Diagnostics) (`/remember:doctor`)

메모리가 나타나지 않거나 이유를 알 수 없을 때 실행하세요. 이 명령어는 해결된 경로, 저장 모드, 그리고 각 훅이 해당 프로젝트에서 발동되었는지 여부를 출력합니다. JSON 형식의 출력과 통합(consolidation) 제한에 대해서는 [docs/diagnostics.md](docs/diagnostics.md)를 참고하세요.

### 훅 (Hooks)

| Claude Code / Codex | Antigravity | Script | 목적 (Purpose) |
| :--- | :--- | :--- | :--- |
| `SessionStart` | `SessionStart` | `session-start-hook.sh` | 메모리를 컨텍스트에 로드하고 누락된 세션을 복구합니다. |
| ... | | | |

Antigravity의 `Stop`은 종료(teardown)가 아니라 턴 경계(turn boundary)이기 때문에, `session-end-hook.sh` 대신 자체 어댑터에 연결됩니다. 위의 행은 이로 인해 생기는 공백입니다.

각 항목이 무엇을 건너뛰고 왜 건너뛰는지, `hooks.d/` 리스너 계약(listener contract), 그리고 왜 `SessionEnd`가 핸드오프를 기록하지 않는지에 대해서는 [docs/hooks.md](docs/hooks.md)를 참고하세요.

## 설정 (Configuring it)

기본값은 플러그인 내부의 `config.json`에 있습니다. 이 기본값을 각 기계에서 `~/.remember/config.json`으로, 프로젝트별로 `<REMEMBER_DIR>/config.json`으로 덮어쓸 수 있습니다. 모든 키, 그 기본값, 그리고 무엇이 이를 읽는지에 대해서는 [docs/configuration.md](docs/configuration.md)를 참고하세요. 메모리를 프로젝트 트리가 아닌 `~/.remember/<slug>/`에 외부 저장 모드(external storage mode)로 유지하려면: [docs/external-storage-mode.md](docs/external-storage-mode.md). 스토어를 사용자가 소유한 git 원격 저장소에 백업하려면: [docs/git-backup-security.md](docs/git-backup-security.md).

## 데이터 파일 (Data files)

모든 것은 `REMEMBER_DIR`에 저장됩니다: 기본적으로 프로젝트 내의 `.remember/`, 또는 [외부 저장 모드](docs/external-storage-mode.md)에서는 `~/.remember/<slug>/`입니다.

| 파일 | 목적 | 
| :--- | :--- |
| `now.md` | 현재 세션 버퍼 | 
| ... | |

세션별 핸드오프 파일, 세션 인덱스, 그리고 임시 파일이 담긴 `tmp/`에 대해서는 [docs/data-files.md](docs/data-files.md)를 참고하세요.

## 신뢰 모델 (Trust Model)

이 플러그인은 다른 코딩 에이전트의 훅(hook)과 마찬가지로 전체 셸 권한으로 실행됩니다. **기본 설치** 시 메모리는 로컬에 `<project>/.remember/` (또는 외부 모드에서 `~/.remember/<slug>/`) 아래 저장되며, 어떠한 내용도 외부에 전송하지 않습니다. 따라서 코딩 에이전트 자체를 넘어서는 새로운 공격 표면은 없습니다.

**Git 백업** 기능은 외부 스토어의 상위 디렉터리가 원격 저장소(upstream)를 가진 git 리포지토리인 경우, 메모리를 커밋하고 (그리고 만약 원격이 있다면 푸시합니다). 별도의 활성화 플래그는 없으며, 이 조건 자체가 트리거가 됩니다. 전체 위협 모델은 [`docs/git-backup-security.md`](docs/git-backup-security.md)를 읽어보세요. 요약하자면: `~/.remember/` 디렉터리를 `~/.ssh/`에 부여하는 것과 같은 주의를 기울이고, 백업 대상을 본인이 소유한 리포지토리에 지정하며, 내장된 원격 URL 검증이 나머지를 처리합니다.

### 이 플러그인이 실행하고, 전송하고, 저장하는 것들

**요약(Summarization)** 기능은 이미 설치되어 인증된 CLI를 호출하며 — 번들링된 바이너리는 절대 아니며, 해당 CLI가 이미 통신하는 서비스를 넘어서는 제3자 서비스도 아닙니다:

* `REMEMBER_SUMMARIZER`는 제공자를 선택합니다: `claude` (중첩된 `claude -p`), `codex` (중첩된 `codex exec`), 또는 `auto` (기본값 — 호스트가 실제로 작성한 트랜스크립트를 읽어 하나를 선택). `REMEMBER_SUMMARIZER_FALLBACK=claude` (선택적 활성화, 기본적으로 설정되지 않음)은 실패한 `codex` 호출을 경고를 발생시키는 대신 `claude -p`를 통해 재시도하며, 실행될 때마다 기록합니다.
* `claude -p`는 도구(`--tools ""`) 없음, MCP 서버(`--mcp-config '{}' --strict-mcp-config`) 없음, 후크(`--setting-sources ''`) 없음, 그리고 공유되는 임시 작업 디렉토리(다른 동시 저장 작업이 사용하는)가 아닌 격리된 임시 작업 디렉토리를 사용하여 실행됩니다. claude-code 2.1.219를 기준으로 검증되었습니다.
* `codex exec`는 `--sandbox read-only` (프로세스 자체에 쓰기 및 네트워크 접근을 거부함 — 모델이 이 샌드박스 내에서 실행하도록 요청하는 명령어에 대한 보장은 아님), `--ignore-user-config` (운영자 자신의 Codex 후크를 건너뜀), 그리고 `-c shell_environment_policy.inherit=none` (Codex가 내부적으로 생성하는 명령어는 환경 변수 자체가 전혀 없어, 심지어 `PATH`도 없음)를 사용하여 실행됩니다. codex-cli 0.150.1 / 0.153.2를 기준으로 검증되었습니다.
* 두 경로 모두 추출되고 필터링된 세션 트랜스크립트(해당 저장 작업을 위해 구축된 프롬프트)만을 해당 CLI의 구성된 제공자에게 전송하며, 다른 서비스에는 절대 전송하지 않습니다.

**자격 증명.** 요약기는 환경을 상속받는 중첩된 `claude -p`를 실행하며, 여기에는 Claude Code 로그인 정보가 포함됩니다 — 이는 후크가 시작하는 모든 프로세스와 정확히 같습니다. 중첩된 `codex exec`는 자격 증명을 명시하지 않는 변수들의 허용 목록(allow-list)만 받습니다. remember 자체는 어떤 자격 증명도 읽지 않습니다: 아무것도 입력되지 않고, OS 자격 증명 저장소에서 아무것도 읽히지 않으며, 플러그인은 어느 곳에서도 로그인 정보를 요청하지 않습니다.