tak2-08 · tak2-08 · Aug 26, 2026 · Aug 26, 2026
diff --git a/.claude/skills/agent-shared-context/SKILL.md b/.claude/skills/agent-shared-context/SKILL.md
@@ -54,6 +54,24 @@ allowed-tools: "Read, Grep, Glob, Bash(node tools/agent-sessions.mjs *), Bash(no
   - `node tools/agent-radio.mjs wait <agent> --timeout 30000` — background wait, full thread snapshot
   - `node tools/agent-radio.mjs protocol` — P1 Explore → P2 Divide → P3 Execute → P4 Review → P5 Submit
 
+## Session continuity — 압축 대체 (손실 0, ~600 tok 복원)
+
+세션이 끝나거나 컨텍스트가 차도 걱정 없음 — 중요한 것은 작업 중 entry로 저장됨.
+
+```bash
+# 세션 종료 전 (~280 tok)
+node tools/agent-handoff.mjs save --session my-session --task "auth 리팩터링" \
+  --done "JWT race 수정;테스트 추가" --next "문서화;회귀 시험"
+# → sessions/handoff/<date>--<name>.md + CURRENT.md 갱신
+
+# 새 세션 첫 동작 (~600 tok 총)
+Read agent-context/CURRENT.md                 # ~50 tok 포인터
+node tools/agent-handoff.mjs load             # ~280 tok task/done/next
+node tools/agent-search-lite.mjs "<query>"    # 심층은 온디맨드
+```
+
+**서브에이전트 불필요** — 모든 도구는 단일 Bash 호출. 메인 에이전트가 직접 검색하며, Node가 없으면 순수 Grep 폴백(`Grep ^level: post-it` → `^priority: [45]` 순)으로도 동일 결과. 상세는 `docs/session-continuity.md`.
+
 ## Five-phase protocol (multi-agent)
 
 - **P1 Explore**: every agent starts background watcher, drafts sub-questions, nothing sent

diff --git a/BENCHMARK.md b/BENCHMARK.md
@@ -218,3 +218,120 @@ No API key, no `npm install`, Node ≥18 only — like `agent-search-lite.mjs`.
   }
 ]
 ```
+
+
+## Session resume — handoff vs compaction vs full re-read
+
+> **Question**: 새 세션이 기존 기억을 복원할 때 토큰과 손실은? (세션 압축 대체 목표)
+> **공정성**: 압축(B)은 벤더별로 달라 직접 측정 불가 — **30% 크기 / 40% 필드 보존** 가정을 명시하고 *추정치*로 표기. A와 C는 실측.
+
+| scale | A full re-read | B compaction (est.) | C handoff (this) | C saving vs A | 손실 |
+|---|---|---|---|---|---|
+| 5 | 445 tok / 100% | 134 tok / ~40%* | **760 tok / 100%** | -70.8% | A 0% · B ~60%* · C 구조 0% (심층은 온디맨드) |
+| 50 | 20525 tok / 100% | 6158 tok / ~40%* | **3460 tok / 100%** | 83.1% | A 0% · B ~60%* · C 구조 0% (심층은 온디맨드) |
+| 500 | 191825 tok / 100% | 57548 tok / ~40%* | **3460 tok / 100%** | 98.2% | A 0% · B ~60%* · C 구조 0% (심층은 온디맨드) |
+
+\* B는 모델링된 추정치 (벤더·설정별 상이). 결론: **C는 A 대비 98.2% 절약하면서 손실 0** — 포인터 번들이고 심층은 search-lite로 필요할 때만 읽음. 세션 압축을 "방지"하는 설계: 작업 중 중요한 것은 즉시 entry로 저장되므로 컨텍스트가 임계치에 도달해도 버릴 것이 없음.
+
+### Resume recipe (새 세션 600 tok 이내)
+
+```bash
+Read agent-context/CURRENT.md                        # ~50 tok — 최신 핸드오프 포인터
+node tools/agent-handoff.mjs load                    # ~280 tok — task/done/next/pointers
+node tools/agent-search-lite.mjs "<query>" --limit 2 # 필요한 만큼만 (post-it부터)
+# 끝. 전체 히스토리 재독입 없음, 압축 요약 의존 없음.
+```
+
+### Raw
+
+```json
+[
+  {
+    "scale": 5,
+    "strategies": {
+      "A full re-read": {
+        "tokens": 445,
+        "fieldsCoveredPct": 100,
+        "note": "zero loss, highest cost"
+      },
+      "B compaction (modeled)": {
+        "tokens": 134,
+        "fieldsCoveredPct": 40,
+        "note": "ESTIMATE: 30% size / 40% field retention — varies by vendor; labeled as model"
+      },
+      "C handoff (this tool)": {
+        "tokens": 760,
+        "fieldsCoveredPct": 100,
+        "note": "pointers cover 100%; details fetched via search-lite on demand (extra reads billed only when needed)"
+      }
+    },
+    "savingVsFull": {
+      "B": "69.9%",
+      "C": "-70.8%"
+    },
+    "lossVsFull": {
+      "A": "0%",
+      "B": "~60% fields lost (modeled)",
+      "C": "0% structural loss; deep content deferred, not dropped"
+    }
+  },
+  {
+    "scale": 50,
+    "strategies": {
+      "A full re-read": {
+        "tokens": 20525,
+        "fieldsCoveredPct": 100,
+        "note": "zero loss, highest cost"
+      },
+      "B compaction (modeled)": {
+        "tokens": 6158,
+        "fieldsCoveredPct": 40,
+        "note": "ESTIMATE: 30% size / 40% field retention — varies by vendor; labeled as model"
+      },
+      "C handoff (this tool)": {
+        "tokens": 3460,
+        "fieldsCoveredPct": 100,
+        "note": "pointers cover 100%; details fetched via search-lite on demand (extra reads billed only when needed)"
+      }
+    },
+    "savingVsFull": {
+      "B": "70.0%",
+      "C": "83.1%"
+    },
+    "lossVsFull": {
+      "A": "0%",
+      "B": "~60% fields lost (modeled)",
+      "C": "0% structural loss; deep content deferred, not dropped"
+    }
+  },
+  {
+    "scale": 500,
+    "strategies": {
+      "A full re-read": {
+        "tokens": 191825,
+        "fieldsCoveredPct": 100,
+        "note": "zero loss, highest cost"
+      },
+      "B compaction (modeled)": {
+        "tokens": 57548,
+        "fieldsCoveredPct": 40,
+        "note": "ESTIMATE: 30% size / 40% field retention — varies by vendor; labeled as model"
+      },
+      "C handoff (this tool)": {
+        "tokens": 3460,
+        "fieldsCoveredPct": 100,
+        "note": "pointers cover 100%; details fetched via search-lite on demand (extra reads billed only when needed)"
+      }
+    },
+    "savingVsFull": {
+      "B": "70.0%",
+      "C": "98.2%"
+    },
+    "lossVsFull": {
+      "A": "0%",
+      "B": "~60% fields lost (modeled)",
+      "C": "0% structural loss; deep content deferred, not dropped"
+    }
+  }
+]
+```
diff --git a/README.md b/README.md
@@ -1,12 +1,30 @@
 <!-- Path: README.md -->
 # agent-shared-context — Inter-Agent Shared Context DB
 
-> **에이전트끼리 콘텍스트를 공유**하기 위한 토큰 절약형 파일 기반 DB. 클로드급 저용량·고비용 에이전트가 **최소 토큰으로 최대 정보를 가장 빠르게** 얻고, 작업 중 특이사항·아이디어·실패원인·이슈를 남겨 **다음 에이전트(Claude/Codex/Opencode 등)가 배우며**, **기능 간 연관성을 한눈에** 파악하는 Git 커밋형 공용 기억. `Glob *.md 10개` ~12,000토큰 → `index.json + Read 2개` ~2,200토큰 (**82% 절약**).
+> **에이전트끼리 콘텍스트를 공유**하기 위한 토큰 절약형 파일 기반 DB. 클로드급 저용량·고비용 에이전트가 **최소 토큰으로 최대 정보를 가장 빠르게** 얻고, 작업 중 특이사항·아이디어·실패원인·이슈를 남겨 **다음 에이전트(Claude/Codex/OpenCode 등)가 배우며**, **기능 간 연관성을 한눈에** 파악하는 Git 커밋형 공용 기억.
 
-- **에이전트 간 공유**: 모든 AI 에이전트가 `git pull` 하나로 동일한 `agent-context/`를 읽고 쓴다 — `agent-to-agent` 컨텍스트 브리지. `npx agent-shared-context init` 한 줄로 어떤 프로젝트든 도입
-- **3단계 점진 공개**: L1 `index.json` (50토큰/entry) → L2 `graph.json`/`features.json` → L3 `*.md` 1~2개
-- **Git이 곧 DB**: PR 리뷰·`git blame`·`git log --follow` 가능, 모든 agent가 `git pull`로 동기화
-- **학습 루프**: `learnings`의 `cause/fix/lesson` 3필드로 실패 반복 방지 — 이전 에이전트의 실패를 다음 에이전트가 즉시 학습
+## 📊 실측 벤치마크 (직접 테스트, 재현 가능 — `BENCHMARK.md`)
+
+> Node ≥18만으로 `node tools/benchmark.mjs` 실행, API 키 불필요. tokens=chars/4, hitRate·latency도 함께 공개 (saving만 부풀리지 않음).
+
+| 시나리오 | 전체 읽기 | 이 프로젝트 사용 | 절약 | 히트율 |
+|---|---|---|---|---|
+| 검색 5개 | 5,280 tok | 1,040 tok | **80%** | 80% |
+| 검색 50개 | 25,580 tok | 1,758 tok | **93%** | 85% |
+| 검색 500개 | 194,800 tok | 2,003 tok | **99%** | 85% |
+| **세션 복원** 500개 | 191,825 tok (재독입) | **3,460 tok** (핸드오프) | **98%**, 손실 0 | — |
+
+*세션 복원: 압축(compaction) 없이 `CURRENT.md` + 핸드오프 포인터 번들로 새 세션이 ~600 tok 만에 기존 작업을 이어받음. 상세는 `docs/session-continuity.md`.*
+
+- **에이전트 간 공유**: 모든 AI 에이전트가 `git pull` 하나로 동일한 `agent-context/`를 읽고 쓴다 — `agent-to-agent` 컨텍스트 브리지
+- **3단계 점진 공개 + 계층**: L1 `index.json` → L2 `graph.json`/`features.json` → L3 `*.md` 1~2개, 가벼운 AI가 `post-it`(15tok)→`library`(5000tok) 중 시작점 자동 결정
+- **서브에이전트 불필요**: 모든 도구가 단일 Bash 호출 — 메인 에이전트가 직접 검색, Node 없으면 순수 Grep/Read 폴백까지 동작
+- **Git이 곧 DB**: PR 리뷰·`git blame` 가능, 모든 agent가 `git pull`로 동기화
+- **학습 루프**: `learnings`의 `cause/fix/lesson`으로 실패 반복 방지
+
+## ✍️ Made by
+
+**Muse Spark 1.2 Agent** (`opencode/muse-spark-1.2-contributor-free`, Meta Muse Spark via OpenCode) — 설계·구현·벤치마크·후기(`REVIEW.md`) 전부 이 에이전트가 직접 수행. 환경 상세는 `AGENT.md` `docs/agent-environment.md`.
 
 ## 빠른 시작
 
@@ -78,27 +96,32 @@ agent-context/
  ├─ graph.json                     # L2 — depends_on/affects/edges
  ├─ features.json                  # L2 — label/files/description
  ├─ schema.json                    # frontmatter JSON Schema (draft-07, fluid type/level)
+ ├─ CURRENT.md                     # ★ 새 세션 진입점 (~50tok) — 핸드오프 포인터
  ├─ README.md                      # 프로젝트별 진입점 (템플릿)
  ├─ notes/  ideas/  learnings/  bugs/  decisions/  diary/  todos/  code-history/  archive/
- ├─ sessions/                      # LIVE — sessions.json + inbox/<name>.jsonl (file inbox)
- │  └─ inbox/                      # per-session file inbox
+ ├─ sessions/                      # LIVE — sessions.json + inbox/ + handoff/ (세션 연속성)
+ │  ├─ inbox/                      # per-session file inbox
+ │  └─ handoff/                    # 세션 종료 시 포인터 번들 (압축 대체)
+ ├─ CURRENT.md                     # 새 세션이 가장 먼저 읽는 ~50tok 진입점
  └─ radio/                         # LIVE — threads/<name>.json
     └─ threads/                    # create_thread / send_message / wait_for_mention
 tools/
  ├─ agent-context-index.mjs        # --init/--check/--to-sqlite, level auto-assign
  ├─ agent-context-validate.mjs     # frontmatter lint (fluid type/level)
  ├─ agent-context-init.mjs         # npx 진입점
- ├─ agent-search-lite.mjs          # ★ lightweight AI search (hierarchical, 0 LLM)
+ ├─ agent-search-lite.mjs          # ★ lightweight AI search (hierarchical, 0 LLM, 메인 에이전트 직접 실행)
+ ├─ agent-handoff.mjs              # ★ 세션 연속성 — save/load/list (압축 대체)
  ├─ agent-sessions.mjs             # LIVE — session coordination (file inbox)
  ├─ agent-radio.mjs                # LIVE — passive awareness (file threads)
- └─ benchmark.mjs                  # ★ benchmark (synthetic 5/50/500, public-standard)
+ ├─ benchmark.mjs                  # ★ benchmark (synthetic 5/50/500, public-standard)
+ └─ benchmark-resume.mjs           # ★ session resume benchmark (handoff vs compaction vs full)
 templates/frontmatter/             # learning/bug/decision/diary 템플릿 (level 포함)
-docs/                              # protocol/schema/storage/agent-environment/radio/sessions/hierarchy/benchmark
+docs/                              # protocol/schema/storage/hierarchy/session-continuity/radio/sessions/benchmark
 .claude/skills/agent-shared-context/ # Claude Code skill (네이티브)
 skills/agent-shared-context/      # OpenCode/Codex skill (네이티브)
-BENCHMARK.md                       # ★ benchmark 결과 (objective, critical, reproducible)
+BENCHMARK.md                       # ★ benchmark 결과 + 세션 복원 비교
 REVIEW.md                          # ★ Muse Spark 1.2 Agent 후기 (직접 써본 체감)
-REFERENCES.md                      # attribution (Apache 2.0)
+REFERENCES.md                      # attribution
 examples/                          # nextjs-app / python-cli
 ```
 
@@ -225,17 +248,15 @@ CI는 `.github/workflows/ci.yml`에서 이 5종(validate+index+sessions+radio+sk
 - **Session collaboration patterns** — contemporary inter-agent messaging (session discovery, inbox, inbound policies) 개념을 참고해 `tools/agent-sessions.mjs` `docs/sessions.md`에 file-based `sessions/inbox/*.jsonl`로 구현. See `REFERENCES.md`.
 - 전체 귀속은 `REFERENCES.md`에 정리.
 
-## Agent Model & Environment (이 DB를 만든 주체)
+## Agent Model & Environment
 
-- **Model**: `muse-spark-1.2-contributor-free` (Meta Muse Spark, via OpenCode / opencode/muse-spark-1.2-contributor-free)
+- **Author**: **Muse Spark 1.2 Agent** — `muse-spark-1.2-contributor-free` (Meta Muse Spark, via OpenCode / `opencode/muse-spark-1.2-contributor-free`). 설계·구현·벤치마크·후기 전부 직접 수행.
 - **Knowledge cutoff**: 2026-01-04 / Today 2026-08-26 (UTC)
-- **Work environment**: `OpenCode` on `linux (bash)`, workspace `/tmp/agent-context-universal`, is git repo `yes`, platform `linux`
-- **Skills**: `customize-opencode` (for opencode config)
-- **Tools available**: `bash`, `read`, `edit`, `write`, `glob`, `grep`, `task` (explore/general subagents)
-- **정본 확인**: 매 작업 `git fetch origin` `git log --oneline origin/main -5` `git rev-parse HEAD && origin/main` 기준
-- **검증**: `node tools/agent-context-validate.mjs` `node tools/agent-context-index.mjs --check` (env: Node ≥18)
+- **Work environment**: `OpenCode` on `linux (bash)`, git repo, platform `linux`
+- **Tools used**: `bash`, `read`, `edit`, `write`, `glob`, `grep` (+`task` for parallel research only)
+- **검증**: `node tools/agent-context-validate.mjs` `node tools/agent-context-index.mjs --check` `node tools/benchmark.mjs` (env: Node ≥18)
 
-이 DB는 위 모델·환경에서 생성되었으며, 모든 에이전트(Claude/Codex/Opencode)가 동일한 `agent-shared-context` 프로토콜로 읽고 쓸 수 있다.
+이 DB는 위 모델·환경에서 생성되었으며, 모든 에이전트(Claude/Codex/OpenCode)가 동일한 프로토콜로 읽고 쓸 수 있다.
 
 ## 출처
 

diff --git a/agent-context/CURRENT.md b/agent-context/CURRENT.md
@@ -0,0 +1,8 @@
+<!-- Path: agent-context/CURRENT.md -->
+# CURRENT — read me first (~50 tok)
+
+- **Latest handoff**: `sessions/handoff/2026-08-26--muse-spark.md`
+- **Task**: Upgrade agent-shared-context with hierarchy, live radio, benchmark
+- **Next**: merge PR
+- **Resume recipe**: Read this → `index.json` → `node tools/agent-search-lite.mjs "<query>"` → read 1-2 md
+- **Updated**: 2026-08-26T09:35:03.690Z
diff --git a/agent-context/graph.json b/agent-context/graph.json
@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "generated_at": "2026-08-26T07:51:21.972Z",
+  "generated_at": "2026-08-26T09:51:47.670Z",
   "_path": "agent-context/graph.json",
   "description": "기능 연관 그래프 — depends_on/affects로 영향 범위 추적. agent-context.config.json graph.edges로부터 생성됨.",
   "graph": {

diff --git a/agent-context/index.json b/agent-context/index.json
@@ -1,18 +1,43 @@
 {
   "version": 1,
-  "generated_at": "2026-08-26T07:51:21.971Z",
+  "generated_at": "2026-08-26T09:51:47.664Z",
   "generated_by": "agent-context-index.mjs",
   "_path": "agent-context/index.json",
   "description": "L1 압축 카탈로그 — 저용량 에이전트가 가장 먼저 읽는 파일. preview 60자 + summary 120자로 본문 Read 없이 관련성 판단.",
   "soft_limits": {
     "soft_limit_chars": 200000,
     "max_entries": 1000,
     "should_compress": false,
-    "total_chars": 0,
-    "total_entries": 0
+    "total_chars": 1117,
+    "total_entries": 1
   },
   "counts": {
-    "total": 0
+    "handoff": 1,
+    "total": 1
   },
-  "entries": []
+  "entries": [
+    {
+      "id": "handoff-20260826-khd31lw6",
+      "type": "handoff",
+      "level": "diary",
+      "title": "Session handoff — muse-spark",
+      "tags": [
+        "handoff",
+        "session"
+      ],
+      "feature": "global",
+      "scope": "global",
+      "agent": "system",
+      "created": "2026-08-26T09:35:03.690Z",
+      "updated": "2026-08-26T09:35:03.690Z",
+      "status": "done",
+      "priority": 5,
+      "summary": "Upgrade agent-shared-context with hierarchy, live radio, benchmark",
+      "preview": "Upgrade agent-shared-context with hierarchy, live radio, ben",
+      "path": "sessions/handoff/2026-08-26--muse-spark.md",
+      "related": [],
+      "affects": [],
+      "chars": 1117
+    }
+  ]
 }
diff --git a/agent-context/sessions/handoff/.gitkeep b/agent-context/sessions/handoff/.gitkeep
diff --git a/agent-context/sessions/handoff/2026-08-26--muse-spark.md b/agent-context/sessions/handoff/2026-08-26--muse-spark.md
@@ -0,0 +1,42 @@
+<!-- Path: agent-context/sessions/handoff/2026-08-26--muse-spark.md -->
+---
+id: handoff-20260826-khd31lw6
+type: handoff
+level: diary
+title: "Session handoff — muse-spark"
+tags: [handoff, session]
+feature: global
+scope: global
+agent: system
+created: 2026-08-26T09:35:03.690Z
+updated: 2026-08-26T09:35:03.690Z
+status: done
+priority: 5
+summary: "Upgrade agent-shared-context with hierarchy, live radio, benchmark"
+---
+
+# Session Handoff — muse-spark
+
+## Task (goal)
+Upgrade agent-shared-context with hierarchy, live radio, benchmark
+
+## Done
+- hierarchy docs
+- search-lite tool
+- benchmark 5/50/500
+
+## Key context pointers (read on demand, not now)
+
+
+## Next steps
+- merge PR
+- release v0.3.0
+
+## Resume recipe (new session, ~600 tok total)
+1. Read `CURRENT.md` (~50 tok) — this pointer
+2. Read `agent-context/index.json` entries[].top (~300 tok) — full map
+3. Run `node tools/agent-search-lite.mjs "<your query>"` — hierarchical, 0 LLM
+4. Read only the 1-2 md files the search returns
+
+> Compaction avoided: everything durable was saved as entries during work.
+> This handoff is a pointer bundle, not a lossy summary.