---
title: "Maester Universal 정리 Summary Ingest 작업지시서"
from: codex
to: ["jadong", "claude-code", "codex"]
project: "maester"
date: 2026-05-09T19:48:16.882731+09:00
status: done
type: work-order
---

# Maester Universal 정리 Summary Ingest — Handoff Packet

## GitHub

- maester-agent: https://github.com/shinjadong/maester-agent/commit/811931d
- maester: https://github.com/shinjadong/maester/commit/6563417

---

# HANDOFF — Universal `정리` Summary Ingest

> 작성: 2026-05-09 KST, Codex CLI
> 상태: 구현 전 작업지시/명세서
> 목적: 어느 AI 앱에서든 사용자가 `정리`라고 하면 현재 대화가 표준 Markdown으로 정리되고 Maester에 자동 적재되게 한다.

## BLUF

현재 Maester에는 원문 Markdown을 적재하는 `maester_ingest` MCP/API가 있고, Context Bridge에는 `정리` 트리거 개념이 있다. 하지만 아직 "Claude App / ChatGPT / Claude Code 등 어느 앱에서든 `정리` 한 단어로 현재 대화 원문을 추출해 표준 문서로 만들고 Maester에 넣는 universal router"는 없다.

다음 작업은 `universal_summary_ingest`를 만드는 것이다.

## 현재 된 것

- Maester MCP:
  - `maester_ingest`
  - `maester_recall`
  - `maester_doc_get`
  - `maester_doc_update`
- Maester API:
  - `/api/maester/ingest`
  - `/api/maester/recall`
  - `/api/maester/docs/{id}`
- Claude App 수집:
  - `consciousness-bridge/src/collectors/claude_app.py`
  - sessionKey 기반 API fetch 가능
  - 방금 대화 `https://claude.ai/chat/bfd9eaf2-37d0-4981-903b-884394591cac` 수동 수집 성공
  - Maester 문서 `idea_20260509_b5c700`로 적재 완료
- ChatGPT CDP bridge:
  - `maester-agent/scripts/chatgpt_cdp_bridge.py`
  - 현재 열린 ChatGPT 대화에 파일 전송/응답 감지 가능
- Document Bridge:
  - `https://ai.shinjadong.cloud/api/comms/msg`
  - 결과 보고/문서 업로드 가능
- Context Bridge:
  - `정리` 규칙은 daily/master/session 갱신 용도로 존재
  - 아직 Maester universal ingest와 연결되지 않음

## 빠진 것

```text
사용자: "정리"
    ↓
현재 앱/대화 식별
    ↓
대화 원문 추출
    ↓
표준 Markdown 생성
    ↓
Maester ingest
    ↓
Document Bridge 결과 보고
    ↓
Context Bridge daily/master/session에 링크 기록
```

이 전체 루프가 아직 하나의 CLI/API/라우터로 묶여 있지 않다.

## 목표 인터페이스

### CLI

```bash
python scripts/universal_summary_ingest.py \
  --source claude_app \
  --conversation-url "https://claude.ai/chat/..." \
  --project keeper-direct \
  --doc-type idea \
  --importance high
```

```bash
python scripts/universal_summary_ingest.py \
  --source chatgpt \
  --current-cdp \
  --project maester \
  --doc-type decision
```

```bash
python scripts/universal_summary_ingest.py \
  --source claude_code \
  --session-id auto \
  --project maester \
  --doc-type code_work
```

### Optional API

```http
POST /api/maester/summary-ingest
```

Payload:

```json
{
  "source": "claude_app",
  "conversation_url": "https://claude.ai/chat/...",
  "project": "keeper-direct",
  "doc_type": "idea",
  "importance": "high",
  "trigger": "정리",
  "write_document_bridge": true,
  "write_context_bridge": true
}
```

## 표준 Markdown 포맷

```markdown
---
source: claude_app
conversation_id: ...
conversation_url: ...
title: ...
project: keeper-direct
doc_type: idea
importance: high
created_at: ...
updated_at: ...
ingested_at: ...
ai_tool: codex_cli
---

# {title}

## BLUF

- 핵심 결론 3줄

## Decisions

- 확정된 결정

## Ideas

- 새 아이디어 / 가설

## Action Candidates

- 실행 후보. 단, 확정 액션이 아니면 `candidate`로 표기

## Money / Opportunity Signals

- 돈 되는 흐름
- 기회 가설
- revenue / sales / lead / conversion 신호

## Risks / Unknowns

- 불확실한 사실
- 확인 필요

## Source Conversation

### 1. human

...

### 2. assistant

...
```

## 구현 설계

### 1. Source Adapters

파일: `scripts/universal_summary_ingest.py` 또는 `tools/summary_ingest.py`

Adapter contract:

```python
class ConversationPayload(TypedDict):
    source: str
    conversation_id: str
    conversation_url: str
    title: str
    model: str
    created_at: str
    updated_at: str
    messages: list[dict]  # role, created_at, text
```

Adapters:

- `ClaudeAppAdapter`
  - `conversation_url`에서 UUID 추출
  - `consciousness-bridge/src/collectors/claude_app.py` 재사용
  - 주의: 현재 collector `_extract_messages()`는 새 Claude 응답 구조의 `text` 필드를 못 읽었음. `chat_messages[].text` fallback을 추가해야 함.
- `ChatGPTCdpAdapter`
  - `scripts/chatgpt_cdp_bridge.py` 확장
  - 현재 열린 대화의 last/user/assistant만이 아니라 전체 visible transcript 추출 필요
  - 장기적으로 CDP DOM parser에 `export-current` 명령 추가
- `ClaudeCodeAdapter`
  - `~/.claude/projects/**.jsonl` 또는 consciousness-bridge `claude_code_indexer` 사용
  - 현재 session id auto 탐색은 별도 구현
- `FileAdapter`
  - 사용자가 `.md` 또는 `.json` 파일을 직접 넘기는 fallback

### 2. Summary Renderer

초기 v1은 LLM 요약 없이 rule-based로 시작해도 된다.

- 원문 보존이 제일 중요하다.
- BLUF/Decisions/Ideas는 간단한 heading 기반 또는 마지막 assistant 답변 요약으로 구성.
- 나중에 Maester/LLM 요약기로 품질 개선.

### 3. Maester Ingest

우선 MCP 또는 내부 Python `tools.maester_ingest.ingest` 중 하나를 사용한다.

권장:

- CLI 내부 실행이면 `tools.maester_ingest.ingest()` 직접 호출이 단순하다.
- "MCP 사용" 요구가 있을 때는 `mcp.client.streamable_http`로 `maester_ingest` 호출.

필수 metadata:

```python
source=<source>
device=<source>
doc_type=<doc_type>
project=<project>
title=f"{source} Summary — {title}"
importance=<importance>
people=<optional people list>
```

### 4. ActionItem 오염 방지

방금 Claude App idea 문서 ingest 결과, 연구/아이디어 원문에서도 ActionItem 후보 10개가 자동 생성됐다. 주간 실행판 오염을 막기 위해 `summary_ingest`에는 아래 옵션이 필요하다.

```bash
--action-policy none|candidate|extract
```

초기 기본값:

```text
idea / research / chat_log => action-policy=candidate 또는 none
execution_report / operator_command => extract
```

현 구현에서 extractor를 끄기 어렵다면 ingest 직후 해당 doc에서 추출된 ActionItem을 `status=dropped`로 soft-drop하고 evidence를 남긴다.

### 5. Document Bridge 기록

Maester ingest 성공 후 bridge에 결과 보고:

```json
{
  "from": "codex",
  "to": ["jadong", "claude-code"],
  "type": "result",
  "project": "maester",
  "title": "정리 저장 완료 — {title}",
  "summary_for_ai": "source=..., maester_doc_id=..., local_file=...",
  "content_md": "..."
}
```

### 6. Context Bridge 기록

`consciousness-bridge`의 DB guard를 고려한다.

- `daily_log.summary`는 교체하지 말고 append 흐름으로 둔다.
- `master_context.status_snapshot.maester.recent_summary_ingests[]` 형태로 append/merge.
- DELETE 금지.

권장 기록:

```json
{
  "summary_ingest": {
    "last_doc_id": "idea_...",
    "last_source": "claude_app",
    "last_title": "...",
    "last_bridge_msg": "msg_...",
    "updated_at": "..."
  }
}
```

## 우선순위

### P0

- `ClaudeAppAdapter` 단일 구현
- `chat_messages[].text` 파서 수정
- URL → Markdown → Maester ingest → Document Bridge result
- `--action-policy none` 기본값 구현

### P1

- ChatGPT CDP current conversation export
- `정리` 전송/감지 UX 정리
- Context Bridge daily/master/session append

### P2

- Claude Code session adapter
- Gemini/other app adapter
- LLM 요약 품질 개선
- idempotency: 같은 conversation_id + updated_at이면 중복 ingest 방지

## Acceptance Criteria

1. 사용자가 Claude App URL을 주고 `정리`라고 하면:
   - 로컬 Markdown 파일 생성
   - MaesterDocument 생성
   - Document Bridge 결과 보고 생성
   - Context Bridge daily_log/master_context 업데이트
2. 같은 URL을 두 번 실행하면:
   - `updated_at`이 같으면 중복 생성하지 않거나 같은 문서 업데이트
3. idea/research 대화는:
   - 실행판 ActionItem을 오염시키지 않음
4. recall 확인:
   - 대화 핵심 키워드로 Maester recall 시 해당 문서가 top 5에 나옴

## 방금 수동 처리한 사례

- Source URL: `https://claude.ai/chat/bfd9eaf2-37d0-4981-903b-884394591cac`
- Title: `한화비전 대표이사 김기철`
- Local Markdown:
  - `/home/tlswk/projects/maester/context/chat-log/claude_app_20260509_hanwha_vision_ceo_kim_gicheol.md`
- Maester doc:
  - `idea_20260509_b5c700`
  - `https://ai.shinjadong.cloud/docs/idea_20260509_b5c700`
- Extracted ActionItem candidates:
  - 10개 생성됨
  - 모두 `dropped` soft-drop 처리 완료
- GitHub context repo:
  - `shinjadong/maester@3bcc9b7`

## 주의사항

- 시크릿 출력 금지.
- `.env`, sessionKey, Maester write token은 문서/브릿지에 쓰지 말 것.
- DB 삭제 금지.
- Supabase RLS/security 작업은 이 이슈와 무관.
- 실제 사업 ActionItem apply는 operator 승인 파일 없이는 금지.


---

# Maester Universal `정리` Summary Ingest — 작업지시서

## 시작 문장

Maester universal `정리` summary ingest를 구현한다. 현재 Maester에는 `maester_ingest` MCP/API와 Context Bridge의 `정리` 개념이 있지만, Claude App/ChatGPT/Claude Code 등 어느 AI 앱에서든 사용자가 `정리`라고 하면 현재 대화를 표준 Markdown으로 만들고 Maester에 자동 적재하는 router는 아직 없다. 우선 Claude App URL 기반 MVP를 만들고, 이후 ChatGPT CDP/Claude Code adapter로 확장한다. 데이터 삭제 금지, 시크릿 출력 금지, `.env`/sessionKey/token 저장소 커밋 금지, 실제 사업 ActionItem apply 금지.

## 목표

사용자가 다음처럼 말하면:

```text
정리 https://claude.ai/chat/<conversation_id>
```

자동으로:

```text
1. Claude App 대화 원문 fetch
2. 표준 Markdown 생성
3. MaesterDocument ingest
4. idea/research 문서의 액션 후보는 실행판 오염 방지
5. Document Bridge 결과 보고
6. Context Bridge daily/master/session에 링크 기록
7. recall 검증
```

까지 처리한다.

## P0 구현 파일

- `scripts/universal_summary_ingest.py`
- 필요 시 `tools/summary_ingest.py`
- 수정 후보:
  - `consciousness-bridge/src/collectors/claude_app.py`
  - `scripts/chatgpt_cdp_bridge.py`
  - `tools/maester_ingest.py`

## P0 기능

### 1. Claude App URL Adapter

- URL에서 conversation UUID 추출
- `~/.consciousness-bridge-session-key` 또는 consciousness-bridge config의 `CLAUDE_APP_SESSION_KEY` 사용
- `claude_app._get_conversation()` 재사용
- `chat_messages[].text` 구조를 반드시 읽을 것

### 2. 표준 Markdown Renderer

필수 섹션:

- YAML frontmatter
- `## BLUF`
- `## Decisions`
- `## Ideas`
- `## Action Candidates`
- `## Money / Opportunity Signals`
- `## Risks / Unknowns`
- `## Source Conversation`

초기에는 원문 보존 우선. LLM 요약 품질은 P1로 미뤄도 된다.

### 3. Maester Ingest

CLI 옵션:

```bash
python scripts/universal_summary_ingest.py \
  --source claude_app \
  --conversation-url "https://claude.ai/chat/..." \
  --project keeper-direct \
  --doc-type idea \
  --importance high \
  --action-policy none \
  --write-document-bridge \
  --write-context-bridge
```

### 4. Action Policy

기본:

```text
idea/research/chat_log => action-policy=none
execution_report/operator_command => action-policy=extract
```

현 ingest가 ActionItem을 자동 생성하면, ingest 직후 해당 doc에서 추출된 ActionItem을 삭제하지 말고 `status=dropped`로 soft-drop한다.

### 5. Idempotency

동일 키:

```text
source + conversation_id + updated_at
```

같은 updated_at이면 중복 문서 생성 금지. 업데이트가 있으면 새 version 또는 새 문서 정책 중 하나를 명시한다.

## 검증

테스트 케이스:

```bash
python scripts/universal_summary_ingest.py \
  --source claude_app \
  --conversation-url "https://claude.ai/chat/bfd9eaf2-37d0-4981-903b-884394591cac" \
  --project keeper-direct \
  --doc-type idea \
  --importance high \
  --action-policy none \
  --write-document-bridge \
  --write-context-bridge
```

기대:

- Markdown file 생성
- Maester doc 생성 또는 기존 doc idempotent update
- recall query `김기철 한화비전 CODEF 팝빌 ONVIF`에서 해당 문서 top 5
- 해당 문서 기반 ActionItem active 0
- Document Bridge result 생성
- Context Bridge에 요약 append

## 이미 수동 완료된 기준 사례

- Claude App URL:
  - `https://claude.ai/chat/bfd9eaf2-37d0-4981-903b-884394591cac`
- Local Markdown:
  - `/home/tlswk/projects/maester/context/chat-log/claude_app_20260509_hanwha_vision_ceo_kim_gicheol.md`
- Maester doc:
  - `idea_20260509_b5c700`
  - `https://ai.shinjadong.cloud/docs/idea_20260509_b5c700`
- 자동 추출 ActionItem:
  - 10개 모두 `dropped`
- Context repo commit:
  - `shinjadong/maester@3bcc9b7`