LightRAG를 위키 DB로 쓰지 마라 — 지식·그래프·기억을 분리한 LLM Wiki v2 설계

무너지는 지점은 "규모"가 아니라 "쓰기 특성"이다

RAG 설명은 세 문장으로 끝낸다. 문서를 잘라 임베딩하고, 질의 시점에 가까운 조각을 꺼내 프롬프트에 붙인다. 그래프 RAG는 여기에 LLM이 추출한 엔티티·관계를 얹어 다중 홉 질의를 가능하게 한다. 중요한 건 그 다음 문장이다 — 이 파이프라인의 산출물(청크·임베딩·엔티티·관계)은 전부 다시 만들 수 있고, 입력(원문)만이 다시 만들 수 없다.

한 저장소에 다 넣으면 무너지는 이유는 데이터가 많아서가 아니라 세 종류의 쓰기가 섞이기 때문이다. 위키 문서 저장은 20ms 트랜잭션이고, 그래프 인덱싱은 문서당 LLM 호출 수십 번짜리 초~분 단위 배치이며, 에이전트 기억은 세션마다 수십 건씩 들어오는 append-only 로그다. 같은 저장소에 두면 가장 느리고 가장 깨지기 쉬운 층이 나머지 둘의 가용성을 결정한다.

이건 이론이 아니다. LightRAG를 PostgreSQL + Apache AGE 백엔드로 운영하던 사용자가 1.4.9.1 → 1.4.9.4 업그레이드를 하다가 17시간 넘게 서버가 죽었다(issue #2255). 규모는 정점 약 34.2만, 방향 간선 약 40.7만 — 개인 위키 기준으로 크지도 않다. 원인은 마이그레이션이 실행한 get_all_edges() 쿼리의 실행 계획이 중간 산출 49억 행짜리 nested loop로 잡힌 것. 여기서 핵심은 "그래프 인덱스가 17시간 죽었다"가 아니라, 만약 위키 원문이 같은 DB 안에 있었다면 그 17시간 동안 글을 읽지도 쓰지도 못했다는 점이다.

세 층의 정의와 속성 대비

마지막 세 행이 이 섹션의 전부다. 나머지는 이 세 행의 결과다.

구분이 실제로 만들어내는 차이

① 재인덱싱 자유도 — 임베딩 모델을 바꿀 수 있느냐. LightRAG README는 못을 박는다. "임베딩 모델은 인덱싱 전에 확정해야 하고 질의 단계에서도 같은 모델을 써야 한다. 바꾸면 모든 청크·엔티티·관계를 재임베딩해야 하며 LightRAG는 재임베딩 도구를 제공하지 않는다." PostgreSQL 백엔드에서는 더 딱딱하다. vector(dim)이 테이블 DDL에 박히므로 차원을 바꾸려면 LIGHTRAG_VDB_CHUNKS / LIGHTRAG_VDB_ENTITY / LIGHTRAG_VDB_RELATION을 드롭해야 한다(issue #2119의 expected 1024 dimensions, not 1536이 정확히 이 증상이다).

원본이 바깥에 있으면 이건 그냥 DROP TABLE + 배치 재인덱싱이다. 원본이 안에 있으면 같은 명령이 데이터 삭제다. 같은 SQL, 전혀 다른 사건.

② 백업 범위 — 스토리지를 지배하는 건 원본이 아니다. 3072차원 float32 임베딩 하나는 12,288바이트다. 한국어 1,000자 청크는 UTF-8로 약 3KB. 임베딩이 원문보다 4배 무겁다(pgvector 0.7+ halfvec으로 반으로 줄여도 2배). 여기에 엔티티/관계 벡터와 LLM 캐시가 더 붙는다. 즉 백업에서 파생 층을 빼는 것만으로 백업 크기가 한 자릿수 배 줄고, RPO 설계가 단순해진다. 파생 층의 RPO는 시간이 아니라 **"재인덱싱에 몇 시간 걸리는가"**로 표현된다.

여기서 이 위키의 대전제 ①에 단서를 하나 붙이고 싶다. "LightRAG는 언제든 통째로 재생성 가능하다"는 측정해두지 않으면 선언에 불과하다. 문서 500건 재인덱싱에 LLM 호출이 몇 번 들어가고 몇 분/얼마가 드는지 분기마다 실측해서 기록하지 않으면, 정작 필요한 날 "재생성 가능"은 검증되지 않은 가정이 된다.

③ 프라이버시 경계 — 임베딩은 원문의 요약이 아니라 원문이다. Morris 등의 Vec2Text는 32토큰 텍스트를 임베딩만으로 복원해 **BLEU 97.3, 완전 일치 92%**를 달성했다. 더 나쁜 건 삭제 쪽이다. 「Ghost Vectors」(arXiv 2606.18497)는 HNSW 벡터 DB의 소프트 삭제된 임베딩이 raw 스토리지 파일에서 복원 가능함을 보였다 — 합성 의료 데이터에서 환자 나이·성별 마커 복원률 100%, 얼굴 임베딩 top-1 신원 복원 99%.

결론: 파생 층의 삭제는 tombstone이 아니라 재빌드여야 한다. 그리고 재빌드는 원본이 밖에 있을 때만 선택지다. 층이 합쳐져 있으면 "지웠다고 표시"밖에 못 한다.

④ 모순 처리 — 세 층이 각각 다른 정답을 쓴다.

• 위키는 모순을 제거한다. 두 문장이 충돌하면 사람이 한쪽을 지우고, git이 이전 판을 보관한다.
• 그래프는 모순을 다루지 못한다. 반대되는 두 문서에서 같은 엔티티가 추출되면 description이 병합되어 한 노드 안에서 자기모순을 일으킨다. 그래프 층에서 이걸 고치려 들면 안 된다 — 원본을 고치고 재인덱싱하는 게 유일한 정정 경로다.
• 기억은 모순을 보존해야 한다. Graphiti(Zep)의 이중 시간 모델이 정답에 가깝다: 사실이 바뀌면 옛 사실을 지우지 않고 무효화 구간을 찍어 "지금 참인 것"과 "그때 참이었던 것"을 따로 질의한다. "우리는 A로 갔다가 실패해서 B로 바꿨다"는 A를 지우는 순간 가치를 잃는다.

LightRAG를 위키 DB처럼 쓰면 생기는 문제

원본 층은 이렇게 두면 위 문제가 전부 파생 층 안에 갇힌다.

-- 원본 층: 여기만 백업하면 전부 복구된다
CREATE TABLE documents (
  id            uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  slug          text NOT NULL UNIQUE,
  title         text NOT NULL,
  body_md       text NOT NULL,              -- 마크다운 원문 = 진실
  frontmatter   jsonb NOT NULL DEFAULT '{}'::jsonb,
  visibility    text NOT NULL DEFAULT 'private'
                CHECK (visibility IN ('private','team','public')),
  content_hash  text GENERATED ALWAYS AS (md5(body_md)) STORED,
  updated_at    timestamptz NOT NULL DEFAULT now(),
  deleted_at    timestamptz                  -- 소프트 삭제 (원본 층에서만)
);

-- 파생 층과의 계약: "무엇을 언제 색인했는가"만 기록. 인덱스 자체는 저장 안 함
CREATE TABLE index_state (
  doc_id          uuid PRIMARY KEY REFERENCES documents(id) ON DELETE CASCADE,
  indexed_hash    text,                      -- 색인 당시 content_hash
  embedding_model text,                      -- 'text-embedding-3-large'
  embedding_dim   int,
  graph_status    text NOT NULL DEFAULT 'pending'
                  CHECK (graph_status IN ('pending','running','done','failed')),
  indexed_at      timestamptz,
  attempts        int NOT NULL DEFAULT 0
);

-- 어휘 검색은 원본 층에 붙인다 (한국어는 simple + pg_bigm/pgroonga 병행 검토)
ALTER TABLE documents ADD COLUMN tsv tsvector
  GENERATED ALWAYS AS (to_tsvector('simple', coalesce(title,'') || ' ' || body_md)) STORED;
CREATE INDEX documents_tsv_idx ON documents USING GIN (tsv);

한국어 어휘 검색은 여기서 갈린다. PostgreSQL 기본 tsvector는 한국어 형태소 분석기가 없어 simple 설정으로는 공백 단위 토큰만 잡는다. 선택지는 pg_bigm(2-gram, GIN 기반이라 crash-safe), PGroonga(가장 빠르지만 인덱스가 크고 crash-safe가 아니라 손상 시 REINDEX 필요), pg_search(ParadeDB, Tantivy 기반 BM25, PGXN 최신 0.22.5) — 매니지드 PG에서 확장 설치가 가능한지부터 확인하는 게 순서다. (라우터가 이 중 무엇을 언제 고르는지는 → 검색 라우터 섹션에서 다룸)

분리하면 치르는 비용 — 정직하게

가장 흔한 실패 모드는 세 번째가 아니라 네 번째다. 원본에서 문서를 지우고 "완료"라고 보고했는데 그래프에 엔티티가 남아 답변에 계속 등장하는 사고. 층별 삭제 확인 없이 삭제를 선언하지 말 것.

-- 드리프트: 이 세 숫자만 대시보드에 띄우면 분리의 비용이 관리 가능해진다
SELECT
  count(*) FILTER (WHERE s.doc_id IS NULL)                          AS never_indexed,
  count(*) FILTER (WHERE s.indexed_hash IS DISTINCT FROM d.content_hash) AS stale,
  count(*) FILTER (WHERE s.embedding_model <> current_setting('app.embed_model', true)) AS wrong_model
FROM documents d
LEFT JOIN index_state s ON s.doc_id = d.id
WHERE d.deleted_at IS NULL;

어느 층으로 보낼지 판별하는 실무 규칙 7개

1. "사람이 지우면 영원히 사라지는가?" → 그렇다면 원본 층. 파생 층에 사람만 아는 정보를 넣는 순간 그 층은 더 이상 파생이 아니다. 가장 흔한 위반: 인덱싱 파이프라인 안에서 LLM이 생성한 요약을 그래프에만 저장하는 것.
2. "내일 인덱서를 다시 돌리면 똑같이 나오는가?" → 나온다면 파생 층. 비결정적 산출물(LLM 요약·분류)을 파생 층에 두려면 프롬프트와 모델 버전을 원본 층에 고정해야 재현이 성립한다.
3. "주어가 나/에이전트인가, 세상인가?" → "이 파라미터의 기본값은 X다"는 위키. "우리는 X를 시도했고 Y 때문에 실패해 Z로 바꿨다"는 기억. 후자를 위키에 쓰면 6개월 뒤 남이 사실로 읽는다.
4. "틀렸을 때 비용을 누가 무는가?" → 남이 물면(공유·발행) 위키, 나만 물면 기억. 이게 승격 게이트의 실질적 기준이다. 기억 → 위키 승격은 "유용해서"가 아니라 "타인이 읽어도 안전해서" 일어난다.
5. "수명이 임베딩 모델보다 긴가?" → 길면 원본 층. 모델 교체 주기(대략 6~18개월)보다 짧게 사는 데이터만 파생 층 단독 보관이 정당하다.
6. "삭제 요청이 법적 의무인가?" → 그렇다면 그 데이터는 파생 층에 들어가면 안 되거나, 들어간다면 tombstone이 아닌 재빌드 삭제 경로가 미리 있어야 한다(Ghost Vectors). 개인 식별 정보를 그래프 엔티티로 승격시키지 말 것 — 엔티티는 문서 삭제 후에도 다른 문서에 살아남는 설계다.
7. "정확한 문자열로 찾을 것인가?" → 설정키·파일 경로·에러 메시지·버전 번호는 어휘 검색이 필요하므로 반드시 원본 층에 원형 그대로 남는다. 그래프 층은 이런 토큰을 엔티티로 승격시키면서 정규화해 원형을 잃는다.

규칙 3과 4가 서로 충돌할 때(유용한 경험인데 검증이 안 됨) 답은 기억에 남기고 승격을 보류다. 승격했다면 원본 기억을 지우지 말고 출처로 연결해 둔다 — 위키 문장이 틀렸을 때 그 문장이 어느 세션의 어떤 관측에서 나왔는지 되짚을 수 있어야 한다. 이 세 층을 하나의 인터페이스로 노출하는 방법(→ MCP 섹션에서 다룸)은 층이 분리돼 있을 때만 깔끔하게 설계된다. 층별 도구가 각각 다른 삭제·신뢰도 계약을 갖기 때문이다.

다섯 모드는 "키워드 2종 × 인덱스 3개"의 조합일 뿐이다

LightRAG(PyPI lightrag-hku, 현재 1.5.6, Python ≥3.10)는 질의를 받으면 먼저 LLM을 한 번 태워 키워드를 두 벌 뽑는다. 하나는 저수준(low-level) 키워드 — "구체적 엔티티", 다른 하나는 고수준(high-level) 키워드 — "개념·테마·요약". 이 두 벌이 서로 다른 벡터 인덱스를 때리는 것이 모드 차이의 전부다. 인덱스는 세 개뿐이다: entities_vdb(엔티티 설명), relationships_vdb(관계 설명), chunks_vdb(원문 청크).

⚠️ 기본값이 문서마다 다르다. 코어 QueryParam.mode의 dataclass 기본값은 "global"인데, 서버/WebUI 문서는 mix를 기본이자 권장으로 쓴다. 절대 기본값에 기대지 말고 매 호출에 명시하라. bypass 모드(검색 없이 LLM 직행)도 있으니 라우터의 "검색 불필요" 분기에 그대로 쓸 수 있다(→ 라우터 설계는 다른 섹션에서 다룸).

지연·토큰의 실제 구조는 이렇다. LightRAG 논문(Legal 데이터셋, Figure 2)은 검색 단계에서 <100 토큰 / API 호출 1회를 보고하는데, GraphRAG는 같은 자리에서 610개 커뮤니티 × ~1,000 토큰 = 610,000 토큰을 태운다. 즉 LightRAG의 검색은 원래 싸다. 비싼 건 인덱싱이다.

인덱싱 비용은 정확히 세 군데서 터진다

②가 지배적인 이유는 단순하다. 추출만이 O(청크 수)로 LLM을 부르는 유일한 경로다. 청크 1,200토큰 기준 1MB 마크다운이면 대략 200~250청크, gleaning 1회를 켜면 400~500회 호출이다. ③은 더 고약하다 — 코퍼스가 커질수록 "PostgreSQL", "FastAPI" 같은 허브 엔티티의 설명 조각이 계속 8개를 넘겨 재요약을 유발한다. 체감상 문서 수에 초선형으로 붙는 비용의 정체가 이것이다.

왜 추출에 non-thinking 모델을 쓰라고 하는가

LightRAG는 LLM 역할을 넷으로 쪼개 놓았다(EXTRACT / QUERY / KEYWORD / VLM). README의 권고는 명확하다:

• EXTRACT: "빠르고 저렴한 주류 모델로 충분하며, non-thinking 모델을 강력 권장" — 느리고 비싼 추출을 피하기 위해.
• KEYWORD: "질의 지연에 직결되므로 반드시 non-thinking".
• QUERY: "길고 노이즈 많은 컨텍스트에서 최종 답을 쓰므로 추출 모델보다 강해야 한다" — thinking 모델 허용.

산수로 보면 당연하다. thinking 토큰이 청크당 1~2k 붙으면 ②에서 그대로 청크 수만큼 곱해진다. 반면 QUERY는 사용자 질의당 1회다. 비싼 모델은 O(질의)에, 싼 모델은 O(문서)에. 이 한 줄이 전체 원가를 결정한다.

튜닝 포인트와 실패 모드:

• gleaning 0으로 내리기 — 추출 호출이 절반이 된다. 대가는 롱테일 엔티티 누락이고, 실패가 조용하다: 그래프가 얇아져도 에러가 없고 local은 멀쩡히 답한다. 먼저 무너지는 건 global(관계 밀도 부족)이다. 참고로 이 값은 env.example에 키가 없다 — 생성자 인자로만 설정한다.
• FORCE_LLM_SUMMARY_ON_MERGE 올리기 — 요약 호출이 줄지만 엔티티 설명이 중복 문장 누더기가 되고, 그게 local 모드 컨텍스트로 그대로 들어간다.
• enable_llm_cache_for_entity_extract=True 유지 — 재인덱싱 원가를 좌우한다. 다만 추출 프롬프트나 모델을 바꾸면 캐시가 전부 무효가 되므로, "모델 교체 = 전량 재추출"로 예산을 잡아라.
• ENTITY_EXTRACTION_USE_JSON=true — env.example 주석 그대로 "지연은 늘지만 신뢰도가 낫다". 야간 배치라면 켜라.

증분 삽입은 쉽고, 삭제는 어렵다

증분 삽입은 실제로 싸다. 새 문서를 같은 파이프라인에 태워 서브그래프를 만든 뒤 노드·엣지 집합의 합집합으로 병합한다. 커뮤니티 재계산이 없다는 게 핵심이다(GraphRAG는 커뮤니티 리포트를 리포트당 ~5,000토큰으로 재생성해야 하고, 논문 데이터셋 기준 커뮤니티가 1,399개였다). 중복은 내용 해시 기반 문서 ID로 막히며, rag.insert(text, ids=[...])로 직접 지정할 수 있다.

위키 대전제와의 접점: 마크다운 파일의 안정 슬러그(또는 PG의 document.id)를 그대로 ids=에 넣어라. 그래야 재발행이 "새 문서"가 아니라 "같은 문서의 갱신"이 되고, PG의 원본과 LightRAG의 파생 인덱스가 같은 키로 조인된다.

삭제는 다르다. adelete_by_doc_id()는 async 전용이며, 청크 → 고아 엔티티/관계 → 벡터 인덱스 → 문서 상태로 캐스케이드하되, 다른 문서에도 등장하는 엔티티는 남은 근거로 재구축해야 한다. 공식 문서 경고 그대로 "모든 삭제는 되돌릴 수 없고", "특히 문서 ID 단위 삭제는 오래 걸린다". 청크와 LLM 캐시가 남아 재인제스트가 깨진다는 버그 리포트(#2442)도 열려 있다.

그래서 대전제 ①(LightRAG는 언제든 통째로 재생성 가능한 파생 인덱스)은 옳다. 다만 한 군데는 반박이 필요하다 — 코퍼스가 수천 문서를 넘으면 전량 재생성은 위 표의 ②를 통째로 다시 무는 일이다. 현실적인 절충은 이중 전략이다: 일상 수정은 adelete_by_doc_id + insert(ids=[동일ID]), 전량 재생성은 workspace를 새로 파서 빌드한 뒤 원자적으로 스왑하고 분기당 1회 회귀 목적으로만 돌린다. workspace 파라미터가 데이터 격리 네임스페이스라 blue/green이 그대로 된다.

이웃 프레임워크와의 차이 (짧게)

공개 비교 글들이 인용하는 500페이지 코퍼스 기준 수치(GraphRAG $50~200·45분 vs LightRAG ~$0.50·3분)는 출처의 자체 측정이고 모델·단가 가정이 공개되지 않았다. 방향성(1~2자릿수 차이)만 취하고, 실제 원가는 자기 코퍼스로 100문서 파일럿을 돌려 측정하라.

최소 설치와 코드

pip install "lightrag-hku[api]"        # 또는: uv tool install "lightrag-hku[api]"

# wiki_index.py — 파생 인덱스 빌더. 원본은 PG/마크다운, 여기는 언제든 버릴 수 있다.
import asyncio, os
from lightrag import LightRAG, QueryParam
from lightrag.kg.shared_storage import initialize_pipeline_status

async def build(workspace: str = "wiki_v2"):
    rag = LightRAG(
        working_dir="./lightrag_cache",
        workspace=workspace,               # blue/green 스왑 단위
        kv_storage="PGKVStorage",          # env: LIGHTRAG_KV_STORAGE
        vector_storage="PGVectorStorage",
        graph_storage="PGGraphStorage",
        doc_status_storage="PGDocStatusStorage",
        chunk_token_size=1200,
        chunk_overlap_token_size=100,
        entity_extract_max_gleaning=1,     # 0 = 추출 호출 반토막, 리콜 하락
        llm_model_func=my_extract_llm,     # non-thinking 모델을 여기 물린다
        embedding_func=my_embedding_func,
        llm_model_max_async=4,             # env: MAX_ASYNC_LLM
        enable_llm_cache_for_entity_extract=True,
    )
    await rag.initialize_storages()
    await initialize_pipeline_status()

    # 원본 문서 ID를 그대로 넘겨야 재발행이 update가 된다
    await rag.ainsert("...본문...", ids=["wiki/architecture/lightrag"],
                      file_paths=["wiki/architecture/lightrag.md"])

    print(await rag.aquery("왜 추출과 질의 모델을 분리했나",
                           param=QueryParam(mode="mix", top_k=40, chunk_top_k=20)))

asyncio.run(build())

initialize_storages()와 initialize_pipeline_status()를 둘 다 부르지 않으면 런타임 에러가 난다. 그리고 임베딩 모델을 중간에 바꾸면 벡터 스토리지가 깨지므로 반드시 workspace를 새로 파라.

도입 전 체크리스트

• [ ] 모드를 코드에서 명시했는가(기본값이 문서마다 다름)
• [ ] EXTRACT/KEYWORD에 non-thinking 모델, QUERY에만 강한 모델을 물렸는가
• [ ] 100문서 파일럿으로 청크 수 × (1+gleaning) × 청크당 토큰을 실측했는가
• [ ] insert(ids=...)에 원본 시스템의 안정 키를 넘기는가
• [ ] workspace 스왑으로 전량 재빌드 경로를 확보했는가(삭제에 의존하지 않기)
• [ ] MAX_TOTAL_TOKENS=30000 / MAX_ENTITY_TOKENS=6000 / MAX_RELATION_TOKENS=8000이 실제 QUERY 모델 컨텍스트에 맞는가

30초는 어디서 나오는가 — 산술로 확인하기

그래프 인덱싱 비용은 거의 전적으로 청크 수 × 청크당 LLM 호출로 결정된다. LightRAG 기본값 CHUNK_SIZE=1200 / CHUNK_OVERLAP_SIZE=100 기준으로 6,000토큰짜리 문서는 약 6청크. 청크마다 엔티티·관계 추출 1회, 그리고 누락분을 다시 묻는 gleaning이 1회 더 붙는다(파이프라인 기본 entity_extract_max_gleaning=1, 즉 청크당 최대 2회. 입력이 DEFAULT_MAX_EXTRACT_INPUT_TOKENS=20,480을 넘으면 자동 생략). 여기에 엔티티 병합 시 설명 요약 호출(FORCE_LLM_SUMMARY_ON_MERGE)이 몇 건 더. 합쳐서 문서당 12~15회다.

기본 동시성은 MAX_ASYNC_LLM=4. 호출당 5~8초(입력 3~4k, 출력 ~800토큰)를 잡으면 문서 1건의 벽시계 시간은 (14 ÷ 4) × 6 ≈ 20~40초. 제목의 "30초 멈춤"은 과장이 아니라 기본 설정의 산술 결과다.

같은 문서의 Fast Path 작업량은 자릿수가 다르다.

경계선은 여기다. 위 네 줄까지가 Fast, 마지막 줄이 Deep.

두 경로를 가르는 진짜 기준은 트랜잭션이다

Fast Path가 커밋해야 하는 것: 원본 마크다운, 청크, 임베딩, FTS 인덱스. 커밋되면 문서는 searchable이고 API는 즉시 202 + doc_id를 돌려준다. Deep Path 잡은 같은 트랜잭션 안에서 큐에 들어가야 한다. Redis/RabbitMQ를 쓰면 "커밋은 됐는데 enqueue가 실패"를 막으려고 outbox 테이블 + 릴레이가 필요하다. Postgres 큐라면 같은 트랜잭션에 pgmq.send() 한 줄이면 끝난다. 이 규모에서 Postgres 큐를 고르는 첫 번째 이유가 이거다.

-- 정본은 여기. LightRAG 인덱스는 이 테이블에서 언제든 재생성된다.
CREATE TYPE doc_state AS ENUM
  ('stored','searchable','graph_indexing','graph_ready','stale','graph_failed');

CREATE TABLE documents (
  id               uuid PRIMARY KEY,
  path             text UNIQUE NOT NULL,
  body             text NOT NULL,
  content_sha256   bytea NOT NULL,
  state            doc_state NOT NULL DEFAULT 'stored',
  graph_synced_sha bytea,          -- 그래프에 실제로 반영된 판본
  graph_error      text,
  updated_at       timestamptz NOT NULL DEFAULT now()
);
CREATE INDEX ON documents (state) WHERE state <> 'graph_ready';

-- Fast Path 전체가 한 트랜잭션. 별도 브로커였다면 여기에 outbox 가 필요하다.
BEGIN;
  INSERT INTO documents (id, path, body, content_sha256, state)
  VALUES ($1, $2, $3, $4, 'searchable')
  ON CONFLICT (path) DO UPDATE
    SET body = EXCLUDED.body,
        content_sha256 = EXCLUDED.content_sha256,
        state = CASE WHEN documents.graph_synced_sha IS NULL
                     THEN 'searchable'::doc_state ELSE 'stale'::doc_state END,
        updated_at = now();
  -- (청크 upsert + 임베딩 insert 생략)
  SELECT pgmq.send('graph_index',
    jsonb_build_object('doc_id', $1::text, 'sha', encode($4,'hex')));
COMMIT;

상태 머신과 UI 노출

핵심은 graph_failed에서도 문서가 검색된다는 것이다. 그래프는 부가가치이지 전제가 아니다 — 대전제 ①(마크다운+Postgres가 정본, LightRAG는 파생 인덱스)의 실무적 귀결이다.

상태의 정본도 우리 테이블이지 LightRAG가 아니다. LightRAG는 자체적으로 PENDING → PARSING → ANALYZING → PROCESSING → PROCESSED / FAILED와 /documents/track_status/{track_id}, /documents/pipeline_status를 갖고 있고 진행률 표시에 쓰기 좋다. 하지만 "이 문서가 그래프에 반영됐는가"의 답은 우리 DB의 graph_synced_sha여야 한다. 인덱스를 통째로 날리고 재생성하는 순간 저쪽 상태는 전부 리셋되기 때문이다.

무너지는 지점: graph_ready를 전역 진행 배너로 만들어 사용자를 기다리게 하면 Fast Path를 만든 의미가 없다. 업로드 직후 포커스는 검색창으로 가야 한다.

큐/워커 선택

권장은 pgmq다. 근거 세 개: ①원본이 이미 Postgres라 enqueue가 공짜로 원자적, ②운영해야 할 인프라가 하나 줄어든다, ③visibility timeout + read_ct가 손으로 짤 재시도 로직을 대신한다. 폴링이 싫으면 LISTEN/NOTIFY를 깨우기 신호로만 쓴다 — 알림은 영속되지 않고 페이로드가 8,000바이트에서 잘리므로 큐 자체로 쓰면 안 된다.

무너지는 지점: 초당 수천 건을 넘기면 Postgres가 병목이 되고 아카이브 테이블(pgmq.a_*)의 vacuum·파티셔닝을 신경 써야 한다. 개인 지식 OS는 초당 1건도 안 되므로 해당 없다 — 그 규모가 되면 그때 Celery로 옮기면 된다.

멱등성·경합·독약 메시지

# vt=300s: 문서당 최장 처리시간(≈40s)의 여유 배수.
# 짧으면 두 워커가 같은 문서를 동시에 추출해 중복 관계가 쌓이고 비용이 2배 나가는데, 에러는 안 난다.
rows = await conn.fetch("SELECT * FROM pgmq.read('graph_index', 300, 1)")
for msg in rows:
    doc_id, sha = msg["message"]["doc_id"], msg["message"]["sha"]
    cur = await conn.fetchval(
        "SELECT encode(content_sha256,'hex') FROM documents WHERE id=$1", doc_id)

    if cur != sha:                    # 동시 수정 경합 → 뒤에 최신 잡이 있다. 그냥 버린다.
        await conn.execute("SELECT pgmq.archive('graph_index',$1)", msg["msg_id"]); continue
    if msg["read_ct"] > 5:            # 독약 메시지. pgmq 에 DLQ 는 없으니 직접 종결.
        await mark_failed(doc_id, "max retries")
        await conn.execute("SELECT pgmq.archive('graph_index',$1)", msg["msg_id"]); continue

    await set_state(doc_id, "graph_indexing")
    try:
        # LightRAG doc id = compute_mdhash_id(content, prefix="doc-") — 본문이 바뀌면
        # '새 문서'로 들어가고 옛 노드가 그대로 남는다. 선행 삭제를 빼먹으면
        # 두 판이 그래프에 공존하며 옛 사실을 근거로 답하기 시작한다.
        # (아래 두 메서드명은 버전 간 변동이 있다 — 설치본 시그니처 확인 필요)
        await rag.adelete_by_doc_id(prev_lightrag_id)
        await rag.ainsert(body)
    except TransientError:
        continue                      # 삭제하지 않음 → vt 만료 후 자동 재가시화
    await conn.execute("SELECT pgmq.archive('graph_index',$1)", msg["msg_id"])
    await set_graph_ready(doc_id, sha)

• 작업 키는 (doc_id, content_sha256). LightRAG는 내용 해시가 같은 문서를 filter_keys()로 알아서 건너뛰므로 "같은 내용 재삽입"은 이미 멱등하다. 문제는 내용이 바뀐 경우다 — 반드시 delete-then-insert.
• 동시 수정 경합은 취소가 아니라 stale-drop으로 푼다. 잡을 꺼냈을 때 payload의 sha가 현재 sha와 다르면 조용히 archive. 최신 sha 잡이 큐 뒤에 있으므로 last-write-wins로 수렴한다. 큐에서 잡을 찾아 지우는 것보다 훨씬 단순하고 안전하다.
• 부분 실패가 가장 비싸다. 20청크 중 12청크까지 추출한 뒤 죽으면 상태가 문서 단위라 처음부터 다시다(= LLM 비용 2배). 완화책은 두 개뿐: 문서를 크게 만들지 말 것(1문서 ≤ 20청크), 그리고 LLM 응답 캐시를 켜서 재실행을 싸게 만들 것.
• rate limit은 임베딩과 추출이 별도 풀이다. text-embedding-3-small Tier 1 기준 3,000 RPM / 1,000,000 TPM(티어별 상이 — 계정 Limits에서 확인). 임베딩을 아무리 때려도 추출용 LLM 쿼터는 안 줄어든다.
• 워커 동시성 산정. 워커 프로세스 P × MAX_ASYNC_LLM A ≤ 공급자 동시 허용치, 그리고 P·A·(호출당 입력토큰) ÷ (호출 시간) ≤ TPM. 시작값은 P=2, A=4(동시 8). MAX_PARALLEL_INSERT는 문서 병렬도이고 공식 권장이 MAX_ASYNC_LLM의 약 1/3(기본 3)이다 — 이걸 올리면 문서 하나하나가 굶어 개별 지연이 늘어난다.

1,000건이면 얼마고 몇 시간인가

문서 평균 6,000토큰·6청크·gleaning 1회 가정. 문서당 LLM 14회, 입력 ≈40k, 출력 ≈10k.

검색 가능해지는 데 0.12달러, 그래프까지 가는 데 90달러 — 750배다. 이게 Fast/Deep을 쪼개는 경제적 근거의 전부다. 비용을 깎아야 하면 손잡이 순서는 ①gleaning 0으로(호출 절반, 재현율 하락) ②모델 티어 하향 ③FORCE_LLM_SUMMARY_ON_MERGE 끄기 ④마지막에 청크 크기 — 청크를 키우면 호출은 줄지만 추출 품질이 급격히 나빠진다. 초기 백필은 Batch API(최대 24시간, 50% 할인)가 정답이다.

마지막 함정: 백필과 정상 운영을 같은 큐로 돌리면 안 된다. 1,000건 백필이 큐를 막으면 방금 올린 문서가 3시간 뒤에 그래프에 들어간다. graph_index / graph_backfill 두 큐로 나누고 워커 풀도 분리하라. (검색 시 graph_ready가 아닌 문서를 그래프 경로에서 어떻게 다룰지는 → 라우터 섹션에서 다룸)

검색 계층에서 실제로 비싼 것은 임베딩도 SQL도 아니라 그래프다. LightRAG 의 local/global/hybrid/mix 모드는 검색 전에 LLM 으로 키워드를 뽑는 단계를 거치고, 그 한 번의 호출만으로 이미 수백 ms~수 초가 나간다. 반면 "그 설정키 뭐였지" 같은 질의는 tsvector 한 방이면 끝난다(한국어 PostgreSQL 하이브리드 검색 p50 1.79ms 실측 사례가 있다). 라우터의 임무는 "더 좋은 답을 고르는 것"이 아니라 비싼 경로를 부르지 않을 이유를 먼저 찾는 것이다.

질의 유형 6종과 라우팅 표

두 가지가 대전제와 직결된다. 첫째, 개인 경험·결정은 위키가 아니라 memory 가 1차다(원칙 ②). "왜 A 대신 B 를 골랐지"에 위키 문서를 1위로 올리면 결정의 이유가 현재 상태 서술로 조용히 대체된다 — 틀린 답이 아니라 다른 질문에 대한 답이라 사용자가 알아채기 어렵다. 둘째, 전역 요약은 온라인 예산 안에 넣지 마라. LightRAG global, GraphRAG global search 는 커뮤니티 리포트 전체를 map-reduce 로 훑는 구조라 대화형 응답 예산과 원천적으로 맞지 않는다. Deep Path 에서 미리 굽고(→ 인덱싱 섹션에서 다룸) 라우터는 캐시만 읽는다.

라우터 구현 3안

권고는 3단 계단이다. ① 정규식이 확신하면 즉시 확정 — 항해형·설정키·1인칭은 실무에서 전체 질의의 상당 비중이고 여기서 끝난다. ② 아니면 임베딩 근접. ③ 소형 LLM 분류기는 온라인 경로에서 빼고 야간 배치 라벨러로만 쓴다. 도메인이 좁으면 어휘 신호가 의미 신호를 이긴다는 게 위 벤치의 요지고, 개인 위키는 정확히 그 "좁은 도메인"이다.

# router.py — 3단 계단. 온라인 경로에 LLM 호출 없음.
import re

ENTITY = re.compile(r"[A-Za-z_][A-Za-z0-9_.]{2,}|`[^`]+`|\"[^\"]+\"")
NAV    = re.compile(r"(어디\s*(있|에)|파일|경로|문서\s*열|\.md\b)")
REL    = re.compile(r"(차이|비교|vs\b|대신|영향|왜.*(안|못)|어떻게.*연결)")
GLOBAL = re.compile(r"(전반|전체적|한눈에|정리해\s*줘|요약해\s*줘|지형)")
MEM    = re.compile(r"(우리|내가|지난번|예전에|삽질|왜.*(하기로|했지|골랐))")
FRESH  = re.compile(r"(최근|요즘|지금|현재|최신|이번\s*주|어제)")

def route(q: str, embed, centroids) -> dict:
    if NAV.search(q):  return {"route": "nav",    "why": "regex:NAV"}
    if MEM.search(q):  return {"route": "memory", "why": "regex:MEM"}
    if GLOBAL.search(q) and not ENTITY.search(q):
        return {"route": "graph_global", "why": "regex:GLOBAL,no-entity"}
    if REL.search(q) and len(set(ENTITY.findall(q))) >= 2:
        return {"route": "graph_local", "why": "regex:REL,entities>=2"}
    v = embed(q)                       # centroids: {route: 정규화된 평균벡터}
    sims = sorted(((float(v @ c), r) for r, c in centroids.items()), reverse=True)
    (top, best), (second, _) = sims[0], sims[1]
    fresh = bool(FRESH.search(q))
    if top >= 0.42 and (top - second) >= 0.05:
        return {"route": best, "why": f"emb:{top:.3f}/d{top-second:.3f}", "fresh": fresh}
    return {"route": "hybrid_default", "why": f"emb-ambiguous:{top:.3f}", "fresh": fresh}

임계값 0.42 / Δ0.05 는 인코더마다 다르다. 라벨 200건으로 직접 캘리브레이션하되, 애매하면 라우팅하지 말고 기본 하이브리드로 떨어뜨려라. 오라우팅 1건의 손해가 하이브리드 1건의 추가 지연보다 항상 크다.

융합: RRF 가 기본, 가중치는 유형별로

BM25 점수는 상한이 없고 코사인은 [-1,1] 이라 가중합은 정규화 없이 성립하지 않는다. min-max 정규화를 쓰면 같은 문서가 배치 구성에 따라 다른 점수를 받아 캐시와 회귀 테스트가 깨진다. 그래서 기본은 순위 기반 RRF: score = Σ wᵢ / (k + rankᵢ), k=60.

마지막 줄이 이 절의 핵심 실패 모드다. 한국어 FTS 가 토큰화 실패로 무의미한 매치 3건만 돌려줘도 RRF 는 그 중 하나를 1위로 대접한다. LightRAG 의 COSINE_THRESHOLD=0.2 처럼 융합 이전에 소스를 통째로 기권시키는 장치가 반드시 필요하다.

-- 단일 라운드트립 하이브리드. :w_fts/:w_vec/:w_mem 은 라우트가 결정.
-- 선행: SET LOCAL hnsw.ef_search = 100; SET LOCAL statement_timeout = '250ms';
WITH fts AS (
  SELECT id, row_number() OVER (ORDER BY ts_rank_cd(tsv, q) DESC) AS r
  FROM wiki_chunk, websearch_to_tsquery('simple', :q) q
  WHERE tsv @@ q ORDER BY ts_rank_cd(tsv, q) DESC LIMIT 50
), vec AS (
  SELECT id, row_number() OVER (ORDER BY embedding <=> :qv) AS r
  FROM wiki_chunk
  WHERE 1 - (embedding <=> :qv) >= 0.20          -- 소스별 기권 게이트
  ORDER BY embedding <=> :qv LIMIT 50
), mem AS (
  SELECT doc_id AS id, row_number() OVER (ORDER BY score DESC) AS r
  FROM memory_search(:q, :qv) WHERE score >= 0.25 LIMIT 20
)
SELECT id,
       COALESCE(:w_fts / (60 + f.r), 0)
     + COALESCE(:w_vec / (60 + v.r), 0)
     + COALESCE(:w_mem / (60 + m.r), 0)          AS rrf,
       f.r AS r_fts, v.r AS r_vec, m.r AS r_mem  -- 사후 부검용 원순위 보존
FROM fts f FULL JOIN vec v USING (id) FULL JOIN mem m USING (id)
ORDER BY rrf DESC LIMIT 20;

ts_rank_cd/tsvector 대신 진짜 BM25 를 원하면 Tiger Data 의 pg_textsearch(to_bm25query() 함수와 <@> 연산자)나 ParadeDB pg_search 로 fts CTE 만 갈아끼우면 된다 — RRF 자체는 확장 없이 순수 SQL 이다.

타임아웃 예산 1.5초와 폴백 체인

폴백은 순차 재시도가 아니라 병렬 발사 + 마감 시각 채택이다. asyncio.wait(tasks, timeout=0.25) 로 세 소스를 동시에 던지고, 마감에 살아 돌아온 것만 융합한다. 순차 체인(FTS 실패 → vector 시도 → graph 시도)은 실패마다 예산을 곱으로 먹어 p95 를 폭발시킨다. 그래프가 마감을 넘기면 취소하지 말고 백그라운드로 넘겨 결과를 캐시에 적재한다 — 같은 질의의 두 번째 시도는 공짜가 된다.

아무것도 못 찾았을 때: 후보 0건과 "저점수 후보 20건"을 반드시 다르게 다뤄라. 0건은 기권이 쉽다("위키에 없습니다" + 인접 문서 3개 + 문서 생성 링크). 위험한 쪽은 후자다 — LLM 은 무관한 청크로도 그럴듯한 답을 만든다. 융합 1위의 원점수가 하한 미만이면 컨텍스트를 아예 넘기지 말고 기권시킨다. LightRAG 는 QueryParam(mode="bypass") 로 "검색 없이 통과" 경로를 명시적으로 표현할 수 있어 이 결정을 코드에 남기기 좋다.

MCP 노출 형태(원칙 ⑤)에도 예산 얘기가 걸린다. 소스별 도구를 4~5개 따로 열면 라우팅 결정이 호스트 에이전트로 새고, 도구가 10개를 넘어가면 선택 정확도와 지연이 함께 나빠진다는 관측이 있다. wiki_search(query, hint?) 하나로 열고 라우터는 서버 안에 두되, hint 로 강제 오버라이드만 허용하는 편이 예산·재현성 양쪽에서 낫다.

라우터가 틀렸을 때: 관측·수정 루프

라우팅 결정은 재현 가능해야 한다. 최소 스키마:

CREATE TABLE query_log (
  id            bigserial PRIMARY KEY,
  ts            timestamptz NOT NULL DEFAULT now(),
  q             text        NOT NULL,
  route         text        NOT NULL,   -- nav|memory|graph_local|...
  route_reason  text        NOT NULL,   -- 'regex:MEM' | 'emb:0.51/d0.09'
  router_ver    text        NOT NULL,   -- 규칙+센트로이드 버전 핀
  sources_hit   jsonb       NOT NULL,   -- {"fts":0,"vec":50,"mem":3,"graph":null}
  ms            jsonb       NOT NULL,   -- {"route":4,"fts":31,"vec":58,"fuse":9}
  top_ids       bigint[]    NOT NULL,
  cited_ids     bigint[],               -- 답변이 실제로 인용한 것
  shadow_route  text,                   -- 야간 LLM 라벨러가 매긴 정답
  abstained     boolean     NOT NULL DEFAULT false
);
CREATE INDEX ON query_log (ts DESC) WHERE cited_ids IS NOT NULL;

여기서 지표 두 개만 뽑으면 된다.

• route_regret: cited_ids 중 선택하지 않은 소스에서만 나온 문서의 비율. 5% 를 넘으면 해당 유형의 가중치를 조정한다.
• shadow 불일치율: 야간 배치로 소형 LLM 이 같은 질의를 라벨링(온라인 경로 아님)해 route 와 대조. 불일치 건만 모아 규칙 1줄 또는 임베딩 예시 발화 1개를 추가하고 router_ver 를 올린다. 규칙을 고친 뒤 과거 로그를 재생해 회귀를 확인할 수 있는 건 오직 이 버전 핀 덕분이다.

실패 모드: 인용은 노이즈가 크다 — LLM 은 상위 문서를 습관적으로 인용하므로 route_regret 은 체계적으로 과소평가된다. 표본 200건 미만에서 가중치를 만지면 잡음을 학습한다.

한국어에서 어휘 검색이 무너지는 지점

기본 to_tsvector('simple', ...) 는 공백 기준이라 조사가 붙은 채 색인된다. "라우터가", "라우터를", "라우터는" 이 서로 다른 토큰이 되고 질의 "라우터"는 셋 중 무엇과도 매치되지 않는다. 영어의 stemmer 같은 구제책이 없다. sources_hit.fts == 0 의 대부분이 여기서 나온다.

공개 벤치마크에서 형태소 분석 계열(PostgreSQL+MeCab, Elasticsearch+nori)은 MIRACL BM25 NDCG 0.61~0.64, 유니코드 기본 토크나이저 계열은 0.36~0.41 로 갈렸다. 다만 반대편 실패도 실측돼 있다 — nori 로 과분해된 상태에서 AND 매칭을 걸면 NDCG 0.13 까지 붕괴한다. 한국어에서 AND 를 기본으로 두지 마라. websearch_to_tsquery 의 암묵적 AND 를 OR + 커버리지 부스트로 바꾸는 편이 안전하다.

라우터 관점의 결론은 불편하지만 명확하다. 토크나이저를 고치기 전까지 "사실 조회 = FTS 우선"은 한국어 위키에서 성립하지 않는다. 고치기 전에는 사실 조회 가중치도 vector 쪽에 두고, sources_hit.fts == 0 비율을 상시 대시보드에 띄워라. 이 값이 30% 를 넘으면 그건 라우팅 문제가 아니라 색인 문제이며, 라우터 가중치를 아무리 만져도 회복되지 않는다.

결론부터: 승급 트리거를 먼저 못 박는다

저장소 선택은 "무엇이 더 좋은가"가 아니라 "언제 갈아타는가"의 문제다. 대전제 ①(마크다운+PostgreSQL 이 원본, LightRAG 는 파생 인덱스)을 지키면 갈아타기 비용은 재구축 시간으로 환산되므로, 승급 기준은 감이 아니라 숫자로 정할 수 있다.

V3 를 "그래프만 분리"로 한정하는 이유는 벤치마크가 그렇게 말하기 때문이다. 43,234 엔티티/134,741 트리플 기준으로 이웃 확장(fan-out)은 Postgres 재귀 CTE 가 오히려 4배 빠르고(1홉 0.4ms vs 2.9ms, 3홉 43.7ms vs 171.5ms), 최단경로는 Neo4j 가 81~135배 빠르다(125~359ms vs 1.5~2.7ms). LightRAG 계열 검색은 대부분 "엔티티 조회 + 1홉 이웃"이라 Neo4j 로 옮겨도 이득이 없다. Neo4j 는 경로를 물을 때만 산다.

V1 — pgvector 를 실무 파라미터로 고정하기

pgvector(현행 0.8.x) 에서 실제로 만지는 손잡이는 셋뿐이다.

빌드 시간에서 사람들이 가장 자주 밟는 지뢰는 maintenance_work_mem(기본 64MB)이다. 인덱스가 여기에 안 들어가면 Postgres 가 디스크 기반 빌드로 조용히 내려앉아 수십 배 느려진다. 재구축 전에 SET maintenance_work_mem='4GB'; SET max_parallel_maintenance_workers=7; 을 세션에 박아두고, max_parallel_workers 도 같이 올려야 워커가 실제로 붙는다.

차원 2000 초과는 vector 로 인덱스를 못 만든다. text-embedding-3-large(3072d) 같은 모델을 쓰면 halfvec(최대 4000d, 차원당 4바이트→2바이트)로 캐스팅한 표현식 인덱스가 사실상 유일한 선택지다. 저장 용량은 절반이 되지만 재현율 손실은 반드시 네 데이터로 측정하라(범용 수치는 확인 필요).

-- 원본(SoT) 은 마크다운 파일 + 이 테이블. 파생 인덱스는 여기서 재생성된다.
CREATE TABLE wiki_chunks (
  id           bigserial PRIMARY KEY,
  doc_path     text NOT NULL,            -- 마크다운 원본 경로 = 진짜 키
  content_hash text NOT NULL,            -- 재구축 idempotency + LLM 캐시 키
  lang         text NOT NULL DEFAULT 'ko',
  status       text NOT NULL DEFAULT 'active',
  body         text NOT NULL,
  embedding    vector(3072),             -- 저장은 vector, 인덱스는 halfvec 캐스팅
  tsv          tsvector GENERATED ALWAYS AS (to_tsvector('simple', body)) STORED
);

-- 2000차원 초과 → halfvec 표현식 인덱스. 질의에도 '동일한 캐스팅 표현'을 써야 탄다.
CREATE INDEX ON wiki_chunks
  USING hnsw ((embedding::halfvec(3072)) halfvec_cosine_ops)
  WITH (m = 16, ef_construction = 200)
  WHERE status = 'active';               -- 부분 인덱스로 저선택도 필터 흡수

-- 저카디널리티 필터는 B-tree 로, 고카디널리티는 iterative scan 으로.
CREATE INDEX ON wiki_chunks (lang, status);

필터링 실패 모드 세 가지. (a) halfvec_cosine_ops 로 인덱스를 만들고 질의는 <->(L2)로 쓰면 인덱스를 아예 안 탄다 — opclass 와 연산자는 반드시 짝을 맞춰야 한다. (b) 표현식 인덱스는 질의문에 똑같은 embedding::halfvec(3072) 표현이 있어야 매칭된다. (c) WHERE 로 걸러낸 뒤 결과가 LIMIT 에 못 미치는 오버필터링은 0.8.0 의 hnsw.iterative_scan = strict_order | relaxed_order 로 완화하지만, hnsw.max_scan_tuples(기본 20,000) 에 걸리면 에러 없이 결과가 부족한 채로 끝난다. 조용한 실패라서 반환 건수를 로그로 세지 않으면 못 잡는다.

억 단위로 갈 계획이면 VectorChord(vchordrq) 를 검토할 값어치가 있다(RaBitQ 압축, 16 vCPU 에서 1억 벡터 인덱스 20분 이내 주장 — 벤더 벤치마크임에 유의). 다만 개인 위키 규모에서 pgvector 를 못 견딜 일은 거의 없다.

V2 — PostgreSQL 하나를 KV·vector·graph 로 동시에 쓰기

LightRAG 는 스토리지 4종을 각각 갈아끼운다. PG 단일화 설정은 다음과 같다.

# LightRAG: KV / vector / graph / doc-status 를 전부 PostgreSQL 로
LIGHTRAG_KV_STORAGE=PGKVStorage
LIGHTRAG_VECTOR_STORAGE=PGVectorStorage
LIGHTRAG_DOC_STATUS_STORAGE=PGDocStatusStorage
LIGHTRAG_GRAPH_STORAGE=PGTableGraphStorage   # AGE 대신 일반 테이블(권장)

POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DATABASE=wiki
POSTGRES_MAX_CONNECTIONS=25
POSTGRES_WORKSPACE=wiki_v3                   # ★ blue/green 재구축의 핵심

POSTGRES_VECTOR_INDEX_TYPE=HNSW_HALFVEC      # HNSW | IVFFlat | HNSW_HALFVEC | VCHORDRQ
POSTGRES_HNSW_M=16
POSTGRES_HNSW_EF=200
EMBEDDING_DIM=3072
COSINE_THRESHOLD=0.2

POSTGRES_WORKSPACE 가 이 설계의 숨은 주인공이다. 파생 인덱스를 새 워크스페이스에 통째로 재생성한 뒤 라우터의 포인터만 바꾸는 blue/green 이 가능해지고, 그게 대전제 ①을 실제 운영 절차로 만들어준다.

Apache AGE 를 쓸 것인가 — 신규라면 쓰지 마라

AGE 를 피하는 이유는 속도만이 아니다. 실제 장애 사례로, LightRAG 1.4.9.1→1.4.9.4 업그레이드 시 AGE 그래프(342,654 정점 / 815,570 엣지)에 대한 마이그레이션 Cypher 가 사실상 카테시안 곱 플랜을 타면서 17시간 이상 전면 다운타임이 발생했고, 이슈는 "not planned" 로 닫혔다. 파생 인덱스가 원본 서비스를 인질로 잡은 셈이다. 소규모에서도 3,500노드/4,500엣지에 top-k=10 검색이 3~5분 걸린다는 보고가 있다.

PG 기반 그래프의 진짜 한계는 다중 홉이다. 재귀 CTE 는 홉마다 중간 결과가 지수적으로 불어나 실무상 3~4홉이 상한이고 5홉 이상은 초 단위~타임아웃으로 무너진다. AGE 도 결국 재귀 SQL 로 번역되므로 같은 폭발을 문법만 예쁘게 감싼 것이다. 반대로 말하면, 검색이 "엔티티 조회 + 1홉 이웃"에 머무는 한 PG 로 충분하다. PostgreSQL 19 에 SQL/PGQ(GRAPH_TABLE, CREATE PROPERTY GRAPH)가 커밋되어 표준 문법이 생기지만, 옵티마이저가 재귀 확장을 어떻게 푸는지는 여전히 미지수라 "문법 개선"이지 "성능 승급"으로 계산하지 마라.

한국어 FTS — 기본 tokenizer 는 쓰면 안 된다

Postgres 기본 파서는 한국어에 형태소 개념이 없다. to_tsvector('simple', ...) 은 공백으로만 자르므로 "위키에"와 "위키"가 다른 토큰이 되고, 조사가 붙는 순간 리콜이 0 이 된다.

선택 기준(단일 노드 개인 위키 기준). ① 문서 5만 건 미만 + 운영 단순함이 최우선 → pg_bigm. 크래시 세이프가 백업 정책을 단순하게 만든다. ② 랭킹·스니펫이 검색 품질에 직결(라우터가 FTS 결과를 vector 결과와 섞어 재정렬 — → 라우터 설계는 다른 섹션에서 다룸) → pg_search. ③ PGroonga 는 속도는 최고지만 "장애 후 REINDEX"라는 운영 부채를 받아들일 때만. mecab 계열은 이미 mecab 파이프라인을 운영 중인 경우가 아니면 신규로 들이지 마라.

백업·마이그레이션·재구축 — 원본과 파생을 다르게 다룬다

• 원본: 마크다운 파일(git) + wiki_chunks 의 doc_path/content_hash/body. pg_dump -Fc 로 논리 백업, 용량이 작아 시간당 스냅샷이 부담 없다.
• 파생: 임베딩 컬럼, LightRAG 의 lightrag_* 테이블, HNSW 인덱스. 원칙적으로 백업 불필요 — 다만 여기서 대전제 ①에 단서를 달아야 한다.

대전제는 "LightRAG 는 언제든 통째로 재생성 가능"이라 말하지만, 재생성이 무료라는 뜻은 아니다. 엔티티/관계 추출은 입력 1,000단어당 약 1,200토큰의 LLM 호출을 태운다. 문서 5,000건 규모면 전량 재구축은 돈과 시간이 모두 드는 작업이다. 그래서 실무 규칙은 이렇게 갈린다.

1. LLM 캐시 테이블은 파생이지만 백업한다. 캐시가 살아 있으면 그래프 재구축이 LLM 호출 없이 진행된다. 단 청킹 파라미터나 모델을 바꾸면 캐시는 무효라고 가정하고 일정을 잡아라.
2. 임베딩은 백업하고 인덱스는 버린다. 임베딩 재계산은 API 비용, 인덱스 재생성은 CPU 시간이다. pg_dump 대상에서 인덱스를 빼고 복원 후 병렬 빌드로 다시 만드는 편이 덤프 크기·복원 시간 모두 유리하다. "데이터 적재 후 인덱스 생성" 순서는 pgvector 공식 권고이기도 하다.
3. 재구축은 in-place 로 하지 않는다. POSTGRES_WORKSPACE 를 바꿔 새 워크스페이스에 만들고, 건수·샘플 질의 회귀를 확인한 뒤 포인터를 돌린다. 위 17시간 다운타임 사례가 정확히 "in-place 마이그레이션이 원본 서비스를 막는" 실패 모드다.

재구축 예산 체크리스트(각 항목을 실제로 재보고 표에 적어둘 것): 임베딩 재계산 시간·비용 / 그래프 추출 LLM 시간·비용(캐시 히트율 포함) / HNSW 병렬 빌드 시간(1M×1536d ≈ 10분대가 기준선) / FTS 인덱스 빌드 시간 / 전체 합이 6시간을 넘으면 V2 의 승급 트리거가 켜진 것이다. 그때 할 일은 Neo4j 도입이 아니라, 먼저 재구축을 증분화하고 워크스페이스 blue/green 을 자동화하는 것이다.

프론트매터는 메타데이터가 아니라 인덱스 계약이다

프론트매터를 "렌더링에 안 쓰이는 장식"으로 두면 검색 품질은 청킹이나 임베딩 모델이 아니라 필드 누락에서 무너진다. 파서·인덱서·라우터가 공유하는 유일한 타입 시그니처이기 때문이다. 각 필드는 반드시 소비처가 하나 이상 있어야 하고, 소비처가 없는 필드는 지운다.

필드명은 되도록 공개 스펙에 맞춘다. Google Cloud의 Open Knowledge Format(OKF) v0.2 는 type 만 필수로 두고 title/description/tags/sources 를 권장하며, status 기본값을 stable 로, 만료를 stale_after 로, 검증 이력을 verified: [{actor, at}] 로 정의한다. Obsidian 계열 도구를 뷰어로 쓴다면 예약어인 tags/aliases/cssclasses 는 반드시 리스트여야 하고, 1.9부터 단수형(tag, alias)은 인식되지 않는다.

트레이드오프: 필드가 늘수록 작성 마찰이 커져 빈 값이 늘고, 더 위험하게는 고카디널리티 필드로 사전 필터를 걸면 ANN recall 이 조용히 무너진다. pgvector HNSW 는 그래프를 걸은 뒤 필터를 적용하므로, 선택도 10% 조건에 hnsw.ef_search=40 이면 평균 4행만 살아남는다. 0.8.0의 iterative scan(hnsw.iterative_scan, hnsw.max_scan_tuples)이 완화해 주지만 CPU와 테일 레이턴시를 판다. 규칙은 하나다 — 필터는 저카디널리티(status, tags, type)만. updated 같은 건 필터가 아니라 정렬·후처리로.

---
id: 01JQ8F3K2M7X9V4B6N0PQRSTUV      # ULID, 불변. 파일이 어디로 가든 유지
type: decision                       # concept | decision | runbook | incident
title: 벡터 인덱스로 pgvector 를 선택한 이유
aliases: [pgvector 결정, why-pgvector, ADR-014]
tags: [postgres, vector-search, adr] # 저카디널리티만
status: stable                       # draft | stable | deprecated
created: 2026-03-11
updated: 2026-08-02
confidence: 0.8                      # <0.6 이면 그래프 인덱싱 제외
sources:
  - url: https://github.com/pgvector/pgvector
    retrieved: 2026-08-02
superseded_by: null                  # status=deprecated 면 필수
---

> **TL;DR** — 별도 벡터 DB 대신 pgvector 를 쓴다. 트랜잭션 하나로
> 원본·청크·임베딩을 함께 커밋할 수 있고, 재색인이 곧 `DELETE`+`INSERT` 다.

ID는 신원, 파일 경로는 주소

OKF v0.2는 concept ID를 "번들 내 파일 경로에서 .md 를 뗀 것"으로 정의한다. 번들 자족성 면에서는 옳지만 개인 위키에는 치명적이다. 리팩터링이 잦은데 파일을 옮기는 순간 ID가 바뀌고, 인덱서 입장에선 삭제+생성으로 보여 청크·엣지·백링크가 통째로 재계산되며 Agent Memory 가 걸어둔 참조가 끊긴다.

처방은 이중 키다. 불변 id(ULID) + 가변 slug(경로 파생). DB FK·그래프 노드·메모리 참조는 id, 사람이 읽는 URL과 [[링크]]는 slug.

둘을 동시에 유지하면 동기화 버그라는 새 실패 모드가 생긴다. 하나만 정본으로 두고 나머지는 파생으로 계산하라. 그리고 사람이 id 를 복붙하다 중복시키면 PK 충돌이 아니라 upsert 경로에서 조용한 덮어쓰기가 난다 — CI에서 id 유일성 검사는 선택이 아니다.

[[위키링크]] 는 해소 실패가 기본값이다

해소 순서를 코드로 못 박아라: ①[[id:01JQ...]] 직접 참조 → ②정확한 경로 → ③파일명(확장자 제외·대소문자 무시) → ④정규화(공백/-/_ 동일 취급) → ⑤aliases 역인덱스 → ⑥실패 시 unresolved 로 기록.

뷰어에 위임하지 마라. Obsidian 1.12.7 기준으로도 프론트매터 aliases 는 자동완성엔 뜨지만 링크 리졸버(getFirstLinkpathDest)가 참조하지 않는 사례가 보고돼 있다. 즉 앨리어스 해소는 파이프라인이 직접 해야 한다. JS 스택이면 mdast-util-wiki-link / remark-wiki-link 가 permalinks 배열로 기존/신규를 구분하고 pageResolver 로 permalink 를 계산하며 [[Real Page:Page Alias]] 형태를 파싱한다.

해소 결과는 반드시 테이블로 떨어뜨린다 — links(src_id, dst_id, raw, resolved bool). 백링크, 고아 탐지, 그래프 재생성이 전부 이 테이블 하나에서 나온다. LightRAG 인덱스는 언제든 통째로 날려도 되지만, 링크 테이블은 마크다운에서 결정적으로 재생성되므로 파생이 아니라 원본 층에 속한다(라우팅에서의 활용은 → 다른 섹션).

실패 모드: unresolved 링크를 CI 에러로 막으면 위키가 자라지 않는다. OKF 도 "Consumers MUST tolerate broken links" 라고 명시한다. 막지 말고 계측하라 — unresolved 비율이 5%를 넘으면 리포트만.

문서 구조를 그대로 청킹 경계로

from langchain_text_splitters import MarkdownHeaderTextSplitter

HEADERS = [("#", "h1"), ("##", "h2"), ("###", "h3")]
TARGET, HARD_MAX, OVERLAP = 480, 512, 64   # 토큰 기준

def chunk(md: str, doc_title: str, count):          # count = 토크나이저
    # strip_headers=False: 헤딩 텍스트를 청크 안에 남긴다(공짜 문맥)
    for sec in MarkdownHeaderTextSplitter(HEADERS, strip_headers=False).split_text(md):
        crumb = " > ".join([doc_title, *[sec.metadata.get(k, "") for k in
                                         ("h1", "h2", "h3") if sec.metadata.get(k)]])
        for body in soft_split(sec.page_content, count):
            yield f"[{crumb}]\n{body}"              # 프리픽스 = contextual embedding

def soft_split(text: str, count):
    buf, blocks = [], atomic_blocks(text)  # 표/코드펜스는 쪼개지 않고 통째 반환
    for b in blocks:
        if count("\n".join(buf + [b])) > HARD_MAX and buf:
            yield "\n".join(buf)
            buf = tail_tokens(buf, OVERLAP)        # 오버랩은 블록 경계에서만
        buf.append(b)
    if buf:
        yield "\n".join(buf)

핵심은 두 인덱스의 청크 크기가 달라야 한다는 것이다. 벡터/FTS는 정밀도(≈512), 그래프 추출은 관계 문맥(≈1200). 하나로 통일하려는 유혹이 실패 모드다.

LLM이 읽기 좋은 본문 형태

• 요약을 맨 위에. 첫 청크가 사실상 문서 대표 벡터가 된다. 결론을 학술 논문처럼 맨 끝에 두면 결론 청크에 주어가 없다.
• 정의 문장 한 줄. "X는 Y이다" 형태. 대명사와 "위에서 말한" 금지 — 청크는 문맥 없이 홀로 읽힌다.
• ## Findings / ## Open Questions. 헤딩 기반 청킹에서 이 둘은 자동으로 독립 청크가 된다. Findings는 confidence 를 올리는 근거 창구, Open Questions는 Agent Memory 승격의 타깃이 된다(→ 다른 섹션).

Git 규약

오염 안티패턴과 CI 체크리스트

제목 중복은 리랭커가 두 문서를 같은 것으로 보게 만들어 둘 다 top-k를 먹고 정답을 밀어낸다. 고아 문서는 프로젝트가 끝난 뒤에도 남아 영구히 검색 결과를 오염시킨다. 만능 문서는 헤딩 30개짜리 God doc이라 어떤 질의에도 애매하게 걸리고 정확히는 안 걸린다. 셋 다 사람 리뷰로는 못 잡으므로 게이트로 만든다.

1. id ULID 형식 + 전역 유일 (중복은 upsert에서 조용한 덮어쓰기)
2. title + aliases 정규화 후 유일 (대소문자·공백 제거 비교)
3. status=deprecated 면 superseded_by 필수, 인덱싱에서 제외
4. unresolved 링크 비율 < 5% (초과 시 실패가 아니라 리포트)
5. 인바운드 링크 0 + 90일 무수정 → orphan 리포트
6. 단일 문서 > 4,000 tok 또는 H2 > 12개 → split 후보
7. sources 가 비었는데 confidence > 0.7 이면 커밋 거부

python-frontmatter(frontmatter.parse() → (metadata, content))로 읽고 Pydantic 모델 하나에 이 규칙을 담아 pre-commit에서 돌리면 200줄이 안 된다. 이 게이트가 없으면 위 계약은 전부 위키의 주석일 뿐이다.

원본과 파생을 코드가 아니라 스키마 레벨에서 갈라놓지 않으면, 두 달 뒤 "이 임베딩은 어느 버전 문서에서 나온 거지?"에 답할 수 없게 된다. 이 섹션은 그 경계를 테이블·키·인덱스로 못 박는 방법을 다룬다.

테이블 지도: 무엇이 원본이고 무엇이 버려도 되는가

여기서 대전제 ①을 한 군데 수정한다. "LightRAG는 언제든 재생성 가능한 파생"은 맞지만, embeddings는 재생성이 무료가 아니다. 그래서 임베딩만은 파생 스키마에 두되 백업은 뜬다. 대신 PK를 chunk_id가 아니라 (content_hash, model)로 잡으면, 문서 리네임·목차 이동·문단 순서 교체에서 재임베딩이 0건이 된다.

코어 DDL

CREATE TABLE pages (
  id           uuid PRIMARY KEY DEFAULT uuidv7(),   -- PG18 내장
  slug         text        NOT NULL,
  title        text        NOT NULL,
  body_md      text        NOT NULL,
  frontmatter  jsonb       NOT NULL DEFAULT '{}',
  content_hash bytea       NOT NULL,                -- sha256(body_md || frontmatter)
  version      bigint      NOT NULL DEFAULT 1,      -- 낙관적 잠금 카운터 = ETag
  updated_at   timestamptz NOT NULL DEFAULT now(),
  deleted_at   timestamptz,                         -- soft delete
  purge_after  timestamptz,                         -- tombstone 만료 시각
  fts tsvector GENERATED ALWAYS AS (
    setweight(to_tsvector('simple', coalesce(title,'')),   'A') ||
    setweight(to_tsvector('simple', coalesce(body_md,'')), 'B')
  ) STORED                                          -- PG18: STORED 생략 금지
);

CREATE UNIQUE INDEX pages_slug_live ON pages (slug) WHERE deleted_at IS NULL;
CREATE INDEX pages_fts_gin  ON pages USING gin (fts);
CREATE INDEX pages_dirty    ON pages (updated_at) WHERE deleted_at IS NULL;

CREATE TABLE page_revisions (
  page_id      uuid   NOT NULL REFERENCES pages(id) ON DELETE CASCADE,
  version      bigint NOT NULL,
  body_md      text   NOT NULL,        -- 전문 저장 (TOAST + lz4)
  content_hash bytea  NOT NULL,
  op           text   NOT NULL,        -- create|edit|promote|revert|delete
  memory_id    uuid,                   -- promote 인 경우 출처 메모리
  author       text   NOT NULL,
  created_at   timestamptz NOT NULL DEFAULT now(),
  PRIMARY KEY (page_id, version)
);

PG18 함정: 18부터 GENERATED ALWAYS AS (...)는 키워드를 생략하면 VIRTUAL이 기본이다. 게다가 virtual 컬럼은 사용자 정의 함수·타입을 참조할 수 없어서, 한국어 tokenizer 계열(textsearch_ko의 mecab 설정 등)을 넣는 순간 생성 자체가 실패한다. STORED를 항상 명시하라.

한국어 FTS는 기본 설정으로 안 된다. simple/english 파서는 "지식그래프를"을 한 토큰으로 잡아 "지식그래프" 검색에 안 걸린다. 선택지는 두 개다: pg_bigm(2-gram, 설치 쉬움·인덱스 큼·짧은 질의에 노이즈) 또는 textsearch_ko(mecab-ko-dic 형태소, 품질 우위·서버에 사전 설치 필요). 개인 위키라면 pg_bigm + trigram으로 시작하고, 재현율이 문제가 될 때 mecab으로 올리는 편이 회수가 빠르다.

인덱스 결정표

재인덱싱 판단: 해시 3계층

updated_at만 보면 오탐(포맷터만 돌려도 갱신)이 나고, 문서 해시만 보면 8KB 문서의 한 줄 수정에 전 청크를 다시 임베딩한다. 계단식으로 판단한다.

1. pages.content_hash 불변 → 전 파이프라인 skip.
2. 변경 시 재청킹 후 청크별 content_hash 비교 → 바뀐 청크만 통과. 편집 1회당 재임베딩이 보통 1~2청크로 줄어든다.
3. embeddings PRIMARY KEY (content_hash, model)에 ON CONFLICT DO NOTHING → 이미 있으면 API 호출 0.

모델 교체는 마이그레이션이 아니라 model 값이 다른 행을 추가하는 일이다. 두 모델을 동시에 유지한 채 검색 품질 A/B를 돌리고, 확정된 뒤에 DELETE ... WHERE model = 'old'로 정리한다.

soft delete와 tombstone

deleted_at만으로는 부족하다. 파생 인덱스(LightRAG 그래프, 벡터)에 이미 들어간 내용을 지웠다는 사실 자체를 전파해야 하기 때문이다. 삭제는 ① pages.deleted_at 설정 → ② page_revisions에 op='delete' 한 행 → ③ 아웃박스에 page.deleted 이벤트(소비자가 delete_by_doc_id 계열 호출) → ④ purge_after = now() + 30 days 후 하드 삭제, 4단계다. purge_after가 없으면 tombstone이 영구 누적되고, purge_after만 있고 이벤트가 없으면 삭제한 문서가 검색 결과에 계속 뜬다 — 실제로 가장 흔한 사고다.

리비전: diff 말고 전문 저장

PostgreSQL은 행이 약 2KB(TOAST_TUPLE_THRESHOLD)를 넘으면 자동으로 압축·아웃오브라인 저장한다. 압축기는 PG14부터 default_toast_compression으로 선택 가능하고 lz4가 쓰인다(배포판 기본값은 직접 확인할 것). 즉 텍스트 위키에서 diff 저장은 대개 조기 최적화다. 실제 비용은 SELECT pg_column_size(body_md) FROM page_revisions로 5분이면 측정된다. diff가 정당해지는 건 리비전/문서 비가 100:1을 넘는 협업 위키뿐이다.

FastAPI 라우트

승격을 내부적으로 PUT 경로에 태우는 게 핵심이다. 그래야 승격된 문장도 리비전(op='promote', memory_id)을 남기고, 나중에 "이 문장 왜 여기 있지?"를 기억까지 역추적할 수 있다.

@router.put("/pages/{slug}")
async def update_page(
    slug: str, body: PageIn,
    db: AsyncSession = Depends(get_db),
    principal: Principal = Depends(require_scope("wiki:write")),
    if_match: Annotated[str | None, Header(alias="If-Match")] = None,
) -> PageOut:
    if if_match is None:
        raise HTTPException(428, "If-Match required")      # RFC 6585
    row = (await db.execute(
        update(Page)
        .where(Page.slug == slug,
               Page.deleted_at.is_(None),
               Page.version == parse_etag(if_match))
        .values(body_md=body.md, content_hash=sha256(body.md),
                version=Page.version + 1, updated_at=func.now())
        .returning(Page)
    )).scalar_one_or_none()
    if row is None:
        raise HTTPException(412, "stale version")          # RFC 9110 §13.1.1
    db.add(Revision(page_id=row.id, version=row.version, body_md=body.md))
    db.add(Outbox(topic="page.updated",
                  payload={"page_id": str(row.id), "version": row.version}))
    await db.commit()          # ← 커밋 전에는 누구에게도 알리지 않는다
    return PageOut.model_validate(row)

If-Match는 강한 validator를 요구하므로 W/"..."를 쓰면 안 된다. ORM 매핑을 쓴다면 SQLAlchemy version_id_col이 같은 일을 해주고 불일치 시 StaleDataError를 던지지만, 위처럼 UPDATE ... WHERE version = ? RETURNING이 왕복 1회로 끝나고 412 변환도 명시적이다.

스트리밍: FastAPI 0.135.0부터 from fastapi.sse import EventSourceResponse, ServerSentEvent가 내장이라 sse-starlette 의존성이 필요 없다(현재 0.141.1). 다만 SSE 핸들러가 DB 세션을 잡은 채 수 분간 살아 있으면 커넥션 풀이 마른다 — 잡 상태 스트림은 풀에서 빌린 세션을 폴링 주기마다 반납하도록 짜라.

아웃박스: "DB 커밋 후 큐 발행"

규칙 하나. HTTP 핸들러는 브로커를 직접 호출하지 않는다. 같은 트랜잭션에 outbox 행을 넣고 커밋하면, 이벤트는 비즈니스 행이 존재할 때에만 존재한다. 릴레이는 별도 프로세스:

SELECT ... FROM outbox WHERE published_at IS NULL ORDER BY id FOR UPDATE SKIP LOCKED LIMIT 100

SKIP LOCKED는 잠긴 행을 기다리지 않고 건너뛰므로 워커를 수평 확장해도 서로 막지 않는다. 다만 "동시 실행 N개 제한" 같은 전역 제약은 SKIP LOCKED로 못 지킨다 — 그건 pg_advisory_xact_lock이 필요하다.

LISTEN/NOTIFY는 웨이크업 신호로만 써라. 페이로드 상한 8000바이트, 큐 8GB, 리스너가 끊긴 동안의 알림은 그냥 사라지고, transaction-mode PgBouncer 뒤에서는 LISTEN이 아예 깨진다. 알림을 유실해도 릴레이의 주기 폴링이 결국 집어가는 구조여야 한다. 브로커를 따로 두기 싫으면 pgmq 확장이 가시성 타임아웃까지 얹어준다.

Alembic 운영 (1.19.1)

• HNSW 인덱스는 데이터가 찬 뒤에 만든다. pgvector 문서 권고이자, 빈 테이블에 만든 그래프는 품질이 나쁘다. 마이그레이션에서는 with op.get_context().autocommit_block(): 안에서 postgresql_concurrently=True로 생성한다(CREATE INDEX CONCURRENTLY는 트랜잭션 안에서 불가).
• ⚠️ asyncpg 드라이버로 마이그레이션을 돌리면 autocommit_block이 멈춰버리는 사례가 보고돼 있다. 런타임은 asyncpg, 마이그레이션 커넥션만 psycopg로 분리하는 게 안전하다.
• 빌드 전에 maintenance_work_mem 상향 + max_parallel_maintenance_workers(기본 2) 상향. 이걸 안 올리면 수십만 벡터에서 인덱스 빌드가 시간 단위로 늘어진다.
• env.py에 transaction_per_migration=True.
• 파생 테이블은 Alembic의 관할이 아니다. 청커 버전이 바뀌면 마이그레이션이 아니라 TRUNCATE chunks + 전량 재큐잉이다. 스키마 버전과 파이프라인 버전을 한 개념으로 묶으면 롤백이 불가능해진다.

체크리스트: ①생성 컬럼에 STORED 명시 ②slug 유일성은 WHERE deleted_at IS NULL 부분 인덱스 ③임베딩 PK는 (content_hash, model) ④쓰기 라우트는 If-Match 없으면 428 ⑤브로커 호출은 커밋 뒤 릴레이에서만 ⑥삭제는 tombstone + 이벤트 + purge_after 3종 세트.

프리미티브 3종을 위키에 겹치기

MCP 서버가 노출하는 건 세 가지뿐이다. Tools(모델이 스스로 골라 호출), Resources(호스트 앱이 컨텍스트에 넣을지 결정), Prompts(사용자가 명시적으로 고름). 스펙이 못 박은 건 "누가 트리거하느냐"지 "무엇이 들었느냐"가 아니다 — Prompts 페이지는 "This refers to who decides when the prompt is used, not who authors its content" 라고 명시한다.

실무 결론: 정본 원문은 Tool과 Resource 양쪽에 이중 노출한다. 리소스는 사람이 붙이는 첨부, 툴은 에이전트가 쓰는 경로. 둘이 같은 wiki://page/{path} URI를 가리키게 하고, wiki_search 결과에는 resource_link 콘텐츠 블록으로 그 URI를 실어 보낸다(스펙이 툴 결과에 허용하는 타입). 리소스에만 걸면 에이전트 경로가 조용히 죽는다 — 예외도 로그도 없이.

툴 표면: 10개로 접는다

수치부터. Anthropic 문서 기준 GitHub·Slack·Sentry·Grafana·Splunk 정도의 흔한 조합이 작업 시작 전에 약 55k 토큰을 정의만으로 먹고, 툴 30~50개를 넘으면 선택 정확도가 떨어지기 시작한다. 그래서 book_list/book_add/book_update/book_note로 펼치지 말고 book_search + book_get + 쓰기 하나로 접는다. 네임스페이스는 접두어로: wiki_ / knowledge_ / memory_ / book_ — tool search의 정규식·BM25가 이 접두어 하나로 그룹 전체를 잡는다.

knowledge_search의 mode는 LightRAG QueryParam.mode 값을 그대로 노출한다(naive/local/global/hybrid/mix). 값을 직접 뚫어두면 라우터가 틀렸을 때 에이전트가 스스로 교정할 수 있다.

에러 규약은 스펙에 이분법이 있다. 툴 실행 오류(입력 검증, 페이지 없음, base_sha 충돌)는 isError: true + 사람이 읽는 문장 — 모델이 self-correct 한다. 프로토콜 오류(없는 툴, CallToolRequest 스키마 위반)만 JSON-RPC error(-32602). 2026-07-28에서 리소스 not-found도 -32002 → -32602로 바뀌었다. 실패 모드: 404를 JSON-RPC error로 던지면 모델은 "툴이 고장났다"로 읽고 재시도를 포기한다. 반대로 인증 실패를 isError로 감싸면 모델이 영원히 재시도한다.

annotations 기본값이 함정이다. destructiveHint 기본 true, openWorldHint 기본 true, readOnlyHint 기본 false. 즉 읽기 툴에 readOnlyHint=True를 안 붙이면 클라이언트는 그 툴을 파괴적·개방형으로 간주해 매번 확인을 띄운다. 동시에 스펙은 클라이언트에게 "tool annotations를 신뢰할 수 없는 서버로부터는 믿지 말라" 고 경고한다 — annotations는 UX 힌트지 보안 장치가 아니다.

# pip install "mcp>=2.0.0" — v2 는 타입이 별도 패키지(mcp-types)로 분리됐다
from mcp.server.mcpserver import MCPServer   # v1: mcp.server.fastmcp.FastMCP
from mcp_types import ToolAnnotations        # v1: mcp.types (v2 에는 mcp/types.py 가 없다)
from pydantic import BaseModel, Field

mcp = MCPServer("wiki")
RO = ToolAnnotations(readOnlyHint=True, destructiveHint=False,
                     idempotentHint=True, openWorldHint=False)

class Hit(BaseModel):
    path: str
    uri: str = Field(description="wiki://page/{path} — 전문은 wiki_get_page 로")
    title: str
    updated_at: str
    score: float
    snippet: str = Field(description="≤400자 발췌, 매치 하이라이트 포함")

class SearchOut(BaseModel):
    route: str = Field(description="fts|vector|graph — 라우터가 실제로 고른 백엔드")
    hits: list[Hit]
    total: int
    next_cursor: str | None = None

@mcp.tool(annotations=RO, meta={"anthropic/maxResultSizeChars": 60000})
async def wiki_search(query: str, k: int = 8, cursor: str | None = None,
                      response_format: str = "concise") -> SearchOut:
    """마크다운 위키 원본(Source of Truth)을 검색한다. 파생 인덱스가 아니라 정본이다.
    쓸 때: "우리가 X를 어떻게 하기로 했지", 런북/결정/파일 찾기.
    쓰지 말 것: 개념 간 관계 추론은 knowledge_graph, 지난 세션의 경험은 memory_search.
    질의는 자연어 문장 그대로. 반환은 발췌뿐이므로 전문이 필요하면 uri 로 wiki_get_page.
    """

@mcp.tool()  # 쓰기 툴: 비워두면 destructiveHint/openWorldHint 가 true 로 간주된다
async def wiki_update_page(path: str, body_md: str, base_sha: str, message: str) -> dict:
    """위키 페이지를 갱신한다. base_sha 불일치면 isError 로 현재 sha 를 돌려준다."""

description은 문서가 아니라 라우터 입력이다. tool search의 regex·BM25는 이름·설명·인자명·인자 설명 전부를 훑는다. 그래서 "쓰지 말 것" 줄이 실제로 오라우팅을 줄인다 — 특히 wiki_search와 memory_search처럼 표면이 비슷한 쌍에서.

응답 크기: 상한을 모르면 잘린다

wiki_search는 발췌 400자 + uri만 반환하고 전문은 별도 호출로 민다. response_format: "concise" | "detailed"는 Anthropic 자체 측정에서 concise가 detailed의 약 1/3 토큰이었다. 실패 모드는 양쪽에 있다. 요약만 반환하면 근거가 소실되므로 hit마다 path + updated_at + uri를 반드시 실어 원본 회귀가 1콜이어야 하고, 반대로 전문을 그냥 반환하면 상한에 걸려 디스크로 밀리고 파일 참조로 대체되어 모델이 내용을 아예 못 본다.

쓰기 툴: 승인은 서버에서 건다

클라이언트 승인 UI에만 기대면 안 되는 이유는 위와 같다 — annotations는 힌트고, 다른 에이전트는 다른 UI를 쓴다. 2026-07-28의 MRTR로 서버가 직접 게이트를 건다: tools/call이 resultType: "input_required" + inputRequests(안에 elicitation/create) + requestState를 반환하고, 클라이언트가 inputResponses를 실어 새 request id로 재시도한다.

-- 승인 게이트와 감사 로그를 서버 쪽 테이블 하나로 합친다
CREATE TABLE mcp_audit (
  id            bigserial PRIMARY KEY,
  ts            timestamptz NOT NULL DEFAULT now(),
  actor         text NOT NULL,        -- 토큰 클레임(sub). 툴 인자로 받지 않는다
  client        text,                 -- _meta 의 io.modelcontextprotocol/clientInfo
  tool          text NOT NULL,
  args_hash     text NOT NULL,        -- sha256(canonical_json(arguments))
  target_path   text,
  base_sha      text,                 -- 낙관적 잠금 근거
  decision      text NOT NULL
                CHECK (decision IN ('auto','approved','denied','expired')),
  request_state text,                 -- MRTR 재시도 상관키(서명된 불투명 문자열)
  result_sha    text,
  latency_ms    int
);
CREATE INDEX ON mcp_audit (target_path, ts DESC);
CREATE INDEX ON mcp_audit (actor, ts DESC);

실패 모드: requestState를 서버 메모리에 두면 라운드로빈 뒤에서 깨진다 — 세션이 없으니 재시도가 다른 인스턴스로 간다. 서명된 불투명 문자열로 만들어 클라이언트가 들고 다니게 하라. 그리고 승인 게이트를 모든 쓰기에 걸면 사람이 지쳐서 전부 승인하게 된다. wiki_update_page는 base_sha 일치 + 변경 라인 수 임계 이하면 auto로 통과시키고, 신규 생성·대량 삭제·memory_save → wiki 승격만 사람에게 올리는 게 실제로 굴러간다.

전송과 인증 — 그리고 세션이 사라진 사양

2026-07-28 개정(현행 최신)은 프로토콜 레벨 세션을 통째로 없앴다: initialize/notifications/initialized 제거, Mcp-Session-Id 헤더 제거(SEP-2567/2575), GET SSE 스트림 제거(→ subscriptions/listen), Last-Event-ID 재개 제거, server/discover 필수. 모든 POST가 MCP-Protocol-Version·Mcp-Method 헤더를 달아야 하고(Mcp-Name 은 tools/call·resources/read·prompts/get 한정), 헤더가 본문 _meta와 어긋나면 400 + -32020 (HeaderMismatch). 대신 스펙은 "호출 간 상태가 필요하면 서버가 명시적 핸들을 반환하고 그걸 평범한 툴 인자로 받아라" 고 못 박는다. 위키에선 검색 커서와 편집 드래프트 ID가 그 핸들이고, 스펙 표현대로 핸들은 이름이지 권한이 아니므로 매 호출 권한을 재검증해야 한다.

인증은 RFC 9728 Protected Resource Metadata 필수(401의 WWW-Authenticate에 resource_metadata), 클라이언트는 RFC 8707 resource 파라미터 필수, 서버는 audience 검증 필수, 받은 토큰을 업스트림으로 흘리는 token passthrough는 금지. 로컬 HTTP라도 Origin 검증 실패 시 403과 127.0.0.1 바인딩은 스펙 강제다(DNS rebinding).

한 서버, 여러 에이전트

클라이언트 쪽은 각자 다르다. Claude Code는 claude mcp add --transport http wiki --scope project <url> + .mcp.json(${VAR:-default} 확장), 툴은 mcp__wiki__wiki_search로 노출되고 이 이름이 그대로 퍼미션 규칙 키다. Codex는 ~/.codex/config.toml의 [mcp_servers.wiki]에 url + bearer_token_env_var.

서버 쪽 격리 근거는 스펙에 있다: tools/list 결과는 커넥션별로 달라지면 안 되지만, 제시된 authorization에 따라 달라지는 건 허용된다 — "credentials are per-request input, not connection state." 따라서 agent_id/scope_id를 툴 인자로 받지 마라. 토큰 클레임에서 뽑아라. 인자로 받는 순간 모델이 문자열 하나로 남의 메모리 네임스페이스를 읽고, "위키는 공유·메모리는 사적"이라는 전제가 그 한 줄에서 무너진다.

트레이드오프는 정직하게: 토큰별 격리는 "Codex 세션에서 만든 결정을 Claude Code가 못 본다"를 뜻한다. 그래서 층을 나눈다 — 위키는 cacheScope: "public"으로 공용, 메모리는 에이전트별 네임스페이스, 승격(→ 다른 섹션에서 다룸)을 통과한 것만 공용으로 넘어간다.

출항 전 체크리스트

• 읽기 툴 전부에 readOnlyHint=True — 안 붙이면 destructive로 간주된다
• 툴 10개 초과 시 접두어 네임스페이스 + 지연 로딩 전제로 설계
• 모든 목록 반환에 next_cursor, 모든 검색 hit에 원본 uri
• 25k 토큰 상한을 넘길 툴에는 _meta["anthropic/maxResultSizeChars"]
• 쓰기 툴은 base_sha 낙관적 잠금 + mcp_audit 행 + 임계 초과 시에만 MRTR 승인
• agent_id는 토큰 클레임에서만, 인자로는 절대 받지 않기

Agent Memory 는 위키의 초안 보관소가 아니다. 위키는 "무엇이 참인가"를, 메모리는 "우리가 무엇을 겪었고 무엇을 정했는가"를 담는다. 그리고 여기서 이 글의 대전제 ①이 한 군데 깨진다 — LightRAG 인덱스는 마크다운에서 통째로 재생성되지만, 메모리의 원본(세션 대화)은 이미 휘발됐다. 메모리 저장소는 파생 인덱스가 아니라 두 번째 원본이고, 따라서 위키와 별도의 백업·마이그레이션·삭제 정책을 가져야 한다. 파생 인덱스처럼 취급해 "언제든 재생성"이라고 적어두면, 마이그레이션 실패 시 조용히 전부 잃는다.

다섯 타입, 다섯 수명

타입을 나누는 이유는 분류학 취미가 아니라 무효화 규칙과 반감기가 타입마다 다르기 때문이다. 한 테이블에 다 넣되 kind 로 정책을 분기한다.

실패 메모리에 "오진"을 같이 적는 게 핵심이다. 다음 세션이 같은 잘못된 가설로 3시간 태우는 걸 막는 건 정답이 아니라 기각된 가설이다. 반대로 실패 메모리는 재발 방지 문구가 없으면 그냥 푸념이 되어 검색 노이즈가 된다 — evidence 가 비어 있는 실패 행은 인덱싱하지 않는 게 낫다.

자동 캡처는 raw 티어에만 쓴다

Claude Code 훅으로 무료로 얻을 수 있는 캡처 지점은 SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, PreCompact/PostCompact, SubagentStart/SubagentStop, Stop, SessionEnd 등이다. 여기서 실무적으로 중요한 제약이 하나 있다: 훅 타임아웃 기본값이 일반 600초, UserPromptSubmit 30초인데 SessionEnd 훅은 전체 예산이 1.5초다. 즉 "세션 종료 시 LLM 으로 요약해 저장"은 SessionEnd 에서 직접 할 수 없다 — 큐에 넣고 워커가 처리해야 한다. PreCompact 는 컨텍스트가 날아가기 직전이라 요약 캡처의 진짜 골든 포인트이고, SessionStart 는 hookSpecificOutput.additionalContext 로 메모리를 주입하는 반대 방향 지점이다(matcher 로 startup|resume|clear|compact|fork 구분 가능).

문제는 노이즈다. PostToolUse 를 전부 인덱싱하면 하루 수백 건의 "pytest 를 실행했다" 류 관측이 쌓이고, 어휘 검색에서 흔한 토큰(test, deploy, error)의 점수가 전부 동점이 되면서 정작 필요한 한 건이 상위 12개 밖으로 밀린다. 처방은 단순하다: 캡처는 공격적으로, 인덱싱은 보수적으로.

경험칙: 인덱싱 대상은 raw 관측의 3~5% 이하로 유지한다. 이 비율이 20% 를 넘어가면 recall@5 가 아니라 precision 이 무너진다.

스키마와 융합 검색

-- Postgres 16+ / pgvector 0.8.6 (2026-07-29)
CREATE TYPE mem_kind AS ENUM ('episodic','decision','preference','procedural','failure');

CREATE TABLE memory (
  id            bigserial PRIMARY KEY,
  kind          mem_kind NOT NULL,
  scope_agent   text NOT NULL,             -- 쓴 주체 (write scope)
  scope_project text NOT NULL,             -- 읽기 경계 (read scope)
  subject_key   text,                      -- 삭제요구 단위(사람/고객) — 인덱스 필수
  body          text NOT NULL,
  body_tsv      tsvector GENERATED ALWAYS AS (to_tsvector('simple', body)) STORED,
  embedding     vector(1024),
  observed_at   timestamptz NOT NULL DEFAULT now(),  -- 겪은 시각
  valid_from    timestamptz NOT NULL DEFAULT now(),  -- 믿기 시작한 시각
  valid_to      timestamptz,                          -- NULL = 현재 유효
  supersedes    bigint REFERENCES memory(id),
  decay_exempt  boolean NOT NULL DEFAULT false,
  confidence    real    NOT NULL DEFAULT 0.5,
  evidence      jsonb   NOT NULL DEFAULT '[]',        -- 커밋sha/PR/로그경로
  promoted_doc  text,                                  -- 위키 승격 시 역참조
  indexed       boolean NOT NULL DEFAULT false         -- false = raw 티어
);
CREATE INDEX ON memory USING gin(body_tsv);
CREATE INDEX ON memory USING hnsw (embedding vector_cosine_ops)
  WHERE indexed AND valid_to IS NULL;
CREATE INDEX ON memory (subject_key) WHERE subject_key IS NOT NULL;

observed_at 과 valid_from 을 분리한 게 bi-temporal 의 최소 형태다. Graphiti 가 created_at/expired_at(시스템 시각)과 valid_at/invalid_at(세계 시각)을 따로 두는 것과 같은 이유 — "언제 참이었나"와 "언제 그걸 알았나"는 다르고, 사후 분석에서 필요한 건 후자다.

검색은 RRF(k=60)로 어휘·벡터를 융합한 뒤 최신성은 융합 이후 곱셈 가중으로만 건다. 임베딩이나 랭킹 함수 안에 시간을 녹이면 나중에 못 끈다.

WITH lex AS (
  SELECT id, row_number() OVER (ORDER BY ts_rank_cd(body_tsv, q) DESC) AS r
  FROM memory, websearch_to_tsquery('simple', $1) q
  WHERE indexed AND valid_to IS NULL AND scope_project = ANY($2) AND body_tsv @@ q
  LIMIT 50),
vec AS (
  SELECT id, row_number() OVER (ORDER BY embedding <=> $3) AS r
  FROM memory
  WHERE indexed AND valid_to IS NULL AND scope_project = ANY($2)
  LIMIT 50)
SELECT m.id, m.kind, m.body,
       (COALESCE(1.0/(60+lex.r), 0) + COALESCE(1.0/(60+vec.r), 0))
       * CASE WHEN m.decay_exempt THEN 1.0
              ELSE greatest(0.35,                      -- 하한 없으면 오래된 정답이 사라진다
                exp(-ln(2) * extract(epoch FROM now() - m.observed_at)
                           / (86400 * h.half_life_days))) END AS score
FROM memory m
LEFT JOIN lex ON lex.id = m.id
LEFT JOIN vec ON vec.id = m.id
JOIN mem_halflife h ON h.kind = m.kind
WHERE lex.id IS NOT NULL OR vec.id IS NOT NULL
ORDER BY score DESC LIMIT 12;

greatest(0.35, ...) 이 없으면 8개월 된 장애 회고 한 건이 영원히 13위로 밀린다. 실제로 최신성 가중의 가장 흔한 실패 모드가 이거다. 그리고 한 세션이 상위를 독식하는 것도 막아야 한다 — agentmemory 는 세션당 최대 3건으로 다양화한다. 같은 규칙을 DISTINCT ON (session_id) 계열로 흉내낼 수 있다.

모순: supersede 는 삭제가 아니다

새 기억이 옛 기억과 충돌하면 지우지 말고 valid_to 를 닫고 새 행에 supersedes 를 건다(Graphiti 의 edge invalidation 과 동일한 발상). 그래야 "그때 우리는 뭘 믿고 있었나"를 물을 수 있고, 오판으로 supersede 한 걸 되돌릴 수 있다.

• 실패 모드: LLM 에게 모순 판정을 맡기면 false positive 가 난다. "포트는 8012" 와 "스테이징 포트는 8013" 은 모순이 아닌데 대체돼버린다.
• 처방: (1) supersede 는 kind 가 같고 스코프가 같을 때만 후보, (2) decision/preference 타입은 자동 supersede 금지 — 사람 승인 게이트, (3) supersede 로그를 감사 테이블에 남겨 되돌리기 가능하게.
• 위키 승격(대전제 ②)은 여기서 걸린다. promoted_doc 역참조를 남기지 않으면, 같은 결정이 위키에도 있고 메모리에도 살아 있어 검색이 두 판본을 동시에 뱉는다. 승격 시 메모리 행은 삭제가 아니라 promoted_doc 채우고 indexed=false 로 내리는 게 안전하다.

시크릿·개인정보·삭제 요구

쓰기 경로에 fail-closed 필터를 둔다. 정규식+엔트로피로 토큰 패턴(sk-, ghp_, AKIA, JWT, 40자 이상 고엔트로피 문자열)을 잡아 거부하고, 자연어 PII 는 Presidio 같은 분석기로 태깅한다. 다만 차단 문구를 프롬프트에 적는 것으로는 절대 못 막는다 — 훅 자동 캡처는 프롬프트를 읽지 않는다. 필터는 저장 API 안에 있어야 한다.

삭제는 더 까다롭다. 최근 연구(Ghost Vectors, arXiv 2606.18497)는 HNSW 인덱스에서 소프트 삭제된 임베딩이 원시 인덱스 파일 접근만으로 복원 가능함을 보였다 — 위키피디아 인물 데이터에서 정확한 이름 25.5%, 지리 정보 46.4%, 얼굴 임베딩은 top-1 신원 99% 복구. API 가 404 를 준다고 지워진 게 아니다.

• 실무 처방: subject_key 로 삭제 단위를 미리 쪼개 두고, 삭제 시 행 DELETE → VACUUM → 해당 파티션 인덱스 REINDEX 까지를 한 트랜잭션 절차로 묶는다.
• 더 강한 보장이 필요하면 subject 별 봉투 암호화 후 키 파기(위 논문의 Epoch Key Rotation 방식) — 인덱스 재구축 없이 복원 불가를 만든다.
• 검증 항목: 삭제 후 인덱스 파일 레벨에서 잔존 여부를 실제로 확인하는 테스트가 있는가. 없으면 삭제 기능은 "동작한 적 없음" 상태일 수 있다.

여러 에이전트가 한 서버를 쓸 때

읽기와 쓰기 스코프를 비대칭으로 설계한다. 읽기는 넓게(프로젝트 전체 union), 쓰기는 좁게(쓴 에이전트 소유), 교차 프로젝트 이동은 명시적 승격만.

가장 흔한 사고는 "공유하면 좋겠지"로 shared 를 켜는 것이다. 에이전트마다 도메인이 다르면 공유 스코프는 서로의 recall 을 갉아먹는다. 기본값은 isolated, 공유는 preference 와 decision 두 타입만 화이트리스트로 여는 걸 권한다.

오픈소스 선택지와 자체 구현 손익분기

벤치마크 숫자는 참고만 하라. mem0 는 LoCoMo 92.5 / LongMemEval 94.4 / p50 0.88s 를 제시하지만 문서 스스로 "managed platform 기준, OSS 는 방향성만 동일"이라 못 박고, Zep 논문은 DMR 94.8%(MemGPT 93.4%) 와 LongMemEval 최대 +18.5%·지연 90% 감소를 보고한다. 전부 벤더 자체 하네스이고 제3자 재현에서 값이 크게 흔들린 사례가 보고돼 있다. 이 숫자로 선택하지 말고, 위 표의 시간축과 삭제 가능성 두 열로 선택하라.

손익분기 판단 기준 — 아래 중 3개 이상이면 자체 구현이 싸다.

• [ ] 위키용 Postgres + pgvector 를 이미 운영 중이다(스키마 2개 추가로 끝)
• [ ] 삭제 요구를 SQL 한 줄로 증명해야 한다(벤더 API 의 소프트 삭제로는 부족)
• [ ] 메모리 타입별로 다른 반감기·무효화 규칙이 필요하다
• [ ] 검색 라우터(대전제 ④)가 위키·메모리를 한 쿼리로 융합해야 한다 → 같은 DB 가 압도적으로 유리
• [ ] 그래프 메모리가 정말 필요하지는 않다 (필요하면 Graphiti 를 붙이는 게 자체 구현보다 싸다)

반대로 엔티티 관계 추론이 핵심이면 자체 구현하지 마라. Graphiti 급 엔티티 해소·커뮤니티 탐지를 직접 짜는 건 몇 달짜리다. 대신 비용을 계산하라 — 에피소드당 LLM 호출이 있고 SEMAPHORE_LIMIT 기본값 10 으로 동시성이 눌려 있다. 자동 캡처를 그대로 그래프에 흘리면 토큰 비용이 선형으로 폭발한다.

압축·통합은 늦게, 예산이 넘칠 때만

여기서 직관과 반대되는 실측이 있다. LongMemEval 기반 연구(arXiv 2607.17545)에 따르면 consolidation 의 효과는 컨텍스트 예산에 따라 부호가 뒤집힌다: 예산 32토큰에서 요약(Abstract)은 52.0% vs 원문 유지 4.0%(+48pp), 128토큰에서 +14.2pp, 그러나 256토큰에서는 원문 유지가 8pp 앞서고 모든 압축 연산자가 손해였다. LoCoMo 에서도 같은 교차가 재현됐다.

결론: eager consolidation 은 대부분 손해다. 매 상호작용마다 LLM 으로 병합하는 방식은 토큰 비용을 쓰면서 정확도까지 깎는다. 대신:

1. 원문은 raw 티어에 그대로 둔다(디스크는 싸다).
2. 통합은 스코프별 토큰 예산 초과 시에만 트리거한다. TOKEN_BUDGET 2000 같은 상한을 스코프마다 두고, 넘칠 때 오래된 episodic 부터 병합한다.
3. 병합은 유휴 시간에(Letta 의 sleep-time 에이전트, 또는 그냥 cron 워커). 사용자 대기 경로에 넣지 않는다.
4. decision/failure/preference 는 압축 금지. 이 타입들은 세부가 곧 가치다.
5. 감쇠는 Ebbinghaus 류 지수 감쇠를 랭킹에만 적용하고, 행을 물리 삭제하지 않는다(삭제 요구 대응과 감쇠는 다른 메커니즘이다).

실패 모드: 통합을 켜두고 원문을 지우면 되돌릴 수 없다. 통합 결과 행에 supersedes 로 원본 id 배열을 남기고 원본은 indexed=false 로만 내려라. 통합 품질이 나쁘다는 게 3주 뒤에 드러났을 때, 그게 유일한 복구 경로다.

(라우터가 언제 memory 를 고르는지, MCP 로 어떻게 노출하는지는 → 다른 섹션에서 다룸)

승격은 "복사"가 아니라 상태 전이다

Agent Memory의 한 줄을 위키 문서로 복사하는 순간 설계가 무너진다. 승격은 candidate → scored → staged → published(+ rejected / reverted) 상태 전이여야 하고, 커밋 포인트는 마크다운 파일과 PostgreSQL 행 두 개뿐이다. LightRAG 재인덱싱은 커밋 뒤에 따라오는 파생 작업이므로 실패해도 승격 자체는 성립한다(원칙 ①③). 순서를 뒤집어 그래프에 먼저 넣으면 되돌리기가 불가능해진다.

원칙 ③에 대한 예외 하나: 승격 경로에서는 Fast Path 인덱싱조차 발행 이후로 미뤄야 한다. 미승인 문장이 검색에 노출되는 순간, 그게 곧 아래에서 다룰 환각 고착의 입구다. 스테이징은 격리 테이블에만 있고 라우터가 절대 읽지 않는다. 그리고 승격된 뒤에도 원본 메모리는 지우지 않는다 — 되돌리기와 재검증의 앵커가 사라지기 때문이다.

1. 후보 탐지 — 요약이 아니라 반복을 본다

"세션 끝날 때마다 LLM에게 승격할 것 요약시키기"는 최악의 트리거다. 비용이 세션 수에 비례하고, 노이즈가 상한 없이 늘어난다. 실제로 쓸 만한 트리거는 세 개뿐이다.

세 트리거를 OR로 걸되, 인시던트 타입만 1회 출현에도 후보로 올린다. 나머지는 반복을 기다린다.

2. 점수화 — LLM 자기보고 확신도는 쓰지 마라

promotion_score = 0.40·R + 0.35·I + 0.25·E

R(재사용성) = min(1, log2(1 + distinct_sessions) / log2(6))   # 5회에서 1.0 포화
I(중요도)   = {incident:1.0, decision:0.8, runbook:0.6, howto:0.45, preference:0.25}
E(근거강도) = min(1, 0.25 × 외부검증가능_앵커수)              # 4개에서 1.0

E를 LLM이 말한 confidence로 대체하고 싶은 유혹이 크지만, 이건 측정된 실패다. verbalized confidence는 70B급에서도 ECE가 약 0.1(기대 정확도와 10%p 어긋남)이고, 소형 모델(Gemma 1.1-2B)에서는 정확도와 거의 무상관으로 무너진다. 그래서 E는 모델의 말이 아니라 셀 수 있는 외부 앵커로만 계산한다: 커밋 SHA, 파일:라인, HTTP로 열리는 URL, 재현 명령어 + 그 출력. 앵커 0개면 E=0이고 자동 승격 후보에서 구조적으로 탈락한다.

0.75는 이론값이 아니라 큐 길이에서 역산한 값이다. 하루 후보 40~60건이 들어오는 개인 위키에서 상위 20%가 자동, 다음 밴드가 10건 안쪽으로 떨어지게 맞춘 결과다. 후보 유입량이 바뀌면 임계값도 바뀌어야 한다 — 고정 상수로 박아두면 3개월 뒤 큐가 300건이 된다.

3. 중복·모순 — 3게이트, 2개 이상 통과해야 merge

임베딩 임계값의 함정: 단일 도메인 위키에서는 모든 문서쌍이 0.8대에 몰린다. 절대값 0.90을 그대로 쓰면 미탐이 폭발한다. 처방은 자기 코퍼스로 캘리브하는 것 — 무작위 문서쌍 1,000개를 샘플링해 코사인 분포의 p99를 "동일" 기준, p95를 "merge 후보" 기준으로 잡고, 문서가 300건 늘 때마다 재계산한다.

CREATE TABLE promotion_candidate (
  id            bigserial PRIMARY KEY,
  memory_ids    bigint[]    NOT NULL,
  title_norm    text        NOT NULL,
  body_md       text        NOT NULL,
  embedding     vector(1024) NOT NULL,          -- bge-m3
  entities      text[]      NOT NULL DEFAULT '{}',
  anchors       jsonb       NOT NULL DEFAULT '[]',  -- [{kind:'commit',ref:'a1b2c3'}...]
  score_r       real NOT NULL, score_i real NOT NULL, score_e real NOT NULL,
  score_total   real GENERATED ALWAYS AS (0.40*score_r + 0.35*score_i + 0.25*score_e) STORED,
  nli_contra_max real NOT NULL DEFAULT 0,
  target_doc_id text,                            -- NULL이면 신규 생성
  state         text NOT NULL DEFAULT 'candidate'
                CHECK (state IN ('candidate','staged','published','rejected','reverted')),
  created_at    timestamptz NOT NULL DEFAULT now()
);
CREATE INDEX ON promotion_candidate USING hnsw (embedding vector_cosine_ops)
  WITH (m = 16, ef_construction = 64);
CREATE INDEX ON promotion_candidate USING gin (title_norm gin_trgm_ops);
-- 앵커 0개 후보의 자동 승격을 스키마 레벨에서 차단
CREATE INDEX ON promotion_candidate (state, score_total DESC)
  WHERE jsonb_array_length(anchors) >= 2 AND nli_contra_max < 0.2;

4. merge를 기본값으로 — 신규 문서는 비싸다

Wikipedia가 이미 답을 실측해줬다. 기존 문서의 diff를 검토하는 pending changes 큐는 보통 비어 있고 1~2일 안에 소화되는데, 신규 문서 생성을 검토하는 AfC는 주기적으로 백로그 드라이브를 열어야 한다. 같은 사람, 같은 커뮤니티, 다른 리뷰 단위다. 신규 문서는 "이 주제가 존재할 자격이 있는가"라는 판단을 요구하고 diff는 "이 줄이 맞는가"만 묻는다.

그래서 파이프라인 기본값은 merge다. merge 규칙:

• 문서 전체 재작성 금지. LLM에게 섹션 하나만 주고 append 또는 replace-lines 패치를 내게 한다. Mem0가 후보 사실과 유사 메모리를 함께 주고 ADD / UPDATE / DELETE / NOOP 중 하나를 tool call로 고르게 하는 방식이 이 층에 그대로 이식된다 — if/else 트리보다 유지보수가 싸고, 결정이 로그에 남는다.
• 게이트를 2개 이상 통과 → target_doc_id 채워서 merge. 1개만 통과 → 신규 생성 + 기존 문서에 related 링크만 추가.
• DELETE는 절대 파일 삭제로 매핑하지 않는다. 삭제 대신 무효화다(다음 절).

5. 환각 고착 — 진짜로 무서운 실패 모드

LLM이 쓴 문장이 위키에 들어가고 → 검색이 그걸 찾아오고 → 다음 세션이 "위키에 이렇게 적혀 있으므로"라며 근거로 재인용하고 → 그 재인용이 새 메모리가 되어 R 점수를 올리고 → 다시 승격된다. 자기 참조로 확신만 증폭되는 루프다. 실제로 존재하지 않는 인용 자체가 대규모로 관측되는 시대에, 이 루프를 안 막으면 위키는 3개월 만에 신뢰할 수 없는 물건이 된다.

방어는 네 겹이고, 넷 다 있어야 한다.

---
id: doc_pg_partition_rotation
origin: llm-promoted          # human-written | llm-promoted | llm-drafted-human-edited
confidence: 0.72              # promotion_score 그대로. 모델 자기보고 아님
sources:
  - {kind: commit, ref: "a1b2c3d", repo: "svc-api"}
  - {kind: file,   ref: "app/db/partition.py:88-140"}
  - {kind: repro,  cmd: "make bench-partition", observed: "p95 240ms → 90ms"}
valid_at: 2026-06-14           # 세상에서 참이 된 시점
invalid_at: null               # 반증되면 여기에 날짜. 파일은 지우지 않는다
verify_after: 2026-12-14       # TTL. incident 90일 / decision 180일 / howto 365일
promoted_from: [mem_84213, mem_84991]
promotion_score: {r: 0.86, i: 0.80, e: 0.75}
---

valid_at / invalid_at을 두는 이유는 Graphiti/Zep의 bi-temporal 모델과 같다 — 틀린 사실을 삭제하지 않고 무효화해야 "왜 예전에 이렇게 알고 있었나"를 추적할 수 있고, 되돌리기가 파괴적이지 않게 된다. 검색 라우터는 기본적으로 invalid_at IS NULL만 반환하고, 명시적 히스토리 질의에서만 무효 문서를 노출한다.

실패 모드도 정직하게: TTL 재검증은 앵커가 기계로 재실행 가능할 때만 작동한다. kind: url 앵커는 200 응답만 확인할 뿐 내용이 바뀐 건 못 잡는다. URL 앵커는 스냅샷 해시를 같이 저장하지 않으면 사실상 장식이다.

6. 인간 게이트 — 생성이 아니라 발행에

게이트를 후보 생성 시점에 두면 하루 50번 물어보게 되고, 그러면 사람은 읽지 않고 승인하기 시작한다. 임상 알림의 49~96%가 무시된다는 수치, 그리고 AI 판독을 검토하던 15년차 방사선과 의사의 정확도가 82%에서 45.5%로 떨어졌다는 관찰이 같은 이야기를 한다. 자동화 편향은 의지력으로 이기는 게 아니라 건수로 이긴다.

• 하루 1회, 최대 10건. 세션당 100건이 아니라 10건이 "사람이 정직하게 평가할 수 있는 수"라는 게 실무 합의다.
• 요약이 아니라 diff를 보여준다. 판단 근거를 요약으로 대체하면 그게 곧 러버스탬핑 유도다.
• 키 3개로 끝나야 한다: a(승인) / r(거절+사유 태그) / e(에디터 열기). 거절 사유 태그는 다음 달 임계값 튜닝의 유일한 라벨 데이터다.
• 자동 승격 허용 조건(AND, 전부 충족): score_total ≥ 0.75 · 외부 앵커 ≥ 2 · nli_contra_max < 0.20 · 기존 문서 merge(신규 생성 아님) · 변경 라인 ≤ 20 · 대상 문서가 protected: true 아님. 하나라도 빠지면 큐로 간다.

7. 재인덱싱과 되돌리기

발행은 git 커밋 + PG 행 업데이트가 전부이고, 인덱싱은 그 뒤 두 갈래다.

LightRAG의 문서 단위 삭제는 해당 문서에만 속한 엔티티/관계를 정리하고, 다른 문서와 공유되는 엔티티는 남은 문서 기준으로 설명을 재구성한다. 다만 동기 별칭이 버전마다 없다 — 1.2.3에서 delete_by_doc_id 부재로 AttributeError가 보고됐다(HKUDS/LightRAG #991). 그래서 async 진입점만 쓰고, 부팅 시 assert hasattr(rag, "adelete_by_doc_id")로 버전 회귀를 막는다. 설치 버전은 핀으로 고정할 것(현행 lightrag-hku 1.5.x, 설치 시점 확인 필요).

되돌리기는 git revert <sha> → 동일한 Fast/Deep 경로 재실행이면 끝난다. 이게 성립하는 유일한 이유가 LightRAG가 언제든 통째로 재생성 가능한 파생 인덱스라는 원칙 ①이다. 그래프 상태가 꼬이면 최후 수단은 전량 재빌드고, 그 비용이 계산 가능하다는 것 자체가 이 아키텍처의 배당금이다. 실패 모드: 재빌드는 문서 수 × LLM 추출 비용에 비례하므로, 문서 2,000건을 넘기면 "언제든 재빌드"는 말뿐이 된다. 그 지점부터는 스냅샷 백업이 필수다.

8. 승격 로그 — 나중에 임계값을 고칠 유일한 근거

이 로그의 목적은 감사가 아니라 튜닝이다. 3개월 뒤 "auto 승인분 중 나중에 revert된 비율"을 뽑을 수 없다면 0.75라는 숫자는 영원히 근거 없는 상수로 남는다. 목표는 자동 승격분의 revert율 5% 미만이고, 이걸 넘으면 임계값이 아니라 E(앵커 정의)부터 의심한다.

관련 문서 점수: 하나의 숫자가 아니라 신호 3개

"관련 문서"를 스칼라 하나로 압축하려는 설계는 거의 항상 무너진다. 구조적 관련성(같은 엔티티를 공유), 확산적 관련성(2~3홉 건너 이어짐), 의미적 관련성(링크는 없지만 내용이 닮음)은 서로 다른 실패 모드를 가진 별개의 신호다. 이걸 따로 계산하고 랭크 단위로 합치는 게 유일하게 안정적인 방법이었다.

세 신호는 스케일이 아예 다르다. AA는 상한 없는 양수, PPR은 합이 1인 확률, 코사인은 [-1,1]. 가중합을 쓰면 코퍼스가 커질 때마다 가중치를 다시 튜닝해야 한다. RRF(Reciprocal Rank Fusion, Σ 1/(60+rank)) 를 쓰면 원점수를 아예 버리고 순위만 보므로 재튜닝이 사라진다. Postgres 안에서 pgvector·tsvector·그래프를 한 쿼리로 융합한 사례에서 전체 30~60ms, 그래프 단계만 5~10ms가 보고돼 있다.

배치 계산은 개인화 PageRank에만 필요하다. nx.pagerank는 요청당 전체 그래프를 도는 파워 이터레이션이라(max_iter=100, tol=1e-6) 문서 수천 개부터 온라인 경로에 못 둔다. 야간에 문서별 상위 20개만 뽑아 doc_related(doc_id, related_id, ppr_rank)에 넣고, 온라인에서는 이 테이블을 세 번째 랭킹 소스로 조인만 한다. 반대로 노드 임베딩(node2vec 류)은 이 규모에서 거의 항상 손해다 — 전이적(transductive)이라 문서를 추가할 때마다 재학습해야 하고, 하이퍼파라미터·시드에 따라 링크 재구성 정확도가 크게 흔들리며, 강한 커뮤니티 구조에서는 단순 구조 특징 + 로지스틱 회귀에 밀린다는 보고가 있다. 수만 문서 규모에서는 AA + PPR + 임베딩 코사인이 상한이라고 보고 시작하는 편이 낫다.

-- 파생 미러 테이블(doc↔entity 이분 그래프). 원본은 마크다운, 이건 언제든 재생성 가능.
WITH src AS (SELECT entity_id FROM doc_entity WHERE doc_id = $1)
SELECT de.doc_id,
       -- Adamic-Adar: 흔한 엔티티일수록 기여를 1/ln(문서빈도) 로 감쇠
       sum(1.0 / ln(greatest(e.doc_freq, 2)))            AS aa_score,
       count(*)                                          AS shared_n,
       (array_agg(e.display_name ORDER BY e.doc_freq))[1:3] AS reason
FROM doc_entity de
JOIN src        ON src.entity_id = de.entity_id
JOIN entity e   ON e.id = de.entity_id
WHERE de.doc_id <> $1
  AND e.is_stopword = false          -- 불용 엔티티 제외
  AND e.doc_freq <= $2               -- 허브 상한: 전체 문서의 8% 넘으면 후보에서 뺀다
GROUP BY de.doc_id
HAVING count(*) >= 2                 -- 엔티티 1개만 공유 = 사실상 노이즈
ORDER BY aa_score DESC
LIMIT 20;

점수 표시의 함정은 세 가지다. ① 정규화 퍼센트를 UI에 띄우지 마라. min-max 정규화는 후보 집합에 의존하므로 같은 문서가 어제 91%, 오늘 44%로 보인다. 사용자는 이걸 시스템 고장으로 읽는다. ② 숫자 대신 근거를 보여라. "관련도 0.83"보다 공유: pgvector, HNSW, RRF가 훨씬 낫고, 근거 문자열을 만들지 못하는 추천은 아예 노출하지 않는 게 정답이다. ③ 절대 임계값 대신 구조적 조건. score > 0.7 컷오프는 코퍼스가 3배가 되면 조용히 무너진다. "상위 8개 + 최소 2개 엔티티 공유"처럼 순위와 구조로 자르면 규모에 불변이다.

자동 백링크는 파생, 자동 위키링크는 제안까지만

백링크는 절대 원본 마크다운에 쓰지 않는다. 인바운드 링크는 doc_link(src_doc, dst_doc, anchor, context, kind) 테이블에서 파생시키고 렌더 타임에 붙인다. 원본에 ## Backlinks 섹션을 자동 생성하면 문서 하나 추가할 때마다 수십 개 파일이 diff에 잡혀 git 히스토리가 죽고, 그 diff 노이즈 때문에 사람이 실제 내용 변경을 못 본다.

여기서 실제로 값을 만드는 필드는 dst_doc이 아니라 context — 링크가 등장한 문장 원문이다. "이 문서를 12개 문서가 참조함"은 정보가 없고, "…pgvector HNSW는 필터 조건에서 결과가 모자랄 수 있어 hnsw.iterative_scan을 켠다"는 문장은 클릭하기 전에 이미 답이다. 백링크 패널은 링크 목록이 아니라 인용문 목록으로 만들어라. 파싱은 Fast Path에서 정규식으로 충분하고, 그래프 인덱싱을 기다릴 이유가 없다.

위키링크 자동 제안은 훨씬 위험하다. Obsidian의 unlinked mentions가 실전에서 겪는 실패가 그대로 재현된다 — 코드블록 안 토큰이 링크 후보로 잡히고, 동명 문서 두 개 중 아무거나 고르고, 흔한 단어가 매 문서에 뜬다. 그래서 쓰기 권한을 주지 않는 3티어로 나눈다.

운영 기준은 하나다: A 티어 제안의 사람 수락률이 90% 아래로 떨어지면 A를 끄고 전부 B로 내린다. 정확도 낮은 자동 링크는 단순 노이즈가 아니라 오염이다 — 잘못된 링크가 그래프 엣지가 되고, 그 엣지가 다시 관련 문서 추천의 근거가 되어 자기가 만든 오류를 자기가 인용하는 루프가 생긴다. B 티어 큐의 미처리 항목이 200개를 넘으면 그건 제안기가 아니라 쓰레기 생성기다.

허브 폭발: 3층 방어

LLM 추출은 반드시 "AI", "시스템", "데이터", "사용자" 같은 걸 엔티티로 뽑는다. 이 노드는 금방 모든 문서에 붙어 그래프를 완전그래프로 만든다. GraphRAG 계열에서 고차수 일반 엔티티가 순회를 지배해 검색을 오염시킨다는 지적이 반복되고, KG 디노이징 연구도 저품질 엣지 제거가 정확도와 지연을 동시에 개선한다고 본다.

Adamic-Adar가 이미 1/ln(degree)로 허브를 감쇠시킨다는 점이 중요하다. 즉 1층·2층은 허브를 없애는 게 아니라 "추천 근거로 쓰지 않는" 것이고, 그래프에서 물리적으로 지우는 건 3층뿐이다. 순서를 반대로 하면 복구가 안 된다.

고아 문서와 중복 엔티티

k8s / K8S / 쿠버네티스 / Kubernetes는 LightRAG를 포함한 대부분의 그래프 RAG에서 문자열 매칭 기반 dedup만 돌기 때문에 서로 다른 4개 노드가 된다. 대소문자·약어·동의어·다국어 표기는 그대로 통과한다. 그래서 정본/별칭 표는 Postgres에 두고, LightRAG 쪽 머지는 그 표를 재생하는 절차여야 한다(원칙 ①). 그래프에서 직접 머지만 하면 재인덱싱 한 번에 전부 날아간다.

CREATE TABLE entity_canonical (
  canonical_key text PRIMARY KEY,      -- 'Kubernetes'
  display_name  text NOT NULL,
  entity_type   text,
  is_stopword   boolean NOT NULL DEFAULT false,
  degree_cap    int,                   -- NULL = 허브 상한 면제(화이트리스트)
  decided_by    text NOT NULL          -- 'human' | 'auto:v3'
);
CREATE TABLE entity_alias (
  alias         text PRIMARY KEY,      -- 'k8s', 'K8S', '쿠버네티스'
  canonical_key text NOT NULL REFERENCES entity_canonical(canonical_key),
  source        text NOT NULL,         -- 'human' | 'trgm' | 'embed'
  confidence    real
);
CREATE INDEX entity_alias_trgm ON entity_alias USING gin (alias gin_trgm_ops);

# 재인덱싱 후 별칭 재적용 (lightrag-hku 1.5.6)
await rag.amerge_entities(
    source_entities=["k8s", "K8S", "쿠버네티스"],
    target_entity="Kubernetes",
    merge_strategy={"description": "concatenate", "entity_type": "keep_first"},
)

후보 생성은 2단계 블로킹으로 충분하다: pg_trgm similarity ≥ 0.45(표기 변형) ∪ 엔티티 설명 임베딩 kNN top-10 & 코사인 ≥ 0.85(동의어·다국어). 그다음 사람이 확정한다. 임계값을 낮춰 자동 머지를 늘리면 역방향 실패가 온다 — Claude Code와 Claude, v2.6과 v2.6.5가 합쳐지고, 머지는 되돌릴 수 없다. 자동 머지는 confidence ≥ 0.95 + 같은 entity_type일 때만, 나머지는 전부 큐로.

고아 문서는 인바운드 링크 0 + 공유 엔티티 0인 문서다. 이건 "정리 대상"이 아니라 추출 실패의 지표다. 고아 비율이 갑자기 튀면 대개 새 문서가 아니라 추출 프롬프트나 청킹이 바뀐 것이다.

시각화는 대부분 장식이다 — 대신 만들 뷰 4개

전체 그래프 뷰는 50노드 미만에서만 읽히고, 200을 넘으면 "헤어볼"이 되며, 500+에서는 렌더 성능까지 문제가 된다는 게 PKM 커뮤니티의 반복된 결론이다. 밀집한 그래프는 이해처럼 보이지만 실제로는 우연한 링크 밀도를 기록할 뿐이다("graph theatre"). 노트 상태·우선순위·날짜 같은 실제로 일할 때 필요한 정보가 하나도 없다는 게 결정적이다.

살아남는 시각화는 딱 둘이다. 로컬 그래프(현재 문서 1~2홉) — 이건 규모와 무관하게 유용하다. 그리고 머지 전 후보 클러스터 그래프 — 중복 엔티티 6개가 한 덩어리로 보이면 사람이 3초 만에 판단한다. 공통점은 둘 다 화면에 뜬 순간 사용자가 내려야 할 결정이 정해져 있다는 것이다("여기로 갈까", "합칠까"). 전체 그래프에는 그 결정이 없어서 아무리 예뻐도 닫게 된다. 예외는 딱 하나, 분기에 한 번 연결요소를 색으로 칠한 스냅샷을 보는 것 — 위키가 서로 안 닿는 섬 세 개로 쪼개졌다는 사실은 리스트로는 안 보인다. 그건 탐색 도구가 아니라 감사 도구다. 나머지 예산은 전부 리스트 뷰로 보내라.

마지막 행이 핵심이다. 그래프가 건강해 보이는 지점과 위키가 썩는 지점이 정확히 겹친다.

그래프 품질 지표

마지막 지표는 다른 지표들의 전제조건이다. LLM 추출은 비결정적이라 재인덱싱마다 엔티티가 달라진다. Jaccard가 0.7까지 떨어지면 "LightRAG는 언제든 재생성 가능한 파생 인덱스"라는 전제 자체가 깨진 것이고, 그때는 추출 temperature를 0으로 고정하거나 엔티티 타입을 좁히는 것부터 해야 한다. 재현율을 재지 않으면 재생성 가능하다고 믿는 것과 실제로 재생성 가능한 것의 차이를 영원히 모른다. (검색 라우터가 이 그래프 신호를 언제 고르는지는 → 라우터 섹션에서 다룸)

전자책 에이전트는 위키의 "읽기" 층이 아니라 산출물 층이다. 위키가 원본이라는 대전제(①)를 지키려면 책은 위키의 복사본이 아니라 핀 고정된 뷰여야 한다 — 책 매니페스트는 문서 ID가 아니라 (doc_id, revision) 쌍을 잡아둔다. 그래야 3개월 뒤 각주를 눌렀을 때 "그 문장이 있던 그 버전"으로 갈 수 있다.

-- 책은 파생물이지만, 파생 시점의 원본 상태는 불변으로 박아둔다
CREATE TABLE book_projects (
  id BIGSERIAL PRIMARY KEY, slug TEXT UNIQUE NOT NULL, topic TEXT NOT NULL,
  glossary JSONB NOT NULL DEFAULT '{}',       -- {"파생 인덱스":{"canonical":..,"banned":[..]}}
  status TEXT NOT NULL DEFAULT 'scoping', created_at TIMESTAMPTZ DEFAULT now()
);
CREATE TABLE book_chapters (
  book_id BIGINT REFERENCES book_projects(id), idx INT, anchor TEXT NOT NULL,  -- 'ch03'
  title TEXT NOT NULL, thesis TEXT NOT NULL,
  target_words INT NOT NULL, actual_words INT,
  source_pins JSONB NOT NULL,                 -- [{"doc_id":123,"revision":"a1b2c3"}, ...]
  draft_md TEXT, summary_md TEXT,             -- summary_md = 다음 챕터로 넘길 300자 요약
  PRIMARY KEY (book_id, idx)
);
CREATE TABLE book_citations (
  book_id BIGINT, chapter_idx INT, sentence_hash TEXT,
  doc_id BIGINT, revision TEXT, start_char INT, end_char INT, cited_text TEXT,
  verified BOOL NOT NULL DEFAULT false
);

8단계 파이프라인과 각 단계의 예산

3단계와 5단계를 분리하는 건 취향이 아니라 API 제약이다. Anthropic Citations는 output_config.format(구조화 출력)과 같이 못 쓴다 — 400을 뱉는다. 목차처럼 스키마가 필요한 산출은 구조화 출력으로, 본문처럼 인용이 필요한 산출은 citations로. 한 요청에서 둘 다 하려는 설계는 첫 호출에서 죽는다.

챕터 요청: 무엇을 캐시하고 무엇을 흘려보내는가

컨텍스트는 네 덩어리다. 고정 프리앰블(용어집 + 전체 목차 + 스타일 가이드) → 앞 챕터 요약 체인 → 이 챕터의 근거 문서 → 챕터 스펙. 이 순서가 곧 캐시 설계다. 프리앰블을 맨 앞에 두고 cache_control을 걸면 캐시 읽기는 입력가의 0.1배, 쓰기는 1.25배(5분 TTL) 또는 2배(1시간 TTL)다. 책 한 권 빌드가 20~40분 걸린다면 ttl:"1h"가 정답이다.

resp = client.messages.create(
    model="claude-opus-5",
    max_tokens=24000,       # ⚠️ Opus 5는 thinking이 기본 ON이고 max_tokens는
                            # thinking+본문 합산 상한 — 본문 6k 목표에 6000을 주면 잘린다
    output_config={"effort": "high"},
    system=[{"type": "text", "text": PREAMBLE,        # 용어집+TOC+스타일 (≈30k tok)
             "cache_control": {"type": "ephemeral", "ttl": "1h"}}],
    messages=[{"role": "user", "content": [
        *[{"type": "document",
           "source": {"type": "text", "media_type": "text/plain", "data": c["text"]},
           "title": c["title"],
           "context": json.dumps({"doc_id": c["doc_id"], "revision": c["revision"]}),
           "citations": {"enabled": True}}   # all-or-none: 한 요청 안에서 전부 켜거나 전부 끄거나
          for c in chunks],
        {"type": "text", "text": PREV_SUMMARIES},  # 앞 챕터 요약 체인 (챕터당 300자)
        {"type": "text", "text": CHAPTER_SPEC},    # thesis / target_words / 금지 주제
    ]}],
)
# 응답은 text 블록 여러 개로 쪼개지고, 근거 있는 블록만 .citations 배열을 갖는다
for b in resp.content:
    if b.type == "text":
        for cit in (b.citations or []):
            store(cit.document_index, cit.start_char_index, cit.end_char_index, cit.cited_text)

title은 길이 제한이 있으므로 doc_id/revision 같은 메타데이터는 context 필드에 JSON 문자열로 넣는다. context와 title은 모델에 전달되지만 인용 대상 본문으로는 쓰이지 않는다.

긴 산출물이 실제로 무너지는 지점

중복 탐지에는 흔한 오판이 하나 있다. MinHash는 표면 중복만 잡는다 — 같은 내용을 다른 문장으로 쓴 두 챕터는 Jaccard가 거의 0으로 나온다. 반대로 임베딩만 쓰면 "같은 주제를 다른 각도로 다룬 정당한 반복"까지 잘라낸다. 실무 조합은 MinHash로 후보를 좁히고(싸다) 임베딩으로 확정(비싸다), 그리고 잘라내는 게 아니라 리뷰 큐로 보내는 것이다. 자동 삭제는 논지 전개를 망가뜨린다.

인용 검증: LLM에게 시키지 말 것

Citations API는 문서 타입별로 인용 단위가 다르다. plain text는 문장 단위 char_location(0-indexed, end 배타적), PDF는 page_location(1-indexed), custom content는 내가 준 블록 인덱스. 위키처럼 마크다운 원본이 있으면 plain text로 넣어 문장 단위를 얻고, 불릿·표처럼 문장 분할이 망가지는 구조는 custom content로 넣어 내가 정한 블록이 곧 인용 단위가 되게 한다.

검증 자체는 모델을 부르지 않는다. (doc_id, revision, start_char, end_char)로 원본을 다시 잘라 cited_text와 바이트 단위로 대조한다. 불일치 = 하드 실패. cited_text는 출력 토큰에 포함되지 않고(다음 턴에 되돌려 보내도 입력 토큰에 안 잡힌다) API가 직접 추출하므로 "출처를 지어내지 마"라는 프롬프트보다 구조적으로 안전하다. 다만 인용이 유효하다는 것과 그 인용이 문장을 뒷받침한다는 것은 다른 문제다. 후자는 별도 NLI/판정 패스가 필요하고, 그건 비용이 든다.

위키에 근거가 없을 때는 3분기로 처리한다. ①사실 주장인데 인용 0개 → 문장 차단, [근거 없음] 마커 + 리뷰 큐. ②연결·요약 문장(사실 주장 아님) → 통과. ③반복적으로 비는 주제 → 위키에 gap 이슈로 등록한다(Agent Memory가 아니라 위키 TODO다 — 검증 없이 메모리가 위키로 승격되면 안 된다는 원칙 ②를 여기서도 지킨다). 실패 모드: 임계를 세게 잡으면 책이 각주로 도배되어 읽을 수 없어진다. 챕터당 인용 밀도 상한(예: 문장의 40%)도 게이트에 넣어야 한다.

변환 실무: pandoc / WeasyPrint와 한글 함정

# EPUB — --epub-chapter-level 은 --split-level 의 deprecated 동의어 (pandoc 3.x)
pandoc book.md -o book.epub \
  --toc --toc-depth=2 --split-level=1 --number-sections \
  --css=epub.css --epub-cover-image=cover.png --epub-metadata=meta.xml \
  --epub-embed-font=PretendardVariable.subset.woff2 -M lang=ko-KR
java -jar epubcheck.jar book.epub      # 5.x. errors 0 아니면 배포 금지

# PDF — 한국어는 WeasyPrint(69.x, Pango>=1.44) 또는 xelatex+xeCJK 권장
pandoc book.md -o book.pdf --pdf-engine=weasyprint --css=print.css --toc
# xelatex 경로: --pdf-engine=xelatex -V CJKmainfont="Noto Serif KR"

비용과 병렬화

챕터당 입력 58k(프리앰블 30k + 근거 25k + 요약 3k), 출력 6k, 20챕터, Opus 5($5/$25 per MTok) 가정:

즉 초안 1회 빌드는 $3~9다. 실제 비용은 일관성 패스·검증·재빌드에서 나온다 — 10번 돌리면 $60~90. 최적화 지점은 여기지 초안이 아니다. 배치는 50% 싸지만 프롬프트 캐시 히트를 잃기 쉬워 실이익이 계산보다 작을 수 있다(측정 필요).

병렬화의 함정: 챕터는 독립이 아니다. 앞 챕터 요약을 넘기는 순간 순차가 강제된다. 절충은 2-pass다 — Pass A는 목차+용어집만 보고 전 챕터를 병렬 초안, Pass B는 요약 체인을 태워 순차로 이음새만 수정. 20개를 동시에 던지면 ITPM/OTPM 한도에 걸려 429가 쏟아지고, max_tokens가 큰 요청을 비스트리밍으로 보내면 SDK가 막거나 HTTP 타임아웃에 걸린다. 스트리밍은 선택이 아니다.

품질 게이트 체크리스트

하드(빌드 실패): 미해결 {{ref:*}} 토큰 0 · 인용 오프셋 대조 불일치 0 · 금지 용어 변형 0 · 챕터 분량비 0.7~1.4 이탈 0 · 문단쌍 Jaccard>0.8 0 · epubcheck error 0 · 모든 챕터가 최소 1개 (doc_id, revision) 핀 보유.
소프트(리뷰 큐): 인용 밀도 상한 초과 · 임베딩 유사 문단 · [근거 없음] 마커 · 톤 일관성.

마지막으로 게이트 자체를 검증해야 한다. 용어를 일부러 흔든 초안, 오프셋을 1칸 민 인용, 존재하지 않는 {{ref:ch99}}를 넣은 뮤테이션 픽스처를 CI에 두고 게이트가 실제로 잡는지 확인한다. 통과율 100%인 게이트는 대개 잘 만든 게이트가 아니라 아무것도 검사하지 않는 게이트다.

골든셋: 50~100개, 그리고 그걸 죽지 않게 만드는 스키마

골든셋은 "잘 만든 질문 모음"이 아니라 회귀 테스트 픽스처다. 50~100개면 충분하다 — 이 구간에서 recall@5의 1~2%p 변화는 노이즈 위로 올라오고, 200개를 넘기면 라벨링 비용은 선형으로 늘지만 검정력은 포화된다.

마지막 항목이 이 설계에서 특히 중요하다. 원칙 ④(라우터가 모드를 고른다)는 검색 품질 골든셋만으로는 검증되지 않는다. 라우터가 틀린 모드를 골라도 최종 답이 맞으면 지표는 전부 초록이고, 비용만 조용히 3배가 된다. 라우터 정확도는 별도 라벨로 따로 재라.

-- 골든셋은 코드와 함께 버전 관리되는 픽스처 (원본 YAML → PG 시드)
CREATE TABLE golden_query (
  id              text PRIMARY KEY,            -- gq-0042, 영구 불변
  question        text NOT NULL,
  intent          text NOT NULL,               -- fact | howto | synthesis | negative
  expected_mode   text NOT NULL,               -- fts | vector | graph | memory
  expected_docs   text[] NOT NULL,             -- 슬러그+앵커: 'infra/pg-tuning#wal'
  expected_answer text,                        -- NULL 허용: negative 는 '모른다'가 정답
  must_not_cite   text[] DEFAULT '{}',         -- 인용되면 실패 (오염 감지)
  source          text NOT NULL,               -- traffic | incident | edge | router
  incident_ref    text,                        -- 실패에서 태어난 케이스의 출처
  added_at        date NOT NULL DEFAULT now(),
  last_verified   date NOT NULL DEFAULT now()  -- 90일 경과 시 CI가 재검토 플래그
);
CREATE INDEX ON golden_query (source, expected_mode);

정답을 chunk_id로 잡으면 청킹 전략을 바꾸는 순간 라벨이 전부 죽는다. 슬러그+앵커로 잡고 채점 시 chunk → (slug, anchor)로 매핑해 비교하라. 이게 원칙 ①(위키가 원본)을 골든셋 층까지 관철하는 방법이다.

지표: 검색과 생성을 따로 게이트한다

두 층은 반드시 독립적으로 게이트한다. 답변 품질은 오르고 recall은 떨어지는 변경(예: 컨텍스트를 잘라 생성 프롬프트를 정리)은 실제로 흔하며, 합산 점수 하나로는 절대 안 잡힌다.

Ragas의 쓸모는 명확하다 — 사람이 매기던 충실도·사실성을 자동화한다. 한계도 명확하다. (1) 순위 지표는 Ragas가 주지 않는다. recall@k·MRR·nDCG는 문서 ID 라벨만 있으면 직접 계산이 가능하고, LLM 호출 0회라 CI에서 무료·결정적이다. (2) 판정자 분산. LLM 판정자는 재실행마다 결론이 바뀌고(확률적 불안정성), 위치 편향이 있으며, 점수 척도를 잘게 쪼갤수록 임의성이 커진다는 게 반복 보고된다. 대응은 셋: 이진/3점 척도, 3회 판정의 중앙값, 판정자 모델·프롬프트 버전 핀 고정. 판정자를 바꾸는 건 "지표 정의 변경"이므로 baseline도 같이 갱신해야 한다.

# ci/eval_gate.py — 검색(결정적)과 생성(LLM 판정)을 따로 게이트
from statistics import mean
from ragas import EvaluationDataset, evaluate
from ragas.llms import LangchainLLMWrapper
from ragas.metrics import LLMContextRecall, Faithfulness, FactualCorrectness

def hit_at_k(cited, expected, k):            # 케이스당 0/1 → 전체 평균이 recall@k
    return float(bool(set(cited[:k]) & set(expected)))

def rr(cited, expected):
    return next((1.0 / i for i, c in enumerate(cited, 1) if c in expected), 0.0)

# 1층: LLM 호출 0회. PR마다 돌려도 비용이 0이다.
retrieval = {
    "recall@5":   mean(hit_at_k(r.cited, r.expected, 5) for r in runs),
    "recall@20":  mean(hit_at_k(r.cited, r.expected, 20) for r in runs),
    "mrr":        mean(rr(r.cited, r.expected) for r in runs),
    "router_acc": mean(r.chosen_mode == r.expected_mode for r in runs),
}
assert retrieval["recall@5"] >= BASELINE["recall@5"] - 0.02   # 절대값 아닌 회귀 폭으로 게이트

# 2층: 판정자는 핀 고정. 바뀌면 baseline 도 같이 갱신한다.
judge = LangchainLLMWrapper(ChatOpenAI(model=JUDGE_MODEL_PIN, temperature=0))
gen = evaluate(
    dataset=EvaluationDataset.from_list(samples),   # user_input / retrieved_contexts / response / reference
    metrics=[LLMContextRecall(), Faithfulness(), FactualCorrectness()],
    llm=judge,
)
assert gen["faithfulness"] >= BASELINE["faithfulness"] - 0.03

라우터·모드 변경은 A/B 말고 인터리빙으로

라우터 변경(hybrid → mix, 벡터 임계값 조정, 리랭커 교체)은 효과 크기가 작아서 일반 A/B로는 표본이 안 모인다. 검색 랭킹에서 인터리빙은 A/B 대비 최대 100배 민감도로 보고된다 — 한 사례에서 90% 일치에 인터리빙 ~400 표본, A/B ~40,000 표본. Team-draft interleaving은 인터리빙 계열 중 민감도가 가장 낮지만 구현이 가장 단순하니, 1인 규모에서는 이걸로 시작하면 된다.

무너지는 지점 둘. 인터리빙은 상대 선호만 준다 — "새 라우터가 낫다"는 알려주지만 "절대 recall이 얼마냐"는 못 준다(그래서 골든셋과 대체재가 아니라 보완재다). 그리고 클릭이 거의 없는 개인 위키에서는 인터리빙 자체가 성립하지 않는다. 대리 신호를 먼저 만들어라: 답변 채택, 재질의율, 인용 클릭.

관측: 지연 분해와 알람 기준

지연은 반드시 분해해서 저장한다. 합계만 있으면 "느려졌다" 알람이 어디를 가리키는지 알 수 없다.

CREATE TABLE query_log (
  id            bigserial PRIMARY KEY,
  ts            timestamptz NOT NULL DEFAULT now(),
  question      text NOT NULL,
  chosen_mode   text NOT NULL,       -- 이 컬럼 하나가 실패 6종 중 5종을 진단한다
  candidates    int  NOT NULL,       -- 0 이면 '빈 결과'
  cited_chunks  text[] NOT NULL,
  t_route_ms int, t_retrieve_ms int, t_rerank_ms int, t_generate_ms int,
  in_tokens  int, out_tokens int, error_code text
);
CREATE INDEX ON query_log (chosen_mode, ts DESC);

-- 비용 폭증은 합계가 아니라 모드별 분해로만 진범이 보인다
SELECT chosen_mode, count(*) AS n, round(avg(in_tokens)) AS avg_in,
       sum(in_tokens) FILTER (WHERE ts > now() - interval '1 day') AS in_1d
FROM query_log WHERE ts > now() - interval '7 days'
GROUP BY 1 ORDER BY in_1d DESC NULLS LAST;

OpenTelemetry를 쓴다면 GenAI 규약이 gen_ai.operation.name="retrieval" 스팬을 정의하고, gen_ai.provider.name(필수)·gen_ai.request.model·gen_ai.usage.input_tokens(권장)를 붙인다. 다만 2026년 7월 기준 gen_ai.* 전 항목이 Development(구 experimental) 등급이고, core semconv v1.42.0(2026-06)에서 deprecate되어 별도 저장소 semantic-conventions-genai로 이관됐다. 스팬 트리 모양(invoke_agent → chat/execute_tool/retrieval)은 지금 채택하되, 속성 이름 고정에 의존하는 대시보드는 만들지 마라.

Fast/Deep 분리(원칙 ③)를 채택한 순간 Deep Path 큐 지연은 관측의 1급 시민이 된다. "PG에는 있는데 그래프에는 없는" 창은 버그가 아니라 설계된 상태이므로, 답변에 그래프 신선도(indexed_at)를 노출해 사용자가 그 창을 볼 수 있게 하라.

비용 모델: 인덱싱 1회성 vs 질의당

1,000 문서 × 평균 1,500 단어 ≈ 200만 토큰을 가정하자.

(임베딩 단가는 2026-08 공개 요금표 기준 text-embedding-3-small $0.02/M — 3-large $0.13/M, Cohere embed-v4 및 voyage-3-lite 각 $0.01/M. 배포 전 재확인. LightRAG 계열 추출이 1,000단어당 ~1,200토큰을 쓴다는 수치는 2차 출처 추정치라 자기 코퍼스로 실측해야 한다.)

재임베딩의 진짜 비용은 토큰이 아니라 인덱스다. pgvector HNSW는 maintenance_work_mem 기본값 64MB에서 디스크 기반 빌드로 떨어져 10~50배 느려진다. 100만 행 규모면 튜닝 여부에 따라 수 분 vs 수십 분이고, REINDEX INDEX CONCURRENTLY도 원래 빌드와 비슷한 메모리를 요구한다. 게다가 LightRAG는 임베딩 모델 교체 시 자동 재임베딩을 제공하지 않는다 — 재생성 스크립트는 네가 갖고 있어야 한다.

여기서 원칙 ①에 한 가지 반박을 걸어둔다. "LightRAG는 언제든 통째로 재생성 가능한 파생 인덱스"는 기술적으로 참이지만, 재생성 비용을 계측하지 않으면 반쯤 거짓말이 된다. 재생성 비용(추출 토큰 + 인덱스 빌드 시간)을 대시보드에 상시 표기하고, 그 값이 "하루 안에 못 돌리는" 수준이 되는 순간 그 인덱스는 파생물이 아니라 자산이다. 분기 1회 전체 재생성 드릴을 스케줄에 넣어 실제로 돌려봐라 — 안 돌려본 재생성 경로는 없는 경로다.

로컬/소형 모델로 추출을 내리는 손익분기는 공개 벤치마크상 하루 ~5,000 요청 부근이다. 프런티어 모델 대비로는 월 800만 토큰 정도에서 넘어가지만, 소형 API 모델과 비교하면 월 2억 토큰 이상이어야 자체 호스팅이 이긴다. 개인 지식 OS의 Deep Path는 여기 한참 못 미친다. 결론: 추출을 로컬로 내리는 정당한 이유는 프라이버시와 레이트리밋이지 비용이 아니다. 비용으로 정당화하려 들면 숫자가 반박한다.

자주 나오는 실패 6종과 진단 순서

여섯 개를 관통하는 원칙 하나: 로그에 없는 수치는 추측하지 마라. grep으로 "새 내용이 인덱스에 있나"만 확인하고 정상 판정하는 게 가장 흔한 오진이다 — 있는데 순위에 안 걸리거나 두 버전이 공존하는 경우가 더 많다. 그리고 위 6종 중 5종은 chosen_mode를 로그에 남겼는가만으로 진단 시간이 한 자릿수 배 갈린다.

4주를 쪼개는 원칙: 매주 "혼자서도 쓸 수 있는 것"이 하나씩 나온다

이 계획의 유일한 규칙은 매 주말마다 그 주 산출물만으로도 실제로 쓸 수 있어야 한다는 것이다. 4주차 끝에야 처음 동작하는 계획은 3주차에 죽는다. 그래서 순서를 기능 난이도가 아니라 일일 사용 습관이 붙는 순서로 잡는다.

1주차: 이것만 되면 나머지는 붙는다

1주차 범위는 잔인하게 좁혀야 한다. 그래프 없음, 메모리 없음, 라우터 없음. documents + chunks 두 테이블, FTS 하나, vector 하나, MCP 도구 세 개다.

-- 확장: pgvector 0.8.6 권장(0.8.2 CVE-2026-3172, 0.8.3~0.8.4 HNSW vacuum 손상 수정 이후)
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS pgroonga;   -- 한국어 형태소/2-gram. 대안: pg_bigm

CREATE TABLE documents (
  id           uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  path         text UNIQUE NOT NULL,          -- vault 상대경로 = 진짜 원본 주소
  title        text NOT NULL,
  body         text NOT NULL,                 -- 마크다운 원문 그대로
  frontmatter  jsonb NOT NULL DEFAULT '{}',
  content_hash text NOT NULL,                 -- sha256(body). 재인덱싱 판정 키
  updated_at   timestamptz NOT NULL DEFAULT now()
);

CREATE TABLE chunks (
  id          bigserial PRIMARY KEY,
  document_id uuid NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
  ord         int  NOT NULL,
  body        text NOT NULL,
  embedding   halfvec(3072),                  -- 2000차원 초과는 halfvec 로만 인덱싱 가능
  UNIQUE (document_id, ord)
);

CREATE INDEX ON documents USING pgroonga (body);
CREATE INDEX ON chunks USING hnsw (embedding halfvec_cosine_ops)
  WITH (m = 16, ef_construction = 64);

주의할 함정 둘. ① PostgreSQL 기본 tsvector 는 한국어 형태소 분석을 하지 않는다 — 영문 전용 파서로 인덱싱해 놓고 "FTS 가 왜 안 잡히지"로 이틀을 태우는 게 이 단계 1순위 실패 모드다. PGroonga(4.0.4에서 PG18 지원, PG18 이후엔 정렬된 인덱스로 인식됨) 또는 pg_bigm 을 처음부터 넣어라. ② 메타데이터 필터를 붙인 벡터 검색은 HNSW 가 조기 종료해 결과가 모자란다. pgvector 0.8.0 이 추가한 hnsw.iterative_scan = strict_order(또는 relaxed_order), hnsw.max_scan_tuples(기본 20000), hnsw.scan_mem_multiplier 를 세션 단위로 켜 두고 recall 을 재라. 안 켜면 "필터만 붙이면 검색이 비는" 증상이 조용히 남는다.

MCP 도구는 세 개로 충분하다: wiki_search(query, k), wiki_get(path), wiki_append(path, text). 서버는 FastMCP 3.4.x 로 짜고 stdio + HTTP 두 전송을 모두 노출한다. 2026-07-28 스펙이 initialize 핸드셰이크와 Mcp-Session-Id 를 없애고 stateless 로 갔기 때문에, HTTP 로 노출해도 sticky session 없이 라운드로빈 뒤에 둘 수 있다 — 1주차엔 그냥 로컬 stdio 로 쓰다가 나중에 옮겨도 코드가 안 바뀐다는 뜻이다.

왜 그래프 → 메모리 → 승격 → 전자책 순서인가

• 그래프가 2주차인 이유: LightRAG 인덱싱은 문서당 대략 1만 토큰 규모의 LLM 호출을 쓴다(공개 벤치마크에선 데이터셋 전체 인덱싱에 수천 초 단위). 즉 느리고 돈이 든다. 이걸 1주차 동기 경로에 넣으면 "문서 하나 넣는 데 40초"가 되고, 그 순간 위키에 글을 안 넣게 된다. Fast Path 가 먼저 서야 Deep Path 를 비동기로 미룰 명분이 생긴다.
• 메모리가 3주차인 이유: 메모리는 에이전트가 실제로 돌아간 세션이 쌓여야 저장할 게 생긴다. 1~2주차에 MCP 를 붙여 실사용을 만들어 놓지 않으면 3주차에 저장할 경험이 없다.
• 승격이 메모리 뒤인 이유: 승격 기준은 책상에서 못 정한다. 메모리 30~50건이 쌓인 뒤 손으로 분류해 봐야 "무엇이 위키로 올라갈 자격이 있는가"가 나온다(기준 자체는 → 다른 섹션).
• 전자책이 마지막인 이유: 출력물은 원본이 마크다운이면 언제든 만들 수 있다. 먼저 만들면 스키마가 출력 포맷에 끌려간다.

스택 확정안과 교체 비용

LightRAG 를 붙일 때 실제로 건드리는 건 이 정도다.

# .env — 1주차엔 이 블록 전체를 주석 처리해도 위키는 돌아간다
LIGHTRAG_KV_STORAGE=PGKVStorage
LIGHTRAG_VECTOR_STORAGE=PGVectorStorage
LIGHTRAG_DOC_STATUS_STORAGE=PGDocStatusStorage
LIGHTRAG_GRAPH_STORAGE=NetworkXStorage   # AGE 준비되면 PGGraphStorage
POSTGRES_HOST=localhost
POSTGRES_DATABASE=wiki
POSTGRES_MAX_CONNECTIONS=25
WORKSPACE=personal_wiki                  # 인덱스 격리 키. 재생성 실험용 두 번째 값을 미리 확보해 둘 것
EMBEDDING_MODEL=text-embedding-3-large
EMBEDDING_DIM=3072
EMBEDDING_BATCH_NUM=32
MAX_ASYNC_LLM=4

# worker: Deep Path 한 건 처리
rag = LightRAG(working_dir="./.lightrag", embedding_func=emb, llm_model_func=llm)
await rag.initialize_storages()          # 빼먹으면 조용히 빈 결과가 나온다
await rag.initialize_pipeline_status()
await rag.ainsert(doc.body, ids=[str(doc.id)])

디렉터리와 리포지토리 배치

knowledge-os/                  # 리포 A: 코드 (단일 리포, 모노레포)
├── apps/web/                  # Next.js 16
├── services/api/              # FastAPI: /documents /search /promotions
├── services/worker/           # pgqueuer 워커 (Deep Path)
├── services/mcp/              # FastMCP 서버 (api 를 HTTP 로 호출만)
├── packages/schema/           # SQL 마이그레이션 + pydantic 모델 (단일 진실)
└── scripts/rebuild_index.py   # 원본 → 파생 전체 재생성
vault/                         # 리포 B: 마크다운 원본 (Obsidian 이 직접 연다)
└── notes/ , daily/ , refs/

리포를 둘로 쪼개는 이유는 하나다. 원본 vault 는 코드 배포와 수명이 다르고, 에디터가 직접 열어야 하며, 되돌리기 단위가 git commit 이어야 한다. 코드 리포에 넣으면 "노트 오타 수정"이 CI 를 돌린다. 반대로 코드는 서비스 4개를 굳이 리포로 쪼개지 마라(아래 참조).

하지 말 것

공수와 "매일 쓰게 되는" 임계점

혼자, 본업 옆에서 만든다는 가정(주 12~15시간)으로 실측형 추정: W1 약 18~22h(스키마·적재·검색·MCP), W2 약 12~16h(큐·워커·재생성 스크립트, LightRAG 첫 인덱싱 디버깅이 변수), W3 약 10~14h, W4 약 10h. 합계 50~62시간. 여기서 가장 크게 초과하는 항목은 항상 두 개다 — 한국어 FTS 세팅과 임베딩 차원/halfvec 인덱스 재빌드.

임계점은 명확하다. 에이전트가 MCP 로 위키를 읽고, 캡처가 3초 안에 끝나는 순간부터 매일 쓴다. 즉 1주차 산출물 + wiki_append 하나가 임계점이고, 그래프·메모리·전자책은 그 위의 복리다. 반대 실패 모드도 같이 적어 둔다: Fast Path 만 있고 캡처 경로가 없으면 3주 뒤 문서 수가 안 늘고, Deep Path 큐가 조용히 밀리면 그래프만 몇 주째 낡은 채로 "잘 되는 것처럼" 보인다. 그래서 W2 의 DoD 에 큐 지연 p95 와 전체 재생성 완주를 넣었다. 파생 인덱스라는 대전제는 재생성을 실제로 한 번 돌려 보기 전까지는 주장일 뿐이다.