llmwiki-serve: Markdown/Obsidian 문서를 코딩 에이전트용 읽기 전용 컨텍스트로 연결하기

HwangJohn · 9월 27, 2026, 12:56오후

llmwiki-serve는 이미 가지고 있는 Markdown, Obsidian 또는 LLMWiki 폴더를 코딩 에이전트가 조회할 수 있는 읽기 전용 Knowledge Source로 열어주는 로컬 서버입니다. 문서를 새로 생성하는 위키 컴파일러가 아니라, 기존 파일을 그대로 두고 필요한 근거를 CLI, HTTP, MCP로 찾고 읽게 하는 도구입니다.

현재 공개 버전은 0.2.13이며 Python 3.11 이상에서 사용할 수 있습니다.

어떤 문제를 해결하나

프로젝트가 커지면 README 외에도 ADR, spec, 릴리스 체크리스트, 회의 노트, 개인 Obsidian 문서가 계속 쌓입니다. 하지만 Codex나 Claude Code 같은 코딩 에이전트가 매 작업마다 이 문서를 모두 알고 있는 것은 아닙니다.

관련 파일을 매번 프롬프트에 붙이는 것은 번거롭고, 문서를 참고시키기 위해 별도의 호스팅형 RAG 서비스나 채팅 UI까지 운영하는 것도 작은 프로젝트에는 부담스러울 수 있습니다.

llmwiki-serve는 기존 작성 방식을 바꾸지 않고, 필요한 문서만 근거와 함께 조회하는 계층을 제공합니다.

기존 Markdown/Obsidian 폴더
          ↓ 읽기 전용 projection
     llmwiki-serve
          ↓ CLI / HTTP / MCP
  Codex, Claude Code, IDE 에이전트, 스크립트

에이전트는 다음과 같은 질문에 필요한 문서를 먼저 찾을 수 있습니다.

"이번 릴리스 전에 확인해야 할 체크리스트가 뭐야?"
"이 설계 변경과 관련된 ADR을 찾아줘."
"이 기능을 수정하기 전에 읽어야 할 spec이 있어?"
"내 Obsidian 문서에서 이 주제와 연결된 노트를 찾아줘."

무엇을 제공하나

Markdown/Obsidian 스타일 wikilink, YAML front matter, heading, tag, 문서 간 링크를 읽습니다.
같은 읽기 전용 projection을 CLI, HTTP, MCP Streamable HTTP로 제공합니다.
검색 결과와 함께 문서 제목, 경로, source ref, 관련 graph hint 등 근거 정보를 반환합니다.
draft, unpublished, confidential 등 비공개로 표시된 문서는 기본 조회 결과에서 제외합니다.
기본 검색은 모델이나 임베딩이 필요 없는 lexical 검색입니다.
원본 Markdown을 수정하거나 업로드하지 않습니다.

반대로 다음 기능을 대신하려는 도구는 아닙니다.

웹 크롤링이나 문서 수집 파이프라인
위키 작성·컴파일 도구
모델 실행 또는 답변 합성
호스팅형 벡터 데이터베이스
완성형 RAG/채팅 애플리케이션

가장 작은 실행 예시

uv가 설치되어 있다면 현재 공개 버전을 다음과 같이 설치할 수 있습니다.

uv tool install llmwiki-serve==0.2.13
llmwiki-serve --help

기존 문서 폴더를 바로 조회하거나 로컬 서버로 열 수 있습니다.

llmwiki-serve manifest ./my-wiki
llmwiki-serve query ./my-wiki "release readiness"
llmwiki-serve serve ./my-wiki --host 127.0.0.1 --port 8765

다른 터미널에서 HTTP로 확인합니다.

curl -s http://127.0.0.1:8765/query \
  -H 'content-type: application/json' \
  -d '{"query":"release readiness","limit":4}'

Windows PowerShell에서는 curl이 Invoke-WebRequest 별칭일 수 있으므로 curl.exe를 명시하는 편이 안전합니다.

MCP Streamable HTTP를 지원하는 클라이언트에는 다음 URL을 등록할 수 있습니다.

http://127.0.0.1:8765/mcp/stream

우선 llmwiki_context로 질문에 필요한 context pack을 받고, 필요할 때 llmwiki_search, llmwiki_read, llmwiki_graph, llmwiki_graph_neighbors, llmwiki_source_refs, llmwiki_source_bundle로 범위를 좁히는 흐름입니다.

선택 기능

기본 설치는 로컬 lexical 검색만 사용합니다. 의미 기반 검색이 필요한 경우에만 [vector] extra와 FastEmbed provider를 명시적으로 켤 수 있습니다. 모델 다운로드도 운영자가 허용하기 전에는 자동으로 수행하지 않습니다.

0.2.13에는 System-One/Jev를 이용한 다음 검색 행동 판단을 선택 기능으로 추가했습니다. 일반적인 context pack을 먼저 만든 뒤, 현재 근거로 멈출지, 문서를 더 읽을지, 다시 검색할지, graph를 볼지, 사용자에게 되물을지를 retrieval_action_guidance로 제안합니다. 검색 결과를 재정렬하거나 최종 답변을 생성하는 기능은 아닙니다.

이 기능은 기본값이 꺼져 있습니다. 사용하려면 provider key를 CLI 인자가 아닌 LLMWIKI_QUERY_ACTION_JUDGE_API_KEY 환경변수로 설정하고, query 또는 server 실행 시 --query-action-judge system-one을 별도로 지정해야 합니다.

llmwiki-serve query ./my-wiki "release readiness" \
  --query-action-judge system-one

Jev provider에는 원문이나 snippet 전체가 아니라 마스킹된 질의와 구조 정보만 전달합니다. raw page text, raw snippet, page ID, source-ref label, raw path, 로컬 root, private URL, 명백한 credential은 provider payload에서 제외합니다. key가 없거나 provider 호출이 실패해도 기존 검색 근거는 그대로 반환하는 fail-open 방식입니다. 다만 외부 provider 경계가 생기고 단일 질의가 느려질 수 있으므로, 운영자가 이 경계를 검토한 경우에만 켜는 기능입니다.

반복적인 graph 조회에는 표준 라이브러리 sqlite3 기반의 SQLite GraphStore를 선택적으로 사용할 수 있습니다. 이 DB는 원본이 아니라 언제든 다시 만들 수 있는 파생 캐시이며, 서비스 대상 wiki 폴더 바깥에 두어야 합니다.

장시간 실행하거나 여러 worker가 같은 projection을 재사용해야 하는 환경에는 [redis] extra로 Redis/Valkey 캐시를 붙일 수 있습니다. 이 캐시에는 문서 본문과 draft를 포함한 민감한 파생 데이터가 들어갈 수 있으므로, 공개 Redis나 신뢰하지 않는 공유 인스턴스에는 연결하지 않는 것을 전제로 합니다.

로컬 사용 시 확인할 점

우선 127.0.0.1에만 바인딩해 사용하는 것을 권장합니다.
외부 네트워크에 노출할 때는 인증, TLS, CORS, 로그 보존 정책을 별도로 검토해야 합니다.
기본 I/O 디버깅 로그에는 요청 질의와 제한된 응답 내용이 기록될 수 있습니다. 필요하면 --io-log off로 끄거나 안전한 경로와 보존 정책을 지정해야 합니다.
graph/vector/Redis sidecar는 원본이 아니지만 민감한 파생 상태일 수 있으므로 공개 저장소나 동기화 폴더에 넣지 않는 편이 안전합니다.
Jev provider key는 명령행이나 저장소에 기록하지 않고 환경변수 또는 별도의 secret manager로 관리해야 합니다.

아직 public preview 단계라서, 실제 Markdown/Obsidian 폴더에 붙였을 때의 피드백을 받고 싶습니다.

잘 읽히지 않는 Markdown 또는 Obsidian 패턴이 있는지
MCP tool 이름과 인자 형태가 실제 에이전트 작업에서 편한지
"에이전트용 읽기 전용 문서 source layer"라는 경계가 이해하기 쉬운지
기본 lexical 검색으로 부족했던 한국어 검색 사례가 있는지