안녕하세요. 코딩 에이전트가 내 Markdown 문서를 직접 찾아 읽게 해주는 llmwiki-serve

를 preview로 공개했습니다.

쓰기 어렵지 않게 만드는 것을 먼저 목표로 잡았습니다. Codex나 Claude Code를 쓰고 있다면 llmwiki-bridge

marketplace plugin을 설치한 뒤 “이 wiki 폴더를 연결해줘”라고 시킬 수 있습니다. 플러그인이 llmwiki-serve

설치, 로컬 서버 실행, MCP 등록 과정을 안내합니다. 한 번 등록해두면 이후 세션에서도 같은 문서 폴더를 도구처럼 조회할 수 있습니다.

요즘 프로젝트를 하다 보면 README, ADR, spec, 회의 노트, Obsidian 문서가 계속 쌓입니다. 문제는 Codex나 Claude Code 같은 에이전트가 그 문서를 항상 잘 읽고 작업하지는 않는다는 점이었습니다.

매번 “이 파일도 봐줘”, “저 폴더도 참고해줘”라고 붙여넣는 건 번거롭고, 그렇다고 이것 때문에 별도 RAG 앱을 만들거나 채팅 UI를 새로 붙이는 것도 과하다고 느꼈습니다.

llmwiki-serve

는 이 사이를 작게 해결하려고 만든 도구입니다.

로컬 Markdown 폴더를 하나 지정하면, 그 폴더를 읽기 전용 context server로 열어줍니다. 에이전트는 여기에 붙어서 관련 문서를 찾고, 필요한 페이지를 읽고, 어떤 문서를 근거로 봤는지 같이 가져갈 수 있습니다.

예를 들면 이런 식입니다.

• “이번 릴리스에서 빠진 체크가 뭐야?”
• “이 설계 변경과 관련된 ADR을 찾아줘.”
• “이 기능을 고치기 전에 봐야 할 spec이 있어?”
• “내 Obsidian vault에서 이 주제와 연결된 노트를 찾아줘.”

이때 원본 Markdown 파일은 수정하지 않습니다. 서버는 문서를 옮기거나 변환해서 관리하지 않고, 현재 폴더를 읽어서 에이전트가 쓰기 좋은 조회 인터페이스만 제공합니다.

지원하는 것은 대략 이렇습니다.

• Markdown 폴더, Obsidian 스타일 wikilink, YAML front matter, heading, tag를 읽습니다.
• CLI, HTTP, MCP로 붙일 수 있습니다.
• 검색 결과와 함께 source ref, 관련 문서, graph context를 돌려줍니다.
• draft/private/confidential 문서는 기본 응답에서 제외합니다.
• 네트워크 응답에서는 로컬 루트 경로를 숨기고, 기본 CORS도 localhost 계열만 허용합니다.

코딩 에이전트에 붙이는 방식도 단순하게 잡았습니다.

가장 쉬운 경로는 marketplace plugin입니다. 이 플러그인은 별도 runtime이 아니라, Codex/Claude Code 안에서 llmwiki-serve

연결을 도와주는 setup/status/doctor skill 묶음입니다.

Codex에서는 이렇게 설치할 수 있습니다.

codex plugin marketplace add knowledge-bridge-labs/llmwiki-plugins --ref main
codex plugin add llmwiki-bridge@knowledge-bridge-labs

Claude Code에서는 이렇게 설치할 수 있습니다.

claude plugin marketplace add --scope user knowledge-bridge-labs/llmwiki-plugins
claude plugin install --scope user llmwiki-bridge@knowledge-bridge-labs

설치 후에는 새 세션을 열고 “Use the llmwiki-bridge:setup

skill to connect ./wiki.”처럼 요청하면 됩니다.

플러그인 없이 직접 붙인다면 기본 흐름은 설치, 서버 실행, MCP 등록입니다.

uv tool install llmwiki-serve
llmwiki-serve serve ./wiki --host 127.0.0.1 --port 8765

그다음 코딩 에이전트에는 http://127.0.0.1:8765/mcp/stream

을 MCP server로 등록합니다. 이렇게 해두면 새 세션에서도 같은 문서 폴더를 llmwiki_context

, llmwiki_search

, llmwiki_read

, llmwiki_graph

같은 도구로 조회할 수 있습니다.

예를 들면 Codex에서는 이렇게 등록할 수 있습니다.

codex mcp add llmwiki --url http://127.0.0.1:8765/mcp/stream

Claude Code에서는 사용자 설정으로 이렇게 등록할 수 있습니다.

claude mcp add -s user --transport http llmwiki http://127.0.0.1:8765/mcp/stream

MCP 등록은 남아 있지만, 실제 조회를 하려면 llmwiki-serve serve ...

프로세스는 켜져 있어야 합니다.

터미널에서 먼저 만져볼 때는 샘플 wiki로 바로 확인할 수 있습니다.

git clone https://github.com/knowledge-bridge-labs/llmwiki-serve.git
llmwiki-serve query ./llmwiki-serve/examples/sample-wiki "release readiness"
llmwiki-serve serve ./llmwiki-serve/examples/sample-wiki --host 127.0.0.1 --port 8765

기본 설치는 가볍게 동작합니다.

모델을 호출하지 않고, 답변을 합성하지 않고, 임베딩 인덱스도 만들지 않습니다. 기본 검색은 로컬 Markdown projection 위의 lexical/literal 검색입니다.

의미 검색이 필요하면 별도 옵션으로 켤 수 있습니다.

uv tool install "llmwiki-serve[vector]"
llmwiki-serve serve ./wiki \
--vector-provider fastembed \
--vector-model sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 \
--vector-model-download allow

이 경우 FastEmbed 기반 vector

/hybrid

검색을 사용합니다. 별도 PyTorch serving을 띄우는 방식은 아니고, FastEmbed가 ONNX Runtime으로 같은 서버 프로세스 안에서 로컬 임베딩을 만듭니다. 기본은 이미 캐시된 모델만 쓰는 local-files-only 모드이고, 처음 실행에서 모델 다운로드가 필요하면 위 예시처럼 --vector-model-download allow

를 명시합니다.

벡터 캐시는 서비스 대상 wiki root 밖의 로컬 sidecar에 저장됩니다. 설치만으로 자동 활성화되지는 않고, 서버를 띄울 때 운영자가 provider를 켜야 합니다.

오래 떠 있는 서버나 멀티 워커 환경에서는 Redis/Valkey projection cache도 붙일 수 있습니다.

uv tool install "llmwiki-serve[redis]"
llmwiki-serve serve ./wiki \
--projection-store redis \
--redis-url redis://127.0.0.1:6379/0 \
--cache-namespace local \
--source-id my-wiki

벤치마크 숫자도 공개 repo에 같이 올려두었습니다.

0.2.8

기준으로 BEIR SciFact test

split을 Markdown으로 projection해서 LlmWikiService.search(query, limit=100)

로 돌린 리포트가 있습니다. 데이터 크기는 5,183

docs, 300

queries, 339

qrels이고, opt-in english

analyzer에서 nDCG@10 0.6905

, Recall@100 0.9287

이 나왔습니다. 같은 quality metric이 Windows와 Ubuntu 리포트에서 일치했고, warm fixed-index 검색 latency는 해당 환경 기준 Windows p50 272.5ms

/ p95 535.2ms

, Ubuntu p50 58.1ms

/ p95 118.2ms

였습니다.

이 수치는 공식 BEIR leaderboard 주장이 아니라, Markdown projection 위에서 같은 데이터를 재현한 공개 aggregate report입니다.

GitHub:

https://github.com/knowledge-bridge-labs/llmwiki-serve

Docs:

https://knowledge-bridge-labs.github.io/llmwiki-docs/

작은 프로젝트 문서 폴더나 개인 vault에 붙여보고 이상한 부분이 있으면 알려주세요. 필요한 기능, 깨지는 Markdown 패턴, 연결이 안 되는 코딩 에이전트가 있으면 GitHub Issues로 남겨주셔도 좋습니다.

Issues:

https://github.com/knowledge-bridge-labs/llmwiki-serve/issues