CCLG는 기억을 파일로 저장하고, 훅에서 필요한 순간만 꺼내 씁니다.

Format: cclg.format.v0.1. 원본 증거는 raw/에 남기고, 장기 기억은 MemoryNode로 저장합니다. 수정은 MemoryPatch와 MemoryEdge로 기록되며, 에이전트는 훅과 MCP를 통해 ActiveMemoryPack과 CodeGraphPack만 소비합니다.

데이터 모델, 저장 위치, 참조 시점

모델 / 경로

주요 필드

언제 쓰이나

언제 읽히나

raw/

원본 증거

파일명, 원문, JSON hook payload, tool output, compact record. 기억의 최종 근거입니다.

쓰기

cclg raw, append_session_event(), import/hook 이벤트가 append-only로 저장합니다.

읽기

source.raw_spans 검증, 감사, 디버깅에서 참조합니다. 기본 prompt에는 직접 주입하지 않습니다.

nodes/

MemoryNode

scope, key, content, status, source, relations, retrieval.

쓰기

cclg add, import-jsonl, apply_patch()가 JSON 파일로 저장합니다.

읽기

search, pack, hook user-prompt, cclg.search, cclg.pack이 active만 검색합니다.

patches/

MemoryPatch

operation, target_ids, new_node_ids, reason, resolution_policy. 변경 의도 자체를 기록합니다.

쓰기

cclg patch, memory.patch tool이 만들고 write_patch()가 audit까지 남깁니다.

읽기

직접 prompt 주입이 아니라 node 상태 변경의 근거입니다. doctor, audit, diff에서 참조합니다.

edges/

MemoryEdge

from, to, type, source_patch_id. 새 기억이 어떤 기존 기억을 어떻게 바꿨는지 남깁니다.

쓰기

apply_patch()가 refines, supersedes, expands, narrows edge를 작성합니다.

읽기

doctor, audit, graph traversal, 사용자 설명에서 변경 경로를 추적합니다.

active/

ActiveMemoryPack / CodeGraph

query, generated_at, memory_nodes, suppressed_nodes, budget, files, symbols, edges, git_churn.

쓰기

compile_pack()은 즉시 생성하고, code-index와 hook은 active/codegraphs/*.json을 저장합니다.

읽기

훅의 additionalContext, MCP tool 결과, CLI TOML 출력으로 에이전트가 직접 소비합니다.

sessions/ audit/

SessionEvent / Audit

session id, event, payload, created_at, patch_written, raw_written, session_event.

쓰기

user-prompt, post-tool, pre-compact, post-compact가 모든 이벤트를 남깁니다.

읽기

나중에 memory distill, 재현, 오류 추적, 변경 원인 분석에서 참조합니다. 기본 active memory와 분리합니다.

훅에서 실제로 언제 참조되는가

사용자가 prompt 입력 Codex/Claude hook이 JSON payload를 cclg-hook user-prompt로 전달합니다.

session/raw 먼저 기록 append_session_event()가 sessions/, raw/, audit/에 이벤트를 남깁니다.

active node만 검색 active_nodes()와 search_nodes()가 status=active인 node만 고릅니다.

ActiveMemoryPack 생성 compile_pack()이 현재 query 기준 기억과 suppressed 목록을 분리합니다.

코드그래프 선택 --include-codegraph이면 git 파일, symbol, import edge, churn을 뽑습니다.

additionalContext 반환 에이전트가 읽는 것은 원본 전체가 아니라 active memory와 code pack 요약입니다.

실제 demo-store로 검증되는 흐름

Old

`nodes/mem_0524abcafba4.json`

content: prompt에 직접 누적한다
status: superseded
현재 truth로 주입되면 안 됨

Patch

`patches/patch_ad5c337890c3.json`

operation: refine
target_ids가 old node를 가리킴
new_node_ids와 변경 이유가 파일로 남음

Active

`nodes/mem_d6caa4a716ff.json`

content: raw evidence + active node 소비
status: active
relations.refines가 old node를 참조

Hook

`sessions/demo-session.json`

prompt event가 raw/session/audit에 저장
active 1개, suppressed 1개 반환
edge는 edges/, codegraph는 active/codegraphs/

명령과 Tool이 어떤 모델을 읽고 쓰는가

명령 / Tool

raw

nodes

patches

active/codegraph

sessions/audit

cclg add

직접 쓰지 않음

MemoryNode 작성

간접 audit 없음

cclg raw

원본 파일 저장

raw_written

cclg patch

target 상태 변경 + 새 node

MemoryPatch + Edge 작성

다음 pack에서 반영

patch_written

cclg pack/search

기본 미참조

active만 읽음

상태 결과만 반영

pack 즉시 생성

cclg-hook user-prompt

prompt event 저장

active 검색

직접 주입 안 함

additionalContext 생성

session_event

cclg-mcp

raw tool 가능

search/add/pack

patch

code_search 등

도구별로 다름

에이전트가 소비하는 출력 단위

Memory

ActiveMemoryPack

현재 task query 기준 active memory
superseded/expired/forgotten은 별도 표시
hook과 MCP가 prompt context로 사용

Code

CodeGraphPack

repo file, symbol, import/define edge
git churn으로 변경 가능성 보정
읽을 파일 순서를 정하는 힌트

Schema

Format Contract

cclg.format.v0.1
format/cclg.format.v0.1.toml
hook output 구조까지 문서화