LLM Wiki를 지식 뇌로 쓰게 해주는 두 가지 자동화

내가 만들고 싶었던 것은 비서 에이전트였다. 다만 그 비서가 나에게 정확히 무엇을 해줄 건지는 정하지 못한 채로 뜬구름 기획만 해왔다. 첫 번째에는 여러 기능이 굴러가는 구조를, 두 번째에는 눈에 보이는 비서의 구조를 만들었지만 둘 다 실제로 쓰기 어려웠다.

두 번을 멈추고 나서야 내가 원하는 것이 조금 구체적으로 보였다. 내가 원한 것은 나를 아는 비서였고, 그러려면 그 비서가 읽을 지식을 쌓고 활용할 수 있는 구조가 먼저 필요했다. 그래서 세 번째에는 LLM Wiki를 제대로 쓰는 방법부터 다시 만들기로 했다.

나는 이 지식 공간을 두 번째 뇌라고 부르고 프로젝트 이름도 second로 지었다. 새로 고안한 방식은 아니다. 사람이 직접 분류하고 링크하는 대신, LLM이 쌓인 기록을 읽어 정리하게 하는 LLM Wiki 방식을 가져다 썼다.

LLM Wiki를 제대로 활용하지 못한 이유

사실 그전에 LLM Wiki 방식으로 개인 지식 공간을 하나 만들어 둔 적이 있다. 지식 정보와 메모를 쌓아 두면 나중에 꺼내 쓸 수 있겠다는 생각이었고, 34페이지까지 내용을 채워 봤다. 그런데 결국 일주일 만에 손을 놓았다.

이유는 두 가지였다.

1. 채우는 일이 전부 내 몫이었다. 내 맥락을 기억하게 하려면, 하던 일을 멈추고 내가 한 일을 위키에 직접 내용으로 채워 넣어야 했다.
2. 위키를 여는 위치가 고정돼 있었다. 쌓는 것도 꺼내는 것도 매번 위키 프로젝트에서 세션을 열어야 했는데, 나는 대부분 다른 프로젝트에서 작업하고 있었다.

결국 LLM Wiki의 장점을 이론으로만 이해했지 제대로 활용하지는 못한 것이다. 그래서 세 번째에는 다른 방식을 찾기보다, 내가 이 위키를 활용하지 않게 된 두 이유를 해결하는 것부터 시작했다.

내가 적지 않아도 쌓이게 만들었다: 수확

먼저 채우는 방식을 바꿨다. 직접 적는 입구를 없애려 한 것은 아니다. 메모를 남기고 싶을 때는 여전히 “적어둬”라고 하고, 읽은 자료는 웹 클리퍼로 스크랩해 둔다. 다만 이 둘은 부수적인 입구다. 이 시스템에 가장 많이 들어오는 것은 Claude Code와 대화하고 작업한 세션의 기록이다.

처음에는 Claude Code 하나에만 수확 연결을 걸었다. Claude Code의 전역 설정에서, 세션을 끝낼 때와 컨텍스트 컴팩트(대화가 길어져 이전 맥락을 압축하기 직전)가 일어날 때마다 같은 수확 스크립트가 실행되게 한 것이다.

{
  "hooks": {
    "PreCompact": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "/Users/angari/projects/second/.claude/hooks/harvest-session.sh",
        "async": true
      }]
    }],
    "SessionEnd": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "/Users/angari/projects/second/.claude/hooks/harvest-session.sh",
        "async": true
      }]
    }]
  }
}

전역 훅이 바로 큐를 쓰는 것은 아니다. 훅이 Claude Code 전용 연결 스크립트를 실행하고, 이 스크립트가 공통 수확 처리를 호출한다.

CORE="$HOME/projects/second/lib/hooks/harvest-core.sh"
exec "$CORE" claude

공통 수확 처리는 받은 claude 정보와 세션 기록 위치를 이용해 .queue/sessions.jsonl에 JSON 한 줄을 추가한다. 대화 전문을 큐에 복사하는 대신, 컴파일이 나중에 열어 읽을 전문 파일의 위치와 그 세션의 정보를 남기는 방식이다.

{
  "time": "2026-07-08T21:00:00",
  "event": "SessionEnd",
  "source": "claude",
  "project": "blog",
  "cwd": "/Users/angari/projects/blog",
  "session_id": "<Claude Code 세션 ID>",
  "transcript": "<세션 전문 JSONL 파일 경로>"
}

그래서 내가 “정리해”라고 하면, 컴파일은 큐에 적힌 transcript 경로의 실제 대화 내용을 열어 읽고 남길 만한 내용을 위키 페이지로 정리한다. 즉, 수확은 전문 파일의 위치를 남기고, 컴파일은 그 내용을 읽어 정리한다.

평소 개발하는 동안에는 수확이 자동으로 돌고, 따로 남기고 싶은 메모나 자료는 원본으로 직접 남긴다. 이 재료들은 컴파일할 때 함께 읽힌다. 무엇을 남기고 무엇을 버릴지 정하는 일까지 맡기지는 않았다. 정리 결과를 보고 빠진 내용을 짚거나, 남길 필요가 없었던 것을 알려 주는 일은 계속 내가 한다.

즉, 직접 적는 일을 없앤 것이 아니라, 직접 적어야만 위키가 채워지던 상태를 수확과 컴파일로 바꾼 것이다.

어느 프로젝트에서든 위키를 바로 쓰게 했다: 환류

두 번째 이유는 위키를 여는 위치가 고정돼 있었다는 점이다. 예전에는 위키를 쓰려면 그 프로젝트에서 세션을 열어야 했다. 이번에는 수확과 마찬가지로, 처음에는 Claude Code 하나에만 연결을 걸어 어느 프로젝트에서든 새 세션을 열 때 위키의 정보를 먼저 받아보게 했다.

Claude Code의 전역 설정에서 SessionStart 훅이 실행되면 환류 연결 스크립트가 호출된다.

{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "/Users/angari/projects/second/.claude/hooks/reflux-session.sh"
      }]
    }]
  }
}

수확과 마찬가지로 이 스크립트는 Claude Code 전용 연결부다. 공통 환류 처리를 실행한다.

CORE="$HOME/projects/second/lib/hooks/reflux-core.sh"
exec "$CORE" full

full 방식에서는 새 세션의 시작 맥락에 두 파일이 들어온다.

필요한 내용은 그 목록을 따라 해당 위키 페이지에서 더 읽는다. 처음부터 모든 지식을 대화에 넣는 것이 아니라, 새 세션이 무엇을 이미 알고 있고 어디를 더 찾아봐야 하는지를 알고 시작하게 만든 것이다.

나는 이렇게 쌓인 맥락을 다음 세션이 받아보는 일을 환류라고 불렀다. 이전 위키에도 기록을 모으는 기능은 있었지만, 그 기록이 내가 일하는 다른 프로젝트로 다시 들어오는 길은 없었다.

이제는 위키를 쓰기 위해 위키 프로젝트로 가야 하는 것이 아니라, 내가 일하는 곳마다 위키가 같이 온다. 그래서 수확으로 쌓인 내용이 컴파일을 거쳐, 다음 작업의 출발점으로 다시 쓰이게 됐다.

LLM Wiki와 second가 맡는 일

수확과 환류는 LLM Wiki 자체의 기능이라기보다는, Claude Code에서 일한 내용을 LLM Wiki에 넣고 정리된 내용을 다음 작업에서 다시 쓰기 위해 second에 붙인 연결 방식이다.

정리하면, 컴파일과 린트는 LLM Wiki를 유지하는 동작이고, 수확과 환류는 second가 그 LLM Wiki를 내 일상 작업에 붙이는 방식이다.

LLM Wiki 자체는 원본을 지식으로 바꾸고 점검한다

LLM Wiki는 세 층으로 나뉜다. 원본 기록은 대화나 메모처럼 바꾸지 않고 보관하는 재료다. 위키는 그 재료에서 의미 있는 내용을 주제별로 정리해 둔 지식 페이지다. 규칙은 어떤 재료를 읽고 어떻게 정리할지 정해 둔 기준이다.

이 구조를 유지하는 핵심 동작은 둘이다.

1. 컴파일은 새 세션, 메모, 스크랩에서 남길 내용만 골라 원본 기록과 위키에 정리한다. 처리한 범위는 장부에 남겨 같은 재료를 다시 읽지 않는다.
2. 린트는 깨진 링크, 연결되지 않은 페이지, 위키에 반영되지 않은 원본처럼 구조적으로 확인할 수 있는 문제를 찾는다. 판단이 필요 없는 색인 누락만 자동으로 고친다.

second를 실제로 쓰는 흐름

예를 들어 며칠 뒤, 전에 만들던 앱을 다시 손보는 흐름은 이렇다.

바꾼 것은 방식이 아니라 동선이었다

LLM Wiki라는 방식 자체는 예전과 달라지지 않았다. 달라진 것은 위키가 내 작업 안으로 들어온 방식이다.

결국 예전 위키를 제대로 쓰지 못한 이유는 LLM Wiki 방식이 부족해서가 아니었다. 위키에 내용을 넣고 꺼내기 위해, 내가 하던 일을 멈추고 그쪽으로 가야 했기 때문이다. 이번에는 그 순서를 뒤집었다. 일하면서 생긴 기록은 수확으로 들어오고, 정리한 내용은 다음 세션에 환류된다.

그래서 second는 내가 따로 관리해야 하는 지식 공간이 아니라, 내가 계속 일할수록 함께 쌓이는 기반이 됐다. 처음 만들고 싶었던 것은 나를 아는 비서였고, 이번에는 그 비서가 나를 알아갈 재료부터 만들었다.